diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml b/.agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml
similarity index 67%
rename from .agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml
rename to .agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml
index 10665d6e64..e49130d5ee 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml
+++ b/.agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-16-movable-mandatory-update-window.md
-2026-09-16-movable-mandatory-update-window.md: 4695074429b76b467e6ec90201632dbb5a007e68
-2026-09-16-movable-mandatory-update-window.zh.md: 3b416c53dc02abce1276bb70a13bb45b4c1afa44
+2026-09-16-movable-mandatory-update-window.md: da996e5b37f990ff773e3ec88de0baed3c4b54f3
+2026-09-16-movable-mandatory-update-window.zh.md: 15fd4eb2520a39d8259321a747b33c833b56cbb1
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.md b/.agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.md
similarity index 98%
rename from .agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.md
rename to .agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.md
index 4695074429..da996e5b37 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.md
+++ b/.agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.md
@@ -1,6 +1,7 @@
 # Agent Note: Movable mandatory-update window
 
 Status: implemented
+Archived: 2026-09-18
 
 English | [中文](2026-09-16-movable-mandatory-update-window.zh.md)
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.zh.md b/.agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.zh.md
similarity index 98%
rename from .agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.zh.md
rename to .agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.zh.md
index 3b416c53dc..15fd4eb252 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-movable-mandatory-update-window.zh.md
+++ b/.agents/notes/archived/bug-fix/2026-09-16-movable-mandatory-update-window.zh.md
@@ -1,6 +1,7 @@
 # Agent Note: 可移动的强更窗口
 
 Status: implemented
+Archived: 2026-09-18
 
 [English](2026-09-16-movable-mandatory-update-window.md) | 中文
 
diff --git a/.agents/notes/archived/feature/2026-08-25-unified-task-list.i18n.yaml b/.agents/notes/archived/feature/2026-08-25-unified-task-list.i18n.yaml
new file mode 100644
index 0000000000..c5b051c49c
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-08-25-unified-task-list.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/archived/feature/2026-08-25-unified-task-list.md
+2026-08-25-unified-task-list.md: f2f955e36a78eee8fa8ff8a804293bcc37a44acd
+2026-08-25-unified-task-list.zh.md: 5a4c51a6cc3d0f331d2559debb73dc02e9cf12c5
diff --git a/.agents/notes/archived/feature/2026-08-25-unified-task-list.md b/.agents/notes/archived/feature/2026-08-25-unified-task-list.md
new file mode 100644
index 0000000000..f2f955e36a
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-08-25-unified-task-list.md
@@ -0,0 +1,49 @@
+# Agent Note: One session-header task list — jobs joined with activities in the UI projection only
+
+Status: implemented
+Archived: 2026-09-03
+
+English | [中文](2026-08-25-unified-task-list.zh.md)
+
+Superseded: the two-roster join described here was removed with the activity seam — the job rows are now the whole roster; see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md).
+
+## Problem
+
+The [activity observation seam](2026-08-24-activity-observation-seam.md) shipped its Web surface as a second session-header button beside the [background-job list](2026-08-08-web-background-job-display.md). A background bash run registers in both planes — `ctx.jobs` for control and `ctx.activities` for observation — so the same work rendered twice: once in "background jobs" with lifecycle and duration, once in "activities" with expandable live output. Two near-identical popovers with different names for overlapping row sets read as a product accident, and the flat activity rows (live and settled interleaved, single-line, no duration) had no visual hierarchy.
+
+## Decision
+
+The service planes stay orthogonal; the join happens once, per row, in the UI projection.
+
+- **`ctx.jobs` and `ctx.activities` remain separate services.** Jobs are the control plane: model-visible ids, a consuming `readOutput` cursor the model drains, `stopping`, `kill`, and the `reported` completion-notice contract. Activities are the transient observation plane: non-consuming absolute offsets, invisible to the model, gone on restart. Merging the services would force one registry to carry both a consuming and a non-consuming cursor and would blur the "model-visible ⟺ logged" line for a plane designed to stay off the session log.
+- **`dsh-client-ui-activity` renders the single merged list; `dsh-client-ui-jobs` is deleted** (pre-release, no compatibility shim), and the merged entry takes the job list's slot order. Each `jobsBySession` row is joined with the activity carrying its `correlation.jobId`: the job supplies identity, lifecycle (`stopping` exists only there), duration, and the model-visible `detail`; the activity supplies the expandable output panel. An activity without a job (a workflow run) keeps its own row; an activity whose job is not in the projection is not dropped. Without the activity registry, job rows still render — they just offer no panel, so the merged control degrades to exactly the old job list.
+- **User-facing vocabulary is "task" (任务)** — `N tasks running` / `N 个任务进行中` — because every row is running work to the user, while "background job" excludes workflow runs and "activity" names the internal plane, not the user concept. The dictionary namespace and package names stay `activity`: internal names follow the naming ledger, not display copy.
+- **Hierarchy**: live rows first (label over a kind-badge-and-status second line, ticking duration), then settled rows compacted to one de-emphasized line; each non-empty section carries its own heading (Running / Finished). Rows without an observable activity render as static rows with no expansion affordance.
+
+Deliberately not joined: subagent delegation rows stay bare job rows (the subagent panel is their surface), and foreground commands stay in their tool cards — neither gains an activity producer.
+
+## Alternatives considered
+
+- **Merge the services** — rejected for the cursor-semantics and model-visibility reasons above.
+- **Keep the job list and bolt output onto it** — leaves workflow runs (activities without jobs) homeless, forcing a second list to survive anyway.
+
+## Refinements from browser acceptance
+
+Driving the merged list in the real app produced four presentation decisions, all scoped to the expanded panel and the header band:
+
+- **The header band order is preset → tasks → subagent catalog.** The root-session descendant count moved out of the breadcrumb (`header.lineage`) into the actions band (order 30) and dropped its `/` separator — a root session has no hierarchy to breadcrumb; child sessions keep their `root / child` switcher where the `/` is real. `SubagentCatalogAction` owns the moved seat; the lineage renderer now renders nothing on roots.
+- **The panel's copy control copies the command** (`TerminalBlock.copyText`), not the output: a long command ellipsizes in the row, so the control is its only complete source, while output is selectable text below. Supplying `copyText` also keeps the control rendered before any output exists.
+- **The panel scrolls instead of folding**: commands and output lines wrap in full (`--dsl-terminal-command-whitespace` / `--dsl-terminal-line-whitespace: pre-wrap`, so the output region never scrolls sideways) and the output region caps at a fixed height (`--dsl-terminal-output-max-height`) with `maxLines: Infinity` disabling the head/tail fold.
+- **The panel draws no run-state dot** (`TerminalBlock.runStateDot: false`) — the row above it already carries the same state — and reclaims the dot gutter via `--dsl-terminal-gutter`. The panel's left spine was dropped with it.
+
+All four land as opt-ins on `TerminalBlock` (props or `--dsl-terminal-*` variables), so tool cards keep their shipped fold/ellipsis/dot behavior unchanged.
+
+## Testing
+
+Component suites cover the join (job lifecycle wins, activity supplies the panel, bare-job rows, standalone activities), sections, durations, and the panel options; `pnpm vitest run packages/client/ui-activity packages/client/ui-primitives packages/client/ui-subagent` runs them. The keyless web e2e pair (`background-job-list`, `live-activity-stream`) replays the merged list end to end against ARIA goldens; `agent-preset-selection` pins the header band order.
+
+## Consequences
+
+- The two web e2e scenarios (`background-job-list`, `live-activity-stream`) now assert one "Tasks" list; the job-list scenario's row gained a live-output panel, which is the join working end to end.
+- A human kill control on live rows is still blocked on the jobs `reported` contract question recorded in the job-display note.
+- The `job` locale namespace is gone with its package; `activity` owns the merged copy including the duration vocabulary.
diff --git a/.agents/notes/archived/feature/2026-08-25-unified-task-list.zh.md b/.agents/notes/archived/feature/2026-08-25-unified-task-list.zh.md
new file mode 100644
index 0000000000..5a4c51a6cc
--- /dev/null
+++ b/.agents/notes/archived/feature/2026-08-25-unified-task-list.zh.md
@@ -0,0 +1,49 @@
+# Agent Note: 会话头部单一任务列表——jobs 与 activity 只在 UI 投影层合并
+
+Status: implemented
+Archived: 2026-09-03
+
+[English](2026-08-25-unified-task-list.md) | 中文
+
+Superseded: 本文描述的双名册 join 已随 activity seam 一并移除——job 行现在就是完整名册；见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。
+
+## 问题
+
+[activity 观察面](2026-08-24-activity-observation-seam.zh.md)的 Web 呈现落地为[后台任务列表](2026-08-08-web-background-job-display.zh.md)旁边的第二个会话头部按钮。一次后台 bash 会同时登记在两个面里——`ctx.jobs` 负责控制、`ctx.activities` 负责观察——于是同一份工作渲染了两次：一次在"后台任务"里带生命周期与时长，一次在"活动"里带可展开的实时输出。两个行集合高度重叠、名字却不同的近似弹层，读起来像产品事故；而活动列表的扁平行（live 与 settled 混排、单行、无时长）也缺乏视觉层次。
+
+## 决策
+
+服务面保持正交；合并只在 UI 投影层逐行发生一次。
+
+- **`ctx.jobs` 与 `ctx.activities` 仍是两个服务。** jobs 是控制面：模型可见的 id、模型消耗式的 `readOutput` 游标、`stopping`、`kill` 与 `reported` 完成通知契约。activity 是瞬态观察面：非消耗式绝对偏移、模型不可见、重启即无。合并服务会迫使一个注册表同时携带消耗式与非消耗式两种游标，并模糊这个刻意不进 session log 的面与"模型可见 ⟺ 已记录"不变量的边界。
+- **`dsh-client-ui-activity` 渲染唯一的合并列表；`dsh-client-ui-jobs` 删除**（预发布阶段，不留兼容层），合并入口占用原 job 列表的 slot 顺位。每个 `jobsBySession` 行与携带其 `correlation.jobId` 的 activity 逐行 join：job 提供身份、生命周期（`stopping` 只存在于此）、时长与模型可见 `detail`；activity 提供可展开的输出面板。没有 job 的 activity（workflow 运行）保留自己的行；job 不在投影里的 activity 也不会被丢弃。没有 activity 注册表时 job 行照常渲染——只是没有面板，合并控件退化为与旧 job 列表完全等价。
+- **用户可见词汇统一为"任务"（task）**——`N 个任务进行中` / `N tasks running`——因为对用户而言每一行都是在跑的工作，而"后台任务"排除了 workflow 运行、"活动"命名的是内部面而非用户概念。词典命名空间与包名保持 `activity`：内部名遵循命名台账，不跟随展示文案。
+- **层次**：进行中的行在前（命令为主行、kind 徽章加状态为副行、时长每秒跳动），已结束的行折为降权单行；每个非空分组带自己的标题（进行中 / 已结束）。没有可观察 activity 的行渲染为无展开交互的静态行。
+
+刻意不合并的：subagent 委托行保持裸 job 行（subagent 面板是它的呈现面），前台命令留在工具卡片里——两者都不接活动生产者。
+
+## 曾考虑的替代方案
+
+- **合并服务层**——因上述游标语义与模型可见性理由否决。
+- **保留 job 列表、把输出挂上去**——workflow 运行（无 job 的 activity）无处安放，第二个列表终究得活下来。
+
+## 浏览器验收带来的细化
+
+在真实应用里驱动合并列表得出四个呈现决策，全部限定在展开面板与头部条带：
+
+- **头部条带顺序为 preset → 任务 → subagent 目录。** 根会话的后代数量从面包屑（`header.lineage`）移入操作区（order 30）并去掉 `/` 分隔符——根会话没有可面包屑的层级；子会话保留 `根 / 子` 切换器，那里的 `/` 是真实层级。移位后的席位由 `SubagentCatalogAction` 拥有；谱系 renderer 在根会话上不再渲染任何东西。
+- **面板的复制控件复制命令**（`TerminalBlock.copyText`）而非输出：长命令在行内被省略号截断，控件是它唯一的完整来源，而输出本身就是下方可选中的文本。提供 `copyText` 还让控件在任何输出出现之前就保持渲染。
+- **面板以滚动取代折叠**：命令与输出行完整换行（`--dsl-terminal-command-whitespace` / `--dsl-terminal-line-whitespace: pre-wrap`，输出区因此永不横向滚动），输出区以固定高度封顶（`--dsl-terminal-output-max-height`），`maxLines: Infinity` 禁用头尾折叠。
+- **面板不画运行状态点**（`TerminalBlock.runStateDot: false`）——上方的行已携带同一状态——并通过 `--dsl-terminal-gutter` 收回状态点落区。面板左侧竖线随之移除。
+
+四项全部以 `TerminalBlock` 的可选项落地（prop 或 `--dsl-terminal-*` 变量），工具卡片保持既有的折叠/省略/状态点行为不变。
+
+## 测试
+
+组件套件覆盖 join（job 生命周期优先、activity 提供面板、裸 job 行、独立 activity）、分段、时长与面板选项；`pnpm vitest run packages/client/ui-activity packages/client/ui-primitives packages/client/ui-subagent` 运行它们。无密钥 web e2e 对（`background-job-list`、`live-activity-stream`）按 ARIA golden 端到端回放合并列表；`agent-preset-selection` 钉住头部条带顺序。
+
+## 后果
+
+- 两个 web e2e 场景（`background-job-list`、`live-activity-stream`）现在断言同一个"任务"列表；job 场景的行获得了实时输出面板，这正是 join 端到端生效的证据。
+- live 行上的人工 kill 控件仍被 job-display note 记录的 jobs `reported` 契约问题阻塞。
+- `job` 词典命名空间随包一起消失；`activity` 拥有合并后的全部文案，包括时长词汇。
diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json
index 88573f7db2..ca509c1070 100644
--- a/.agents/notes/archived/manifest.json
+++ b/.agents/notes/archived/manifest.json
@@ -751,6 +751,9 @@
     "bug-fix/2026-09-09-content-sized-diagram-previews.i18n.yaml": "sha256:a4404fe8e35ca5b6371f9cdb58fea6724cf3e7737bb2db8a3a321d534454b17c",
     "bug-fix/2026-09-09-content-sized-diagram-previews.md": "sha256:5239e98e5c057d6f7e10c3f10a0f67273778d99b0c4f10b31a1921c3c6474b80",
     "bug-fix/2026-09-09-content-sized-diagram-previews.zh.md": "sha256:c1ee3790a9d5c3561e1d93d5e649afa904c7d19b9d77248c85ef16daccd953e2",
+    "bug-fix/2026-09-16-movable-mandatory-update-window.i18n.yaml": "sha256:e526ce14ae9557e24364e3686778b130090445ef2152d976b7cc93e76eac6401",
+    "bug-fix/2026-09-16-movable-mandatory-update-window.md": "sha256:67546cea0b3de2b3e32957a508dbde097d91dd919fe067c8dbecb2c65b50c366",
+    "bug-fix/2026-09-16-movable-mandatory-update-window.zh.md": "sha256:20a0aade6ee71c89e84d70e23c89bb51e8a38c674d103dd43022feabb8d27be3",
     "bug-fix/2026-09-11-session-controller-fork-turn-cut.i18n.yaml": "sha256:4442529ced1c8e48d30f7b50c65ff03eb92dce9815beb438cedbf29f234bce47",
     "bug-fix/2026-09-11-session-controller-fork-turn-cut.md": "sha256:a996f24a896c7fc5d81e015db3eae27d8a46c853287572e815623ce35eae1b12",
     "bug-fix/2026-09-11-session-controller-fork-turn-cut.zh.md": "sha256:6486f0eacf5067ef9850dc32f1c27b2109a7d4e9e3c498366f5c38742bb53ac5",
@@ -1375,6 +1378,9 @@
     "feature/2026-08-25-loaded-turn-chat-navigation.i18n.yaml": "sha256:86bd02d56cf95ac465d0f6e326ccf75432ffb9c3db47373ae6a795195cff9ea7",
     "feature/2026-08-25-loaded-turn-chat-navigation.md": "sha256:0ee1cb6da76b93e467d747aa8ba07697ba648cb213ba52202c51ee1e85dff1a8",
     "feature/2026-08-25-loaded-turn-chat-navigation.zh.md": "sha256:5d3e567027fc65241856bf9f9cf0d73a20d53214c49bfbc884ab2ddd19503918",
+    "feature/2026-08-25-unified-task-list.i18n.yaml": "sha256:fec0d4a3ecf59aafd440bc801c686b14d63152c937f51bebe0da61ff615f6f33",
+    "feature/2026-08-25-unified-task-list.md": "sha256:30bd4e338a3de2f59af98d512c7878928c61846e6700d6012fc45e51c0bf94df",
+    "feature/2026-08-25-unified-task-list.zh.md": "sha256:88fce0a52b5387ea98c1f68742c03b2f475c5465c680befb32c587066e52cfce",
     "feature/2026-08-26-web-trigger-menu-presentation-polish.i18n.yaml": "sha256:69179f3056c6d5fc35119e83dd7a5af30213502dac3c1f2d4fd43eae96ee2ecf",
     "feature/2026-08-26-web-trigger-menu-presentation-polish.md": "sha256:c54e3bbe528d6be711541c61e777e6e4ed4fbc1374df97d846b015d3693679f4",
     "feature/2026-08-26-web-trigger-menu-presentation-polish.zh.md": "sha256:7db49018eebbba539838d734a80fbb330e2b73fea3b343900591a3605c6c03b5",
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 e7aa78354c..22bf3c01c4 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: c386d3b338c94e0e5bbf8e99c2c7a30971ba92b7
-2026-06-20-generic-long-running-tool-runtime.zh.md: 002514740a15c5961960d20976fc18f7fd8071ff
+2026-06-20-generic-long-running-tool-runtime.md: 5960eb268656d7e316c763631451db1c6d1c6e49
+2026-06-20-generic-long-running-tool-runtime.zh.md: ea63ae82962a735b3a96e1803708172a33f83e9d
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 c386d3b338..5960eb2686 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
@@ -27,7 +27,7 @@ The literal types live on the [tasks subsystem page](../../../../docs/subsystems
 
 The process-local provider also owns bounded admission, whose rationale is recorded in the [bounded background job admission decision](../../archived/bug-fix/2026-08-11-bounded-background-job-admission.md). Its positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10`; `start()` derives each exact `Agent` object's active count from `running` and `stopping` records, while every unowned task shares one service bucket. Capacity rejection occurs before `run()` and id allocation, and producer `done` settlement is the only event that releases a stopping task's place. The provider does not queue, preempt, or retain a second mutable count.
 
-`outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `JobSnapshot`; 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.
+`outputLimitBytes` is producer-owned presentation policy, not a registry buffer. The registry validates and projects it unchanged into `JobView`; 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', jobId }`; 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 job runtime: later cancellation of the producing tool call must not kill the published task. `job_kill`, owner disposal, and service teardown request cancellation; foreground execution remains coupled to the call's `exec.signal`.
 
@@ -62,7 +62,7 @@ For contract-compliant producers, `AgentHandle.dispose()` resolves only after ow
 - `read(id, caller?)` for a consuming stream delta or an idempotent final result.
 - `kill(id, caller?, reason?)` for cancellation.
 - `wait(id, timeoutMs, caller?, signal?)` for bounded terminal waiting.
-- `onJobDone(listener)` for effect-scoped observation with exact-owner delivery and listener containment.
+- `events.subscribe(filter, listener)` for effect-scoped observation of registration, progress, output, settlement, and removal, filtered by owner or owner scope, with listener containment.
 - `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.
@@ -81,7 +81,7 @@ Stream reads share one task-scoped consuming cursor because the owning model is
 
 The system prompt tells the model to retain job 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 delivers a logged message to the exact owner's session. A busy owner is injected; an idle owner is woken, under the bounded policy the [idle-owner wake decision](../feature/2026-08-11-background-job-completion-wakes-an-idle-owner.md) owns.
 
-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-jobs` 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 job <id>` prefix and `job_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 job 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.
+`dsh-tool-jobs` keeps the delivery ledger: a wait claims the task when it starts (and withdraws if the task outlives the wait) and a `job_kill` claims it when accepted, so a settlement the model already received through a tool result injects no redundant completion notice; teardown settlements and unowned tasks are never announced ([seam consolidation](2026-09-03-jobs-seam-consolidation.md)). Listener failures are logged independently, do not stop later listeners, and are not awaited by waiters or teardown. When a view carries `outputLimitBytes`, `dsh-tool-jobs` 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 job <id>` prefix and `job_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 job 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
 
@@ -105,7 +105,7 @@ Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup,
 
 ### An immediate abstract task-runtime backend
 
-The current `JobStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry contract Agent Note](../../archived/architecture/2026-07-26-job-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
+The current `JobSpec.run()` contract returns in-process hooks and pushes output through an in-process `JobHandle`, and owners resolve to live `Agent`s in-process. A durable backend changes identity, restart, ownership, and observation semantics, so at introduction time the registry stayed one concrete service rather than freezing the wrong boundary. The [task-registry contract Agent Note](../../archived/architecture/2026-07-26-job-registry-seam.md) later separated the contract from the process-local implementation without changing these in-process semantics.
 
 ### Consumer-owned authorization or cleanup events
 
diff --git a/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md b/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md
index 002514740a..ea63ae8296 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
@@ -27,7 +27,7 @@ Status: implemented
 
 进程内 Service Provider 还拥有有界准入，其理由记录在[有界后台任务准入决策](../../archived/bug-fix/2026-08-11-bounded-background-job-admission.md)中。它的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数，默认值为 `10`；`start()` 从 `running` 与 `stopping` 记录派生每个确切 `Agent` 对象的活动数量，而全部无 owner 任务共享一个服务级桶。容量拒绝发生在 `run()` 与 id 分配之前，处于 stopping 的任务只有在生产方 `done` 结算时才释放名额。Service Provider 不排队或抢占任务，也不保留第二份可变计数。
 
-`outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `JobSnapshot`；通用任务控制器添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有控制器行为，因此运行时不会向无关的生产方类别施加隐式默认值。
+`outputLimitBytes` 是生产方拥有的呈现策略，而非注册表缓冲区。注册表校验该值，并将其原样投影到 `JobView`；通用任务控制器添加自身的状态或通知元数据后，再将该上限应用于完整的面向模型输出。省略该值时保持现有控制器行为，因此运行时不会向无关的生产方类别施加隐式默认值。
 
 面向模型的生产方会在规范成功值中暴露已提交的 id，通常为 `{ kind: 'background', jobId }`；Native 渲染仍可保留便于人类阅读的行文。预先被中止的后台调用会失败，而不是返回空操作，因为不存在可履行所承诺句柄的任务。一旦注册过程发布 id，取消就归任务自身的控制器与任务运行时所有：随后取消生产工具调用不得终止已发布的任务。`job_kill`、所有者资源释放和服务拆除会请求取消；前台执行仍与调用的 `exec.signal` 耦合。
 
@@ -62,7 +62,7 @@ job id 在运行时全局可见且可预测，因此注册表会授权每次访
 - `read(id, caller?)`：消费式流增量或幂等的最终结果。
 - `kill(id, caller?, reason?)`：取消。
 - `wait(id, timeoutMs, caller?, signal?)`：有界的终止等待。
-- `onJobDone(listener)`：effect 作用域内的观察，具有精确所有者投递和监听器隔离。
+- `events.subscribe(filter, listener)`：effect 作用域内对注册、进度、输出、结算与移除的观察，按所有者或所有者 scope 过滤，具有监听器隔离。
 - `attachController(name)`：任务控制器可用性防线。
 
 `wait` 在任务完成时返回终止快照，在等待超时时返回当前快照。中止一次等待只取消该次等待。如果结算已经将终止投递分配给该等待方，终止快照仍然优先。等待方在中止时同步注销，因此同一 tick 内发生结算时，不会代表一个实际未收到任何内容的读取方压制完成通知。
@@ -81,7 +81,7 @@ job id 在运行时全局可见且可预测，因此注册表会授权每次访
 
 系统提示词要求模型保留 job id、在后台工作运行时继续处理独立工作而非忙轮询或重复启动同一任务、在给出最终答案前收集相关任务，并终止不再重要的工作。完成时，系统会向确切所有者的会话交付一条已记录的消息：繁忙的所有者走注入，空闲的所有者会被唤醒，其有界策略由[空闲所有者唤醒决策](../feature/2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md)负责。
 
-当读取或等待交付终止任务、尚在等待的等待方在结算时认领了投递，或模型显式终止任务时，运行时将终止任务标为 `reported`。已报告的任务不会注入冗余的完成通知。监听器失败会独立记录，不会阻止后续监听器，也不会被等待方或资源销毁过程等待。当快照携带 `outputLimitBytes` 时，`dsh-tool-jobs` 会保持 UTF-8 边界，并复用生产方已有的截断标记，而不会重复添加。读取会为状态后缀预留空间并保留输出尾部；完成通知会先为稳定的 `background job <id>` 前缀与 `job_output` 指令预留空间，再截断可变的 kind、label、status、detail，乃至截断标记本身，因此 PTY 的最小上限仍能标识需要收集的任务。任务控制器在策略有机会拒绝或短路分发之前，于最先执行的 pre-execute 监听器中解析调用方可见的生产方上限；随后通过任务定义最后一道的 `finalizeContent` 回调应用该上限，使规范化的工具错误、外层流水线失败与单文本策略结果都无法绕过该边界；经特意结构化的多块策略结果仍由策略拥有其形状与大小。
+`dsh-tool-jobs` 持有投递台账：等待在开始时认领任务（任务比等待活得更久则撤回），`job_kill` 被接受时也认领，因此模型已经通过工具结果收到的结算不会再注入冗余的完成通知；teardown 结算与无主任务从不播报（[seam 收敛](2026-09-03-jobs-seam-consolidation.zh.md)）。监听器失败会独立记录，不会阻止后续监听器，也不会被等待方或资源销毁过程等待。当视图携带 `outputLimitBytes` 时，`dsh-tool-jobs` 会保持 UTF-8 边界，并复用生产方已有的截断标记，而不会重复添加。读取会为状态后缀预留空间并保留输出尾部；完成通知会先为稳定的 `background job <id>` 前缀与 `job_output` 指令预留空间，再截断可变的 kind、label、status、detail，乃至截断标记本身，因此 PTY 的最小上限仍能标识需要收集的任务。任务控制器在策略有机会拒绝或短路分发之前，于最先执行的 pre-execute 监听器中解析调用方可见的生产方上限；随后通过任务定义最后一道的 `finalizeContent` 回调应用该上限，使规范化的工具错误、外层流水线失败与单文本策略结果都无法绕过该边界；经特意结构化的多块策略结果仍由策略拥有其形状与大小。
 
 ## 生产方显式启用
 
@@ -105,7 +105,7 @@ bash seam 暴露 `resolve`、`run` 和 `start`。`start(spec)` 返回一个 `She
 
 ### 立即抽象任务运行时后端
 
-当前 `JobStart.run()` 约定传入进程内回调与确切的 `Agent` 对象。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表约定 Agent Note](../../archived/architecture/2026-07-26-job-registry-seam.md)后来在不改变这些进程内语义的前提下，将约定与进程内实现分离。
+当前 `JobSpec.run()` 约定返回进程内钩子并经进程内的 `JobHandle` 推送输出，所有者也在进程内解析为存活的 `Agent`。持久化后端会改变身份、重启、所有权与观察语义，因此在引入之时注册表保持为单一具体服务，而非固化错误的边界。[任务注册表约定 Agent Note](../../archived/architecture/2026-07-26-job-registry-seam.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 d12179dde4..6a0f5d94c7 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: 56c9770966647e97763e0eaf339e4589fba673fb
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 04351105a56304020f5696cf1ce82d7a83ed2ced
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: ff00327c388b0468e5e98d488141aa35eb40d104
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 3f7f18a9907b2f43f7cd8467f054f0d0bfcef14a
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 56c9770966..ff00327c38 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,6 +23,8 @@ The exe is packaged with the **`--sea` (enhanced SEA) mode** of [@yao-pkg/pkg](h
 
 `@yao-pkg/pkg` is an exact-pinned root `devDependency` invoked as `pnpm exec pkg`, with [`patches/@yao-pkg__pkg@6.21.0.patch`](../../../../patches/@yao-pkg__pkg@6.21.0.patch) removing the SEA bootstrap's `patchChildProcess` call. Unpatched, pkg rewrites spawned commands named `node` — including the string after a `-c`/`/c` flag, exactly the Bash tool's `bash -c` form — to the executable itself and stamps `PKG_EXECPATH` into every child environment, so a model-issued `node --version` silently boots the dsh CLI; Node's own SEA layer performs no such rewrite, and a SEA binary cannot impersonate plain Node because it always boots its embedded app. With the call removed, children resolve `node` through PATH like any other process (a machine without Node reports command-not-found honestly), no `PKG_EXECPATH` reaches children, absolute `process.execPath` spawns still re-enter the app, worker threads never applied the hook, and `process.pkg` sidecar selection is untouched.
 
+The same patch makes the SEA bootstrap's native-addon extraction atomic. On the first `dlopen` of an addon inside the VFS, pkg's `patchDlopen` copies the addon's package tree to `$PKG_NATIVE_CACHE_PATH/pkg/<sha256 of the .node file>/` (default `~/.cache/pkg/...`), a per-user directory that every concurrent process of the same executable shares; upstream writes each file straight to its final path with `writeFileSync`, which truncates a file another process may already have mapped and lets that process's `existsSync`/hash check read a half-written file. Concurrent first starts therefore die with SIGBUS on Linux or fail with `ERR_DLOPEN_FAILED: Library not loaded` on sharp's libvips on macOS (#4664). The patch routes the three write sites through a same-directory temporary file and `renameSync`, so a cache path is either absent or complete, every process finishes its own copy pass before it loads, and concurrent renames of identical content need no lock. The cache location, hash keying, and per-file comparison are unchanged, so a consumer that isolates the cache per instance through `PKG_NATIVE_CACHE_PATH` keeps working; worker threads only define the hook and never install it. Measured (linux-x64, node24 target, pkg 6.21.0, a probe that loads sharp with its 18 MB libvips library, 16 concurrent first starts against one empty cache, five rounds): 39 of 80 processes died with SIGBUS before the change and 0 of 80 after it, with no temporary files left behind.
+
 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 interface is a plugin inside the dsh application
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 04351105a5..3f7f18a990 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,6 +23,8 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后
 
 `@yao-pkg/pkg` 是精确钉版的根 `devDependency`，经 `pnpm exec pkg` 调用，并以 [`patches/@yao-pkg__pkg@6.21.0.patch`](../../../../patches/@yao-pkg__pkg@6.21.0.patch) 移除 SEA bootstrap 中的 `patchChildProcess` 调用。未打补丁时，pkg 会把 spawn 的 `node` 命令——包括 `-c`/`/c` 标志后的命令串，恰是 Bash 工具的 `bash -c` 形态——改写为 exe 自身，并向每个子进程环境注入 `PKG_EXECPATH`，模型下发的 `node --version` 会静默启动 dsh CLI；Node 自身的 SEA 层没有这种改写，且 SEA 二进制永远启动内嵌应用、无法充当纯 Node。移除该调用后，子进程像普通进程一样经 PATH 解析 `node`（无 Node 的机器如实报 command not found），子进程环境不再出现 `PKG_EXECPATH`，以 `process.execPath` 绝对路径 spawn 的重入不受影响，worker 线程本来就未应用该钩子，`process.pkg` 侧车选择也不受影响。
 
+同一补丁还把 SEA bootstrap 的原生插件解包改成原子写入。VFS 内的插件首次 `dlopen` 时，pkg 的 `patchDlopen` 会把该插件所在的包目录整棵拷到 `$PKG_NATIVE_CACHE_PATH/pkg/<.node 文件的 sha256>/`（默认 `~/.cache/pkg/...`），这是同一个 exe 的所有并发进程共用的按用户目录；上游用 `writeFileSync` 直接写目标路径，会把另一个进程可能已经映射的文件截断，并让该进程的 `existsSync`/哈希比对读到写了一半的文件。因此并发首次启动在 Linux 上以 SIGBUS 崩溃，在 macOS 上对 sharp 的 libvips 报 `ERR_DLOPEN_FAILED: Library not loaded`（#4664）。补丁让三处写入都经过同目录临时文件加 `renameSync`，于是缓存路径要么不存在、要么完整，每个进程都在加载前走完自己的拷贝，相同内容的并发 rename 不需要锁。缓存位置、哈希键与逐文件比对均未改变，通过 `PKG_NATIVE_CACHE_PATH` 按实例隔离缓存的消费方照常工作；worker 线程只定义该钩子而从不安装。 实测（linux-x64、node24 构建目标、pkg 6.21.0，一个加载 sharp 及其 18 MB libvips 库的探针，16 个进程对同一个空缓存并发首次启动，跑五轮）：改动前 80 个进程中 39 个以 SIGBUS 崩溃，改动后 80 个全部正常，且无残留临时文件。
+
 术语提醒：pkg 的 `/snapshot` VFS 与本仓库测试体系的「快照」（ACP（Agent Client Protocol）回放预期输出、`$DSH_SNAPSHOT`）无关，本文用「VFS」指前者。
 
 ### 对外服务接口是 dsh 应用中的插件
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 16ecfcc400..a3dae54b9b 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: 09631349226837d7f93112fe5e9c517f2fee099c
-2026-07-16-explicit-turn-cancellation.zh.md: baf039d49578895d53ffae4c6b88d29b3d1563b6
+2026-07-16-explicit-turn-cancellation.md: d59accf2dc3f894ffab226e5ddc9d2e746f4d93e
+2026-07-16-explicit-turn-cancellation.zh.md: 8fb0728eb2bbe8fa01dbefebe7e02aa8c836617a
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 0963134922..d59accf2dc 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
@@ -12,7 +12,7 @@ The [initiating Agent scope decision](2026-07-15-agent-initiator-scope.md) inten
 
 ## Decision
 
-Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. TypeScript enforces that vocabulary at this typed same-process boundary, with no runtime validator, fallback, or special compatibility contract for untyped callers. An active `TurnCancellation` copies the typed discriminant into a fresh frozen signal reason; idle cancellation has no holder to mutate and does not arm later work.
+Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' } | { kind: 'hook'; reason: string } | { kind: 'disposed' }`, and `agent.cancel()` requires one. TypeScript enforces that vocabulary at this typed same-process boundary, with no runtime validator, fallback, or special compatibility contract for untyped callers. The holder aborts with the caller's own object rather than a detached copy, so a transport reaching that signal can extend it: Node's fetch assigns a `stack` onto the reason it receives. The loop therefore copies the declared fields where the cause becomes durable data. Freezing the cause at `cancel()` is not an alternative — undici performs that assignment from strict-mode code, so a frozen reason makes `fetch` reject with `TypeError: Cannot add property stack` in place of the abort reason. Idle cancellation has no holder to mutate and does not arm later work.
 
 An interrupted live turn ends with the coarse durable `{ kind: 'aborted' }` outcome. The terminal event records what happened to the turn, while the runtime signal identifies who requested cancellation; it does not duplicate `user` or `parent` into replay. Session seed/load rejects legacy aborted records with a reason or any other extra field, so replay cannot reintroduce caller-owned cancellation detail. The process-local `agent/cancel-requested` notification is not durable; a future audit requirement uses a separate durable control-request event so a request and its eventual outcome remain distinct. Durable events contain no stack, signal, error object, free-form cancellation text, or backend-private detail.
 
@@ -22,7 +22,7 @@ The driver keeps only a cause-less pre-run marker for queued work cancelled befo
 
 The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining APIs keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's provider-managed termination and join boundary; the [native-containment decision](2026-08-28-subprocess-native-containment.md) owns the supported local scope, Job, and fallback mechanics. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
 
-`ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a canonical frozen cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam.
+`ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a typed cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam.
 
 Agent disposal requests the runtime-only `{ kind: 'disposed' }` interruption on the active holder. If cancellation already won the controller reason, the reason cannot be rewritten, so terminal classification first checks lifecycle state: disposed wins, then a supported `user` or `parent` cause becomes the coarse aborted outcome, and unrelated exceptions retain the existing error path. ACP cancellation maps to `user`; in-process spawn and fork propagation map to `parent`. Remote ACP subagents retain their existing wire protocol.
 
@@ -30,7 +30,7 @@ Cancellation remains cooperative. The loop checks interruption before and after
 
 ## Verification
 
-Contract tests verify the typed caller union, frozen detachment, default and first-wins behavior, the coarse Session JSON round trip and legacy-record rejection, ACP `user`, in-process subagent `parent`, and disposal precedence. Loop tests make cooperative listeners wait on the signal at pre-step, system-prompt assembly, request, model stream, request-error recovery, tool execution, and turn stopping; they assert one signal within a turn, a fresh signal across turns, and no cancellation authority during terminal publication or a blocked durability flush. A real hook bridge test cancels and reaps a blocked prompt hook before idle.
+Contract tests verify the typed caller union, field copying where the cause becomes durable data, default and first-wins behavior, the coarse Session JSON round trip and legacy-record rejection, ACP `user`, in-process subagent `parent`, and disposal precedence. Loop tests make cooperative listeners wait on the signal at pre-step, system-prompt assembly, request, model stream, request-error recovery, tool execution, and turn stopping; they assert one signal within a turn, a fresh signal across turns, and no cancellation authority during terminal publication or a blocked durability flush. A real hook bridge test cancels and reaps a blocked prompt hook before idle.
 
 Initiator-scope tests assert that every hook still observes the exact Agent and no ambient turn signal, concurrent Agents retain independent identities and signals, and a nested child driver shadows only identity. Race tests cover idle cancellation, pre-run cancellation, replacement submission from a `running` listener, repeated cancellation, and cancel-versus-dispose quiescence.
 
diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
index baf039d495..8fb0728eb2 100644
--- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`；`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程边界中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因；空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
+Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' } | { kind: 'hook'; reason: string } | { kind: 'disposed' }`，`agent.cancel()` 必须显式传入其一。TypeScript 在这个类型化的同进程边界中强制执行该词汇，不提供运行时校验器、后备行为，也不为无类型调用方提供特殊兼容性约定。持有者中止时携带的是调用方自己的那个对象，而非一份分离的拷贝，因此能接触到该 signal 的传输层可以向其添加属性：Node 的 fetch 会给它收到的 reason 赋一个 `stack`。所以循环在 cause 成为持久数据的那一步拷贝已声明字段。在 `cancel()` 处冻结 cause 并非可选方案——undici 是在严格模式代码中执行该赋值的，被冻结的 reason 会让 `fetch` 以 `TypeError: Cannot add property stack` 取代中止原因而拒绝。空闲状态下没有可修改的持有者，也不会让后续工作预先进入取消状态。
 
 正在运行的轮次被中断后，以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么，运行时 signal 标识谁请求了取消；回放不会重复保存 `user` 或 `parent`。会话 seed/load 会拒绝携带取消原因或任何其他额外字段的旧式中止记录，因此回放无法重新引入由调用方持有的取消细节。仅限进程内的 `agent/cancel-requested` 通知不会持久化；未来若有审计需求，应使用独立的持久化控制请求事件，让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。
 
@@ -22,7 +22,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它
 
 显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 API 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)）。进入 pre-step 时、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器由提供方管理的终止与等待边界；[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责受支持本地路径上的 scope、Job 与 fallback 机制。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
-`ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
+`ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带类型化的 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
 
 Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时的 `{ kind: 'disposed' }` 中断。若取消已经先占用控制器的中断原因，该原因便无法改写，因此终态分类会先检查生命周期状态：资源释放结果优先，之后受支持的 `user` 或 `parent` 取消原因形成粗粒度的中止结果，其他异常保留现有错误路径。ACP（Agent Client Protocol）取消映射为 `user`；进程内 spawn 和 fork 的传播映射为 `parent`。远程 ACP subagent 保持现有协议。
 
@@ -30,7 +30,7 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 ## 验证
 
-约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
+约定测试验证类型化调用方联合类型、在 cause 成为持久数据处拷贝字段、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal；并断言同一轮次使用一个 signal，不同轮次使用全新的 signal，终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。
 
 发起方作用域测试断言所有钩子仍观察到同一个 Agent 且没有环境中的轮次 signal，并发 Agent 保持独立的身份与 signal，嵌套子驱动只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的完全停稳。
 
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 e891710dea..da98873480 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: 990a9b6eef862a7ac4a549358beae7f9081eaa0b
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 5c90611fab36611766bb407138c4f0c8a6b3a01b
+2026-07-25-web-client-session-scope-and-provide-channel.md: 76561bc0e330b3e3a26607569ae327217d0a0b67
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: d5d92b2ca53ba78929dd8591a6ded7028e4fed24
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 990a9b6eef..76561bc0e3 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
@@ -26,9 +26,9 @@ The reference-owned lifetime and Provider targeting now follow [Client Session r
 Host-side `session.create(workspaceId)` produces Session + Agent + cwd in one piece (an atomic bundle, never split); the client side is the mirror of that birth — the instant a session row enters the list mirror, the client mints its Agent scope (actx + provide + the full input surface mounted):
 
 - Session identity is the host's true form from birth: the sessionId arrives via the `session.create` response / the `host/session-added` frame, and every client-side address (the scope tag, slot store keys, RPC addressing) uses that same id.
-- The materialization moment = the instant the user picks a Workspace (cwd settled): the client calls `session.create({workspaceId})` on the spot and receives the complete entity.
+- A manual Workspace pick or successful [first-use startup initialization](../feature/2026-09-20-default-workspace.md) establishes cwd before the client calls `session.create({workspaceId})` and receives the complete entity.
 - "New Session with no workspace picked" is a **pure view state** (a navigation position) corresponding to no session/scope entity; until the pick, the composer is locked whole (no slash, no plain text).
-- A "blank session" is just an ordinary materialized session whose log is still empty; to every Agent-scope plugin on the host (goal/plan/skill/…) it is indistinguishable from any session, so slash/plan are all naturally live.
+- A "blank session" is an ordinary materialized session with no turn yet; to Agent-scope plugins on the host (goal/plan/skill/…) it remains an ordinary Session, so slash/plan are naturally live.
 
 ### Agent scope: the actx is the sole session carrier in the client-side cordis world
 
@@ -63,14 +63,14 @@ Session instances share the scope's lifecycle, while the catalog reports discove
 
 A session "materialized but with no first prompt" is governed by the summary-derived bit `blank` (a derived column, not a header field; SessionHeader stays immutable):
 
-- The Host criterion is absence of `turn/start`; slash-command and configuration events do not clear `blank`. Live summaries use the Session projection. Cold summaries use cached metadata, leaving cache misses visible as unknown. Reuse acquires the writer under [blank Session acquisition](2026-09-17-process-local-blank-sessions.md).
+- The Host criterion is absence of `turn/start`: the `sessionListMetadata.blank` projection starts true and only that event clears it, so slash-command, configuration, and creation-checkpoint events leave it true even after they reach disk — blank does not mean unpersisted. Missing metadata falls back to `session.seq === 0` for live Sessions and false for cold ones; cold summaries otherwise read cached metadata, leaving cache misses visible as unknown. Reuse acquires the writer under [blank Session acquisition](2026-09-17-process-local-blank-sessions.md).
 - The wire carries it in two places: the required `SessionSummary.blank` column, and the required `blank` field on the `host/session-added` frame (always true at creation, letting other tabs enter the same blank-session state into their mirrors).
-- The client mirror only lowers, never raises (monotonic), flipped from three sources, all reusing existing wire signals:
-  - The sender's own tab: the **successful response** to the first `prompt()` flips false (acceptance proves the user/message is already in the host log — this flip is confirmation, not optimism; `onEngaged` synchronously updates the list mirror, converting the current `New Session` row in place to an ordinary title, adding no list row). A rejected first prompt keeps the session blank: aligned with host authority, still shown as `New Session`, keeping its connectWorkspace reuse eligibility while it remains a Workspace member.
-  - Other tabs: the `host/session-status (running:true)` frame flips it — a blank session never runs, so the first running necessarily means no longer blank;
-  - Reconnect alignment: `session.list`'s summary.blank is authoritative, so a tab that missed frames aligns naturally on its next pull; a stale blank:true can never mark a converted session back to blank.
+- Client display also reflects accepted/running observations, whose retention the [blank rollback decision](../bug-fix/2026-09-15-client-session-blank-reconciliation.md) owns:
+  - The sender's own tab: the **successful response** to the first `prompt()` converts the current `New Session` row in place, adding no list row — acceptance is display memory, not proof that a turn or user message reached durable history. A rejected first prompt keeps the session blank: aligned with host authority, still shown as `New Session`, keeping its connectWorkspace reuse eligibility while it remains a Workspace member.
+  - Other tabs: the `host/session-status (running:true)` frame converts it — a blank session never runs, so the first running necessarily means no longer blank;
+  - Reconnect alignment: a list pull updates Host summaries while the Manager keeps those observations, and a `sessionListMetadata` hint of existing history prevents re-blanking on top of that; an empty-history response cannot mark a converted session back to blank.
 - List discipline: the store retains every row; the Workspace browser's grouping, flat view, search, and counts share one visible projection — every non-blank session shows, while blank sessions show only the row retained by the `mainView` source, with its title forced to `New Session`. After a Workspace switch, the old blank entity stays in the mirror but is hidden from the list while the target Workspace's main blank shows; the user-visible surface therefore holds at most one blank row globally.
-- Blank Sessions can persist through creation checkpoints and command events. Browser reloads and Host restarts reuse eligible blanks after acquiring their writer; occupied blanks are skipped. Old logs remain on disk without automatic cleanup.
+- Blank Sessions can persist through creation checkpoints and command events, and have no automatic garbage collection: browser reloads, Host restarts, and Workspace connections reuse eligible blanks after acquiring their writer and skip occupied candidates, while list-loading and multi-tab races can still create additional blank Sessions, whose old logs remain on disk.
 
 ### connectWorkspace: the sole entry point of New Session
 
@@ -129,12 +129,13 @@ Blank Sessions retain the header's leading and corner slots so navigation contro
 | 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 |
+| A dedicated conversion frame | Existing acceptance and running signals provide the observations used by the display rule; a new frame is unnecessary for that rule |
 
 ## Consequences
 
 - Plugins gain session context isomorphic to the host's: per-session state hangs on the actx and mounts/tears down in one piece with the scope fiber, making leaks structurally impossible; two-session isolation is structurally guaranteed by the scope filter.
 - The client object layer converges to a wire mirror: session identity, lifecycle, and capability adjudication all defer to the host entity — the input system (the next layer) always faces a session with a real Agent, and providers like slash/skill uniformly address by sessionId directly.
-- Blank-session governance takes zero dedicated mechanisms: state rides one derived bit, visibility rides the unified list projection (only the current blank shows, as `New Session`), reuse acquires the persisted writer, and the ordinary ceiling rides same-Workspace reuse.
+- Blank-session governance takes zero dedicated mechanisms: state rides one derived bit, visibility rides the unified list projection (only the current blank shows, as `New Session`), reuse acquires the persisted writer, and the ordinary ceiling rides same-Workspace reuse. The accepted/running display memory that guards the conversion is Client-local.
+
 - The cost: the id→ctx handoff discipline and provide's Concurrent discipline are conventions rather than type-enforced, pinned by review and tests. The single state axis still withholds machine faces until a Session exists; the [resident conversation shell](../../../../packages/client/ui-conversation/README.md) routes activation to the Workspace picker during that interval.
 - Known gaps: approval/question recovery across prune (TODO); model selection returns in live-mutation shape (the host `selectModel` trio is ready-made, its client consumer not yet built).
diff --git a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
index 5c90611fab..d5d92b2ca5 100644
--- a/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md
@@ -26,9 +26,9 @@ web client 只有一张全局会话面：slot 全部从根上下文渲染，插
 host 侧 `session.create(workspaceId)` 一体产出 Session + Agent + cwd（作为不可拆分的原子整体）；client 侧就是这次出生的镜像——会话行进入 list mirror 的瞬间，client 为它铸 Agent scope（actx + provide + 输入面全套挂上）：
 
 - 会话身份自出生即为 host 真身：sessionId 由 `session.create` 响应 / `host/session-added` 帧带来，client 侧一切寻址（scope tag、slot store 键、RPC 地址）用的都是同一个 id。
-- 实体化时点 = 用户选定 Workspace（cwd 确定）的瞬间：client 当场调 `session.create({workspaceId})`，拿到完整实体。
+- 手动选定 Workspace 或完成[首次使用的启动初始化](../feature/2026-09-20-default-workspace.zh.md) 后，cwd 已确定，client 再调 `session.create({workspaceId})`，拿到完整实体。
 - 「New Session 且未选 workspace」是**纯视图态**（一个导航位置），不对应任何会话/scope 实体；选定之前 composer 整体锁死（无 slash、无纯文本）。
-- 「空会话」就是一个日志还空着的普通实体化会话；对 host 上所有 Agent-scope 插件（goal/plan/skill（技能）/…）它与任何会话无异，slash/plan 天然全活。
+- 「空会话」是尚无轮次的普通实体化会话；对 host 上的 Agent-scope 插件（goal/plan/skill（技能）/…）而言，它仍是普通 Session，因此 slash/plan 自然可用。
 
 ### Agent scope：actx 是 client 侧 cordis 世界的唯一会话载体
 
@@ -63,14 +63,14 @@ Session 实例与 scope 同生命周期；catalog 只报告可发现性，不持
 
 「实体化但无首条提示词」的会话经 summary 派生位 `blank` 治理（派生列而非 header 字段，SessionHeader 保持不可变）：
 
-- Host 判据是没有 `turn/start`；slash 命令与配置事件不会清除 `blank`。Live summary 使用 Session 投影。Cold summary 使用缓存元数据，缓存缺失时以未知状态保留在列表中。复用按[空白 Session 获取](2026-09-17-process-local-blank-sessions.zh.md)规则取得写锁。
+- Host 判据是没有 `turn/start`：`sessionListMetadata.blank` 投影初始为 true，且只有该事件会清除它，因此 slash 命令、配置事件与创建检查点即使已落盘也不会清除——blank 不代表未持久化。metadata 缺失时，live Session 回退到 `session.seq === 0`，cold Session 回退到 false；cold summary 其余情况读缓存元数据，缓存缺失时以未知状态保留在列表中。复用按[空白 Session 获取](2026-09-17-process-local-blank-sessions.zh.md)规则取得写锁。
 - wire 承载两处：`SessionSummary.blank` 必填列；`host/session-added` 帧必填 `blank` 字段（创建时恒 true，供别的 tab 按同一空会话状态入镜像）。
-- client 镜像只降不升（单调），三来源翻转，全部复用既有 wire 信号：
-  - 发送方本地：首次 `prompt()` 的**成功响应**翻 false（受理即证明用户消息已入 host 日志——此点翻转是确证而非乐观；`onEngaged` 同步更新列表镜像，当前 `New Session` 行原地转为普通标题，不新增列表行）。首条提示词被拒则会话保持 blank：与 host 权威对齐、继续显示为 `New Session`、在仍为该工作区成员时保持 connectWorkspace 复用资格。
-  - 其他端：`host/session-status (running:true)` 帧翻转——blank 会话从不 running，首次 running 必然已非 blank；
-  - 重连对齐：`session.list` 的 summary.blank 是权威，错过帧的端下次拉取自然对齐；陈旧的 blank:true 不能把已转正的会话重新标回 blank。
+- 客户端展示还受已观察到的受理/运行影响，其保留期限由 [blank 回退修复决策](../bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md) 拥有：
+  - 发送方本地：首次 `prompt()` 的**成功响应**把当前 `New Session` 行原地转正，不新增列表行——受理是展示记忆，不证明轮次或用户消息已写入持久历史。首条提示词被拒则会话保持 blank：与 host 权威对齐、继续显示为 `New Session`、在仍为该工作区成员时保持 connectWorkspace 复用资格。
+  - 其他端：`host/session-status (running:true)` 帧转正——blank 会话从不 running，首次 running 必然已非 blank；
+  - 重连对齐：列表拉取更新 Host 摘要，Manager 则保留这些观察；在此基础上，`sessionListMetadata` 提示已有历史也会阻止回退 blank，因此空历史响应不能把已转正的会话标回 blank。
 - 列表纪律：store 保留全部行；Workspace browser 的分组、平铺、搜索和计数共用同一可见投影——所有非 blank 会话都显示，blank 会话只显示由 `mainView` 来源持有的一行，并强制标题为 `New Session`。切换 Workspace 后，旧 blank 实体仍在镜像中但从列表隐藏，目标 Workspace 的主 blank 显示；因此用户可见面全局至多一条 blank 行。
-- 空白 Session 可以通过创建检查点与命令事件持久化。浏览器刷新与 Host 重启会在取得写锁后复用符合条件的空白会话，并跳过被占用的候选。旧日志保留在磁盘上，不自动清理。
+- blank Session 可以通过创建检查点与命令事件持久化，且没有自动垃圾回收：浏览器刷新、Host 重启与工作区连接会在取得写锁后复用符合条件的空白会话并跳过被占用的候选；但列表加载与多 tab 竞态仍可能创建额外的 blank Session，其旧日志保留在磁盘上。
 
 ### connectWorkspace：New Session 的唯一入口
 
@@ -129,12 +129,13 @@ blank Session 保留 header 的 leading 与 corner slot，让右侧栏展开入
 | 组件收 wiring 回调包（inject→props 两层下传） | 标准件通道让组件自取；公共 API 收敛为 hooks + 稳定 props |
 | Hero 无会话视图与会话 Conversation 整支互换 | 即使外层 layout 不变，Hero、picker 与 composer 子树仍会一起重建，界面产生整块抖动 |
 | 让 InputBar 自身变成 `session-maybe` | 输入状态机、键盘命令面与动作都被迫接受缺省值；只替换 disabled 输入体能把可选性留在外壳边界 |
-| 专用「转正」帧 | `session-status(running:true)` 语义蕴含转正（blank 会话从不 running），加帧是 wire 多一型换零信息 |
+| 专用「转正」帧 | 既有受理和运行信号已经提供展示规则所需的观察；该规则不需要新增帧 |
 
 ## 后果
 
 - 插件获得与 host 同构的会话上下文：逐会话状态挂 actx、随 scope fiber 一次拆装，泄漏结构性不可能；双会话隔离由 scope filter 结构性保证。
 - client 对象层收敛为 wire 镜像：会话身份、生命周期、能力判别全部以 host 实体为准——输入体系（下一层）面对的永远是「有真 Agent 的会话」，slash/skill 等提供方一律以 sessionId 直接寻址。
-- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），复用时获取持久化写锁，常规上限靠同 Workspace 复用。
+- 空会话治理零专用机制：状态靠一个派生位，可见性靠统一列表投影（仅 current blank 以 `New Session` 展示），复用时获取持久化写锁，常规上限靠同 Workspace 复用。转正所依赖的受理/运行展示记忆仅保留在客户端。
+
 - 代价：id→ctx 换乘纪律、provide 的 Concurrent 纪律都是约定而非类型强制，靠 review 与测试钉住。单一状态轴仍会在 Session 存在前隐藏 machine face；这段时间内，[常驻会话壳](../../../../packages/client/ui-conversation/README.zh.md)会把激活操作转到 Workspace picker。
 - 已知欠账：approval/question 跨 prune 恢复（TODO）；模型选择以 live-mutation 形状回归（host `selectModel` 三件套现成，其 client 消费方尚未构建）。
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
index 190fecf123..279482f67a 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
-2026-08-02-typert-remote-method-calls.md: b599b3f9a353738bbb44a4da9b5a72be8309e2fb
-2026-08-02-typert-remote-method-calls.zh.md: 64dc84f0ae07b10d50452ef7e36c30db102953cf
+2026-08-02-typert-remote-method-calls.md: 2a12aaf78f638d8af786d2ca817a3fee07a2c614
+2026-08-02-typert-remote-method-calls.zh.md: bf4a7b0179b4dc878a0a53c7076c02e6f1bf0273
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
index b599b3f9a3..2a12aaf78f 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md
@@ -31,8 +31,8 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T
 | `@deepseek-ai/dsh-typert-protocol` | Declares only the minimal `ctx.typert` protocol | `TypertRemoteService`, decorators, binding fallback, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser |
 | Typert registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers |
 | Typert generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` |
-| API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, and invokes methods |
-| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, Typert interception, and owner-registered exact Fetch routes on the same channel |
+| API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and projects unary results into carrier-neutral fields and attachments |
+| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, physical serialization, trust, error transport, Typert interception, and owner-registered exact Fetch routes on the same channel |
 | API Gateway's Client face | `ctx.remote`, `ctx.remote.<namespace>` | Mounts Remote contributions, materializes each namespace as a traced `remote.<namespace>` child Service, and delegates canonical calls to `ctx.connection.rpc` |
 | API Remotes | No new service | Owns Host Agent/Session lookup policy and serves as the only Client business facade, selecting and mounting `/remote` contributions while exposing the selected API declarations |
 | Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers |
@@ -181,7 +181,7 @@ Consequently, `SessionId`, the Agent wire ID, the request, and the result all re
 
 Remote methods themselves use declaration-map navigation. Typert anchors `InvocationModel.location` to the decorated Host method-name token and emits a source-map segment on the corresponding property of the namespace interface. For an adapter-backed endpoint, after the TypeScript editor resolves `ctx.remote.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition.
 
-Typert generates a wire Zod codec for the same symbol key. The Host Gateway uses parameter and identity codecs to validate input. Client Remote trusts its generated TypeScript arguments and successful Host results instead of executing invocation codecs. If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON.
+Typert generates a wire Zod codec for the same symbol key. The Host Gateway uses parameter and identity codecs to validate input. Client Remote trusts its generated TypeScript arguments and JSON success results. Binary success results use their generated codec after multipart decoding, as specified by [binary Remote transfer](2026-09-17-workspace-file-binary-transfer.md). If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON.
 
 Named business types referenced by Remote methods must be exported from public, type-only subpaths. If the only reachable entry also imports Host Services, Cordis `Context` merges, or Host-only implementations, the build fails and requires the business package to provide a safe type entry. Primitives, literals, and simple compositions explicitly supported by Typert need no additional names.
 
@@ -514,7 +514,7 @@ Canonical public types require business DTOs to have type-only entries, which ma
 
 Type imports and runtime contributions have different effects. `import type {}` extends only the static Remote surface. If a real calling environment omits the value contribution, the Client Remote Service must fail with an explicit "Remote not mounted" error.
 
-Generated Host and Client artifacts carry matching Zod factories, but Client Remote does not materialize invocation schemas. Canonical symbol keys, the same generated model, and Host wire validation keep the two sides aligned without comparing schema object identities across realms.
+Generated Host and Client artifacts carry matching Zod factories; Client Remote materializes only binary result schemas. Canonical symbol keys, the same generated model, and Host wire validation keep the two sides aligned without comparing schema object identities across realms.
 
 A consumer may import a Remote contract that is not currently mounted on the Host. The types mean "this protocol capability was selected by the consumer," not that a corresponding Service currently exists in the target process; an unavailable endpoint must fail explicitly at runtime.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
index 64dc84f0ae..bf4a7b0179 100644
--- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md
@@ -31,8 +31,8 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只
 | `@deepseek-ai/dsh-typert-protocol` | 只声明 `ctx.typert` 的最小协议 | `TypertRemoteService`、decorator、binding 回退、descriptor、lookup/Context 和 Remote map；不依赖 compiler、Zod、Connection 或 Browser |
 | Typert registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider |
 | Typert generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物，并把当前环境产物注册到 `ctx.typert` |
-| API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver 并调用方法 |
-| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、Typert 拦截，以及各 owner 在同一 channel 上注册的精确 Fetch route |
+| API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service，解码参数、解析 receiver、调用方法，并将一元结果投影为载体无关的字段与附件 |
+| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、物理序列化、trust、错误传输、Typert 拦截，以及各 owner 在同一 channel 上注册的精确 Fetch route |
 | API Gateway 的 Client face | `ctx.remote`、`ctx.remote.<namespace>` | mount Remote contribution，把每个 namespace 实体化为可追踪的 `remote.<namespace>` 子 Service，并把规范调用交给 `ctx.connection.rpc` |
 | API Remotes | 无新增服务 | 负责 Host Agent/Session lookup 策略，并作为 Client 业务的唯一 facade，选择并挂载 `/remote` contribution，同时暴露所选 API 声明 |
 | Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider |
@@ -181,7 +181,7 @@ import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/
 
 Remote 方法本身使用 declaration map 导航。Typert 把 `InvocationModel.location` 固定在 Host 被装饰方法的方法名 token，并在 namespace interface 的对应属性上写入 source-map segment。对于由适配器支撑的 endpoint，TypeScript editor 从 `ctx.remote.models.list` 取得生成 declaration 后，再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`，map 不把 decorator、class 或整个签名误当成方法定义位置。
 
-Typert 为同一 symbol key 生成 wire Zod codec。Host Gateway 用参数与 identity codec 校验输入；Client Remote 信任生成的 TypeScript 参数与成功的 Host 结果，不执行调用 codec。复杂类型无法生成严格 codec 时，LIB 构建失败，不降级为 `unknown` 或无校验 JSON。
+Typert 为同一 symbol key 生成 wire Zod codec。Host Gateway 用参数与身份 codec 校验输入。Client Remote 信任生成的 TypeScript 参数与 JSON 成功结果。二进制成功结果在 multipart 解码后执行生成的结果 codec，具体由[二进制 Remote 传输](2026-09-17-workspace-file-binary-transfer.zh.md)规定。复杂类型若无法生成严格 codec，LIB 构建失败，不降级为 `unknown` 或未校验 JSON。
 
 Remote 方法引用的命名业务类型必须从纯类型公共 subpath 导出。如果唯一可达入口会带入 Host Service、Cordis `Context` merge 或 Host-only 实现，构建失败并要求业务包提供安全的类型出口。原始值、字面量和 Typert 明确支持的简单组合不需要额外命名。
 
@@ -514,7 +514,7 @@ SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化
 
 类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface；真实调用环境遗漏 value contribution 时，Client Remote Service 必须以明确的「Remote 未挂载」错误失败。
 
-生成的 Host 与 Client 产物携带匹配的 Zod factory，但 Client Remote 不实例化调用 schema。规范 symbol key、同一生成模型和 Host wire 校验让两侧保持一致，而无需跨 realm 比较 schema 对象 identity。
+生成的 Host 与 Client 产物携带匹配的 Zod factory；Client Remote 仅实例化二进制结果 schema。规范 symbol key、同一生成模型和 Host wire 校验让两侧保持一致，而无需跨 realm 比较 schema 对象 identity。
 
 消费端可以导入 Host 当前未挂载的 Remote contract。类型表示「该协议能力已被消费端选择」，不保证目标进程当前存在对应 Service；运行时 endpoint 不可用必须明确失败。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml
index 0e4340ea02..7606190f02 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal 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-remote-event-delivery.md
-2026-08-10-remote-event-delivery.md: 1706cc525bd7707874353a6658ec2f52597044a9
-2026-08-10-remote-event-delivery.zh.md: ac79642e90791892870c8920e02867faea180b07
+2026-08-10-remote-event-delivery.md: 3eaa26fb92c40b3a20cab11d4522bcf68b8a207f
+2026-08-10-remote-event-delivery.zh.md: d41589f1b800da98342210d2e429a2b67b6c61f2
diff --git a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md
index 1706cc525b..3eaa26fb92 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md
@@ -195,3 +195,7 @@ The few required Client symbols are mirrored on the test side: `scaffold.ts` exp
 - **Capabilities deliberately omitted.** Payload projection and redaction are unsupported, scopes other than Agent are unsupported, and ordinary notifications are not replayed. Recoverable state needs a query, cursor, or opening baseline; a waterfall is replayed only while its original Host invocation remains pending.
 - **Some Client packages remain in the Host graph.** Twelve projects, including `connection`, `runtime`, and `ui-slots`, remain reachable through unsplit `directory-picker-browse`/`-native` and `api/gateway → client/connection`. They compile and no longer pull in API Remotes' Client face, so this change does not split them. Direct `dsh-client-runtime/client` imports in two chat e2e files rely on Runtime's current presence in that graph rather than a general guarantee.
 - **The package intentionally publishes no invariant companion.** A prior revision asserted delivery form on the live event bus, coupling diagnostics to the allowlist and causing Rolldown to emit a third bundle chunk omitted by the mechanically derived publication list. The Host-face `TypertForwardableEventEntry` assertion already rejects those mismatches at compile time, and the package README records why no independent runtime relation remains.
+
+## Related
+
+- [Remote duplex stream](2026-09-19-remote-duplex-stream.md): every Remote stream carries a Client uplink on the same logical stream; the duplex `$events` listed under its Deferred section replaces the unary `$events/result` path once it lands.
diff --git a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md
index ac79642e90..d41589f1b8 100644
--- a/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.zh.md
@@ -197,3 +197,7 @@ Client 要求首项是带非空 `clientId` 与 `host.home` 的 `ready`；后续
 - **放弃的能力**：不支持投影或脱敏载荷，不支持 Agent 以外的 Scope，也不为普通通知提供重放。需要可靠恢复的状态必须拥有查询、cursor 或 opening baseline；waterfall 只重放仍处于同一次 Host 调用生命周期内的 pending request。
 - **仍有 client 包留在 host 图里**：12 个工程（`connection`、`runtime`、`ui-slots` 等）经未拆分的 `directory-picker-browse`/`-native` 与 `api/gateway → client/connection` 仍可达 host 图。它们都能编译且不再牵连 api/remotes 的 client face，因此没有阻塞本次改动；拆分那些包能减少几个，但经评估后不做。两个 chat e2e 直接引 `dsh-client-runtime/client` 依赖 `runtime` 本来就在图里——属偶然而非保证。
 - **本包不发布 invariant companion**：早先的修订曾在活事件总线上断言投递形状（`thisArg === null`、`mode === 'emit'`），这让诊断逻辑与名单值耦合，并使 rolldown 把它提成第三个 bundle chunk——而机械推导的发布文件清单并不携带它。Host 面的 `TypertForwardableEventEntry` 断言已在编译期拒绝这些偏离，包 README 也记录了不再存在独立运行时关系的原因。
+
+## 相关
+
+- [Remote 双工流](2026-09-19-remote-duplex-stream.zh.md)：所有 Remote 流在同一逻辑流上承载客户端上行；其「后续」列出的双工 `$events` 落地后取代 unary `$events/result` 路径。
diff --git a/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.i18n.yaml
index 6fa3c9e31b..6a9b597434 100644
--- a/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md
-2026-08-25-electron-desktop-packaging-and-updates.md: f58e8dc471faeb717dd79d32df4afc1b5cc3458f
-2026-08-25-electron-desktop-packaging-and-updates.zh.md: 2d2d5c68f28974b606693d5b6727c864c92a0763
+2026-08-25-electron-desktop-packaging-and-updates.md: a985e1c91a1ccdb9c4aab0bc519974f9b6fafd4a
+2026-08-25-electron-desktop-packaging-and-updates.zh.md: 17ace865477d4fae3650b56d6725be07c7bd0e0f
diff --git a/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md b/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md
index f58e8dc471..a985e1c91a 100644
--- a/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md
+++ b/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md
@@ -75,6 +75,8 @@ The [immediate-window decision](2026-09-09-desktop-immediate-window-and-direct-s
 
 `DSH_DESKTOP_AUTO_UPDATE_ENV` selects the test deployment by default or the production deployment for both the target-specific generic-provider URL and COS destination. Release automation supplies the test HTTPS origin through `DOWNLOAD_TEST_ORIGIN` and each deployment's bucket through `DOWNLOAD_TEST_COS_BUCKET` or `DOWNLOAD_PROD_COS_BUCKET`; keeping mutable test routing and COS storage identities out of source lets deployment infrastructure change without a code release, while the public production origin remains fixed. Packaging resolves only the public updater URL, disables electron-builder publishing, removes every COS credential field from its subprocess environment, and writes a completion record only after electron-builder and every signing or notarization hook succeeds. Target upload additionally requires the selected bucket, then requires the completion record, root dsh version, Desktop version, version-derived channel metadata, artifact names, sizes, and SHA-512 values to agree before it reads the selected credentials or sends data. It uploads immutable versioned updater payloads and any separate blockmaps before replacing the channel metadata emitted by electron-builder, and it never deletes historical objects. Stable versions use the `latest` metadata name; prereleases use the first semantic-version prerelease identifier. NSIS embeds its blockmap in the signed executable; the macOS ZIP carries a separate blockmap. Both let electron-updater download changed blocks when supported, while application replacement and the local pnpm package operation remain separate operations.
 
+Test releases require `DOWNLOAD_TEST_RELEASE_ID` from the platform dotenv file. Their feeds and binaries share `dsh-desk/<release-id>/`; production retains its fixed directories. The ID is part of the packaged update URL, so upload rejects a different ID. Internal distribution can supply a new installer after rotation; installed clients retain their existing feed. Random directories reduce guessing but provide no authorization for link holders. The [release configuration](../../../../apps/desktop/README.md#upload-updates) defines generation and reuse.
+
 ## Security and release policy
 
 Core dsh and the private Desktop Host come only from the signed application resource tree. Plugin installation forwards package specs to pnpm, including local and remote sources, but never accepts raw pnpm commands. pnpm owns dependency resolution and the profile’s `allowBuilds` policy; the Host loads activated bundles.
diff --git a/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md b/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md
index 2d2d5c68f2..17ace86547 100644
--- a/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md
@@ -75,6 +75,8 @@ Electron 更新只使用一个 `electron-updater` 发布流和签名 `electron-b
 
 `DSH_DESKTOP_AUTO_UPDATE_ENV` 默认为测试部署，也可以选择生产部署，并同时决定目标专用的 generic-provider URL 与 COS 目标。发布自动化通过 `DOWNLOAD_TEST_ORIGIN` 提供测试 HTTPS origin，并通过 `DOWNLOAD_TEST_COS_BUCKET` 或 `DOWNLOAD_PROD_COS_BUCKET` 提供各部署的 bucket；可变的测试路由与 COS 存储身份不写入源码，部署基础设施变更时无需发布新代码，而公开的生产 origin 仍固定。打包只解析公开更新 URL、禁止 electron-builder 发布、从子进程环境中删除每个 COS 凭据字段，并且只有在 electron-builder 以及每个签名或公证 hook 成功后才写入完成记录。目标上传还必须提供所选 bucket，随后会先要求完成记录、根 dsh 版本、Desktop 版本、根据版本得出的频道元数据、产物名称、大小与 SHA-512 全部一致，再读取所选凭据或发送数据。它先上传不可变且带版本的更新载荷与所有独立 blockmap，最后替换 electron-builder 生成的频道元数据，并且不会删除历史对象。稳定版本使用 `latest` 元数据名称，预发布版本则使用语义化版本的第一个预发布标识符。NSIS 把 blockmap 嵌入已签名的可执行文件，macOS ZIP 则使用独立 blockmap；两者都让 electron-updater 在平台支持时只下载变化的数据块，而应用替换与本地 pnpm 包操作仍是两个独立操作。
 
+测试发布必须从平台 dotenv 文件提供 `DOWNLOAD_TEST_RELEASE_ID`。清单和安装包共用 `dsh-desk/<release-id>/`，生产环境保留固定目录。ID 是打包更新 URL 的一部分，因此上传会拒绝不同的 ID。轮换后可通过内部分发提供新安装包，已安装客户端保留原清单地址。随机目录降低被猜中的概率，但不对持有链接者进行鉴权。[发布配置](../../../../apps/desktop/README.zh.md#upload-updates)定义生成与复用方式。
+
 ## 安全与发布策略
 
 核心 dsh 和私有 Desktop Host 只来自签名应用的资源树。插件安装把包规格交给 pnpm，包括本地和远程来源，但不接受原始 pnpm 命令。pnpm 负责依赖解析和 profile 的 `allowBuilds` 策略；Host 加载已启用的 bundle。
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
index ad8ffb6167..04fa599e6f 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal 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-31-released-session-format-migrations.md
-2026-08-31-released-session-format-migrations.md: 273b51ac7ce9c507c2322499788dc2084b857415
-2026-08-31-released-session-format-migrations.zh.md: 69132ec1763ad12b51480e150c3968aa1dcacf61
+2026-08-31-released-session-format-migrations.md: e21793e0ea3d0c5376cbb3949c5d6ef599b9afb1
+2026-08-31-released-session-format-migrations.zh.md: 637d8fcf0206661df9a6f1b3b470ad8a55746720
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
index 273b51ac7c..e21793e0ea 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md
@@ -131,7 +131,7 @@ Existing write handles retain the process-local claim and kernel-backed cross-pr
 
 ### Parent catalog prerequisites
 
-V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; absent entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs without backfilling that child, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. An unsupported generation or unreadable header elsewhere in that scan refuses migration because it cannot prove unrelatedness. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The storage decoder classifies physical JSON and compression failures before the collector adds child context; filesystem reads and cancellation keep their original errors. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
+Runtime child-failure handling in this paragraph is partially superseded by [session-local catalog preparation](../bug-fix/2026-09-19-session-local-subagent-migration.md): opening the parent still completes its catalog from direct-child reads, but unreadable children do not block healthy parent history. V3→V4 completes parent child discovery from retained direct-child headers and own descriptors. Storage supplies compact descriptor evidence to the catalog assembly, which binds it into the V3→V4 stage factory; the Stage waits for the parent's final inherited cut before validating catalog payloads and deriving available own discovery facts. Nested seed markers discard inherited catalog candidates without interpreting their payloads. An existing catalog entry survives an unavailable descriptor, including a child that failed before its first step. Descriptor v1 denotes continuable mode; v2/v3 explicitly record mode. Available unambiguous discovery fields must agree with the parent; new complete entries require one supported descriptor. Missing, unsupported, or multiple descriptors preserve the logs and retain unknown-mode membership without inventing discovery fields, as recorded in [incomplete child evidence](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md). JSONL rechecks related membership and source revisions when preparing, reusing, and publishing. Unreadable or unsupported headers are excluded from discovery; failures reading a recognized child preserve its header identity as unknown-mode membership. Source drift invalidates preparation; read open retries once automatically, while write open refuses publication. Diagnostics retain the offending child path and distinguish unsupported migration evidence from malformed child data. The collector reports child decoding and descriptor failures as warnings with the child path; cancellation and source-consistency checks still stop preparation. The V0–V3-only catalog avoids recursive child migration. Current V4 reads skip that scan but apply the same own-catalog field, uniqueness, and current delivery ownership checks as strict restoration. See the [format specification](../../../../packages/session/session-format-v3-to-v4/README.md).
 
 Raw parent/child migration tests retain 24 historical creation-time conflicts as rejection evidence. Detached controls align only the child creation time and prove event-preserving restoration, including a published child without a descriptor. Headless/ACP and SDK snapshot adapters validate live parent/child clocks before normalization and preserve their equality during refresh; committed predecessor generations remain unchanged.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
index 69132ec176..637d8fcf02 100644
--- a/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md
@@ -131,7 +131,7 @@ POSIX publication 使用 hard-link creation 加目录 sync；Windows 使用 no-o
 
 ### 父目录前置事实
 
-V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；缺失记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志但不补填对应子 Session，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。扫描中其他任何不支持代际或不可读 header 都会拒绝迁移，因为无法证明它与父 Session 无关。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。存储解码器先将物理 JSON 与压缩错误归类，再由收集器补充子日志信息；文件系统读取与取消保留原始错误。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
+本段的运行时子会话错误处理部分由[逐会话目录准备](../bug-fix/2026-09-19-session-local-subagent-migration.zh.md)取代：打开父会话仍通过读取直属子会话补齐目录，但不可读子会话不再阻断健康父历史。V3→V4 使用保留的直属子 Session header 和自身 descriptor 补齐父 Session 的子代理发现记录。存储将紧凑的 descriptor 证据提供给 catalog 组装处，由其绑定到 V3→V4 stage 工厂；Stage 等待父 Session 的最终继承截点确定后，才校验目录 payload 并导出可获得的自身发现事实。嵌套的 seed 标记丢弃继承目录候选，不解释其 payload。已有目录记录允许 descriptor 不可用，包括在首次 step 之前失败的子 Session。Descriptor v1 表示 continuable 模式；v2/v3 显式记录模式。可获得且明确的发现字段必须与父目录一致；新增完整记录要求一个受支持的 descriptor。Descriptor 缺失、版本不受支持或存在多个时，保留日志与未知模式成员关系，不编造发现字段，理由见[不完整子目录证据](../bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)。JSONL 在准备、复用和发布时重新检查关联成员与来源修订。不可读或不支持的 header 不参与发现；读取已识别子会话失败时，其 header 身份保留为未知模式成员关系。来源变化使准备缓存失效；只读打开自动重试一次，写打开则拒绝发布。诊断保留出错子日志的路径，并区分不支持的迁移证据与畸形子数据。收集器将子解码和 descriptor 失败报告为带子路径的警告；取消与来源一致性检查仍中止准备。仅支持 V0–V3 的目录避免递归迁移子 Session。当前 V4 读取跳过该扫描，但会执行与严格恢复相同的自身目录字段、唯一性及当前投递归属检查。见[格式规范](../../../../packages/session/session-format-v3-to-v4/README.zh.md)。
 
 原始父子迁移测试保留 24 个历史创建时间冲突作为拒绝证据。独立的内存对照只对齐子创建时间，证明恢复保留事件，包括已发布但没有 descriptor 的子 Session。Headless/ACP 与 SDK 快照适配器在规范化之前校验实时父子时钟，并在刷新时保持两者相等；已提交的前代文件保持不变。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml
new file mode 100644
index 0000000000..497481e7d2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md
+2026-09-01-jobs-absorb-activity-record.md: 508608f7eb694bf131bad9a25e856d32c7079559
+2026-09-01-jobs-absorb-activity-record.zh.md: 2c157d951042f1cd6f8a3a66129773bc99cd5b02
diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md
new file mode 100644
index 0000000000..508608f7eb
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md
@@ -0,0 +1,48 @@
+# Agent Note: The job registry absorbs the observation record; the standalone activity seam is removed
+
+Status: implemented
+
+Superseded: the record declaration (`JobStart.record`, `RecordingJob`, `readRecord`, `pumpJobOutput`) and the split wire (`SessionJob.record` on the session control stream, `ctx.jobOutput`) described below were consolidated into one output ring and direct operations on `ctx.jobs` — see [the jobs seam consolidation](2026-09-03-jobs-seam-consolidation.md). The argument for absorbing the standalone activity seam into `ctx.jobs` still holds.
+
+English | [中文](2026-09-01-jobs-absorb-activity-record.zh.md)
+
+## Problem
+
+The [activity observation seam](../feature/2026-08-24-activity-observation-seam.md) shipped live output streaming as a second registry beside `ctx.jobs`: producers registered the same work twice (a job for lifecycle, an activity for observation), kept the two terminal states consistent by hand (`observeBackgroundActivity` waited for `proc.done` before mapping the outcome so a pump failure could not freeze a wrong terminal state), correlated the rows through `ActivityCorrelation.jobId`, and wrapped every observation call in registry-absent degradation branches. The Web client maintained two rosters (session-control `jobs` frames and the activity control stream) and joined them per row. Measured before the merge: eight pairing call sites, and one producer population — background bash/pwsh (both registries), PTY sends and subagent delegations (jobs only), foreground workflow (activity only).
+
+The one activity without a job was the foreground workflow mirror. Everything else the split enabled — independent observers, absolute-offset reads, bounded retention — is a property of the record, not of the registry split.
+
+## Decision
+
+`ctx.jobs` owns the observation record; `packages/activity/`, `packages/api/activity-controller`, and the correlation vocabulary are removed.
+
+- **`JobStart.record?: true`** declares an observable output record. `run(job)` now receives the job's producer face — `RecordingJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }` for a `record: true` start, the plain `RunningJob { id, updateDetail(detail) }` otherwise — so the id is issued before the starter runs (a throwing starter still registers nothing; its ordinal is skipped). Writes staged inside the starter surface at the registration commit. `updateDetail` works for every job and gives `job_list` a live progress line; `append` without a record declaration logs and drops.
+- **There is no `end`.** Job settlement — the producer outcome, a kill, or teardown — is the record's only close: it trims retention to the settled cap and fires the final `onOutput` signal. The dual-settlement pairing (`ActivityHandle.end` first-wins against teardown force-ends) is deleted, not reimplemented.
+- **`readRecord(id, from, caller)`** is the non-consuming multi-reader view (absolute UTF-8 offsets, `lossy` below the retained window), fenced like every other job read; it never marks the job `reported`. The model-facing `readOutput` cursor is untouched — the two projections serve different readers and stay separate by design.
+- **`jobs-local`** absorbs the chunk ring (`retainBytes` 256 KiB live, `settledRetainBytes` 16 KiB settled), and `pumpJobOutput` replaces `pumpActivityOutput` beside the seam. Producers fold the pump's final drain into `hooks.done` so the record holds its last bytes before settlement closes it.
+- **The wire splits by role.** `SessionJob.record` (present exactly for record jobs) marks a row observable on the session control stream; `job.follow({sessionId?, jobId, from?})` on the `job` namespace of `api-job-controller` streams anchor/output/status frames with the fenced read resolved from the request's session. `api-activity-controller` is deleted; its roster stream is redundant (the jobs frames are the roster) and its observe machinery lives in `api-job-controller` (`observe.ts`, client `ctx.jobOutput`), which resolves its Remote faces in its own apply.
+- **`ui-activity` returns to its upstream name `ui-jobs`** and renders one roster: `jobsBySession` rows, expandable exactly when `record` is present. The two-roster join is deleted.
+- **Foreground workflow loses its live panel deliberately.** `tool-workflow`'s activity mirror is removed; a foreground run surfaces through its recorded run/member lifecycle events only, and the per-line `workflow/phase` / `workflow/log` narration has no observer until workflow gains `run_in_background` and registers a record job. Jobs stay a pure background registry — no `foreground` mode bit, no model-invisible rows, no run-less rows.
+
+## Alternatives considered
+
+- **A `foreground: true` job mode** to keep the foreground workflow panel: it needs two coupled enforcement points (reported-at-birth and a `job_list` filter) whose divergence double-delivers or leaks rows to the model, for one edge feature replaceable by `run_in_background`.
+- **Serving model reads from the record** (deleting `readOutput`): model reads are producer-formatted (truncation and spill notices, sandbox markers) and consuming; the record is raw, channel-labeled, and non-consuming. Unifying them moves producer-specific formatting into the registry or noise into the observer stream.
+- **Keeping the split with shared implementation** (a common registry library): it removes the duplicated skeleton but keeps the real costs — double registration, terminal-state pairing, correlation, a second wire roster, and a second package family.
+
+The [prior seam note](../feature/2026-08-24-activity-observation-seam.md)'s argument against durable session events and control-stream framing for live output still holds and carries over unchanged: the record is process-local observation state, never a session event, so "model-visible ⟺ logged" is untouched.
+
+## Review corrections
+
+Review of the merged design settled five points that the sections above leave implicit:
+
+- **The pump's wait holds constant resources.** `pumpJobOutput` subscribes to the producer's `done` once and keeps one pending timer; settlement clears the timer and wakes the current wait. Racing the same pending promise every poll round retained a reaction per round until the job ended — a day-long job at the default cadence accumulated over a million closures.
+- **Client disposal waits for carrier quiescence.** The `ctx.jobOutput` effect disposer is async and awaits every open `RemoteStream.dispose()`, because Cordis awaits async disposers and a fiber that reported unloaded while an old iterator was still closing could overlap the next plugin instance under HMR.
+- **The roster flags a record, it does not count bytes.** `SessionJob.record: true` replaced `outputTotal`: `append` commits no roster change (only lifecycle commits fire `onJobsChanged`), so a mirrored count went stale the moment output arrived, and broadcasting the roster per append was rejected as traffic for a number no row needed. The live offsets ride the observation stream's `opened` anchor.
+- **The record is a best-effort live preview.** Producers copy stdout and stderr per poll round, so writes inside one window land stdout first; pipe capture cannot recover the true interleaving (only a PTY or `2>&1` can), and the client concatenates chunks regardless of `channel`. `channel` stays on the wire because it is what makes that limit visible and what a distinct stderr rendering would need.
+- **The declaration types the face.** `JobStart` is a union discriminated by `record`: `RecordingJobStart.run` receives `RecordingJob`, `PlainJobStart.run` receives `RunningJob` without `append`, and the registry builds the plain face without the method — output the registry has nowhere to keep is unrepresentable instead of warned about and dropped.
+- **Web e2e keep-alive is a barrier, not a clock.** The background command holds on a file the test owns in the job's cwd and the scenario kills it explicitly, so no CI stall can settle the job first; each scenario is one test, never a chain of tests sharing a job id.
+
+## Consequences
+
+Every observable row is a killable job; a pure-observation surface with no lifecycle would need a new home (harness diagnostics belong to the inspector plane, not here). A future remote job provider must implement lifecycle and record together. The record's retention config lives on `jobs-local`; the observation wire's cadence config (`observeFlushMs`, `observeMaxFrameBytes`) lives on `api-job-controller`.
diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md
new file mode 100644
index 0000000000..2c157d9510
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md
@@ -0,0 +1,48 @@
+# Agent Note：job 注册表吸收观测 record；独立的 activity seam 被移除
+
+Status: implemented
+
+Superseded：下文描述的 record 声明（`JobStart.record`、`RecordingJob`、`readRecord`、`pumpJobOutput`）与拆分的线路（会话控制流上的 `SessionJob.record`、`ctx.jobOutput`）已收敛为一个输出环与 `ctx.jobs` 上的直接操作——见 [jobs seam 收敛](2026-09-03-jobs-seam-consolidation.zh.md)。把独立 activity seam 吸收进 `ctx.jobs` 的论证仍然成立。
+
+[English](2026-09-01-jobs-absorb-activity-record.md) | 中文
+
+## 问题
+
+[activity 观测 seam](../feature/2026-08-24-activity-observation-seam.zh.md) 把实时输出流做成了 `ctx.jobs` 旁边的第二个注册表：生产者要把同一份工作登记两次（job 管生命周期，activity 管观测），手工保持两个终态一致（`observeBackgroundActivity` 要等 `proc.done` 才映射 outcome，防止 pump 失败把错误终态冻上去），通过 `ActivityCorrelation.jobId` 关联两行，并给每个观测调用包上注册表缺失的降级分支。Web 客户端维护两份名册（session-control 的 `jobs` 帧与 activity control 流）并逐行做 join。合并前实测：八个配对调用点；生产者人口为——后台 bash/pwsh（双注册表）、PTY 发送与 subagent 委托（仅 jobs）、前台 workflow（仅 activity）。
+
+唯一没有 job 的 activity 是前台 workflow 镜像。拆分带来的其他一切——独立观察者、绝对偏移读取、有界保留——都是 record 的性质，不是注册表拆分的性质。
+
+## 决策
+
+`ctx.jobs` 拥有观测 record；`packages/activity/`、`packages/api/activity-controller` 与 correlation 词表被移除。
+
+- **`JobStart.record?: true`** 声明可观测输出 record。`run(job)` 现在收到 job 的生产者面——`record: true` 的 start 收到 `RecordingJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }`，其余收到普通的 `RunningJob { id, updateDetail(detail) }`——因此 id 在 starter 运行前签发（starter 抛出仍然不登记任何东西；序号被跳过）。starter 内暂存的写入在登记提交时可见。`updateDetail` 对所有 job 可用，让 `job_list` 也能看到实时进度行；未声明 record 的 `append` 记日志并丢弃。
+- **没有 `end`。** job 结算——生产者 outcome、kill 或 teardown——是 record 唯一的关闭：裁剪到结算保留量并发出最后一个 `onOutput` 信号。双结算配对（`ActivityHandle.end` 与 teardown 强结的 first-wins 对账）被删除，而非重新实现。
+- **`readRecord(id, from, caller)`** 是非消耗多读者视图（绝对 UTF-8 偏移，低于保留窗口为 `lossy`），围栏与其他 job 读取一致；永不置 `reported`。模型面的 `readOutput` 游标原样保留——两个投影服务不同读者，刻意保持分离。
+- **`jobs-local`** 吸收块环（`retainBytes` 运行期 256 KiB，`settledRetainBytes` 结算后 16 KiB），`pumpJobOutput` 在 seam 旁替换 `pumpActivityOutput`。生产者把 pump 的末次排空折进 `hooks.done`，让 record 在结算关闭前握有最后的字节。
+- **wire 按角色拆分。** `SessionJob.record`（恰在 record job 上存在）在会话控制流上标记行可观测；`api-job-controller` 的 `job` 命名空间上的 `job.follow({sessionId?, jobId, from?})` 流式发送 anchor/output/status 帧，围栏读取者由请求的 session 解析。`api-activity-controller` 删除；其名册流是冗余的（jobs 帧就是名册），observe 机制位于 `api-job-controller`（`observe.ts`，客户端 `ctx.jobOutput`），它在自己的 apply 里解析所依赖的 Remote 面。
+- **`ui-activity` 改回上游名字 `ui-jobs`**，渲染单一名册：`jobsBySession` 行，恰在 `record` 存在时可展开。双名册 join 被删除。
+- **前台 workflow 有意失去实时面板。** `tool-workflow` 的 activity 镜像被移除；前台 run 只通过已记录的 run/member 生命周期事件呈现，逐行的 `workflow/phase` / `workflow/log` 叙述在 workflow 获得 `run_in_background` 并登记 record job 之前没有观察者。jobs 保持纯后台注册表——没有 `foreground` 模式位、没有模型不可见行、没有无 run 行。
+
+## 曾考虑的替代方案
+
+- **`foreground: true` job 模式**以保留前台 workflow 面板：它需要两个耦合的执行点（出生即 reported 与 `job_list` 过滤），两者一旦分叉就会双投递或向模型泄漏行，而它换来的只是一个可被 `run_in_background` 替代的边缘特性。
+- **用 record 服务模型读取**（删除 `readOutput`）：模型读取是生产者格式化的（截断与 spill 提示、sandbox 标记）且消耗型；record 是原始、带 channel 标签、非消耗的。统一二者要么把生产者特有格式化搬进注册表，要么把噪声混入观察者流。
+- **保留拆分但共享实现**（公共注册表库）：它消除重复骨架，但保留真正的成本——双重登记、终态配对、correlation、第二条 wire 名册与第二个包族。
+
+[先前 seam note](../feature/2026-08-24-activity-observation-seam.zh.md) 反对用持久会话事件或 control 流承载实时输出的论证仍然成立并原样沿用：record 是进程本地观测状态，从不是会话事件，「模型可见 ⟺ 已记录」不受影响。
+
+## 评审修正
+
+对已合并设计的评审确定了上文各节未言明的五点：
+
+- **泵的等待资源恒定。** `pumpJobOutput` 对生产者的 `done` 只订阅一次，同一时刻只保留一个待触发的 timer；结算清掉 timer 并唤醒当前等待。此前每个轮询轮次都对同一个 pending promise 赛跑，每轮留下一个 reaction 直到任务结束——默认节奏下跑一天的任务会累积上百万个闭包。
+- **客户端卸载等待载体静止。** `ctx.jobOutput` 的 effect disposer 是异步的，await 每条打开的 `RemoteStream.dispose()`：Cordis 会 await 异步 disposer，而一个在旧 iterator 仍在关闭时就宣告卸载完成的 fiber，在 HMR 下可能与下一个插件实例重叠。
+- **名册标记 record，不计字节。** `SessionJob.record: true` 取代了 `outputTotal`：`append` 不提交名册变更（只有生命周期提交触发 `onJobsChanged`），镜像的计数在输出到达的瞬间就陈旧了；而为一个没有任何行需要的数字按 append 广播整份名册被否决。实时偏移随观测流的 `opened` 锚帧到达。
+- **record 是尽力而为的实时预览。** 生产者按轮询轮次复制 stdout 与 stderr，同一窗口内的写入先 stdout 落地；pipe 捕获无法还原真实交错（只有 PTY 或 `2>&1` 可以），客户端拼接 chunk 时也不区分 `channel`。`channel` 留在 wire 上，因为它正是让这一限制可见、也是将来区分渲染 stderr 所需要的东西。
+- **声明决定生产者面的类型。** `JobStart` 是按 `record` 判别的联合类型：`RecordingJobStart.run` 收到 `RecordingJob`，`PlainJobStart.run` 收到没有 `append` 的 `RunningJob`，注册表给普通 job 构造的面根本没有这个方法——注册表无处存放的输出成为不可表达，而不是警告后丢弃。
+- **Web e2e 的保活是 barrier 而非时钟。** 后台命令守在测试拥有的、位于 job cwd 的文件上，由场景显式 kill，因此 CI 卡顿不可能先把任务结算掉；每个场景是一个测试，绝不是共享 job id 的测试链。
+
+## 后果
+
+每个可观测行都是可 kill 的 job；没有生命周期的纯观测面需要新的归属（harness 诊断属于 inspector 平面，不在这里）。未来的远端 job provider 必须同时实现生命周期与 record。record 的保留配置在 `jobs-local`；观测 wire 的节奏配置（`observeFlushMs`、`observeMaxFrameBytes`）在 `api-job-controller`。
diff --git a/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.i18n.yaml
new file mode 100644
index 0000000000..1d1a4bc731
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md
+2026-09-03-jobs-seam-consolidation.md: 2742ff1a80ec4cc4d8e5948f63d306abb9753733
+2026-09-03-jobs-seam-consolidation.zh.md: 1fa61919a27362ce42419b57e0960e9be86ea07e
diff --git a/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md
new file mode 100644
index 0000000000..2742ff1a80
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md
@@ -0,0 +1,35 @@
+# Agent Note: One output ring, one projection, one event stream for background jobs
+
+Status: implemented
+
+English | [中文](2026-09-03-jobs-seam-consolidation.zh.md)
+
+## Problem
+
+The job seam had grown by accretion. Producers declared their output twice — a consuming `readOutput` hook the model read and an optional `record: true` ring observers read — and the registry kept two vocabularies for one job (`JobSnapshot` for the model, `SessionJob` on the session control stream, `JobWireChunk` on the observation wire). Three listener families (`onJobDone`, `onJobsChanged`, `onOutput`) delivered overlapping facts with different owner filters, and the registry itself tracked `reported`, a bit that only the model-facing tool could interpret. Review of the merged design called the interface layer the weakest part: a reader could not tell which of `read`, `readRecord`, `JobStart`, `RecordingJob`, and `updateDetail` was the contract and which was an accident of history.
+
+## Decision
+
+- **One ring per job.** `JobSpec` replaces `JobStart`: a spec names optional pull `output` sources (`JobOutputSource`, the subprocess `readFrom` family) that the registry pumps at its own cadence (`pumpPollMs` on `dsh-jobs-local`), and every producer receives a `JobHandle` whose `append` pushes chunks into the same ring. The model's consuming read and every observer's absolute-offset read serve the same bytes; `readOutput` and the `record` discriminator are gone. Shell producers hand the registry their `observed` offset readers and fold sandbox facts into the terminal `detail`; the terminal producer adapts its consuming send reader through a byte-counting source; the subagent returns its answer as `JobOutcome.result`, which the first read after settlement carries once.
+- **Two cursors, one storage.** `JobRegistry.read(id)` is the stateful model cursor; `JobRegistry.readAt(id, from)` is the stateless observer read. Model reads exclude `log` chunks (producer narration for observers) and render stdout, then one `[stderr]` section, exactly as the shell tools always did.
+- **`updateProgress` replaces `updateDetail`.** `JobView.progress` is the live line and is cleared at settlement; `JobView.detail` is the terminal reason, with the model's `job_kill` reason merged in.
+- **One projection.** `JobView` (client-safe leaf `@deepseek-ai/dsh-jobs/view`) is what the model tools, the browser roster, and the observation frames consume; `owner` is the session id, never the `Agent`.
+- **Direct caller-scoped operations.** `JobRegistry.list`, `get`, `read`, `readAt`, `kill`, and `wait` accept the caller session on each call. Omitting the caller permits only unowned jobs. The output ring and browser streams do not require a separate caller-bound operation object.
+- **One event stream.** `events.subscribe(filter, listener)` with `{ owner }`, `{ owners: 'scope' }`, or `{ owners: 'all' }` replaces the three listener families. `settled` names its cause (`producer`, `kill`, `teardown`); `output` carries only the id and the new total.
+- **The notice ledger moves to `dsh-tool-jobs`.** The registry no longer tracks `reported`. The tool claims a job when a wait starts (and withdraws on timeout or abort) and when `job_kill` is accepted; the settlement event drops the entry, teardown settlements and unowned jobs are skipped, and the destination is the agent registered for the owner session at settlement.
+- **The roster leaves the session control stream.** `dsh-api-job-controller` owns `job.list({ sessionId })` — whole-set frames after each coalesced burst of lifecycle commits, never per append — beside `job.follow`, and its client installs `ctx.jobs` (`watchRows`, `observe`, one snapshot). `dsh-api-session-controller` carries queues and projections only; `ui-jobs` watches its session's roster while mounted, and a row is expandable while live or once it left retained output behind.
+
+`attachController` and the owner-relative `servesOwner` gate stay as they were; whether a producer may offer `run_in_background` without a mounted controller is deferred, since the gap predates this change.
+
+## Alternatives considered
+
+- **Keep three listeners with a shared owner filter.** It preserves the accreted names but not the property reviewers asked for — one place to learn what the registry announces — and `onJobDone`'s exact-owner delivery is what forced the registry to keep an `Agent` in every projection.
+- **Keep `reported` in the registry.** Only the tool knows which deliveries reach the model (a wait's tool result, a kill's acknowledgement); the registry could only approximate it, and the approximation was the source of the double-notice and missed-notice bugs the review listed.
+- **Keep the roster on the session control stream.** It saved one Remote stream but coupled the session controller to the job registry and mirrored a `record` flag the ring's byte count now answers directly (`output.total`).
+- **Serve `log` chunks to the model too.** Producer narration is for observers; the model already receives the same facts through `progress` and the terminal `detail`.
+
+## Consequences
+
+The model-visible text is unchanged: status lines, tool descriptions and schemas, and notice wording are byte-identical, and the only new model-visible fact is the kill reason a `killed` status line now carries. A producer that needs to stream output picks pull sources or `append`; it never formats a consuming delta. The Web client renders every live job as expandable, so a job that never writes shows an empty running panel instead of a static row. `JobKindMap` merges are host-side, so a browser program types `JobView.kind` as the kinds it knows and treats the rest as opaque strings, which is all the roster does with it.
+
+Review follow-ups after the master merge tightened four of these edges. A job's first event is always `registered`: the announcement precedes the pump, whose first drain runs synchronously and may announce output. A settled ring keeps every byte the model cursor has not consumed until the first terminal model read, so a job that finishes before its first `job_output` loses nothing the live cap retained. `dsh-tool-jobs` holds one claim per wait call with a `live` flag that the caller's abort clears synchronously from the abort event, so a settlement announced before the registry's rejection reaches the tool still delivers its notice, and a timed-out wait drops only its own claim while a concurrent wait keeps the settlement covered. The browser records an observation failure that precedes the anchor as an errored view, so the panel shows the notice instead of staying blank. The `@deepseek-ai/dsh-jobs/invariant` companion checks the announced event protocol per job (registered first, one settlement, removal last) and each announced projection against the registry's own read, which is the cross-observation the [companion rule](../simplification/2026-08-28-omit-unneeded-invariant-companions.md) requires; the earlier single-view field checks are gone. The spill file a pull source keeps is job metadata (`JobView.output.spillPaths`, reported by every pump read and withdrawn once a read stops naming it), not per-chunk metadata, and the model's read renders the shell tools' dropped-output notice for a producer-side gap as well as for ring eviction, naming those files even after the gap chunk itself was evicted — the `before this read` variant this change had introduced is gone. An observation generation that sees its job removed mid-stream (the owner's teardown) closes with the removed job's terminal projection instead of a failed read. A rejected background spawn produces no process output, so the shell providers now serve the `spawn failed: …` note as the whole observed stderr stream (the consuming read still folds it in once), and `ShellProcess.observed` with both readers is required: the model's first `job_output` after such a failure reads exactly what master's consuming read rendered.
diff --git a/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md
new file mode 100644
index 0000000000..1fa61919a2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md
@@ -0,0 +1,35 @@
+# Agent Note：后台 job 的一个输出环、一个投影、一条事件流
+
+Status: implemented
+
+[English](2026-09-03-jobs-seam-consolidation.md) | 中文
+
+## 问题
+
+job seam 是逐步堆出来的。生产者要把输出声明两次——模型读取的消耗式 `readOutput` 钩子，以及观察者读取的可选 `record: true` 环——注册表也为同一个 job 保留了两套词汇（模型侧的 `JobSnapshot`、会话控制流上的 `SessionJob`、观测线路上的 `JobWireChunk`）。三个监听器家族（`onJobDone`、`onJobsChanged`、`onOutput`）用不同的拥有者过滤投递彼此重叠的事实，注册表自己还跟踪着只有模型侧工具才解释得了的 `reported` 位。合并后设计的评审把接口层称作最薄弱的部分：读者分不清 `read`、`readRecord`、`JobStart`、`RecordingJob` 与 `updateDetail` 里哪些是约定、哪些是历史遗留。
+
+## 决策
+
+- **每个 job 一个环。** `JobSpec` 取代 `JobStart`：spec 声明可选的拉取式 `output` 源（`JobOutputSource`，子进程的 `readFrom` 家族），由注册表按自己的节奏（`dsh-jobs-local` 的 `pumpPollMs`）泵送；每个生产者都收到一个 `JobHandle`，其 `append` 把块推进同一个环。模型的消耗式读取与每个观察者的绝对偏移读取服务同一批字节；`readOutput` 与 `record` 判别字段被移除。shell 生产者把它们的 `observed` 偏移读取器交给注册表，并把沙箱事实折进终态 `detail`；terminal 生产者通过一个计字节的源适配其消耗式发送读取器；subagent 把回答作为 `JobOutcome.result` 返回，结算后的第一次读取携带它一次。
+- **两个游标，一份存储。** `JobRegistry.read(id)` 是有状态的模型游标；`JobRegistry.readAt(id, from)` 是无状态的观察者读取。模型读取排除 `log` 块（给观察者的生产者叙述），并渲染 stdout，再接一段 `[stderr]`，与 shell 工具一贯的做法完全一致。
+- **`updateProgress` 取代 `updateDetail`。** `JobView.progress` 是实时行，结算时清除；`JobView.detail` 是终态原因，合并了模型 `job_kill` 给出的原因。
+- **一个投影。** `JobView`（客户端安全叶子 `@deepseek-ai/dsh-jobs/view`）是模型工具、浏览器名册与观测帧共同消费的形状；`owner` 是会话 id，从不是 `Agent`。
+- **直接传入调用方的操作。** `JobRegistry.list`、`get`、`read`、`readAt`、`kill` 与 `wait` 在每次调用时接收调用方会话。省略调用方时仅允许访问无主 job。输出环与浏览器流不需要独立的调用方操作对象。
+- **一条事件流。** 带 `{ owner }`、`{ owners: 'scope' }` 或 `{ owners: 'all' }` 过滤的 `events.subscribe(filter, listener)` 取代三个监听器家族。`settled` 标出原因（`producer`、`kill`、`teardown`）；`output` 只携带 id 与新的 total。
+- **播报台账移到 `dsh-tool-jobs`。** 注册表不再跟踪 `reported`。工具在等待开始时认领 job（超时或中止则撤回），在 `job_kill` 被接受时也认领；结算事件删除条目，teardown 结算与无主 job 被跳过，投递目标是结算时登记在拥有者会话下的 agent。
+- **名册离开会话控制流。** `dsh-api-job-controller` 在 `job.follow` 旁拥有 `job.list({ sessionId })`——每轮聚合过的生命周期提交之后发一次整集帧，从不按追加发——其客户端安装 `ctx.jobs`（`watchRows`、`observe`、一份快照）。`dsh-api-session-controller` 只承载队列与投影；`ui-jobs` 在挂载期间关注其会话的名册，行在 job 进行中或留有保留输出时可展开。
+
+`attachController` 与相对拥有者的 `servesOwner` 门保持原样；没有挂载控制器的生产者是否可以提供 `run_in_background`，因为这个缺口早于本次变更，暂不处理。
+
+## 考虑过的替代方案
+
+- **保留三个监听器并共享一个拥有者过滤。** 它保住了堆出来的名字，却保不住评审要的性质——一个地方就能学会注册表宣布什么——而且 `onJobDone` 的精确拥有者投递正是迫使注册表在每个投影里保留 `Agent` 的原因。
+- **把 `reported`留在注册表。** 只有工具知道哪些投递到达了模型（等待的工具结果、kill 的确认）；注册表只能近似，而这个近似正是评审列出的重复播报与漏播报 bug 的来源。
+- **把名册留在会话控制流上。** 省了一条 Remote 流，却把会话控制器耦合到 job 注册表，还镜像了一个环的字节数如今直接回答的 `record` 标志（`output.total`）。
+- **也把 `log` 块交给模型。** 生产者叙述是给观察者的；模型已经通过 `progress` 与终态 `detail` 收到同样的事实。
+
+## 后果
+
+模型可见文本保持不变：状态行、工具描述与 schema、播报措辞逐字节相同，唯一新增的模型可见事实是 `killed` 状态行现在携带的 kill 原因。需要流式输出的生产者选择拉取源或 `append`，从不格式化消耗式增量。Web 客户端把每个进行中的 job 渲染为可展开，因此从不写输出的 job 显示为空的运行中面板而非静态行。`JobKindMap` 的合并发生在宿主侧，浏览器程序把 `JobView.kind` 视为它认识的 kind 集合，其余当作不透明字符串——名册对它也只做这些。
+
+合并 master 之后的评审跟进收紧了其中四条边。job 的第一个事件永远是 `registered`：通告先于泵，而泵的首轮 drain 同步执行且可能通告输出。已结算的环在模型的首次终态读取之前保留模型游标尚未消费的全部字节，因此在首次 `job_output` 之前结束的 job 不会丢失运行期上限保留的任何内容。`dsh-tool-jobs` 为每次等待调用保存一条带 `live` 标记的认领，调用方 abort 时在 abort 事件里同步清掉该标记，因此注册表的拒绝尚未传回工具之前宣布的结算仍会投递通知；超时的等待只丢弃自己的认领，并发的另一个等待仍覆盖该结算。浏览器把先于锚点发生的观察失败记录为带错误的视图，面板显示提示而不是留白。`@deepseek-ai/dsh-jobs/invariant` 伴生插件校验每个 job 的事件协议（先 `registered`、恰一次结算、最后 `removed`）以及每个通告的投影与注册表自身读取的一致性，这正是[伴生插件规则](../simplification/2026-08-28-omit-unneeded-invariant-companions.zh.md)要求的交叉观察；先前只针对单个视图的字段校验已删除。拉取源保留的 spill 文件是 job 元数据（`JobView.output.spillPaths`，每次泵读取都会上报，读取不再点名时即撤回），不是逐块元数据；模型读取对生产者侧缺口与环淘汰都渲染 shell 工具的丢失输出提示并列出这些文件，即使缺口块本身已被淘汰——本次变更曾引入的 `before this read` 变体已删除。观察生成过程若在流中看到其 job 被移除（拥有者 teardown），以被移除 job 的终态投影收尾，而不是一次失败的读取。被拒绝的后台 spawn 不产生任何进程输出，因此 shell provider 现在把 `spawn failed: …` 提示作为 observed stderr 的整条流提供（消耗式读取仍只折入一次），且 `ShellProcess.observed` 及其两个读取器改为必填：这类失败之后模型的首次 `job_output` 读到的正是 master 的消耗式读取所渲染的内容。
diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml
index 050ce7d48f..f44cffc1fa 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-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-09-05-workspace-files-service.md
-2026-09-05-workspace-files-service.md: 40157508a83abc61245845a1dbe4f1749e175563
-2026-09-05-workspace-files-service.zh.md: 51de0ad5b644f27e30557ea6b11ba62b8ef9a715
+2026-09-05-workspace-files-service.md: 65bebf18175d9a94452c92cd36ada3c5ef267ce5
+2026-09-05-workspace-files-service.zh.md: b4ca420042dc702f9bc1eaf5bb09f2667a19322d
diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
index 40157508a8..65bebf1817 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
@@ -25,15 +25,13 @@ Two constraints frame the service. File reads through `ctx.fs` use the Session's
 
 `api/remotes` and both root aggregates reference the matching Host/Client leaf. The package exports `.`, `./client`, `./types`, `./typert`, and `./remote`, with one `workspace-files` web-app row supplying both faces. The Client plugin injects `['resources', 'remote', 'remote.workspaceFiles']`; the resource model takes result types directly from the protocol package, and the text preview owns the Sidebar parameter declaration, so the Client compilation graph has no reverse dependency on Remote assembly or Sidebar UI.
 
-### The `workspaceFiles` Remote namespace
+### The `workspaceFiles` file operations
 
-Every Host method takes `WorkspaceFileScope` first. The Gateway resolves it from the wire Session identity by reading the live Session header or, for a cold Session, `SessionPersistence.stat`; it never activates an Agent, reads the event body, or falls back to a parent Session. The scope carries the selected Session id and its `cwd`, with the sandbox policy's deployment root used only when that header has no `cwd`. A Client passes its Session id and never names a root. The seven signatures, as `src/index.ts` declares them:
+Every Host method takes `WorkspaceFileScope` first. The `workspaceFileScope` Gateway lookup resolves Session identity. It reads the live Session header or, for a cold Session, `SessionPersistence.stat`; it never activates an Agent, reads the event body, or falls back to a parent Session. The scope carries the selected Session id and its `cwd`, with the sandbox policy's deployment root used only when that header has no `cwd`. A Client passes its Session id and never names a root. The five signatures, as `src/index.ts` declares them:
 
 ```ts ignore-check
 @Remote async read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
-@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
-@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes>
-@Remote async readRelated(workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal): Promise<WorkspaceFileBytes>
+@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal): Promise<WorkspaceFileBytes>
 @Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
 @Remote async list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
 @Remote({ mode: 'stream' }) changes(workspaceFileScope: WorkspaceFileScope, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
@@ -41,20 +39,20 @@ Every Host method takes `WorkspaceFileScope` first. The Gateway resolves it from
 
 - **`stat`** returns `WorkspaceFileStat { absolutePath, version, bytes? }`: the file's identity, its opaque freshness token, and its size when the backend reports one. It accepts a regular file only.
 - **`read`** returns one window of lines, `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`; `lines` counts the page's lines, so a page holding one empty line (`text: ''`, `lines: 1`) and a page past the end (`lines: 0`) read differently. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines and defaults to `maxLines`, which it may not exceed. Lines end at `\n` and a final `\n` terminates the last line rather than opening an empty one; `text` joins the page's lines with `\n` and carries no terminator; `eof` is true when the page includes the last line, and an offset past the end returns an empty page with `eof` true. The pager walks `streamText`, counts the lines before the window without keeping them, admits each in-window segment against `maxBytes` before buffering it, and returns at the first character past the window, so a file of any size costs one page of memory. The `version` and `bytes` on a page are the stat's, taken before the stream.
-- **`readBytes`** returns one window of raw bytes, `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest byte count and defaults to `maxBytes`, which it may not exceed. `data` is base64, shorter than `length` where the file ends and empty at or past it; `eof` is true when the window includes the last byte. Nothing is decoded and nothing is refused as binary. `read` pages by lines and never by bytes; a byte window is `readBytes`.
-- **`readAll` and `readRelated`** return complete `WorkspaceFileBytes` under `maxFileBytes`. `readRelated` resolves a relative filesystem path from the base file's directory; the Host applies the same regular-file checks and backend read authority to both files. [Document Preview](2026-09-08-document-preview-operations.md) owns their loading and address semantics.
+- **`readBytes`** returns native bytes with file metadata, offset, and EOF. The required options object selects a complete read under `maxFileBytes` when `range` is absent, or a bounded window under `maxBytes` when present. `range: {}` uses offset zero and the configured window cap; windows can read files above the complete-file cap. The [binary transfer decision](2026-09-17-workspace-file-binary-transfer.md) owns the Remote response encoding.
+- **`baseFile`** selects target resolution independently of `range`: the target `path` must be relative and resolves from the base file's directory. The Host applies regular-file checks to both files and preserves backend read authority. [Document Preview](2026-09-08-document-preview-operations.md) owns content loading and address semantics.
 - **`list`** returns `WorkspaceDirectoryListing { path, entries, truncated }`: the listed directory as a workspace path relative to the root (empty for the root), its direct children in the backend's stable name order as `{ name, type, size? }`, and whether `maxEntries` cut the list. `type` is `file`, `directory`, or `other`; a symlink child reports the type of what it points to and a dangling one is `other`, while opening such a child still fails the link gate below. Dotfiles are listed; nothing is filtered.
 - **`changes`** yields `WorkspaceFileWatchFrame`: `{ kind: 'ready' }` after the observation queue is registered and the workspace root resolves, followed by `{ kind: 'change', change }`. The `WorkspaceFileChange` payload is `{ absolutePath, version }` for a present file or `{ absolutePath, absent: true }` for one observed gone. Its source is `fs/observed` inside the workspace root, never an OS watcher. Observations after the first pull are queued, including during root resolution; cancellation or plugin disposal ends the generation.
 
 ### Paths on the wire
 
-Two path vocabularies leave the service, and each method uses exactly one. `read`, `readBytes`, `readAll`, `readRelated`, `stat`, and `changes` name a file by `absolutePath`: its absolute path in the filesystem's execution world, symlinks resolved (`ctx.fs.processPath(target)`), so the Client provider matches a change frame to an open address by absolute path: the Client sends the address's path unchanged to the Host and binds the follower only to a successful `stat.absolutePath`, without reading a Session summary's cwd. `list` speaks workspace paths — the same syntax its `path` argument accepts, absolute or relative to the root — because its consumer is a tree rooted there. The field is called `absolutePath` and not `url` because it is not a resource address; the address grammar belongs to `dsh-util-workspace-path` and is described with the resource model. Input paths to `read`, `readBytes`, `readAll`, `readRelated`, `stat`, and `list` are absolute or relative to the session's workspace root, never to the backend's own cwd.
+Two path vocabularies leave the service, and each method uses exactly one. `read`, `readBytes`, `stat`, and `changes` name a file by `absolutePath`: its absolute path in the filesystem's execution world, symlinks resolved (`ctx.fs.processPath(target)`), so the Client provider matches a change frame to an open address by absolute path: the Client sends the address's path unchanged to the Host and binds the follower only to a successful `stat.absolutePath`, without reading a Session summary's cwd. `list` speaks workspace paths — the same syntax its `path` argument accepts, absolute or relative to the root — because its consumer is a tree rooted there. The field is called `absolutePath` and not `url` because it is not a resource address; the address grammar belongs to `dsh-util-workspace-path` and is described with the resource model. Input paths to `read`, `readBytes`, `stat`, and `list` are absolute or relative to the session's workspace root, never to the backend's own cwd; `readBytes` with `baseFile` resolves the target from that file's directory.
 
 `version` is an opaque string a consumer compares for equality and never parses: the local backend derives it from device, inode, size, and nanosecond mtime and ctime, so a rewrite that leaves the content identical still changes it. `offset` means a line on `read` and a byte on `readBytes`; the two units never mix, and `eof` on either means the window reached the file's end.
 
 ### File checks and workspace containment
 
-`read`, `readBytes`, `readAll`, `readRelated`, and `stat` share regular-file checks and then rely on the filesystem backend's read authority. `list` shares path inspection but also checks workspace containment, while `changes` filters observations to the workspace root. The service applies the following checks:
+`read`, `readBytes`, and `stat` share regular-file checks and then rely on the filesystem backend's read authority. `list` shares path inspection but also checks workspace containment, while `changes` filters observations to the workspace root. The service applies the following checks:
 
 1. **The path itself.** `lstat` inspects the path before anything follows it: a missing path is `not-found`, and a symlink — wherever it points, including back inside the workspace — is `not-regular-file` (kind `symlink`) for the file methods and `not-directory` for `list`. An empty path is a `gateway/bad-request`.
 2. **Workspace containment for `list`.** The directory resolves to a target and `ctx.fs.contains(root, target)` decides, where `root` is the `WorkspaceFileScope.workspaceRoot` resolved from the selected Session header. A `..` traversal or an absolute directory outside the root is `outside-workspace`. `changes` applies the same backend containment predicate to observed targets.
@@ -73,7 +71,7 @@ Each failure is one `RemoteError` code with typed details, declared beside the t
 | `workspace-file/outside-workspace` | a `list` target is not inside the workspace root | `{ path }` |
 | `workspace-file/too-large` | a page's text or byte window exceeds `maxBytes`, or a complete read exceeds `maxFileBytes` | `{ path, limit }` |
 | `workspace-file/not-text` | invalid UTF-8 up to the page's end, or a NUL byte in the sample or the page (`read` only) | `{ path }` |
-| `workspace-file/not-regular-file` | `read`, `readBytes`, `readAll`, `readRelated`, or `stat` on something that is not a regular file | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
+| `workspace-file/not-regular-file` | `read`, `readBytes`, or `stat` on something that is not a regular file | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
 | `workspace-file/not-directory` | `list` on something that is not a directory | `{ path, kind: 'file' \| 'symlink' \| 'other' }` |
 | `workspace-file/unsupported-address` | Client-minted: a resource address this provider cannot serve | `{ address }` |
 | `workspace-file/unknown-workspace` | Client-minted: an `absolute` address, which carries no Session | `{ address }` |
@@ -109,7 +107,7 @@ The Client export registers one `ResourceProvider<'file'>` into `ctx.resources`
 
 ### Related notes
 
-The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, `useResource`, the `dsh-resource://<type>/…` address grammar, and the reasoning for one resource per address; the [text preview and file tree](../feature/2026-09-05-sidebar-text-preview-and-file-tree.md) are the shipped consumers of `read`, `list`, and the `file` provider; the [right Sidebar docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) is the surface they open into; [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) is where serving files over HTTP was rejected. Anyone extending this system reaches the same seven methods through `remote.workspaceFiles` and the same `file` resource through `useResource<'file'>`; the wire types are published as `@deepseek-ai/dsh-api-workspace-files/types`. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) owns Host read access and the HTML security trade-off; [Document Preview](2026-09-08-document-preview-operations.md) owns content loading and per-tab freshness.
+The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, `useResource`, the `dsh-resource://<type>/…` address grammar, and the reasoning for one resource per address; the [text preview and file tree](../feature/2026-09-05-sidebar-text-preview-and-file-tree.md) are the shipped consumers of `read`, `list`, and the `file` provider; the [right Sidebar docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) is the surface they open into; [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) is where serving files over HTTP was rejected. Anyone extending this system reaches the same five methods through `remote.workspaceFiles` and the same `file` resource through `useResource<'file'>`; the wire types are published as `@deepseek-ai/dsh-api-workspace-files/types`. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) owns Host read access and the HTML security trade-off; [Document Preview](2026-09-08-document-preview-operations.md) owns content loading and per-tab freshness.
 
 ## Alternatives considered
 
@@ -117,7 +115,7 @@ The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`,
 
 **A dual-face package with reverse UI dependencies.** The split-package choice followed two project-reference cycles after `api/remotes` referenced the Client leaf: the resource model imported Remote assembly for result types, and the file provider imported Sidebar UI for its parameter map. TypeScript rejected these cycles with `TS6202`. [dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) supersedes that split: result types come directly from the protocol package, and Sidebar parameter registration belongs to the text preview; both root aggregates retain explicit compiler entries.
 
-**Serving workspace files over HTTP.** Already rejected by [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) on origin grounds and not revisited: `read` and `readBytes` carry plain text and base64 over the authenticated Remote carrier, so no document is served, no URL is minted, and no origin question arises.
+**Serving navigable workspace documents.** Rejected on origin grounds; the [binary transfer](2026-09-17-workspace-file-binary-transfer.md) returns multipart data while HTML remains isolated in a Blob iframe.
 
 **Log-reachable or workspace-contained authorization for file reads.** The one precedent that sends file content over the wire, command attachments, authorizes only files that appear in the session log. That excludes typed paths, while workspace containment excludes readable files elsewhere on the Session backend. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) instead makes the backend's read decision authoritative and keeps containment only for workspace-shaped operations.
 
@@ -138,14 +136,14 @@ The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`,
 - Change frames report the agent's own operations only. A file edited by the user's editor, a shell, or a subprocess raises no frame; an agent merely reading a file that something else changed does raise one, because the read observes a new version.
 - File-kind inspection precedes backend reads, and `list` reports kind before an outside position. A page's `version` may be one write behind its content, and a stalled `changes` consumer grows Host memory because a generation's queue is unbounded; each is a known trade-off recorded in the package README.
 - The `file` resource pushes change, not content, so a preview learns a file moved on without a payload and reads the pages it wants; a failed open keeps following the address, so the agent creating the file brings the tab live without user action.
-- `readBytes` has no shipped consumer yet; Document Preview uses `readAll` for complete-file formats.
+- Office authorization probes use `readBytes` with a one-byte `range`; Document Preview uses the same method without `range` for complete-file formats.
 
 ## Testing
 
-Host specs in `packages/api/workspace-files/tests` exercise header-only scope resolution for live and cold subagent Sessions, the deployment fallback, missing identities, and lookup disposal; the paged read (whole file, nested path, empty file, multi-byte UTF-8, the line window's edges, defaults and refused limits, carriage returns kept); the byte window (defaults, a middle window with more following, tail windows exact and short, past-end and empty files, NUL and invalid UTF-8 round-tripping through base64, version parity with `stat`, the cap as `too-large`, bad ranges, a window of a file far above the cap, and `eof` inferred without a size); `stat`; outside-workspace reads and backend refusals; `list` with containment, truncation, symlink children, and `not-directory`; and the `changes` stream driven by `fs/observed` and filtered by root. Client specs cover the provider's frames, the change feed, unsupported addresses, and registration and disposal. `fs/fs` and `fs-local` specs pin `readByteRange`; `dsh-util-workspace-path` specs pin the file-address grammar. The connection fixture serves `stat`, paged `read`, `list`, and an opt-in `changes` frame for the web e2e suite.
+Host specs in `packages/api/workspace-files/tests` exercise header-only scope resolution for live and cold subagent Sessions, the deployment fallback, missing identities, and lookup disposal; the paged read (whole file, nested path, empty file, multi-byte UTF-8, the line window's edges, defaults and refused limits, carriage returns kept); the byte window (defaults, a middle window with more following, tail windows exact and short, past-end and empty files, NUL and invalid UTF-8 round-tripping through `Uint8Array`, version parity with `stat`, the cap as `too-large`, bad ranges, a window of a file far above the cap, and `eof` inferred without a size); `stat`; outside-workspace reads and backend refusals; `list` with containment, truncation, symlink children, and `not-directory`; and the `changes` stream driven by `fs/observed` and filtered by root. Client specs cover the provider's frames, the change feed, unsupported addresses, and registration and disposal. `fs/fs` and `fs-local` specs pin `readByteRange`; `dsh-util-workspace-path` specs pin the file-address grammar. The connection fixture serves `stat`, paged `read`, `list`, and an opt-in `changes` frame for the web e2e suite.
 
 ## Deferred
 
 - A bound on a `changes` generation's queue.
-- The shipped consumer of `readBytes` (image and binary previews) and any write, search, or media route; the service is read-only.
+- Write and search operations; the service is read-only.
 - Scopes other than `session` in the file address; the grammar leaves room, the provider serves one.
diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md
index 51de0ad5b6..b4ca420042 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md
@@ -25,15 +25,13 @@ Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工
 
 `api/remotes` 和两个根聚合分别引用匹配的 Host/Client 叶子。包导出 `.`、`./client`、`./types`、`./typert` 和 `./remote`，web-app 中单个 `workspace-files` 条目供应两面。Client 插件注入 `['resources', 'remote', 'remote.workspaceFiles']`；资源模型直接从协议包取结果类型，Sidebar 参数声明归文本预览，因此 Client 编译图不再反向依赖 Remote 装配或右栏 UI。
 
-### `workspaceFiles` Remote 命名空间
+### `workspaceFiles` 文件操作
 
-每个 Host 方法首参都是 `WorkspaceFileScope`。Gateway 从线路上的 Session 身份解析它：优先读取 live Session header，cold Session 则只调用 `SessionPersistence.stat`；不会激活 Agent、读取事件正文或回退到父 Session。scope 携带所选 Session id 及其 `cwd`，仅当该 header 没有 `cwd` 时才使用沙箱策略的部署根。Client 传入 Session id，从不自行命名根。七个签名照 `src/index.ts` 的声明：
+每个 Host 方法首参都是 `WorkspaceFileScope`。`workspaceFileScope` Gateway lookup 解析 Session 身份。它优先读取 live Session header，cold Session 则只调用 `SessionPersistence.stat`；不会激活 Agent、读取事件正文或回退到父 Session。scope 携带所选 Session id 及其 `cwd`，仅当该 header 没有 `cwd` 时才使用沙箱策略的部署根。Client 传入 Session id，从不自行命名根。五个签名照 `src/index.ts` 的声明：
 
 ```ts ignore-check
 @Remote async read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
-@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
-@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes>
-@Remote async readRelated(workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal): Promise<WorkspaceFileBytes>
+@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal): Promise<WorkspaceFileBytes>
 @Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
 @Remote async list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
 @Remote({ mode: 'stream' }) changes(workspaceFileScope: WorkspaceFileScope, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
@@ -41,20 +39,20 @@ Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工
 
 - **`stat`** 返回 `WorkspaceFileStat { absolutePath, version, bytes? }`：文件身份、不透明的新鲜度令牌，以及后端报得出时的大小。它只接受普通文件。
 - **`read`** 返回一个行窗口 `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`；`lines` 计页内行数，使只含一个空行的页（`text: ''`、`lines: 1`）与越过文件末尾的页（`lines: 0`）可区分。`range.offset` 是 1 起算的首行，缺省 1；`range.limit` 是最多行数，缺省 `maxLines` 且不得超过。行以 `\n` 结束，末尾的 `\n` 终止最后一行而不是开启一空行；`text` 以 `\n` 连接本页各行且不带终止符；页含最后一行时 `eof` 为 true，越过末尾的 offset 返回 `eof` 为 true 的空页。切页器沿 `streamText` 前进，数过窗口前的行而不保留，把每个窗内片段先按 `maxBytes` 核准再缓冲，并在越过窗口的第一个字符处返回，因此任意大小的文件只花一页内存。页上的 `version` 与 `bytes` 来自流之前的那次 stat。
-- **`readBytes`** 返回一个原始字节窗口 `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`。`range.offset` 是 0 起算的首字节，缺省 0；`range.length` 是最多字节数，缺省 `maxBytes` 且不得超过。`data` 为 base64，文件在窗内结束则短于 `length`，位于或越过末尾则为空；窗口含最后一个字节时 `eof` 为 true。不做任何解码，也不按二进制拒绝。`read` 按行分页、绝不按字节；字节窗口走 `readBytes`。
-- **`readAll` 与 `readRelated`** 在 `maxFileBytes` 上限内返回完整的 `WorkspaceFileBytes`。`readRelated` 从基准文件所在目录解析相对文件系统路径；Host 对两个文件执行相同的普通文件检查和后端读取权限。[Document Preview](2026-09-08-document-preview-operations.zh.md) 负责其加载与地址语义。
+- **`readBytes`** 返回原生字节、文件元数据、偏移量和 EOF。必填选项对象未传 `range` 时，在 `maxFileBytes` 上限内完整读取；传入时，在 `maxBytes` 上限内读取有界窗口。`range: {}` 使用零偏移和配置的窗口上限；窗口可读取超过完整文件上限的文件。[二进制传输决议](2026-09-17-workspace-file-binary-transfer.zh.md)负责 Remote 响应编码。
+- **`baseFile`** 独立于 `range` 选择目标解析方式：目标 `path` 必须为相对路径，从基准文件所在目录解析。Host 对两个文件执行普通文件检查，并保留后端读取权限。[Document Preview](2026-09-08-document-preview-operations.zh.md)负责内容加载与地址语义。
 - **`list`** 返回 `WorkspaceDirectoryListing { path, entries, truncated }`：被列目录相对根的工作区路径（根为空串）、其直接子项按后端的稳定名序以 `{ name, type, size? }` 给出，以及 `maxEntries` 是否截断了列表。`type` 为 `file`、`directory` 或 `other`；符号链接子项报告其指向目标的类型，悬空者为 `other`，而打开这样的子项仍会在下文的链接关被拒。dotfile 照常列出，不做任何过滤。
 - **`changes`** 产出 `WorkspaceFileWatchFrame`：在观察队列注册且工作区根解析完成后先发 `{ kind: 'ready' }`，随后为 `{ kind: 'change', change }`。载荷 `WorkspaceFileChange` 对存在的文件为 `{ absolutePath, version }`，对消失的文件为 `{ absolutePath, absent: true }`。来源是工作区根内的 `fs/observed`，不监视操作系统。首次拉取后的观察都会排队，包括根解析期间的观察；取消或插件释放会结束该代流。
 
 ### 线路上的路径
 
-离开服务的路径词汇有两套，每个方法只用其中一套。`read`、`readBytes`、`readAll`、`readRelated`、`stat` 与 `changes` 以 `absolutePath` 命名文件：它在文件系统执行环境中、符号链接已解析的绝对路径（`ctx.fs.processPath(target)`），因此 Client 提供者按绝对路径把变更帧匹配到已打开的地址：Client 把地址路径原样交给 Host，并只按成功的 `stat.absolutePath` 绑定跟随者，不读取会话摘要的 cwd。`list` 说工作区路径——与其 `path` 参数相同的语法，绝对或相对根——因为其消费方是一棵以根为起点的树。该字段叫 `absolutePath` 而不叫 `url`，因为它不是资源地址；地址语法归 `dsh-util-workspace-path` 所有，与资源模型一并描述。`read`、`readBytes`、`readAll`、`readRelated`、`stat` 与 `list` 的输入路径是绝对路径或相对会话工作区根的路径，从不相对后端自己的 cwd。
+离开服务的路径词汇有两套，每个方法只用其中一套。`read`、`readBytes`、`stat` 与 `changes` 以 `absolutePath` 命名文件：它在文件系统执行环境中、符号链接已解析的绝对路径（`ctx.fs.processPath(target)`），因此 Client 提供者按绝对路径把变更帧匹配到已打开的地址：Client 把地址路径原样交给 Host，并只按成功的 `stat.absolutePath` 绑定跟随者，不读取会话摘要的 cwd。`list` 说工作区路径——与其 `path` 参数相同的语法，绝对或相对根——因为其消费方是一棵以根为起点的树。该字段叫 `absolutePath` 而不叫 `url`，因为它不是资源地址；地址语法归 `dsh-util-workspace-path` 所有，与资源模型一并描述。`read`、`readBytes`、`stat` 与 `list` 的输入路径是绝对路径或相对会话工作区根的路径，从不相对后端自己的 cwd；带 `baseFile` 的 `readBytes` 从基准文件所在目录解析目标。
 
 `version` 是消费者只比较是否相等、从不解析的不透明字符串：本地后端由设备、inode、大小及纳秒级 mtime 与 ctime 导出，因此内容不变的重写也会改变它。`offset` 在 `read` 上指行、在 `readBytes` 上指字节；两套单位从不混用，二者的 `eof` 都表示窗口到达了文件末尾。
 
 ### 文件检查与工作区包含
 
-`read`、`readBytes`、`readAll`、`readRelated` 与 `stat` 共享普通文件检查，之后依赖文件系统后端的读取权限。`list` 共享路径检查，但还会检查工作区包含关系；`changes` 则把观察过滤到工作区根内。服务执行以下检查：
+`read`、`readBytes` 与 `stat` 共享普通文件检查，之后依赖文件系统后端的读取权限。`list` 共享路径检查，但还会检查工作区包含关系；`changes` 则把观察过滤到工作区根内。服务执行以下检查：
 
 1. **路径本身。** `lstat` 在跟随任何东西之前检查路径：缺失路径为 `not-found`；符号链接——不论指向哪里，包括指回工作区内——对文件方法为 `not-regular-file`（kind 为 `symlink`），对 `list` 为 `not-directory`。空路径是 `gateway/bad-request`。
 2. **`list` 的工作区包含。** 目录解析为目标，由 `ctx.fs.contains(root, target)` 判定，其中 `root` 是从所选 Session header 解析出的 `WorkspaceFileScope.workspaceRoot`。`..` 爬出或根外绝对目录为 `outside-workspace`。`changes` 对观察到的目标使用相同的后端包含判定。
@@ -73,7 +71,7 @@ Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工
 | `workspace-file/outside-workspace` | `list` 的目标不在工作区根内 | `{ path }` |
 | `workspace-file/too-large` | 一页文本或字节窗口超过 `maxBytes`，或全文读取超过 `maxFileBytes` | `{ path, limit }` |
 | `workspace-file/not-text` | 到页末为止的非法 UTF-8，或样本或页内的 NUL 字节（仅 `read`） | `{ path }` |
-| `workspace-file/not-regular-file` | 对非普通文件执行 `read`、`readBytes`、`readAll`、`readRelated` 或 `stat` | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
+| `workspace-file/not-regular-file` | 对非普通文件执行 `read`、`readBytes` 或 `stat` | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
 | `workspace-file/not-directory` | 对非目录执行 `list` | `{ path, kind: 'file' \| 'symlink' \| 'other' }` |
 | `workspace-file/unsupported-address` | Client 铸出：本提供者无法服务的资源地址 | `{ address }` |
 | `workspace-file/unknown-workspace` | Client 铸出：不携带 Session 的 `absolute` 地址 | `{ address }` |
@@ -109,7 +107,7 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`，存
 
 ### 相关记录
 
-[资源模型](2026-09-05-client-resource-model.zh.md)拥有 `ctx.resources`、`useResource`、`dsh-resource://<type>/…` 地址语法以及"每个地址一份资源"的推理；[文本预览与文件树](../feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md)是 `read`、`list` 与 `file` 提供者随包交付的消费方；[右侧 Sidebar 停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)是它们打开进去的界面；[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)是经 HTTP 供文件被否决之处。任何在这套体系上扩展的人都经 `remote.workspaceFiles` 触达同样的七个方法、经 `useResource<'file'>` 触达同样的 `file` 资源；线路类型以 `@deepseek-ai/dsh-api-workspace-files/types` 发布。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)负责 Host 读取权限与 HTML 安全取舍；[Document Preview](2026-09-08-document-preview-operations.zh.md)负责内容加载和逐 tab 新鲜度。
+[资源模型](2026-09-05-client-resource-model.zh.md)拥有 `ctx.resources`、`useResource`、`dsh-resource://<type>/…` 地址语法以及"每个地址一份资源"的推理；[文本预览与文件树](../feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md)是 `read`、`list` 与 `file` 提供者随包交付的消费方；[右侧 Sidebar 停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)是它们打开进去的界面；[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)是经 HTTP 供文件被否决之处。任何在这套体系上扩展的人都经 `remote.workspaceFiles` 触达同样的五个方法、经 `useResource<'file'>` 触达同样的 `file` 资源；线路类型以 `@deepseek-ai/dsh-api-workspace-files/types` 发布。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)负责 Host 读取权限与 HTML 安全取舍；[Document Preview](2026-09-08-document-preview-operations.zh.md)负责内容加载和逐 tab 新鲜度。
 
 ## Alternatives considered
 
@@ -117,7 +115,7 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`，存
 
 **带有反向 UI 依赖的双面包。** 拆包选择源于 `api/remotes` 引用 Client 叶子后形成的两条工程引用环：资源模型为了结果类型引用 Remote 装配，文件提供者为了 Sidebar 参数表引用右栏 UI。TypeScript 以 `TS6202` 拒绝这些环。[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)取代拆包选择：结果类型直接取自协议包，Sidebar 参数注册移至文本预览；保留两个根聚合中的显式编译入口。
 
-**经 HTTP 供工作区文件。** 已被[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)以 origin 理由否决且未重议：`read` 与 `readBytes` 经认证的 Remote 载体传送纯文本与 base64，因此不供文档、不铸 URL，也不产生 origin 问题。
+**提供可导航的工作区文档。** 因源隔离问题不采用；[二进制传输](2026-09-17-workspace-file-binary-transfer.zh.md)返回 multipart 数据，HTML 仍隔离在 Blob iframe 中。
 
 **文件读取采用“日志可达”或工作区包含授权。** 唯一把文件内容送过线路的先例——命令附件——只授权出现在会话日志里的文件，这会排除手输路径；工作区包含则会排除 Session 后端其他位置的可读文件。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)改为以后端读取决策为准，只对工作区形态的操作保留包含限制。
 
@@ -138,14 +136,14 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`，存
 - 变更帧只报告 agent 自己的操作。用户编辑器、shell 或子进程改动的文件不产生帧；agent 仅仅读取一个被别处改动的文件却会产生帧，因为读取观察到了新版本。
 - 文件类型检查先于后端读取，`list` 也先报种类再报根外位置。页的 `version` 可能落后内容一次写入，停滞的 `changes` 消费者会让 Host 内存增长，因为一代流的队列无界；每一条都是包 README 记录在册的已知取舍。
 - `file` 资源推送变更而非内容，因此预览不靠载荷就得知文件已更新并读取它想要的页；失败的打开继续跟随地址，因此 agent 创建该文件时 tab 无需用户动作即恢复正常。
-- `readBytes` 尚无随包交付的消费方；Document Preview 对整文件格式使用 `readAll`。
+- Office 授权探测使用带单字节 `range` 的 `readBytes`；Document Preview 对整文件格式使用同一方法并省略 `range`。
 
 ## Testing
 
-`packages/api/workspace-files/tests` 中的 Host spec 覆盖 live 与 cold subagent Session 的 header-only scope 解析、部署 fallback、缺失身份与 lookup 释放；分页读取（整文件、嵌套路径、空文件、多字节 UTF-8、行窗口边界、缺省与拒绝的 limit、保留回车）；字节窗口（缺省、中段与尾窗、越界与空文件、base64 往返、版本、上限、坏范围以及无大小时的 `eof`）；`stat`；工作区外读取及后端拒绝；`list` 的包含、截断、符号链接与 `not-directory`；以及由 `fs/observed` 驱动并按根过滤的 `changes`。Client spec 覆盖提供者帧、变更流、不支持地址及注册与释放。`fs/fs` 与 `fs-local` spec 钉住 `readByteRange`；`dsh-util-workspace-path` spec 钉住文件地址语法。connection fixture 为 web e2e 套件提供 `stat`、分页 `read`、`list` 与一帧可选启用的 `changes`。
+`packages/api/workspace-files/tests` 中的 Host spec 覆盖 live 与 cold subagent Session 的 header-only scope 解析、部署 fallback、缺失身份与 lookup 释放；分页读取（整文件、嵌套路径、空文件、多字节 UTF-8、行窗口边界、缺省与拒绝的 limit、保留回车）；字节窗口（缺省、中段与尾窗、越界与空文件、`Uint8Array` 往返、版本、上限、坏范围以及无大小时的 `eof`）；`stat`；工作区外读取及后端拒绝；`list` 的包含、截断、符号链接与 `not-directory`；以及由 `fs/observed` 驱动并按根过滤的 `changes`。Client spec 覆盖提供者帧、变更流、不支持地址及注册与释放。`fs/fs` 与 `fs-local` spec 钉住 `readByteRange`；`dsh-util-workspace-path` spec 钉住文件地址语法。connection fixture 为 web e2e 套件提供 `stat`、分页 `read`、`list` 与一帧可选启用的 `changes`。
 
 ## Deferred
 
 - 给 `changes` 一代流的队列加上限。
-- `readBytes` 随包交付的消费方（图片与二进制预览）以及任何写入、搜索或媒体路由；本服务只读。
+- 写入和搜索操作；本服务只读。
 - 文件地址中 `session` 之外的作用域；语法留有余地，提供者只服务一个。
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
index 414fda0806..ecb554c14d 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
-2026-09-08-document-preview-operations.md: be3a835a6296cb28d9a90c5c5e8b9bf7367598c2
-2026-09-08-document-preview-operations.zh.md: efb87e16cc126001c1a6eb2bf938124d7e00044a
+2026-09-08-document-preview-operations.md: 0b90c17ba94d0c7cd30afb0a6e6a033f8f12d0df
+2026-09-08-document-preview-operations.zh.md: ec9c208c97dfe75afdb0915c655d9c1c7b4d42ff
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
index be3a835a62..0b90c17ba9 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
@@ -16,9 +16,9 @@ Document Preview separates resource observation from content reads. The [resourc
 
 Readable files use `dsh-resource://file/session/<sessionId>/<path>`. The path may be workspace-relative or absolute; an encoded absolute path retains its leading slash. `fileAddressFor` always emits this Session-address form. The provider and Preview RPC take the Session only from that address, never from the current selection, first holder, or owning tab. A Session-less `absolute` URI cannot be read; the provider reports `workspace-file/unknown-workspace`. Session authorization is a file-protocol rule, not an additional Resource identity.
 
-[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists supported alternatives and remembers a manual choice per tab. Plain text remains available for unknown extensions and text-compatible renderers. Registered binary suffixes determine text compatibility independently of loading mode; HTML and SVG remain outside those suffixes and retain source viewing. A single candidate renders no viewer control. Registered binary suffixes omit plain text; known binary suffixes without a renderer show an unsupported state without reading the file ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls existing `read`, `readAll`, and `readRelated` through ordinary injection and decodes bytes in its own `rpc.ts`. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session.
+[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists supported alternatives and remembers a manual choice per tab. Plain text remains available for unknown extensions and text-compatible renderers. Registered binary suffixes determine text compatibility independently of loading mode; HTML and SVG remain outside those suffixes and retain source viewing. A single candidate renders no viewer control. Registered binary suffixes omit plain text; known binary suffixes without a renderer show an unsupported state without reading the file ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls `ctx.remote.workspaceFiles.read` for text and `ctx.remote.workspaceFiles.readBytes` for native bytes, with `baseFile` for related resources. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session.
 
-Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array<ArrayBuffer>` data; Host transport remains base64. Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `<img>` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL.
+Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array<ArrayBuffer>` data; Host transport uses the [binary workspace file transfer](2026-09-17-workspace-file-binary-transfer.md). Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `<img>` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL.
 
 PDF.js's official TextLayerBuilder owns selection boundaries and copy normalization over the width-fitted canvas, with shared page cleanup and a component-owned resize observer. Responsive sizing uses the CSS `scale` property independently of PDF.js's page rotation and translation transforms. Its end-of-content marker and stacking rules constrain selection in blank regions; line-break highlighting is suppressed. Per-page cancellation uses the builder's cleanup rather than aborting the first page's signal, because the official selection listeners are shared across pages.
 
@@ -28,7 +28,7 @@ PDF.js's official TextLayerBuilder owns selection boundaries and copy normalizat
 
 **Methods attached to an Iterator or its values.** This conflates observation with commands and repeats capability identity in data frames. Frames carry data and failures; explicit Preview RPC callbacks perform reads.
 
-**A core public-projection factory, or the same assembly inside `open`.** Separate stream values, operations bundles, and public interfaces add assembly without another current consumer that needs it. Preview's shared RPC adapter already keeps Session decoding and base64 out of renderers. Resource offers no provider-agnostic command interface or opening-bound command lifetime; adding either needs consumer evidence beyond file preview.
+**A core public-projection factory, or the same assembly inside `open`.** Separate stream values, operations bundles, and public interfaces add assembly without another current consumer that needs it. Preview's shared RPC adapter already keeps Session addressing and byte transport out of renderers. Resource offers no provider-agnostic command interface or opening-bound command lifetime; adding either needs consumer evidence beyond file preview.
 
 **UI Session as extra Resource identity, or authorization from the first holder or current selection.** A retained tab can belong to a different Session from the selected one, and the UI location does not identify the addressed file. Encoding the required Session in the file address preserves Host authorization while letting all readers of one address share observation.
 
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
index efb87e16cc..ec9c208c97 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
@@ -16,9 +16,9 @@ Document Preview 将资源观察与内容读取分开。[资源模型](2026-09-0
 
 可读取的文件使用 `dsh-resource://file/session/<sessionId>/<path>`。路径可以相对工作区，也可以是绝对路径；编码后的绝对路径保留前导斜杠。`fileAddressFor` 始终生成这种 Session 地址。提供方与 Preview RPC 只从该地址取 Session，不取当前选择、首个持有者或 tab 所属 Session。不带 Session 的 `absolute` URI 无法读取；提供方报告 `workspace-file/unknown-workspace`。Session 授权是文件协议规则，不是额外的 Resource 身份。
 
-[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册；组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册，其次比较后缀长度和注册顺序。工具栏列出受支持的候选，按 tab 记住手动选择。未知扩展名及文本兼容的渲染器仍可使用纯文本。文本兼容性由注册的二进制后缀决定，与加载方式无关；HTML 和 SVG 不属于二进制后缀，保留源码查看。只有一个候选时不显示查看器控件。注册声明为二进制的后缀不提供纯文本；已知二进制后缀没有注册渲染器时不发起读取，并显示不支持预览的空态（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。子组件收到累积文本或完整原生字节、原始资源地址，以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 经普通注入调用既有 `read`、`readAll` 与 `readRelated`，在自己的 `rpc.ts` 解码字节。刷新仍按 tab 独立进行，不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。
+[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册；组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册，其次比较后缀长度和注册顺序。工具栏列出受支持的候选，按 tab 记住手动选择。未知扩展名及文本兼容的渲染器仍可使用纯文本。文本兼容性由注册的二进制后缀决定，与加载方式无关；HTML 和 SVG 不属于二进制后缀，保留源码查看。只有一个候选时不显示查看器控件。注册声明为二进制的后缀不提供纯文本；已知二进制后缀没有注册渲染器时不发起读取，并显示不支持预览的空态（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。子组件收到累积文本或完整原生字节、原始资源地址，以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 通过 `ctx.remote.workspaceFiles.read` 读取文本，通过 `ctx.remote.workspaceFiles.readBytes` 读取原生字节，关联资源使用 `baseFile`。刷新仍按 tab 独立进行，不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。
 
-Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array<ArrayBuffer>` 数据；Host 传输保持 base64。发布后的缓冲区只读借用，绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行，字体和解码数据以相同版本随包发布，转移输入前先复制，以保留 Preview 的缓冲区。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时，HTML 在 Blob iframe 中运行，设置 `sandbox="allow-scripts"`，不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责；不透明源 iframe 创建自己的资源 Blob，因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL，在 `<img>` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度；较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中，较高的图片扩展共享滚动区的纵向范围（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此脚本保持不可执行，也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。
+Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array<ArrayBuffer>` 数据；Host 传输使用[工作区文件二进制传输](2026-09-17-workspace-file-binary-transfer.zh.md)。发布后的缓冲区只读借用，绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行，字体和解码数据以相同版本随包发布，转移输入前先复制，以保留 Preview 的缓冲区。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时，HTML 在 Blob iframe 中运行，设置 `sandbox="allow-scripts"`，不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责；不透明源 iframe 创建自己的资源 Blob，因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL，在 `<img>` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度；较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中，较高的图片扩展共享滚动区的纵向范围（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此脚本保持不可执行，也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。
 
 PDF.js 官方 TextLayerBuilder 在适配宽度的 canvas 上负责选择边界和复制规范化，共享页面清理，并使用由组件拥有的 resize observer。响应式尺寸适配使用独立的 CSS `scale` 属性，与 PDF.js 的页面旋转和平移变换组合。其内容结束标记和堆叠规则限制空白区域中的选择；换行高亮被抑制。逐页取消使用 builder 的清理操作，而不 abort 第一页的信号，因为官方选择监听器跨页面共享。
 
@@ -28,7 +28,7 @@ PDF.js 官方 TextLayerBuilder 在适配宽度的 canvas 上负责选择边界
 
 **把方法挂到 Iterator 或其值上。** 这会混淆观察与命令，并在数据帧中重复能力身份。帧携带数据和失败；显式 Preview RPC 回调负责读取。
 
-**核心公开投影工厂，或在 `open` 内做同样的组装。** 分开的流值、operations 组合与公开接口增加了组装步骤，没有另一个当前消费方需要它。Preview 的共享 RPC 适配已让渲染器无需解码 Session 和 base64。Resource 不提供与提供方无关的命令接口，也不提供绑定于打开实例的命令生命周期；增加任一种都需要文件预览之外的消费方证据。
+**核心公开投影工厂，或在 `open` 内做同样的组装。** 分开的流值、operations 组合与公开接口增加了组装步骤，没有另一个当前消费方需要它。Preview 的共享 RPC 适配已让渲染器无需处理 Session 寻址和字节传输。Resource 不提供与提供方无关的命令接口，也不提供绑定于打开实例的命令生命周期；增加任一种都需要文件预览之外的消费方证据。
 
 **把 UI Session 作为额外 Resource 身份，或由首个持有者、当前选择决定授权。** 保留的 tab 可以属于不同于当前选择的 Session，UI 所在位置也不能标识地址指向的文件。将所需 Session 编入文件地址，既保留 Host 授权，也让同地址的所有读者共享观察。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml
index 9e68a09547..1d1ecb3a28 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
-2026-09-09-profile-resolution-generations.md: ced79eefc8c46a43cabd5b6a79db2644526c022f
-2026-09-09-profile-resolution-generations.zh.md: 98c509488aaeaa8d1b5e722bf6e3ea6346d45c46
+2026-09-09-profile-resolution-generations.md: 649c6c358fece5557031b4a21f3d3ebdd9dac8f7
+2026-09-09-profile-resolution-generations.zh.md: 4e84cc1f1b763c88b4ae96c4c44ae79de0d4c0d6
diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
index ced79eefc8..649c6c358f 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
+++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
@@ -8,11 +8,11 @@ English | [中文](2026-09-09-profile-resolution-generations.zh.md)
 
 A profile loads plugin rows from its own package project, while Harness packages and packages carried by selected bundles can live outside that project's ordinary dependency tree. Bridging the trees through shared symlinks, profile-owned links, or packaged-executable proxy packages persists package selections across processes and installations. Those files require reconciliation and locking, expose generated proxy manifests to metadata readers, and cannot represent a process-local change atomically.
 
-The runtime design keeps installation-first, ordered-bundle, and local-before-fallback precedence. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement accepts only additive package sets and never mutates a live table entry by entry.
+The runtime design keeps installation-first, ordered-bundle, and local-before-fallback precedence. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement preserves existing package mappings and local package names, permits linked-root membership changes, and never mutates a live table entry by entry.
 
 ## Decision
 
-Profile startup computes one immutable `RuntimeResolution` and installs it into Node's ESM and CommonJS resolvers. Runtime is the only resolution backend; there is no mode selector or disk materializer. `PluginPackages.replace()` publishes a complete additive successor with one reference replacement.
+Profile startup computes one immutable `RuntimeResolution` and installs it into Node's ESM and CommonJS resolvers. Runtime is the only resolution backend; there is no mode selector or disk materializer. `PluginPackages.replace()` publishes a complete successor with one reference replacement.
 
 ### One selection algorithm
 
@@ -62,19 +62,26 @@ The [source launcher](2026-07-29-dsh-source-launch-tsx-esm.md) uses tsx's ESM-on
 
 For example, `@deepseek-ai/dsh-tools` creates its scheduler key with `Symbol()`. A Tools instance loaded from `lib/` cannot expose that scheduler through a key imported from the separate `src/` module instance. Source launches keep Tools and AgentLoop in `src/`; plain Node launches keep them in `lib/`. The scheduler retains its local Symbol; correct imports share one module instance.
 
+The source launcher does not install a CommonJS TypeScript hook. `createRequire().resolve()` still selects the package's published JavaScript entry and requires that file to exist. Source-mode resolution tests therefore use fixture-provided CommonJS files; checks of real installation CommonJS entries run with build outputs present.
+
+<a id="immutable-generations"></a>
 ### Immutable generations
 
-A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured.
+A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required dependency-graph manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured.
 
-Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. A generation hit and a successful native selection can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Calls with explicit CommonJS paths or non-default conditions never reuse a default-resolution cache entry.
+Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. Profile-importer hits and successful native selections can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Linked importer routes are not cached: each resolution reads current peer declarations at the ancestor positions it visits. Explicit CommonJS paths bypass interception entirely; non-default conditions never reuse a default-resolution cache entry.
 
-The launcher constructs one startup generation. The service accepts an additive successor, but no package-manager transaction invokes replacement in this implementation.
+Linked-root membership is immutable within a generation. A successor may add or remove roots without restarting the process. When no remaining root covers a directory, subsequent resolutions there use native Node lookup, including new requests from already loaded modules. A request may then select a development copy or fail because the package is absent. Removing interception does not unload modules, replace existing references, or clear Node's own caches.
+
+The router retains the real target of each successfully published link name for its lifetime, solely to validate successors. Removing a root does not erase that record or keep its directory intercepted. Re-adding the same name and target is allowed; a different target is rejected because Node caches real paths. Failed publication changes neither the current generation nor the recorded targets.
+
+The launcher constructs one startup generation. The service accepts a complete successor, but no package-manager transaction invokes replacement in this implementation.
 
 ### Shared ESM and CommonJS rule
 
 The resolver uses `node-addon-require-builtin` to read `internal/modules/esm/loader` and `internal/modules/cjs/loader`. The ESM adapter wraps the per-thread singleton `CascadedLoader` resolve methods. The CommonJS adapter wraps the internal builtin's `Module._resolveFilename`; that `Module` is the same object exported by `node:module`.
 
-Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profile scope, and explicit calls outside the supported lookup. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same local, interception, and native-after-interception package order with the request's conditions, while Node retains exact target resolution. For a scoped bare request, a package self-reference keeps the original parent even when an npm alias gives its installed directory another name. A profile-local or plugin-private package also keeps the original parent when Node resolves the requested entry before the virtual shared-fallback position; a CommonJS package directory without `exports` does not suppress the fallback when only its requested subpath is absent. Otherwise the router uses an interception hit through that entry's declaring anchor or continues native lookup after the virtual fallback. Explicit CommonJS path lists apply the same insertion rule independently to each path in caller order.
+Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profiles and registered linked roots, and every CommonJS request with explicit `paths`. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same package order with the request's conditions, while Node retains exact target resolution. Package self-references keep the original parent, including npm aliases. Profiles have a fixed interception position; linked importers apply current peer eligibility at each native ancestor position. Native CommonJS probes determine whether a legacy subpath miss continues to another position. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) owns the complete selection rule.
 
 The adapters call the captured native resolver after routing. Node remains responsible for exports, import and require conditions, main files, subpaths, extensions, native caches, and error codes. Routed ESM failures replace the internal lookup anchor in Node's diagnostic with the original importer. A selected package's invalid export or missing target does not trigger another same-name candidate. CommonJS does not replace `_findPath` or reproduce `_resolveFilename`.
 
@@ -84,7 +91,7 @@ The guarantee covers Node's default `import`, `import()`, `import.meta.resolve`,
 
 The runtime resolution lists the packages it supplies; Loader entries form the active plugin list. Consumers keep using Loader's existing entry lifecycle and filter the entries relevant to their own scope. Consumers that need package metadata pass a specifier and owning tree base URL to a lightweight `app-boot` service without requiring a `./package.json` export. An installed runtime resolution is authoritative, including a miss; a service created without one retains native lookup for low-level embedders.
 
-The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. A repeated query uses the same generation and therefore cannot drift from the route used for the import. Non-Node importers that need package metadata must explicitly implement the same deterministic resolver interface.
+The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. Package-directory queries use the same package selection, including current ancestor peer declarations for linked importers, but do not validate the requested subpath or load its file. Non-Node importers that need package metadata must explicitly implement the same resolver interface.
 
 The implementation lives under `app-boot/src/profile-resolution/`. `service.ts` provides the long-lived `ctx.pluginPackages` and owns the main-thread interception and the Worker resolution lifetime; `resolver.ts` implements runtime resolution lookup and the Node Internal adapters; `worker-bootstrap.ts` installs the inherited runtime resolution in one thread. Profile selection and runtime resolution construction remain in `profile.ts`. Workers reference the bootstrap only through the public `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` export.
 
@@ -100,17 +107,17 @@ New Workers inherit the latest published generation. Existing Workers keep the g
 
 A caller adding a package completes its pnpm transaction before constructing a successor generation. Replacement rejects any generation that changes the directory or version of an existing package. The caller publishes an additive successor before mounting the new Loader row; this implementation does not provide that package transaction. A mount failure may leave the package installed but inactive.
 
-Replacing, upgrading, or removing an already loaded package requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. Generation replacement does not claim to unload modules.
+Changing or removing an existing runtime package mapping, or removing a recorded profile-local package name, requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. These restrictions do not prohibit removing a linked root from the interception scope. Generation replacement does not claim to unload modules.
 
 ### Filesystem and runtime carriers
 
-The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor, and symlinks anywhere in the profile tree are ordinary filesystem content without dedicated recognition. Profile-local package metadata and bundle dependency discovery follow the same Node lookup; ordinary pnpm-installed packages retain native precedence. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records the complete order. Writable profile state and package-manager transactions remain outside the resolver.
+The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor. Construction records links to directories outside the shared profiles tree and the active profile itself, including targets without their own manifest. Installation-scope package directories stay outside linked interception even when a broader linked root contains them. Eligible linked importers retain native ancestor order and per-position peer mappings. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records precedence and scope. Writable profile state and package-manager transactions remain outside the resolver.
 
 Runtime resolution requires a supported Node Internal loader interface. The Electron Host runs through the Electron executable with `ELECTRON_RUN_AS_NODE=1`; packaged builds read the dsh tree from ASAR and map executable ASAR entries to electron-builder's unpacked tree. Pkg and Electron use the same runtime resolution mechanism as ordinary Node launches.
 
 ### Performance and verification
 
-Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Ordinary hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. A CommonJS request may perform one native probe followed by one routed resolution when a local package directory exists without `exports` but lacks the requested subpath. Out-of-scope calls do not read manifests and cache only whether each parent belongs to the profile scope.
+Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Profile hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. Linked requests for supplied package names read the visited ancestor manifests and do not cache the selected route. CommonJS can probe multiple positions when legacy subpaths are missing. Out-of-scope calls do not read manifests and cache only whether each parent has an interception layer.
 
 One-off local measurements taken during implementation ran built JavaScript under plain Node in fresh processes and compared it with a process that installed no hook. The measurement script and results are not committed, and these figures are not a benchmark or CI budget. Seven alternating rounds covered outside, profile-local, and fallback imports through dynamic import, `import.meta.resolve`, require, and `require.resolve`. Across Node 22.19, 24.18, and 26.8, the largest positive hot-path median was 4.5%. On Node 24.18, a 256-package cold workload regressed by at most 11.2% and generation construction took 16.027 ms median; the 32-package local `require.resolve` case added 1.033 ms across the batch (+34.7%) from fixed startup cost.
 
@@ -135,7 +142,7 @@ Behavior tests exercise root order, transitive and peer dependencies, local and
 ## Verification
 
 - One eager computation supplies the runtime resolution; startup neither writes nor retires module-resolution data.
-- [Generation tests](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) cover installation and selected-bundle graphs with ordinary directories and recursive symlinks, including different dependency versions beside logical and real anchors.
+- [Generation tests](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) cover installation and selected-bundle graphs with ordinary directories and recursive symlinks, including different dependency versions beside logical and real anchors. They also cover linked-root removal, same-target restoration, overlapping roots, native misses, new requests from loaded modules, and relink rejection after removal.
 - [Source-launch tests](../../../../apps/cli/tests/source-launch.compat.spec.ts) and [built-bin tests](../../../../apps/cli/tests/built-bin.e2e.ts) run both profile layouts through the real CLI. They assert ESM/CJS versions, loaded paths, per-format dependency identity, and consistent Tools/AgentLoop module instances with an accessible scheduler key.
 - Pkg and Electron carriers select runtime resolution; Electron executes its Host in Node mode from the ASAR-backed dsh tree while native executable entries remain unpacked.
 - ESM and CommonJS adapters share one router and delegate final resolution to Node without `module.registerHooks` or `_findPath` replacement.
@@ -145,4 +152,4 @@ Behavior tests exercise root order, transitive and peer dependencies, local and
 
 ## Consequences
 
-Runtime startup avoids disk mutation and proxy manifests while retaining package-precedence rules. Real-directory anchors align dependency discovery with default Node loading and tsx workspace mapping, including cases where a logical symlink path would select another version. The implementation accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker; it provides no disk-only backend or dual comparison mode. Generation replacement remains additive until the product owns module-cache invalidation and Worker restart.
+Runtime startup avoids disk mutation and proxy manifests while retaining package-precedence rules. Real-directory anchors align dependency discovery with default Node loading and tsx workspace mapping, including cases where a logical symlink path would select another version. The implementation accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker; it provides no disk-only backend or dual comparison mode. Package mappings and local package names remain additive; linked-root membership may change without unloading modules.
diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md
index 98c509488a..4e84cc1f1b 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md
@@ -8,11 +8,11 @@ Status: implemented
 
 profile 从自己的包项目加载插件配置项，而 Harness 包和所选 bundle 携带的包可能位于该项目普通依赖树之外。通过共享 symlink、profile 自有链接或打包可执行文件的代理包连接两棵依赖树，会让选包结果跨进程和安装版本持续存在。这些文件需要协调和锁来维护，并向元数据读取方暴露生成的代理 manifest（元数据清单），也无法原子表示进程内变更。
 
-运行时设计保留安装优先、有序 bundle 和本地包优先于 fallback 的顺序。它覆盖插件模块内部的 import 以及 Loader 配置项的 import，并在主线程和 Harness 自有 Worker 中工作。generation 替换只接受新增包的集合，不会逐项修改正在使用的表。
+运行时设计保留安装优先、有序 bundle 和本地包优先于 fallback 的顺序。它覆盖插件模块内部的 import 以及 Loader 配置项的 import，并在主线程和 Harness 自有 Worker 中工作。generation 替换保留既有包映射和本地包名，允许调整 linked root 集合，不会逐项修改正在使用的表。
 
 ## Decision
 
-profile 启动生成一个不可变 `RuntimeResolution`，并将其安装到 Node 的 ESM 与 CommonJS 解析器。runtime 是唯一的解析后端，不提供模式选择器或磁盘物化器。`PluginPackages.replace()` 通过一次引用替换发布完整的新增型后继 generation。
+profile 启动生成一个不可变 `RuntimeResolution`，并将其安装到 Node 的 ESM 与 CommonJS 解析器。runtime 是唯一的解析后端，不提供模式选择器或磁盘物化器。`PluginPackages.replace()` 通过一次引用替换发布完整的后继 generation。
 
 ### 唯一选包算法
 
@@ -62,19 +62,26 @@ ESM `import` 和 CommonJS `require` 都选中这些版本。在每种模块格
 
 例如，`@deepseek-ai/dsh-tools` 使用 `Symbol()` 创建 scheduler 键。从 `lib/` 加载的 Tools 实例，无法通过另一个 `src/` 模块实例导入的键暴露该 scheduler。源码启动让 Tools 与 AgentLoop 都位于 `src/`；普通 Node 启动让两者都位于 `lib/`。scheduler 保留模块本地的 Symbol；正确的 import 共享同一个模块实例。
 
+源码启动器不安装 CommonJS TypeScript 钩子。`createRequire().resolve()` 仍选择包发布的 JavaScript 入口，并要求该文件存在。因此，源码模式的解析测试使用 fixture 提供的 CommonJS 文件，真实安装包的 CommonJS 入口检查则在构建产物存在时运行。
+
+<a id="immutable-generations"></a>
 ### 不可变 generation
 
-一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用，完整调用只读该引用。generation 构造在发布前读取所有必需 manifest；失败时当前 generation 不变。发布成功只替换一个引用，执行中的调用可以继续使用它已捕获的 generation。
+一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用，完整调用只读该引用。generation 构造在发布前读取依赖图所需的全部 manifest；失败时当前 generation 不变。发布成功只替换一个引用，执行中的调用可以继续使用它已捕获的 generation。
 
-选包缓存和包元数据缓存归 generation 所有。发布下一代后，旧 generation 在调用方退出后自然不可达，不逐项清理缓存。generation 命中和原生解析成功结果可以缓存，但 generation 未命中会重新扫描，因此未命中后安装的 profile 本地包会通过原生查找变为可见。显式 CommonJS paths 或非默认 conditions 不得复用默认解析缓存。
+选包缓存和包元数据缓存归 generation 所有。发布下一代后，旧 generation 在调用方退出后自然不可达，不逐项清理缓存。profile importer 的命中和原生解析成功结果可以缓存，但 generation 未命中会重新扫描，因此未命中后安装的 profile 本地包会通过原生查找变为可见。linked importer 的路由不缓存，每次解析读取所访问祖先位置当前的 peer 声明。显式 CommonJS paths 完全绕过拦截，非默认 conditions 不复用默认解析缓存。
 
-launcher 只构造启动 generation。服务接受新增型后继 generation，但本实现没有包管理器事务调用替换操作。
+linked root 集合在一个 generation 内不可变。后继 generation 可以增加或移除 root，无需重启进程。目录不再被任何剩余 root 覆盖时，该目录后续的解析使用原生 Node 查询，包括已加载模块发起的新请求。请求可能因此选中开发副本，也可能因缺包而失败。移除拦截不会卸载模块、替换已有引用或清空 Node 自身的缓存。
+
+解析器在自身生命周期内保留每个已成功发布的 link 名称对应的真实目标，仅用于校验后继 generation。移除 root 不会抹掉该记录，也不会让其目录继续被拦截。同名、同目标可以重新加入；不同目标会被拒绝，因为 Node 缓存真实路径。发布失败时，当前 generation 和已记录目标均不变。
+
+launcher 只构造启动 generation。服务接受完整的后继 generation，但本实现没有包管理器事务调用替换操作。
 
 ### ESM 与 CommonJS 共用规则
 
 resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader` 和 `internal/modules/cjs/loader`。ESM 适配器包装每线程单例 `CascadedLoader` 的 resolve 方法。CommonJS 适配器包装内部 builtin 导出的 `Module._resolveFilename`；该 `Module` 与 `node:module` 导出的对象相同。
 
-两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 作用域外 parent 和支持的查找以外的显式调用都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射；外部 bare target 按相同 conditions 遵循本地包、interception 和 native-after-interception 的选包顺序，精确 target 解析仍由 Node 负责。对于作用域内的 bare request，package self-reference 保留原 parent，即使 npm alias 使安装目录使用另一个名称。Node 能在虚拟共享 fallback 之前从 profile 本地包或插件私有包解析到所请求入口时，也保留原 parent；没有 `exports` 的 CommonJS 包目录仅缺少所请求 subpath 时，不会压过 fallback。其他请求在 interception 命中时通过该条目的声明锚点解析，未命中时从虚拟 fallback 之后继续原生查找。显式 CommonJS path 列表按调用方顺序，对每个 path 独立应用相同的插入规则。
+两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 与已记录 linked root 之外的 parent，以及所有带显式 `paths` 的 CommonJS 请求，都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射；外部 bare target 按请求的 conditions 遵循相同选包顺序，精确 target 解析仍由 Node 负责。包自引用保留原 parent，包括 npm alias。profile 使用固定拦截位置，linked importer 则在每个原生祖先位置应用当前 peer 条件。原生 CommonJS 探测决定旧式子路径缺失是否继续查询下一个位置。完整选包规则由[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)统一记录。
 
 适配器完成路由后调用捕获的原生 resolver。exports、import/require conditions、main、subpath、扩展名、原生缓存和错误码仍归 Node 处理。路由后的 ESM 失败会把 Node 诊断中的内部查找锚点替换为原始 importer。选中包的无效 export 或缺失目标不会触发另一个同名候选。CommonJS 不替换 `_findPath`，也不复制 `_resolveFilename`。
 
@@ -84,7 +91,7 @@ resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader
 
 runtime resolution 列出它提供的包；Loader entries 组成活动插件列表，两者不能合并。消费方继续使用 Loader 原有 entry 生命周期，并按自身 scope 过滤相关 entries。需要 package metadata 的消费方将 specifier 和所属树的 base URL 交给 app-boot 中的轻量服务，无需 package 导出 `./package.json`。安装 runtime resolution 后，即使查询未命中也以它为准；底层嵌入方只安装服务而不提供 runtime resolution 时，服务保留 Node 原生查找。
 
-解析器不提供 `imported(entry)`，不观察 ModuleJob，不包装 Entry 方法，不把 fiber 与 import 调用关联，也不替换 registry、tree 或 HMR 方法。重复查询读取同一个 generation，因此不会偏离 import 使用的路线。需要包元数据的非 Node importer 必须显式实现同一个确定性 resolver 接口，不能把调用来源推断重新引入 Node 主路径。
+解析器不提供 `imported(entry)`，不观察 ModuleJob，不包装 Entry 方法，不把 fiber 与 import 调用关联，也不替换 registry、tree 或 HMR 方法。包目录查询使用相同选包规则，包括 linked importer 祖先当前的 peer 声明，但不校验所请求的子路径或加载文件。需要包元数据的非 Node importer 必须显式实现同一个 resolver 接口。
 
 实现集中在 `app-boot/src/profile-resolution/`。`service.ts` 提供长期存在的 `ctx.pluginPackages`，并拥有主线程拦截与 Worker runtime resolution 的生命周期；`resolver.ts` 实现 runtime resolution 查询和 Node Internal 适配器；`worker-bootstrap.ts` 在线程内安装继承的 runtime resolution。profile 选包和 runtime resolution 构造留在 `profile.ts`。Worker 只通过 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` 公开入口引用 bootstrap。
 
@@ -100,17 +107,17 @@ runtime resolution 列出它提供的包；Loader entries 组成活动插件列
 
 添加包的调用方先完成 pnpm 事务，再构造下一代。替换操作会拒绝改变任何既有 package name 的目录或版本。调用方先发布只增加映射的后继 generation，再挂载新的 Loader 配置项；本实现不提供该包事务。挂载失败可以留下已安装但未启用的包。
 
-替换、升级或删除已加载包需要重启，因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。generation 换代不声称卸载模块。
+修改或删除既有运行时包映射，或删除已记录的 profile 本地包名，需要重启，因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。这些限制不禁止从拦截范围移除 linked root。generation 换代不声称卸载模块。
 
 ### 文件系统与运行时载体
 
-解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置；其余包名把该目录当作普通祖先，profile 树内任何位置的软链接都是普通文件系统内容，没有专门识别。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找；正常由 pnpm 安装的包保留原生优先级。完整顺序见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。
+解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置；其余包名把该目录当作普通祖先。构造时记录目标同时位于共享 profiles 树和当前 profile 自身之外的目录链接，包括没有自身 manifest 的目标。installation 作用域包目录不参与 linked 拦截，即使更宽的 linked root 包含它们。符合条件的 linked importer 保留原生祖先顺序与逐位置的 peer 映射。优先级和范围见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。
 
 运行时解析要求受支持的 Node Internal loader 接口。Electron Host 通过设置 `ELECTRON_RUN_AS_NODE=1` 的 Electron 可执行文件运行；打包构建从 ASAR 读取 dsh 依赖树，并把 ASAR 中的可执行条目映射到 electron-builder 的 unpacked 目录。pkg 与 Electron 使用和普通 Node 启动相同的 runtime resolution 机制。
 
 ### 性能与验证
 
-generation 构造发生在启动或显式更新阶段，不属于单次 resolve，但需要单独报告绝对延迟。普通热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析；缓存命中直接返回 generation 级结果。当本地 CommonJS 包目录没有 `exports` 且仅缺少所请求 subpath 时，一次请求可能先执行一次原生探测，再执行一次路由解析。作用域外调用不读取 manifest，只缓存 parent 是否位于 profile scope。
+generation 构造发生在启动或显式更新阶段，不属于单次 resolve，但需要单独报告绝对延迟。profile 热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析；缓存命中直接返回 generation 级结果。linked importer 请求运行时表提供的包名时，读取所访问的祖先 manifest，不缓存选中的路由。旧式子路径缺失时，CommonJS 可以探测多个位置。作用域外调用不读取 manifest，只缓存 parent 是否具有拦截层。
 
 实现期间的一次性本地测量用 plain Node 在全新进程中执行构建后的 JavaScript，并与完全没有安装 hook 的进程比较。测量脚本和结果未提交，这些数据不是 benchmark 或 CI 预算。七轮交替顺序覆盖 outside、profile-local 和 fallback 的 dynamic import、`import.meta.resolve`、require、`require.resolve`。Node 22.19、24.18 和 26.8 的热路径中位数最大正向回退为 4.5%。Node 24.18 的 256 包 cold workload 最大回退为 11.2%，generation 构造中位数为 16.027 ms；32 包本地 `require.resolve` 因固定启动成本在整批增加 1.033 ms（+34.7%）。
 
@@ -135,7 +142,7 @@ generation 构造发生在启动或显式更新阶段，不属于单次 resolve
 ## Verification
 
 - 一次 eager 计算供应 runtime resolution；启动既不写入也不退休模块解析数据。
-- [Generation 测试](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts)覆盖普通目录和递归软链接下的安装图与所选 bundle 图，包括逻辑锚点和真实锚点旁存在不同依赖版本的情况。
+- [Generation 测试](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts)覆盖普通目录和递归软链接下的安装图与所选 bundle 图，包括逻辑锚点和真实锚点旁存在不同依赖版本的情况。测试还覆盖 linked root 移除、同目标恢复、重叠 root、原生缺包、已加载模块的新请求，以及移除后重新链接不同目标时的拒绝。
 - [源码启动测试](../../../../apps/cli/tests/source-launch.compat.spec.ts)与[构建入口测试](../../../../apps/cli/tests/built-bin.e2e.ts)通过真实 CLI 运行两种 profile 布局，断言 ESM/CJS 版本、加载路径、各模块格式内的依赖身份，以及一致的 Tools/AgentLoop 模块实例和可访问的 scheduler 键。
 - pkg 与 Electron 载体选择 runtime 解析；Electron 以 Node 模式从 ASAR 承载的 dsh 依赖树执行 Host，原生可执行条目保持 unpacked。
 - ESM 与 CommonJS 适配器共享同一个路由器，并把最终解析委托给 Node，不使用 `module.registerHooks` 或替换 `_findPath`。
@@ -145,4 +152,4 @@ generation 构造发生在启动或显式更新阶段，不属于单次 resolve
 
 ## Consequences
 
-runtime 启动避免磁盘修改和代理 manifest，同时保留包优先级规则。真实目录锚点让依赖发现对齐 Node 默认加载与 tsx workspace 映射，也覆盖软链接逻辑路径会选中另一版本的情况。实现需要持续维护 Node Internal 兼容测试，并在每个自有 Worker 中尽早执行自包含 bootstrap；它不提供纯磁盘后端或 dual 对比模式。在产品拥有模块缓存失效和 Worker 重启前，generation 替换只能新增映射。
+runtime 启动避免磁盘修改和代理 manifest，同时保留包优先级规则。真实目录锚点让依赖发现对齐 Node 默认加载与 tsx workspace 映射，也覆盖软链接逻辑路径会选中另一版本的情况。实现需要持续维护 Node Internal 兼容测试，并在每个自有 Worker 中尽早执行自包含 bootstrap；它不提供纯磁盘后端或 dual 对比模式。包映射和本地包名仍只允许新增；linked root 集合可以变化，而不卸载模块。
diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml
index 97cdb07d3f..eed28e3666 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
-2026-09-09-workspace-file-read-authority.md: d1a5b9d9634381cb74b17651c67f2b701402ff1c
-2026-09-09-workspace-file-read-authority.zh.md: f8b0fae4325a90548c6b9dc33ac46b17248b04e7
+2026-09-09-workspace-file-read-authority.md: 140816e8c48a6628133cf9208d5b48545e2e5eaf
+2026-09-09-workspace-file-read-authority.zh.md: 75ffee32c40930c459018ab0fde42d5324371ba8
diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
index d1a5b9d963..140816e8c4 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
+++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
@@ -10,11 +10,11 @@ Workspace Files serves both file content and workspace navigation. Applying work
 
 ## Decision
 
-`read`, `readBytes`, `readAll`, `readRelated`, and `stat` inherit the addressed Session filesystem backend's read authority. The workspace root is the base for relative input paths, not a read boundary; absolute paths and relative paths that leave the workspace are readable when the backend allows them. The service still requires regular files, refuses symlinks, and applies its text and byte caps.
+`read`, `readBytes`, and `stat` inherit the addressed Session filesystem backend's read authority. The workspace root is the base for relative input paths, not a read boundary; absolute paths and relative paths that leave the workspace are readable when the backend allows them. The service still requires regular files, refuses symlinks, and applies its text and byte caps.
 
 `list` and `changes` remain workspace-scoped because they expose workspace navigation and observation rather than a named file read. `list` rejects a directory outside the root, and `changes` filters observations through the backend's workspace-containment predicate.
 
-`readRelated` resolves a relative path from the base file's directory. A `..` path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with `sandbox="allow-scripts"`; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML.
+`readBytes` with `baseFile` resolves a relative path from the base file's directory. A `..` path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with `sandbox="allow-scripts"`; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML.
 
 The [Workspace Files service](2026-09-05-workspace-files-service.md) owns paging, file checks, listing, and observation. [Document Preview](2026-09-08-document-preview-operations.md) owns which related files are packaged and the iframe sandbox.
 
diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md
index f8b0fae432..75ffee32c4 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md
@@ -10,11 +10,11 @@ Workspace Files 同时提供文件内容与工作区导航。对所有操作应
 
 ## Decision
 
-`read`、`readBytes`、`readAll`、`readRelated` 与 `stat` 继承被寻址 Session 的文件系统后端读取权限。工作区根是输入相对路径的基准，而不是读取边界；只要后端允许，就可以读取绝对路径和离开工作区的相对路径。服务仍要求普通文件、拒绝符号链接，并应用文本和字节上限。
+`read`、`readBytes` 与 `stat` 继承被寻址 Session 的文件系统后端读取权限。工作区根是输入相对路径的基准，而不是读取边界；只要后端允许，就可以读取绝对路径和离开工作区的相对路径。服务仍要求普通文件、拒绝符号链接，并应用文本和字节上限。
 
 `list` 与 `changes` 仍限于工作区，因为它们暴露工作区导航和观察，而不是读取一个具名文件。`list` 拒绝根外目录，`changes` 通过后端的工作区包含判定过滤观察。
 
-`readRelated` 从基准文件所在目录解析相对路径。因此，只要 Session 后端允许，`..` 路径就可以读取工作区外的 JavaScript 或 CSS。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时，Document Preview 把有界、静态声明的本地脚本与样式表打包进带 `sandbox="allow-scripts"` 的 HTML Blob iframe；不透明源阻止访问父应用，但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。
+带 `baseFile` 的 `readBytes` 从基准文件所在目录解析相对路径。因此，只要 Session 后端允许，`..` 路径就可以读取工作区外的 JavaScript 或 CSS。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时，Document Preview 把有界、静态声明的本地脚本与样式表打包进带 `sandbox="allow-scripts"` 的 HTML Blob iframe；不透明源阻止访问父应用，但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。
 
 [Workspace Files 服务](2026-09-05-workspace-files-service.zh.md)负责分页、文件检查、列举和观察。[Document Preview](2026-09-08-document-preview-operations.zh.md)负责选择要打包的关联文件及 iframe sandbox。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml
index c27ef04676..b40fa370ec 100644
--- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
-2026-09-11-node-office-kit.md: 6cab947d7cb8d4c2c416a83f0b765813c7f98ea9
-2026-09-11-node-office-kit.zh.md: 8ed1a81922249cf0b9c1a74b06e5ce9d44696e0a
+2026-09-11-node-office-kit.md: 132ac8b3dd709f9f16254a5569dec59f01d29fda
+2026-09-11-node-office-kit.zh.md: c7bdab2322766c42cfee4092f158d7b6b530e875
diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
index 6cab947d7c..132ac8b3dd 100644
--- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
+++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
@@ -14,7 +14,7 @@ The [office-to-pdf capability](../../../../packages/document/README.md) delegate
 
 The [platform engine decision](2026-09-15-platform-office-engines.md) requires the kit’s declared native target engine, or WASM when no native target is declared. Missing or invalid required engines reject conversion. The shared [bounded provider](2026-09-15-bounded-office-conversion.md) owns admission, conversion reuse, and cancellation through scratch cleanup. Preview consumes that provider without registering another converter or requiring Office authoring skills.
 
-The service, Remote methods, and Client registration accept DOC, DOCX, XLS, XLSX, PPT, and PPTX. The kit verifies bounded ZIP membership and content types for OOXML inputs and the OLE compound-file header for binary Office inputs before LibreOffice imports them. Renaming text to an Office suffix does not admit it. Binary formats return no missing-font diagnostics because the kit does not extract their font tables. It writes a fresh, exclusively created PDF in a caller-owned private directory. DSH reads and validates the complete output before removing scratch files. The [service’s Remote method](../../../../packages/document/office-to-pdf/README.md) authorizes source access through [Workspace Files](2026-09-09-workspace-file-read-authority.md), preserves the source path/version, and returns PDF bytes. Source read caps and generated PDF caps remain independent. One source path/version snapshot governs the access probe and deferred read, including size-failure rechecks, so conversion cannot publish bytes under another identity. Preview bytes do not enter Session storage or persistent caches.
+The service and Remote methods accept DOC, DOCX, XLS, XLSX, PPT, and PPTX. The Client preview registers DOC, DOCX, PPT, and PPTX; XLS and XLSX use the unsupported-preview state and can open in the system default application without requesting conversion. The kit verifies bounded ZIP membership and content types for OOXML inputs and the OLE compound-file header for binary Office inputs before LibreOffice imports them. Renaming text to an Office suffix does not admit it. Binary formats return no missing-font diagnostics because the kit does not extract their font tables. It writes a fresh, exclusively created PDF in a caller-owned private directory. DSH reads and validates the complete output before removing scratch files. The [service’s Remote method](../../../../packages/document/office-to-pdf/README.md) authorizes source access through [Workspace Files](2026-09-09-workspace-file-read-authority.md), preserves the source path/version, and returns PDF bytes. Source read caps and generated PDF caps remain independent. One source path/version snapshot governs the access probe and deferred read, including size-failure rechecks, so conversion cannot publish bytes under another identity. Preview bytes do not enter Session storage or persistent caches.
 
 A converter reuses font metadata obtained by its first conversion Worker; original font buffers and decoded glyph coverage remain conversion-local. Workers validate indexed files when reading them. Exact installed families precede configured alternatives, and complete family/style/weight/italic/width/pitch/language/code-point requests retain their distinct matches. WASM callbacks import original font files, including complete collections, into MEMFS. Native engines also retain their platform's font discovery. Neither path downloads or installs fonts; native OS-managed font memory is outside the explicit import budget. Recreating the converter refreshes its metadata after font changes.
 
@@ -24,7 +24,7 @@ DSH exports raster images at configurable resolution, defaulting to 192 DPI for
 
 The [Office viewer](../../../../packages/client/ui-sidebar-documentpreview/README.md#office-preview) lives under Document Preview’s `client/office/` directory, alongside the loading lifecycle, PDF body, and reader types it uses. Keeping these components in one package removes an independent UI boot entry without creating cross-plugin runtime imports. Its bounded cache validates authorized source metadata, shares pending conversions between readers, cancels only when the final reader leaves, excludes failures, and clears on connection reset. Conversion starts when a user opens a preview. Missing declared font families accompany the PDF and are available from the document toolbar’s warning icon; font-table inventories and unrelated engine defaults are not warnings. The shared preview entry’s `office` cache settings use the existing page-global injection channel because the module boot graph carries package identities, not Loader configuration. Reloading the page adopts updated YAML values.
 
-Ordinary file reads and Office responses share `documentFileBytes()`, which decodes into one typed byte buffer rather than materializing a JavaScript element array from the binary string. Element-array expansion can exhaust the browser heap for a PDF that the configured Host limits permit. A child-process regression checks byte equality within a fixed heap, while the built browser scenario verifies the transport and PDF Worker together. Cache byte limits do not bound transient transport or viewer memory.
+Office responses use `documentFileBytes()`, which decodes into one typed byte buffer rather than materializing a JavaScript element array from the binary string. Element-array expansion can exhaust the browser heap for a PDF that the configured Host limits permit. A child-process regression checks byte equality within a fixed heap, while the built browser scenario verifies the transport and PDF Worker together. Cache byte limits do not bound transient transport or viewer memory.
 
 The [kit ownership decision](2026-09-14-independent-libreoffice-kit.md) defines npm distribution and bundled offline conversion.
 
diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md
index 8ed1a81922..c7bdab2322 100644
--- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 [平台引擎决策](2026-09-15-platform-office-engines.zh.md)要求使用 kit 已声明的原生目标引擎，未声明原生目标时使用 WASM。缺失或无效的必需引擎会拒绝转换。共享的[有界提供方](2026-09-15-bounded-office-conversion.zh.md)负责准入、转换复用以及持续到临时文件清理完成的取消。预览消费该提供方，不注册另一个转换器，也不依赖 Office 创作 skills。
 
-服务、Remote 方法和 Client 注册接受 DOC、DOCX、XLS、XLSX、PPT 和 PPTX。LibreOffice 导入前，kit 校验 OOXML 输入的有界 ZIP 成员和内容类型，以及二进制 Office 输入的 OLE 复合文件头。将文本改为 Office 后缀不能通过校验。kit 不提取二进制格式的字体表，因此这些格式不返回缺失字体诊断。kit 在调用方拥有的私有目录中独占创建新的 PDF。DSH 读取并校验完整输出后才删除临时文件。[服务的 Remote 方法](../../../../packages/document/office-to-pdf/README.zh.md)通过 [Workspace Files](2026-09-09-workspace-file-read-authority.zh.md)授权源文件访问，保留源路径和版本，并返回 PDF 字节。源文件读取上限与生成 PDF 上限相互独立。读取权限探测和延迟读取（包括超限失败后的复查）采用同一个源路径／版本快照，防止转换将字节发布到另一个源身份下。预览字节不会进入 Session 存储或持久缓存。
+服务与 Remote 方法接受 DOC、DOCX、XLS、XLSX、PPT 和 PPTX。Client 预览注册 DOC、DOCX、PPT 和 PPTX；XLS 与 XLSX 使用不支持预览的空状态，可由系统默认应用打开，并且不请求转换。LibreOffice 导入前，kit 校验 OOXML 输入的有界 ZIP 成员和内容类型，以及二进制 Office 输入的 OLE 复合文件头。将文本改为 Office 后缀不能通过校验。kit 不提取二进制格式的字体表，因此这些格式不返回缺失字体诊断。kit 在调用方拥有的私有目录中独占创建新的 PDF。DSH 读取并校验完整输出后才删除临时文件。[服务的 Remote 方法](../../../../packages/document/office-to-pdf/README.zh.md)通过 [Workspace Files](2026-09-09-workspace-file-read-authority.zh.md)授权源文件访问，保留源路径和版本，并返回 PDF 字节。源文件读取上限与生成 PDF 上限相互独立。读取权限探测和延迟读取（包括超限失败后的复查）采用同一个源路径／版本快照，防止转换将字节发布到另一个源身份下。预览字节不会进入 Session 存储或持久缓存。
 
 converter 复用首个转换 Worker 返回的字体元数据；原始字体缓冲区和解码后的字符覆盖范围仍只属于单次转换。Worker 读取字体时校验索引中的文件。已安装字体族的精确匹配优先于配置的替代字体，完整的字体族、样式、字重、斜体、宽度、字距、语言与码点请求保留各自的匹配结果。WASM 回调将包含完整字体集合的原始字体文件导入 MEMFS。原生引擎还保留各平台的字体发现能力。两条路径均不下载或安装字体；原生操作系统管理的字体内存不受显式导入预算约束。字体变化后，重新创建 converter 会刷新元数据。
 
@@ -24,7 +24,7 @@ DSH 按可配置分辨率导出栅格图片，默认 192 DPI，对应共享 PDF
 
 [Office 查看器](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md#office-preview)位于文档预览的 `client/office/` 目录，与其使用的加载生命周期、PDF 正文和读取器类型同属一个包。这些组件放在同一包中，既减少一个独立 UI 启动入口，也无需跨插件运行时导入。其有界缓存校验已授权的源元数据，在读取方之间共享待完成转换，仅在最后一个读取方离开时取消，不缓存失败，并在连接重置时清空。用户打开预览时才开始转换。缺失的已声明字体族随 PDF 返回，可通过文档工具栏的警告图标查看；字体表清单与无关的引擎默认字体不构成警告。共享预览入口的 `office` 缓存设置复用页面全局注入通道，因为模块启动图携带包标识而不传递 Loader 配置。重新加载页面后采用更新的 YAML 值。
 
-普通文件读取与 Office 响应共享 `documentFileBytes()`，解码使用一个类型化字节缓冲区，不将二进制字符串物化为 JavaScript 元素数组。即使 PDF 符合 Host 配置的大小限制，元素数组展开也可能耗尽浏览器堆内存。子进程回归测试在固定堆容量内检查字节一致性，构建后的浏览器场景则一起验证传输和 PDF Worker。缓存字节限制不约束临时传输或查看器内存。
+Office 响应使用 `documentFileBytes()`，解码使用一个类型化字节缓冲区，不将二进制字符串物化为 JavaScript 元素数组。即使 PDF 符合 Host 配置的大小限制，元素数组展开也可能耗尽浏览器堆内存。子进程回归测试在固定堆容量内检查字节一致性，构建后的浏览器场景则一起验证传输和 PDF Worker。缓存字节限制不约束临时传输或查看器内存。
 
 [kit 归属决策](2026-09-14-independent-libreoffice-kit.zh.md)定义 npm 分发和随应用打包的离线转换。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.i18n.yaml
new file mode 100644
index 0000000000..f3e123135e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.md
+2026-09-17-shared-office-runtime.md: 25b6ddccbb5b17b93bec2c0b024dfcb63e94abc3
+2026-09-17-shared-office-runtime.zh.md: 99dffe8d0233e60480689ff983b6261cbb83bb7b
diff --git a/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.md b/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.md
new file mode 100644
index 0000000000..25b6ddccbb
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.md
@@ -0,0 +1,37 @@
+# Agent Note: Shared Office runtime for Desktop and SDK
+
+Status: implemented
+
+English | [中文](2026-09-17-shared-office-runtime.zh.md)
+
+## Problem
+
+SDK deployments need the same Office authoring libraries as Desktop while keeping interpreter payloads in read-only container image layers. A Desktop-owned query and builder require downstream carriers to duplicate dependency locks and path conventions.
+
+## Decision
+
+[`tool-workspace-dependencies`](../../../../packages/skill/tool-workspace-dependencies/README.md) owns manifest validation, interpreter paths, installation and the model query. It stays in the skill group beside its Office workflow consumer: the payload supplies those workflows, while the package exposes no workspace entity service. Desktop imports this package and retains copy-on-first-use installation. The packaged SDK profile enables the query and Office skills from its carrier default; `DSH_PRIMARY_RUNTIME` overrides that path, including an empty-string opt-out. It reads the payload in place. The common base and `sdk-minimal` do not enable Office implicitly.
+
+The [shared build entry](../../../../scripts/primary-runtime/prepare.ts) owns the download lock, extraction and native smoke checks for Desktop targets and GNU/Linux x64/ARM64. Desktop supplies output paths and its release version, requires Node.js and pnpm, and applies its signing-specific subprocess environment. Other carriers choose their output directory and may build a Python-only payload. The existing `desktopVersion` manifest field retains its name and records the carrier release; `payloadDigest` distinguishes locked inputs and component selection.
+
+The [Desktop primary-runtime decision](../feature/2026-09-14-desktop-primary-runtime.md) continues to own Desktop installation and platform signing. This decision replaces only its Desktop-only builder and query placement; both records remain active.
+
+`runtime.json` stores Python, Node.js and pnpm versions at the top level and all Python distribution versions in `pythonPackages`. Build metadata does not single out numpy or pandas. The shared parser accepts legacy `components` files without rewriting them, retains their consistency checks, and returns only the canonical flat fields. Mixed formats are rejected. The build digest includes the assembly format so changed manifest bytes invalidate payload reuse.
+
+The Python runtime wheel carries target-native CPython and Office libraries plus external skills in a sibling `<platform>-<arch>/` resource directory. Short platform directory names leave room for Python extension and dependency DLL paths after installation on Windows. Bundling supplies defaults; the skill registry still lets project, custom and user skills override same-name bundled entries, and profile patches can disable or replace Office skills without replacing Python. This retains configurable workflows while eliminating a separate environment installation step. Real filesystem resources let Python load native extensions and skills invoke their shared checker without startup extraction. The wheel grows by the compressed payload size; public-index size limits remain enforced by the release workflow.
+
+## Alternatives considered
+
+**Keep implementation in Desktop.** This leaves SDK and container builders depending on application packaging and signing code despite needing only interpreters, Office resources and a query.
+
+**Enable Office in the common base.** A base deployment has no guaranteed bundled interpreter or resources. Explicit SDK carrier configuration makes that requirement observable without changing unrelated profiles.
+
+**Always copy to the Harness home.** Copying duplicates image-layer content, requires a writable destination and cannot serve the intended immutable carrier deployment.
+
+**One component field per Python library.** This duplicates the distribution map and requires schema changes for each library. A complete map records the locked package set independently of the interpreter and package-manager fields.
+
+## Consequences
+
+Successful tool preparation is shared by concurrent calls for one plugin lifetime. Failed preparation is retryable; disposal removes registration and waits for outstanding filesystem work. Copy mode verifies a staged replacement and restores the preceding installation after a failed publication. In-place mode performs no payload writes. Paths are absolute, and runtime metadata and declared entries are checked before results are returned.
+
+SDK configuration changes require restart. Missing Office resources produce a startup warning and leave the optional skill provider inactive; runtime metadata and interpreter availability are validated on the first tool call. musl builds remain outside the lock. Cross-target assembly verifies archive hashes but requires execution on the target host; the Linux artifact CI lane owns native Linux checks. Unit coverage pins manifest, installation and lifecycle behavior; SDK profile tests observe optional tools, skill discovery and results, and the recorded workspace-dependencies scenario pins model-visible validation errors.
diff --git a/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.zh.md b/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.zh.md
new file mode 100644
index 0000000000..99dffe8d02
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: Desktop 与 SDK 共享 Office 运行时
+
+Status: implemented
+
+[English](2026-09-17-shared-office-runtime.md) | 中文
+
+## 问题
+
+SDK 部署需要与 Desktop 相同的 Office 创作库，同时将解释器 payload 保存在只读容器镜像层中。由 Desktop 持有查询工具和构建器，会要求下游载体重复维护依赖锁与路径约定。
+
+## 决策
+
+[`tool-workspace-dependencies`](../../../../packages/skill/tool-workspace-dependencies/README.zh.md) 持有清单校验、解释器路径、安装逻辑和模型查询。它保留在 skill 组中，与 Office 工作流消费者相邻：payload 服务于这些工作流，本包不提供 workspace 实体服务。Desktop 引用本包并保留首次使用时复制安装。打包的 SDK profile 通过载体默认路径启用查询和 Office skills；`DSH_PRIMARY_RUNTIME` 覆盖该路径，空字符串表示禁用。它原位读取 payload。公共 base 与 `sdk-minimal` 不会隐式启用 Office。
+
+[共享构建入口](../../../../scripts/primary-runtime/prepare.ts) 持有 Desktop 目标与 GNU/Linux x64/ARM64 的下载锁、解压和本机冒烟检查。Desktop 提供输出路径和发布版本，要求包含 Node.js 与 pnpm，并应用签名专用子进程环境。其他载体选择自己的输出目录，也可构建 Python-only payload。现有 `desktopVersion` 清单字段保留名字并记录载体发布版本；`payloadDigest` 区分锁定输入与组件选择。
+
+[Desktop 第一方运行时决策](../feature/2026-09-14-desktop-primary-runtime.zh.md)继续持有 Desktop 安装与平台签名规则。本决策仅替代其中由 Desktop 独占构建器和查询实现的部分；两份记录均保持有效。
+
+`runtime.json` 在顶层保存 Python、Node.js 和 pnpm 版本，并在 `pythonPackages` 中保存全部 Python 分发包版本。构建元数据不单独列出 numpy 或 pandas。共享解析器接受旧 `components` 文件而不改写它们，保留旧格式的一致性校验，并仅返回统一的扁平字段。混合格式会被拒绝。构建摘要包含组装格式，因此清单字节变化会使旧产物身份失效。
+
+Python runtime wheel 将目标平台的 CPython、Office 库和外部 skills 放在可执行文件同级的 `<platform>-<arch>/` 资源目录中。较短的平台目录名为 Windows 安装后的 Python 扩展与依赖 DLL 路径保留长度空间。打包提供默认资源；skill 注册表仍允许项目、自定义目录和用户 skills 覆盖同名随包条目，profile patch 可在保留 Python 的同时禁用或替换 Office skills。这样既保留工作流配置能力，又省去单独安装环境的步骤。真实文件系统资源允许 Python 加载原生扩展，并让 skills 调用共用检查脚本，无需启动时解包。wheel 体积增加一个压缩 payload；发布流程仍执行公开索引的大小限制检查。
+
+## 考虑过的替代方案
+
+**将实现保留在 Desktop。** SDK 和容器构建器只需要解释器、Office 资源和查询，却仍会依赖应用打包及签名代码。
+
+**在公共 base 中启用 Office。** base 部署不保证提供内置解释器或资源。显式 SDK 载体配置可以让该要求可见，并保持其他 profile 的行为。
+
+**总是复制到 Harness home。** 复制会重复镜像层内容、要求目标可写，也无法满足预期的不可变载体部署。
+
+**为每个 Python 库增加组件字段。** 这会重复分发包版本表，并使新增库要求修改 schema。完整版本表将锁定包集合与解释器、包管理器字段分开记录。
+
+## 影响
+
+同一插件生命周期内的并发调用共享成功的工具准备结果。准备失败后可重试；卸载移除工具注册并等待未完成的文件系统工作。复制模式验证暂存替换内容，并在发布失败后恢复原安装。原位模式不写入 payload。路径为绝对路径，返回结果前会检查运行时元数据和所声明的条目。
+
+SDK 配置变更需要重启。缺少 Office 资源会产生启动警告，并使可选的 skill 提供方保持未激活；运行时元数据和解释器是否存在在首次工具调用时校验。musl 构建仍不在锁文件范围内。跨目标组装校验归档哈希，但需要在目标主机执行；Linux 产物 CI 负责本机 Linux 检查。单元覆盖固定清单、安装与生命周期行为；SDK profile 测试观察可选工具、skill 发现与结果，workspace-dependencies 录制场景固定模型可见的校验错误。
diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml
new file mode 100644
index 0000000000..7eef4b0fa9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md
+2026-09-17-workspace-file-binary-transfer.md: b419c8bd15f51246825ceddf2905ec055bbc70ae
+2026-09-17-workspace-file-binary-transfer.zh.md: 9cf3d7074c3d536a5c8a39732231c6996d6f6ead
diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md
new file mode 100644
index 0000000000..b419c8bd15
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md
@@ -0,0 +1,31 @@
+# Agent Note: Binary workspace file transfer
+
+Status: implemented
+
+English | [中文](2026-09-17-workspace-file-binary-transfer.zh.md)
+
+## Problem
+
+Document previews need native bytes. Encoding file contents as base64 adds about one third to the payload before compression and requires browser decoding. A separate file Fetch route also duplicates the Gateway's method dispatch, Session lookup, and error handling.
+
+## Decision
+
+The [Remote method architecture](2026-08-02-typert-remote-method-calls.md) owns method dispatch and lifetime; this note defines binary success encoding and Client validation. The [workspace file service](2026-09-05-workspace-files-service.md) exposes one binary `readBytes` Remote. Its required options object independently selects a byte `range` and a `baseFile` for relative target resolution. Without `range`, it reads a complete file. This avoids separate method names for orthogonal choices while preserving bounded `fs.readBytes` and `fs.readByteRange` reads.
+
+Typert recursively recognizes `Uint8Array` in unary result types, including root values, optional fields, and containers. Generated result codecs provide `encode()` for subtrees whose types can contain bytes and `decode()` to validate the reconstructed value without iterating, copying, or freezing byte payloads; Client declarations narrow each byte buffer to `ArrayBuffer`. Gateway executes the generated encoder, keeps strict JSON values unchanged, and performs runtime byte detection for source-mode calls. It returns JSON-compatible metadata and result-relative byte attachments to Connection. Connection owns standard `FormData` parts and preserves the RPC envelope and correlation id in JSON metadata; it does not inspect business values or depend on Typert reflection. An attachment table associates byte parts with paths through the JSON result; field names remain business-owned. The Client restores `Uint8Array` views over `Blob.arrayBuffer()` and Gateway delegates validation to the generated decoder. Ordinary results and errors retain JSON responses. Gateway owns method dispatch, Session lookup, cancellation, result projection, and mount lifetime; feature code needs no multipart reader or dedicated route.
+
+## Alternatives considered
+
+- Separate `readAll`, range, and related-file methods mix independent path and extent choices. One options object permits their combination without adding another method.
+- A workspace-only Fetch route keeps binary transport out of Remote but requires feature-specific dispatch, Session lookup, and error decoding.
+- A whole-result binary marker or a reserved `data` field couples transport to one business result. Type-directed codecs and attachment paths support independently named and nested fields without adding result-wide categories.
+- A custom metadata prefix needs owned framing and length validation. FormData delegates those mechanics to the platform, at the cost of Blob copies.
+- Metadata HTTP headers constrain long Unicode paths. Multipart fields keep paths in the body; HTML stays in an isolated Blob iframe rather than a navigable Host response.
+
+## Consequences
+
+Byte ranges retain only the requested bytes under `maxBytes`, independently of `maxFileBytes`. Complete reads retain a bounded whole file; this is not a streaming preview or zero-copy optimization. On HTTP disconnect, the bridge aborts the request signal and drains materialized response chunks without writing to the socket: cancelling Node multipart bodies can race their producer and cause an unhandled `ERR_INVALID_STATE` rejection. Office authorization probes use the same Remote with a one-byte range; converted PDFs remain base64 in the separate Office Remote and use its bounded decoder. Plugin callers migrate to `readBytes` options and stop decoding its data as base64. Binary arguments, events, and stream items remain unsupported; recursive types require acyclic runtime values. No Session event or persistence format changes.
+
+## Validation
+
+Workspace tests cover complete and ranged reads, combined base-file resolution, limits, Session lookup, cancellation, and binary RPC round trips. Connection and Gateway tests cover nested and multiple attachments, framing, correlation, malformed multipart, and cancelled or withdrawn calls; Typert tests cover recursive result codecs, Client declarations, and rejected binary inputs or streams. The built browser scenario checks raw PNG bytes plus HTML, PDF, image, and text previews. Local benchmarks compare full and ranged reads using identical synthetic files, and distinguish transport/decoding from the complete read path.
diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md
new file mode 100644
index 0000000000..9cf3d7074c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 工作区文件二进制传输
+
+Status: implemented
+
+[English](2026-09-17-workspace-file-binary-transfer.md) | 中文
+
+## 问题
+
+文档预览需要原生字节。将文件内容编码为 base64 会在压缩前使载荷增加约三分之一，并要求浏览器解码。独立的文件 Fetch 路由还会重复 Gateway 的方法分发、Session 查找和错误处理。
+
+## 决策
+
+[Remote 方法架构](2026-08-02-typert-remote-method-calls.zh.md)负责方法分发与生命周期；本记录规定二进制成功响应的编码及 Client 校验。[工作区文件服务](2026-09-05-workspace-files-service.zh.md)提供单一的二进制 `readBytes` Remote。其必填选项对象独立选择字节 `range` 和用于相对目标解析的 `baseFile`。未传 `range` 时读取完整文件。这避免为正交的选择设置不同方法名，同时保留有界的 `fs.readBytes` 和 `fs.readByteRange` 读取。
+
+Typert 递归识别一元结果类型中的 `Uint8Array`，包括根值、可选字段和容器。生成的结果 codec 提供 `encode()` 处理类型可能包含字节的子树，并通过 `decode()` 校验还原后的值，不逐字节遍历、复制或冻结字节载荷；Client 声明将每个字节缓冲区限定为 `ArrayBuffer`。Gateway 执行生成的 encoder，保持 strict JSON 值不变，并为源码模式调用执行运行时字节识别；随后向 Connection 返回 JSON 兼容元数据及相对于结果的字节附件。Connection 负责标准 `FormData` 部分，并在 JSON 元数据中保留 RPC 信封和关联 id；它不检查业务值，也不依赖 Typert 反射。附件表将字节部分与 JSON 结果中的路径关联，字段名仍由业务拥有。Client 恢复基于 `Blob.arrayBuffer()` 的 `Uint8Array` 视图，Gateway 将校验交给生成的解码器。普通结果与错误继续使用 JSON 响应。Gateway 负责方法分发、Session 查找、取消、结果投影及挂载生命周期；功能代码无需 multipart 读取器或专用路由。
+
+## 考虑过的替代方案
+
+- 分立的 `readAll`、范围和关联文件方法混合了路径与读取范围两个独立选择。单一选项对象支持组合，无需再增加方法。
+- 工作区专用 Fetch 路由让二进制传输独立于 Remote，但需要功能专属的方法分发、Session 查找与错误解码。
+- 整体结果的二进制标记或保留的 `data` 字段会将传输与某一种业务结果耦合。按类型生成的 codec 和附件路径支持独立命名及嵌套字段，无需新增整体结果分类。
+- 自定义元数据前缀需要自有的帧格式与长度校验。FormData 将这些机制交给平台，代价是 Blob 复制。
+- 元数据 HTTP 头会限制较长的 Unicode 路径。Multipart 字段将路径保留在正文中；HTML 仍置于隔离的 Blob iframe，不作为可导航的 Host 响应。
+
+## 影响
+
+字节范围仅保留 `maxBytes` 内的请求字节，不受 `maxFileBytes` 约束。完整读取保留有上限的整个文件；这不是流式预览或零复制优化。HTTP 连接断开后，桥接器中止请求信号，并排空已准备的响应块，不再写入 socket：取消 Node multipart 响应体可能与其生产方竞争，导致未处理的 `ERR_INVALID_STATE` 拒绝。Office 授权探测使用同一 Remote 的单字节范围；转换后的 PDF 仍通过独立的 Office Remote 传输 base64，并使用其有界解码器。插件调用方迁移到 `readBytes` 选项，并停止将其 data 按 base64 解码。仍不支持二进制参数、事件和流条目；递归类型要求运行时值无环。不改变 Session 事件或持久化格式。
+
+## 验证
+
+Workspace 测试覆盖完整与分段读取、基准文件解析组合、上限、Session 查找、取消以及二进制 RPC 往返。Connection 和 Gateway 测试覆盖嵌套及多附件、帧格式、关联关系、畸形 multipart，以及取消或撤销的调用；Typert 测试覆盖递归结果 codec、Client 声明，以及对二进制输入和流的拒绝。构建后的浏览器场景验证原始 PNG 字节以及 HTML、PDF、图片和文本预览。本机 benchmark 使用相同合成文件比较完整与分段读取，并区分传输/解码和完整读取路径。
diff --git a/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.i18n.yaml
new file mode 100644
index 0000000000..ef7c78129d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-18-volatile-config-references.md
+2026-09-18-volatile-config-references.md: afaa6affdc3d18da182ec069126033cb55393b72
+2026-09-18-volatile-config-references.zh.md: 3d8800cb92dec4da80b698cb8b3c073331ed266f
diff --git a/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.md b/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.md
new file mode 100644
index 0000000000..afaa6affdc
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.md
@@ -0,0 +1,33 @@
+# Agent Note: Volatile configuration references
+
+Status: implemented
+
+English | [中文](2026-09-18-volatile-config-references.zh.md)
+
+## Problem
+
+Replacing an entire plugin to change a value also disposes its services and effects. Separate settings subscriptions require each consumer to implement another source of live configuration.
+
+## Decision
+
+Schemastery declares live fields with `.volatile()`, preserving node types and form metadata while returning stable references to immutable snapshots. Cosmokit owns the shared protocol. General comparison treats two volatile references as equal. Loader calculates raw config differences using schema-declared volatile paths and retains raw config for subsequent activation. When the raw diff reports no ordinary change but the raw config differs, Loader parses and validates the candidate through the fiber's `internal/config` hook, compares ordinary effective values, commits references when those values still match, and notifies the owning fiber; every update path, including profile reconciliation, HMR Include refreshes and direct `entry.update()` calls, reaches this step through `Entry.update`. Fiber does not own this update policy, and HMR supplies file watching.
+
+Only volatile changes preserve the instance. Ordinary-field changes use the existing remount lifecycle and do not update the old references. An instance-local `loader/volatile-update` event reports paths after the complete candidate is validated and all references are committed. It uses ordinary `emit`; listener completion is not a configuration commit condition. References can be retained, while values may only be captured for one operation. Missing optional values retain a readable reference.
+
+Config schemas own the field types, defaults, roles, and live-update declaration needed by schema-driven settings forms. Existing settings consumers remain unchanged; automatic form generation and their migration are separate work. The [configuration guide](../../../../docs/cordis-tutorial/05-config.md) owns plugin-author usage.
+
+## Alternatives considered
+
+**Restart for every configuration change.** This releases resources that remain valid when only operation-time parameters change.
+
+**Add another settings-specific live-value API.** It duplicates runtime update semantics and makes plugins depend on settings to consume ordinary configuration.
+
+**Wrap values only during mounting.** Direct schema parsing would return a different kind of value from the plugin's config, requiring separate consumer types.
+
+## Consequences
+
+Schemas reject independent volatile references inside dynamic containers; entire objects and arrays can be volatile values. Immutable snapshots accept plain data. Simplification unwraps references, and shared symbols support ESM/CJS copies. Group/Include retain dispatch while volatile-only target updates bypass `internal/update`. Direct `fiber.update()` retains its semantics, including custom handling, saving and `noSave`. Loader commits live volatile updates itself; no separate plugin is required.
+
+Schema metadata keeps comparison independent of parsing: the diff does not execute expressions, validators or config hooks. Object nodes compare missing or null values using their declared defaults, even without volatile descendants; this avoids remounts for equivalent object defaults. Ordinary expression edits retain raw comparison even when they resolve to equal values. Loader compares parsed ordinary values, including URLs by normalized address. If an ordinary expression produces a different value, Loader applies the ordinary remount instead of committing; strict comparison treats class instances other than URL, Date and RegExp by identity, so an ordinary transform that builds a fresh instance per parse always remounts. Listener failures during the notification are logged and do not fail the update. Loader validates volatile candidates before committing; invalid edits remain in raw config but leave running references unchanged until a later activation.
+
+The schema and lifecycle regression suite covers direct updates, invalid candidates, instance isolation, dependency replacement, real file watching, and save/reload behavior. The HMR module suite covers replacement after live config updates. These tests do not claim settings migration or automatic form rendering.
diff --git a/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.zh.md b/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.zh.md
new file mode 100644
index 0000000000..3d8800cb92
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-18-volatile-config-references.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: Volatile 配置引用
+
+Status: implemented
+
+[English](2026-09-18-volatile-config-references.md) | 中文
+
+## Problem
+
+为了改变一个值而替换整个插件，也会销毁插件的服务和副作用。独立的 settings 订阅要求每个消费者额外实现一套动态配置来源。
+
+## Decision
+
+Schemastery 使用 `.volatile()` 声明动态字段，保留节点类型和表单元数据，解析结果是具有不可变快照的稳定引用。共享协议位于 Cosmokit。通用比较将两个 volatile 引用视为相等。Loader 根据 schema 声明的 volatile 路径计算原始配置差异，并保留原始配置供后续激活使用。原始 diff 未报告普通字段变化但原始配置有差异时，Loader 经 fiber 的 `internal/config` 钩子解析并校验候选配置，比较普通字段的有效值，在这些值仍匹配时提交引用并通知所属实例；所有更新路径，包括 profile 重载、HMR 的 Include 刷新和直接调用 `entry.update()`，都经 `Entry.update` 到达这一步。Fiber 不承担这项更新策略，文件监视由 HMR 提供。
+
+仅 volatile 变化保留实例。普通字段变化沿用现有重新挂载生命周期，不更新旧引用。实例局部的 `loader/volatile-update` 事件在完整候选配置通过校验且所有引用提交后报告路径。事件使用普通 `emit`；监听器完成不是配置提交条件。可以保存引用，而值只能在单次操作中保存。缺省可选值仍具有可读取的引用。
+
+Config schema 负责提供基于 schema 的 settings 表单需要的字段类型、默认值、角色和动态更新声明。现有 settings 消费者保持不变；自动表单生成及其迁移是独立工作。[配置指南](../../../../docs/cordis-tutorial/05-config.zh.md)负责插件作者的使用说明。
+
+## Alternatives considered
+
+**每次配置变化都重启。** 当只有操作时读取的参数变化时，这会释放仍然有效的资源。
+
+**增加另一套 settings 专用动态值 API。** 这会重复运行时更新语义，并使插件为了读取普通配置而依赖 settings。
+
+**仅在挂载时包装值。** 直接解析 schema 与插件配置将返回不同种类的值，需要独立的消费者类型。
+
+## Consequences
+
+Schema 拒绝动态容器内部的独立 volatile 引用；整个对象和数组可以作为一个 volatile 值。不可变快照接受普通数据。配置简化解包引用，共享 symbol 支持 ESM/CJS 副本互操作。Group/Include 保留分发，目标插件的仅 volatile 更新不进入 `internal/update`。直接调用 `fiber.update()` 保留原语义，包括自定义处理、保存及 `noSave`。动态 volatile 更新由 Loader 自己提交，不需要额外插件。
+
+Schema 元数据使比较独立于解析：diff 不执行表达式、校验器或配置钩子。对象节点的缺省值或 null 按声明的默认值比较，即使没有 volatile 后代字段；等价的对象默认值不触发重新挂载。普通表达式即使求值结果相等，修改时仍按原始值比较。Loader 比较解析后的普通值，其中 URL 按规范化地址比较。普通表达式产生不同值时，Loader 改为按普通流程重新挂载而不提交；严格比较对 URL、Date、RegExp 之外的类实例按身份比较，因此每次解析都产生新实例的普通 transform 字段总是走重新挂载。通知阶段监听器抛错只记录日志，不使更新失败。Loader 在提交前校验 volatile 候选；非法编辑保留在原始配置中，但在后续激活之前不改变运行中的引用。
+
+Schema 和生命周期回归测试覆盖直接更新、无效候选、实例隔离、依赖替换、真实文件监视及保存后重新加载。HMR 模块测试覆盖动态配置更新后的代码替换。这些测试不代表 settings 迁移或自动表单渲染已经完成。
diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml
index f625fbdf15..da2d68745b 100644
--- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-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/architecture/2026-09-19-profile-resolution-lookup-order.md
-2026-09-19-profile-resolution-lookup-order.md: da9c501cff6c902863def6d39e4052097c75bcb3
-2026-09-19-profile-resolution-lookup-order.zh.md: 72a9e876a49770ed2bdc544e2ee9104619eedc80
+2026-09-19-profile-resolution-lookup-order.md: 6dfb5511afe885875a778b8a4f1b7c5fc3c0d842
+2026-09-19-profile-resolution-lookup-order.zh.md: 2474a9b040cb4917e71b7002d36c1e61fe3bc106
diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md
index da9c501cff..6dfb5511af 100644
--- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md
+++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md
@@ -12,13 +12,13 @@ A developer must be able to restate the resolution rule in one sentence: which p
 
 ## Decision
 
-Module resolution inside a profile is an ordinary Node ancestor `node_modules` chain. dsh does exactly one thing: every package name in the runtime resolution computed at startup occupies the package directory position `$DSH_HOME/profiles/node_modules/<package>`. When the chain reaches this layer, a package name with an entry is answered by the runtime resolution's package, and a package name without an entry sees the physical directory at this layer. Every other resolution behavior matches Node. [Construction, publication, Worker inheritance, and runtime carriers of immutable generations](2026-09-09-profile-resolution-generations.md) are recorded by the existing Note and are not repeated here.
+Ordinary module requests retain Node's ancestor `node_modules` order. Inside a profile, runtime resolution entries occupy their package positions at `$DSH_HOME/profiles/node_modules`. For an importer in a recorded external linked directory, each candidate `D/node_modules` applies one rule: a name declared in `D/package.json` under `peerDependencies` and present in the runtime resolution uses the runtime package at that position; otherwise Node tries the physical package there. A nearer candidate precedes a peer declaration farther up. Explicit CommonJS `paths` always bypass interception. Node owns the remaining resolution behavior. [Construction, publication, Worker inheritance, and runtime carriers of immutable generations](2026-09-09-profile-resolution-generations.md) are recorded by the existing Note and are not repeated here.
 
 ### Part 1: Resolution rules
 
 #### 1. The ancestor chain: Node's ancestor `node_modules` lookup
 
-The importer is the module file that issues the `import` or `require`. Node starts from the importer's directory, tries the `node_modules` under each directory level upward until the filesystem root, and then tries `NODE_PATH` and the global directories. The nearest layer wins; within one layer, matching is by package name only.
+The importer is the module file that issues the `import` or `require`. Node starts from the importer's directory and searches ancestor `node_modules` positions up to the filesystem root, skipping a redundant `node_modules/node_modules` position. CommonJS also searches `NODE_PATH` and its global directories; ESM does not. The nearest matching candidate wins, subject to Node's package-entry and failure rules.
 
 Symlinks are followed to their real path per Node's default behavior. Once a module is loaded by its real path, the ancestor chain for its subsequent imports is the real path's ancestor chain, regardless of where it was linked from.
 
@@ -32,7 +32,7 @@ The chain below defines the numbering that every table in this Note references.
 ⑤ /node_modules
 ```
 
-① holds the plugin's private dependencies, ② the packages the profile installed, ③ the interception layer where the runtime resolution occupies the package directories it has entries for, ④ the Harness home, and ⑤ the filesystem root followed by `NODE_PATH` and the global directories.
+① holds the plugin's private dependencies, ② the packages the profile installed, ③ the interception layer where the runtime resolution occupies the package directories it has entries for, ④ the Harness home, and ⑤ the filesystem root. CommonJS then retains its `NODE_PATH` and global-directory lookup without peer interception at those extra positions.
 
 #### 2. The interception layer: the runtime resolution occupies `$DSH_HOME/profiles/node_modules/<package>`
 
@@ -46,22 +46,39 @@ Node remains responsible for `exports`, `imports`, conditions, `main`, subpaths,
 
 The interception layer reads, writes, and deletes no disk links. Leftover historical symlinks are treated as ordinary filesystem content: the positions of installation package names at ③ are already occupied by the runtime resolution, so old links are never read; all other package names see the contents of ③ normally along the ancestor chain. Profile load removes, once, the projections the link backend of the dsh 0.1.5 releases wrote into a profile: symlinks under the profile's `node_modules` whose target lies inside `<profile>/.dsh-module-fallback/node_modules`, followed by that directory. pnpm-installed packages and every other symlink stay.
 
-#### 3. What the interception layer holds: the runtime resolution's scan contents
+#### 3. Linked directories: peer interception at each ancestor position
 
-The runtime resolution is computed once at profile startup and consists of three parts.
+When `<profile>/node_modules/<package>` links to a real directory R outside the profiles tree, R is a linked root. R need not contain `package.json` or `node_modules`: it may be a package directory, a monorepo package, or a `src` directory. Importers below R follow Node's real ancestor chain. The recorded root decides which importers participate; it does not stop their lookup at R.
+
+Linked interception excludes importers inside installation-scope package directories, using both their configured and real paths. A broad checkout link therefore does not take over the host's own dependency lookup. Overlapping linked roots describe one participation scope: the importer determines the ancestor chain, so neither root order nor link names choose a different peer set.
+
+At each candidate `D/node_modules`, a matching current `D/package.json` peer declaration uses the runtime package if the table supplies that name. This occupies only that package's position, including when `D/node_modules` does not physically exist. Without both a declaration and a runtime entry, Node tries the physical candidate. A missing manifest does not stop lookup. `dependencies` and `devDependencies` do not enable interception, and a peer version range is not an additional resolver filter. The same rule applies to third-party peers such as React when the runtime table supplies them.
+
+A nearer physical candidate wins before any later ancestor peer declaration. If a selected package's `exports` rejects the request, Node's error is final. A legacy CommonJS subpath miss can continue to the next position, where that directory's peer rule applies again; the physical copy at an occupied position is not retried. Each new linked resolution reads the manifests at the positions it visits, without memoizing its selected route. An unreadable manifest supplies no peers; Node retains its native manifest diagnostics. This does not clear Node's caches or automatically reload already loaded modules.
+
+Runtime resolution construction scans top-level and `@scope/*` links in `<profile>/node_modules`. A successor may add or remove linked roots within the existing package-mapping and local-name constraints. Removal needs no restart: a directory no longer covered by any root returns to native lookup for subsequent resolutions. The [generation rules](2026-09-09-profile-resolution-generations.md#immutable-generations) define publication, existing module references, and relink checks across removal. A dependency whose real path lies outside every recorded linked root remains outside interception, even when a plugin links to it.
+
+#### 4. What the interception layer holds: the runtime resolution's scan contents
+
+The runtime resolution is computed once at profile startup and consists of four parts.
 
 - Installation closure: starting from the `package.json` of the currently running dsh package, a breadth-first traversal follows `dependencies` and `peerDependencies`; each edge resolves from the manifest that declares it per Node rules, and the first installed package found owns a package name. The closure holds several hundred entries, roughly half in the `@deepseek-ai/` scope and half third-party libraries. These entries apply to every profile.
 - Bundle-only entries: for a bundle selected by the profile that is not part of the closure, the same traversal starts from its manifest, and package names the closure already owns are not overridden. These entries apply only to profiles that select that bundle; they let the Loader import the bundle's embedded plugins by bare name from the profile root.
 - Local package names: package names among the profile's direct dependencies that are already installed in `$DSH_HOME/profiles/<name>/node_modules`. They already sit at ② on the ancestor chain; recording them only saves one directory probe.
+- Linked roots: top-level and `@scope/*` links in `$DSH_HOME/profiles/<name>/node_modules` whose targets are directories outside both the shared profiles tree and the active profile directory; each records its link name and real directory. Their own manifests are optional. Missing targets and files are excluded. An application-owned profile outside the shared tree does not register its internal pnpm store links as external roots.
 
 The CLI derives the installation anchor from `import.meta.url`, which Node has already resolved to its real path; the Desktop Host builds it from its runtime directory, which is not a symlink. Both leave the installation root equal to its real directory, so bundle discovery and dependency traversal use the same location. During the traversal, every dependency level uses the real directory of its owning package as the lookup anchor for the next level and records the location of the manifest that declares it. After a hit, Node resolves from that declaring location and gets the same result the package's own internal imports get. Every entry records the package name, package directory, version, declaring location, and scope. Declared but uninstalled dependencies are skipped; the bundle package root itself does not become an entry.
 
-#### 4. Hook coverage
+#### 5. Hook coverage
 
-The hook participates only when the importer is under `$DSH_HOME/profiles/**`. Builtin, relative-path, absolute-path, and URL requests, and every request whose importer is outside the tree, go straight to Node.
+The hook participates only when the importer is under `$DSH_HOME/profiles/**` or a linked root. Builtin, relative-path, absolute-path, and URL requests, and every request whose importer is outside both locations, go straight to Node. `require.resolve(request, { paths })` also goes straight to Node, including when a path names a profile or linked directory.
 
 The ESM and CommonJS adapters call the same routing function, and the main thread and Harness-owned Workers install the same runtime resolution. The implementation lives in `packages/boot/app-boot/src/profile-resolution/resolver.ts`; runtime resolution construction lives in `packages/boot/app-boot/src/profile.ts`.
 
+#### 6. Package directories and module files
+
+`packageDir('pkg', parentURL)` and `packageDir('pkg/sub', parentURL)` locate the package directory without loading code or validating the subpath. Ordinary entry and file requests still ask Node to apply `exports`, `main`, conditions, and file existence. A package-directory query can therefore succeed while importing a missing or unexported file fails. `import.meta.resolve` can return a URL for an exported file that does not exist; importing that URL still fails, as in native Node.
+
 ### Part 2: Walkthroughs
 
 #### Table 1: Ancestor chain and interception for ESM and CommonJS across request forms
@@ -70,12 +87,12 @@ The table uses the installation package `@deepseek-ai/dsh-tools` (has a runtime
 
 | Request form | ESM | CommonJS | Position of the package name at ③ | When a file is missing inside the package |
 |---|---|---|---|---|
-| Bare name `pkg`, package has `exports` | If ① or ② has a `pkg` directory, Node takes the entry point from its `exports` | Same as ESM; a candidate directory at ① or ② whose entry file is missing does not count as a candidate | With entry: the runtime resolution's package; without entry: the physical directory | A missing entry point under `exports` is an `exports` error, final |
-| Bare name `pkg`, package has no `exports` | As above, entry point from `main` or `index` | As above | As above | ESM fails, final; CommonJS continues looking for an entry point at the next layer |
+| Bare name `pkg`, package has `exports` | If ① or ② has a `pkg` directory, Node takes the entry point from its `exports` | Node selects the require condition from the same candidate | With entry: the runtime resolution's package; without entry: the physical directory | A missing exported target is final |
+| Bare name `pkg`, package has no `exports` | Entry point from `main` or `index` | Native legacy entry lookup | As above | ESM fails, final; CommonJS continues only for a native lookup miss, not an invalid declared `main` |
 | Subpath `pkg/sub`, package has `exports` | The first `pkg` found decides; if `./sub` is not exported, `ERR_PACKAGE_PATH_NOT_EXPORTED` is final | Same as ESM | As above | Final; no other copy is searched |
 | Subpath `pkg/sub`, package has no `exports` | If the first `pkg` found has no `sub`, `ERR_MODULE_NOT_FOUND` is final | Tries `<layer>/pkg/sub` layer by layer: ① and ②, then the position of the package name at ③ (the runtime resolution's package directory when an entry exists), then ④ | As above | ESM final; CommonJS continues to the next layer, that is ④ |
 | `#alias` package-internal alias | After the owning manifest's `imports` maps it to a bare name, handled per the rows above; a mapping to a relative path goes straight to Node | Same as ESM, with conditions from the caller or the defaults | Same as the matching row | Same as the matching row |
-| `require.resolve(pkg, { paths })` | No such form | Applies the same rule to each item in `paths` independently: an item inside the profile tree walks ① and ②, ③, ④ from that item; an item outside the tree goes to Node; in the caller's order | As above | The item continues to its next layer, then the next item takes its turn |
+| `require.resolve(pkg, { paths })` | No such form | Entire request goes to Node with the original options, regardless of the paths' locations | No interception; physical contents only | Native Node continuation and errors |
 | Package self-reference (the importer's package imports by its own `name`) | Goes to Node with the original importer kept | Same as ESM | Not involved | Not applicable |
 | Relative / absolute / URL / builtin | Goes to Node | Goes to Node | Not involved | Not applicable |
 
@@ -91,11 +108,20 @@ After a runtime resolution hit, the `ERR_MODULE_NOT_FOUND` and `ERR_PACKAGE_PATH
 
 #### Table 3: Ancestor chain when a plugin is linked outside the tree
 
+The profile links `<profile>/node_modules/my-plugin` to the plugin's real directory R. R's manifest declares `@deepseek-ai/dsh-tools` as a peer and installs it as a devDependency, and declares `zod` as a dependency.
+
 | Import source → target | Hook participates | Result |
 |---|---|---|
 | profile → linked plugin | Participates up to ② | Node follows the symlink at ②; the plugin loads by its real path |
-| Linked plugin → its own third-party dependencies | Does not participate | The real path's ancestor chain; uses the version in the developer's own `node_modules` |
-| Linked plugin → dsh installation packages | Does not participate | The copy in the developer's own `node_modules`; `ERR_MODULE_NOT_FOUND` when absent. Part 3 describes how to make it the same copy as the running dsh |
+| Linked plugin → `zod` | Participates; `zod` is not occupied at `R/node_modules` | `R/node_modules/zod`, the developer's installed version |
+| Linked plugin → `@deepseek-ai/dsh-tools` (peer) | Participates; the name is occupied at `R/node_modules` | The running dsh's copy; the devDependency copy in `R/node_modules` is not read |
+| Linked plugin → a stateful dsh package declared only as a dependency | Participates; the name is not occupied | Its own copy in `R/node_modules`, creating a second instance; the same mistake as installing the dsh package at ② inside the tree. Declare it as a peer instead |
+| Linked plugin → undeclared package name | Participates; R does not occupy the name | Physical contents of `R/node_modules`, then the same per-position rule along the real ancestor chain |
+| Transitive dependency inside R → any package name | Participates | Each position uses its own manifest's peers; nearer physical candidates precede later peer declarations |
+| Link target R has no manifest → peer declared by an ancestor | Participates | Search starts at R; an earlier physical candidate wins, otherwise the ancestor peer can select the runtime package even without physical `node_modules` there |
+| Hoisted dependency whose real directory is outside every linked root → any package name | Does not participate | Native Node lookup from that dependency's real directory |
+| Installation-scope package inside a broad linked directory → any package name | Does not participate in linked interception | Native lookup retains the host package's own dependencies |
+| Any importer → `require.resolve(pkg, { paths })` | Does not participate | Native Node lookup using the supplied paths |
 
 ### Part 3: Developer integration guide
 
@@ -107,12 +133,11 @@ The plugin's own third-party dependencies are hoisted to `$DSH_HOME/profiles/<na
 
 #### 2. Development mode: the plugin repository is outside the profile tree
 
-`npm link`, or a bare directory path such as `dsh plugin add ../my-plugin` (which pnpm treats as `link:`), makes the entry in the profile a symlink to the plugin repository. The plugin loads by its real path and the hook takes no part in its imports. The plugin repository's own dependency tree must resolve dsh installation packages to the same copy as the running dsh; both layouts below satisfy this.
+`npm link`, or a bare directory path such as `dsh plugin add ../my-plugin` (which pnpm treats as `link:`), makes the profile entry a symlink to the plugin repository, which becomes a linked root. The plugin loads by its real path. When lookup reaches its manifest's peer position, the running installation supplies matching runtime entries, whether dsh was installed globally from npm, bundled with Desktop, or started from the source repository. The devDependency copy at that position serves the compiler and is not loaded by an ordinary request. A link to a `src` directory without a manifest can use a parent directory's peers through the same ancestor lookup.
 
-- Layout A: the plugin repository installs `@deepseek-ai/dsh` and the `@deepseek-ai/dsh-*` peers the plugin uses as devDependencies and starts with the dsh in that repository, for example `pnpm exec dsh --profile <name>`. The running installation is the copy on the plugin's ancestor chain, so the runtime resolution and the real paths agree.
-- Layout B: the plugin repository links the dsh packages it uses to the local dsh source repository (`link:../deepseek-harness/packages/core/tools` or `pnpm link`) and starts `pnpm dsh --profile <name>` from the source repository. Both sides load the same copy from the source repository.
+Use the same manifest declarations as the harness packages: declare dsh packages whose instances must be shared with the host under both `peerDependencies` and `devDependencies`. The peer declaration occupies their positions at `R/node_modules`; the dev copies serve the compiler and standalone tests. Keep third-party dependencies and stateless dsh utilities such as `@deepseek-ai/dsh-brand` and `@deepseek-ai/dsh-util-values` under `dependencies`. After changing `peerDependencies`, new resolutions during a plugin reload use the new declaration; Node and Cordis still own the lifetime of already loaded modules.
 
-Not provided and not recommended: having the hook proxy installation packages for real paths linked out of the tree, which requires tracking every real root entered from the profile, something Node itself does not do for developers either; and starting with a dsh installed elsewhere while the plugin repository installs its own dsh devDependencies, which produces two module instances and splits both `Symbol()` keys and `instanceof` checks.
+Two other layouts remain available: install `@deepseek-ai/dsh` in the plugin repository and run `pnpm exec dsh --profile <name>` there, or link dsh packages to a local source repository and start dsh from that repository. Both make the running dsh and the repository's copies identical, but linked plugins do not require either layout.
 
 ## Alternatives considered
 
@@ -126,16 +151,32 @@ Not provided and not recommended: having the hook proxy installation packages fo
 
 **Hide the whole physical directory that holds the interception layer.** This conflicts with "all other resolution matches Node": non-installation packages placed in `$DSH_HOME/profiles/node_modules` would become invisible to every profile.
 
-**Extend the hook to the real directories of plugins linked outside the tree.** This requires tracking every real root entered from the profile during resolution and rewriting results for some package names under those directories; Node does this for no linked-out package, and the two layouts in Part 3 do not need it.
+**Let every runtime resolution entry occupy its package directory at `R/node_modules`.** This has exactly the same form as ③, but the closure's hundreds of third-party libraries would shadow the plugin repository's own `zod` and `yaml` versions, unlike ① and ② preceding ③ inside the tree. Occupying only peers preserves the plugin's own third-party versions.
+
+**Use the nearest importer's manifest `dependencies` to decide which names resolve natively.** That declaration does not identify a lookup position and cannot describe undeclared packages found at an ancestor. Per-position peer declarations add one eligibility rule without replacing Node's search order.
+
+**Read only the linked root's peers or require its own manifest.** A link can name a `src` directory, and nearer packages and ancestor manifests have their own lookup positions. Fixing interception at R would skip these declarations or override a nearer physical candidate.
+
+**Freeze the peer set during runtime resolution construction.** Every edit to `peerDependencies` would require restarting dsh. Reading at resolution time lets new lookups observe changes, at the cost of reading the visited manifests in development mode. Node's module caches still determine whether an already loaded request needs resolution again.
+
+**Intercept explicit CommonJS paths inside profiles.** An explicit search list is the caller's choice. Passing it unchanged to Node keeps one clear exception instead of making individual items obey different policies.
+
+**Connect the ancestor chain above the linked root back to the profile's ② and ③.** This follows the form of Node's `--preserve-symlinks`: `R/node_modules` remains the first native layer, so the devDependency copy still wins and the duplicate-instance problem remains.
 
 ## Verification
 
 - The table-driven matrix in [profile-resolution.spec.ts](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts): importers are the profile root and a plugin inside the profile; package names are an installation entry, a bundle-only entry, and a name outside the table; every presence combination of the four layers ①②③④, with ② and ③ each in two forms, a real directory and a symlink pointing elsewhere; every cell asserts that ESM import, CommonJS require, `require.resolve`, and the `packageDir` metadata land in the same directory.
+- Linked-root cases in the same file link a profile package to an external repository with a same-named devDependency copy in its `node_modules`. Package names cover an installation entry declared as a peer, one declared as a dependency, the repository's own third-party dependency, and an undeclared name; importers cover the repository's own files and transitive dependencies inside it. The cases assert agreement across the four resolution forms, that the devDependency copy is not read, and that the next resolution observes a rewritten `peerDependencies` declaration.
+- The [differential matrix](../../../../packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts) constructs independent native, intercepted, and reference directories. Only the reference copy replaces eligible peer positions with links to the runtime package; Node resolves the resulting files. Single-package and pnpm monorepo cases compare entry, file, directory, import/require, `import.meta.resolve`, and explicit-path outcomes, including absent manifests, absent `node_modules`, malformed peer declarations, React, outside-scope helpers, and legacy subpath continuation. Assertions compare package selection, existing paths, error codes, and module identity; explicit paths use the pristine native reference.
 - Dedicated cases in the same file cover each row of Table 1: bare names and subpaths with and without `exports`, `#alias`, explicit `paths`, package self-reference, CommonJS skipping ③ and going straight to ④ when a subpath is missing after a runtime resolution hit, and the interception position of an out-of-tree profile.
-- The [real CLI launch test](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts), under src and lib launches and under plain-directory and npm-link layouts, places an old `@deepseek-ai/dsh-tools` link at ③ and an external package with its embedded dependency at ③, and asserts that Tools and AgentLoop share one module instance, that the external package resolves along its real path, and that every file and link target stays byte-identical.
+- The [real CLI launch test](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts) covers src and lib launches with ordinary and npm-link layouts, plus a link to a manifest-free `src` directory whose parent declares a peer. It checks shared Tools/AgentLoop instances, native explicit-path selection of the developer's copy, real-path dependency resolution, and unchanged files and link targets. Source-mode CommonJS checks use fixture packages with existing JavaScript entries; real installation CommonJS entries require their build outputs.
 
 ## Consequences
 
-Gained: startup writes nothing to disk; installation packages always come from the running installation; all other resolution matches Node, so developers can predict results with their Node knowledge; no recognition code exists for any historical directory layout.
+Gained: module resolution needs no disk projections; dsh installation packages selected at an interception layer come from the running installation, including peers declared by plugins linked outside the tree; other resolution retains Node's ancestor-chain and package-entry rules; the lookup path does not recognize historical projection directories.
 
-Paid: third-party libraries in the installation closure still occupy package directories at ③, so a profile plugin that declares a third-party library as a peer or omits the declaration gets the version dsh uses internally, as in the disk-link era; plugins should declare third-party libraries as dependencies. Plugins linked outside the tree cannot obtain installation packages through the hook and must align themselves using the layouts in Part 3. Consumers that bypass the hook, namely child processes a plugin spawns itself, third-party Workers, and external tools run inside the profile directory, can no longer find installation packages through disk links in `$DSH_HOME/profiles/node_modules`. The resolver continues to depend on supported Node Internal interfaces.
+Paid: third-party libraries in the installation closure still occupy package directories at ③; a profile plugin without a nearer copy gets the installation's version. A linked request selects a runtime package only at a matching peer position, and a nearer physical copy still wins. Developers must place declarations and dependencies accordingly. Runtime resolution does not enforce peer version ranges.
+
+Only direct links from `<profile>/node_modules` become linked roots; dependencies whose real directories lie outside every recorded root use native Node. Peer requests do not return to the profile's ②: a name absent from the runtime table must be found on the real ancestor chain. Linked requests pay for current peer-manifest reads. Changing a link target still requires restart; module-cache invalidation and automatic watching are separate from this rule.
+
+Explicit CommonJS paths, plugin-spawned processes, third-party Workers, and external tools do not receive runtime peer mappings. Consumers outside the hook cannot find installation packages through generated disk links. The resolver continues to depend on supported Node Internal interfaces.
diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md
index 72a9e876a4..2474a9b040 100644
--- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md
@@ -12,13 +12,13 @@ profile 从自己的包项目加载插件。dsh 本体包和 bundle 内嵌的依
 
 ## Decision
 
-profile 内模块的解析是一条普通的 Node 祖先 `node_modules` 链。dsh 只做一件事：启动时算出的 runtime resolution 中的每个包名，占据 `$DSH_HOME/profiles/node_modules/<包名>` 这个包目录的位置。链走到这一层时，有条目的包名由 runtime resolution 的包回答，没有条目的包名看这一层的物理目录。除此之外的一切解析行为与 Node 一致。[不可变 generation 的构造、发布、Worker 继承与运行时载体](2026-09-09-profile-resolution-generations.zh.md)由既有 Note 记录，本篇不复述。
+普通模块请求保留 Node 的祖先 `node_modules` 顺序。profile 内，runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上对应的包位置。对于已记录的树外链接目录中的 importer，每个候选 `D/node_modules` 只应用一条规则：包名同时出现在 `D/package.json` 的 `peerDependencies` 和 runtime resolution 中，就由运行时包占据该位置；否则 Node 尝试该位置的物理包。更近的候选先于更高祖先的 peer 声明。显式 CommonJS `paths` 始终绕过拦截。其余解析行为由 Node 负责。[不可变 generation 的构造、发布、Worker 继承与运行时载体](2026-09-09-profile-resolution-generations.zh.md)由既有 Note 记录，本篇不复述。
 
 ### 一、解析规则
 
 #### 1. 主线：Node 的祖先 `node_modules` 链
 
-importer 指发起 `import` 或 `require` 的那个模块文件。Node 从 importer 所在目录开始，逐层向上尝试每一级目录下的 `node_modules`，直到文件系统根，再尝试 `NODE_PATH` 与全局目录。最近的一层优先；同一层内只按包名匹配。
+importer 指发起 `import` 或 `require` 的那个模块文件。Node 从 importer 所在目录开始，沿祖先 `node_modules` 候选位置查到文件系统根，跳过多余的 `node_modules/node_modules` 位置。CommonJS 还查询 `NODE_PATH` 与全局目录，ESM 不查询。在 Node 的包入口与失败规则下，最近的匹配候选优先。
 
 软链接按 Node 默认行为跟随到真实路径。一个模块一旦以真实路径加载，它后续 import 的主线就是真实路径的祖先链，与它被链接到哪里无关。
 
@@ -32,7 +32,7 @@ importer 指发起 `import` 或 `require` 的那个模块文件。Node 从 impor
 ⑤ /node_modules
 ```
 
-① 是插件私有依赖，② 是 profile 安装的包，③ 是拦截层，runtime resolution 占据其中有条目的包目录，④ 是 Harness home，⑤ 是文件系统根，随后是 `NODE_PATH` 与全局目录。
+① 是插件私有依赖，② 是 profile 安装的包，③ 是拦截层，runtime resolution 占据其中有条目的包目录，④ 是 Harness home，⑤ 是文件系统根。CommonJS 随后保留 `NODE_PATH` 与全局目录的查询，不在这些额外位置应用 peer 拦截。
 
 #### 2. 拦截层：runtime resolution 占据 `$DSH_HOME/profiles/node_modules/<包名>`
 
@@ -46,22 +46,39 @@ Node 仍然负责 `exports`、`imports`、conditions、`main`、子路径、扩
 
 拦截层不读、不写、不删任何磁盘链接。历史残留的软链接一律按普通文件系统内容处理：本体包名在 ③ 上的位置已被 runtime resolution 占据，旧链接永远不会被读到；其余包名按主线正常看到 ③ 里的内容。profile 加载时一次性删除 dsh 0.1.5 系列发布版的 Link 后端写进 profile 的投影：profile `node_modules` 下目标位于 `<profile>/.dsh-module-fallback/node_modules` 内的软链接，以及该目录本身。pnpm 安装的包和其他软链接都保留。
 
-#### 3. 拦截层里有什么：runtime resolution 的扫描内容
+#### 3. 链接目录：在每个祖先候选位置应用 peer 拦截
 
-runtime resolution 在 profile 启动时一次算出，由三部分组成。
+`<profile>/node_modules/<包名>` 链接到 profiles 树外的真实目录 R 时，R 是一个 linked root。R 不必包含 `package.json` 或 `node_modules`，可以是包目录、monorepo 中的单个包，也可以是 `src` 目录。R 之下的 importer 沿 Node 的真实祖先链查询。记录的根目录决定哪些 importer 参与拦截，不会把它们的查找限制在 R 内。
+
+linked 拦截排除 installation 作用域包目录内的 importer，同时识别配置路径和真实路径。因此，链接整个 checkout 不会接管宿主自身的依赖查询。重叠的 linked root 共同描述参与范围：祖先链由 importer 决定，root 顺序和链接名称都不会选择另一套 peer 集合。
+
+在每个候选 `D/node_modules`，当前 `D/package.json` 的 peer 声明命中且运行时表提供该包名时，就使用运行时包。这只占据该包的位置，即使 `D/node_modules` 在磁盘上不存在也成立。声明和运行时条目缺少任一项，Node 就尝试物理候选。缺少 manifest 不会终止查找。`dependencies` 与 `devDependencies` 不启用拦截，peer 的版本范围也不是额外的解析筛选条件。运行时表提供 React 等第三方 peer 时，同样适用这条规则。
+
+更近的物理候选先于后续祖先的 peer 声明。选中包的 `exports` 拒绝请求时，Node 的错误是终局。旧式 CommonJS 子路径缺失可以继续到下一位置，再应用那个目录的 peer 规则；不会重试已被占据位置上的物理副本。每次新的 linked 解析读取所访问位置的 manifest，不缓存选中的路由。不可读的 manifest 不提供 peer，Node 保留其原生 manifest 诊断。这不清除 Node 缓存，也不自动重新加载已加载的模块。
+
+runtime resolution 构造时扫描 `<profile>/node_modules` 的顶层与 `@scope/*` 链接。successor 可以在既有包映射和本地包名约束内新增或移除 linked root。移除无需重启：目录不再被任何 root 覆盖时，后续解析恢复原生查询。[Generation 规则](2026-09-09-profile-resolution-generations.zh.md#immutable-generations)定义了发布、已有模块引用，以及跨越移除操作的重新链接检查。依赖的真实路径在所有已记录 linked root 之外时，即使插件链接到它，也不参与拦截。
+
+#### 4. 拦截层里有什么：runtime resolution 的扫描内容
+
+runtime resolution 在 profile 启动时一次算出，由四部分组成。
 
 - installation 闭包：从当前运行的 dsh 包的 `package.json` 出发，沿 `dependencies` 与 `peerDependencies` 做广度优先遍历，每条边从声明它的 manifest 按 Node 规则解析，同一个包名由第一次找到的已安装包占有。闭包有数百条，约一半在 `@deepseek-ai/` 作用域，一半是第三方库。这些条目对所有 profile 生效。
 - bundle-only 条目：profile 选中的、不属于闭包的 bundle，从它的 manifest 出发做同样的遍历，闭包已占有的包名不覆盖。这些条目只对选中该 bundle 的 profile 生效，用于让 Loader 从 profile 根按裸名导入 bundle 内嵌的插件。
 - 本地包名：profile 直接依赖中已经安装在 `$DSH_HOME/profiles/<name>/node_modules` 的包名。它们本来就在主线 ② 上，记录下来只为免去一次目录探测。
+- linked root：`$DSH_HOME/profiles/<name>/node_modules` 顶层与 `@scope/*` 里目标同时位于共享 profiles 树和当前 profile 目录之外的目录链接，记录链接名称与真实目录。目录自身的 manifest 可缺省。目标缺失或为文件的链接都排除。位于共享树外的应用自有 profile，不会把内部 pnpm store 链接登记为外部 root。
 
 CLI 的安装锚点来自 `import.meta.url`，Node 已对它做过 realpath；Desktop Host 从其运行时目录拼出锚点，该目录不是软链接。两者的安装根目录都等于真实目录，bundle 发现与依赖遍历使用同一个位置。遍历中每一层依赖都以所属包的真实目录作为下一层的查找锚点，并记录声明它的 manifest 位置。命中后 Node 从这个声明位置解析，得到与该包自己内部 import 相同的结果。每个条目记录包名、包目录、版本、声明位置与作用域。已声明但未安装的依赖跳过；bundle 包根自身不成为条目。
 
-#### 4. hook 覆盖范围
+#### 5. hook 覆盖范围
 
-hook 只在 importer 位于 `$DSH_HOME/profiles/**` 时参与。builtin、相对路径、绝对路径、URL 请求，以及 importer 在树外的一切请求，直接交给 Node。
+hook 只在 importer 位于 `$DSH_HOME/profiles/**` 或某个 linked root 之下时参与。builtin、相对路径、绝对路径、URL 请求，以及 importer 在这两处之外的一切请求，直接交给 Node。`require.resolve(request, { paths })` 同样直接交给 Node，包括路径指向 profile 或链接目录的情况。
 
 ESM 与 CommonJS 两个适配器调用同一个路由函数，主线程与 Harness 自有 Worker 都安装同一份 runtime resolution。实现位于 `packages/boot/app-boot/src/profile-resolution/resolver.ts`，runtime resolution 的构造位于 `packages/boot/app-boot/src/profile.ts`。
 
+#### 6. 包目录与模块文件
+
+`packageDir('pkg', parentURL)` 与 `packageDir('pkg/sub', parentURL)` 定位包目录，不加载代码，也不校验子路径。普通入口与文件请求仍由 Node 应用 `exports`、`main`、conditions 和文件存在性规则。因此，包目录查询可以成功，同时导入缺失或未导出的文件会失败。`import.meta.resolve` 可以为不存在的已导出文件返回 URL，但导入该 URL 仍然失败，这与原生 Node 一致。
+
 ### 二、预演
 
 #### 表 1：ESM 与 CommonJS 在各类请求下的主线与拦截
@@ -70,12 +87,12 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数，主线程与 Harne
 
 | 请求形态 | ESM | CommonJS | ③ 上该包名的位置 | 包内缺文件时 |
 |---|---|---|---|---|
-| 裸包名 `pkg`，包有 `exports` | ①② 有 `pkg` 目录则 Node 在其中按 `exports` 取入口 | 同 ESM；①② 的候选目录缺入口文件时不算候选 | 有条目：runtime resolution 的包；无条目：物理目录 | 有 `exports` 的入口缺失是 `exports` 错误，终局 |
-| 裸包名 `pkg`，包无 `exports` | 同上，入口取 `main` 或 `index` | 同上 | 同上 | ESM 终局报错；CommonJS 从下一层继续找入口 |
+| 裸包名 `pkg`，包有 `exports` | ①② 有 `pkg` 目录则 Node 在其中按 `exports` 取入口 | Node 从同一候选选择 require condition | 有条目：runtime resolution 的包；无条目：物理目录 | 已导出目标缺失时终局报错 |
+| 裸包名 `pkg`，包无 `exports` | 入口取 `main` 或 `index` | 原生旧式入口查询 | 同上 | ESM 终局报错；CommonJS 仅对原生查询未命中继续，声明的 `main` 无效时不继续 |
 | 子路径 `pkg/sub`，包有 `exports` | 第一个找到的 `pkg` 决定；`./sub` 未导出则 `ERR_PACKAGE_PATH_NOT_EXPORTED` 终局 | 同 ESM | 同上 | 终局，不找别的副本 |
 | 子路径 `pkg/sub`，包无 `exports` | 第一个找到的 `pkg` 内没有 `sub` 则 `ERR_MODULE_NOT_FOUND` 终局 | 逐层尝试 `<层>/pkg/sub`：①②，然后 ③ 上该包名的位置（有条目即 runtime resolution 的包目录），然后 ④ | 同上 | ESM 终局；CommonJS 继续下一层，即 ④ |
 | `#alias` 包内别名 | 所属 manifest 的 `imports` 映射到裸包名后，按上面各行处理；映射到相对路径则直接交 Node | 同 ESM，conditions 取调用方传入或默认值 | 同对应行 | 同对应行 |
-| `require.resolve(pkg, { paths })` | 无此形式 | 对 `paths` 中每一项独立套用同一规则：项在 profile 树内则从该项出发走 ①②、③、④；项在树外交 Node；按调用方给出的顺序 | 同上 | 该项继续下一层，再轮到下一项 |
+| `require.resolve(pkg, { paths })` | 无此形式 | 无论路径位于何处，都把整个请求及原始选项交给 Node | 不拦截，只看物理内容 | 原生 Node 的继续查询与错误 |
 | 包自引用（importer 所属包按自己的 `name` import） | 交 Node，保留原 importer | 同 ESM | 不参与 | 不适用 |
 | 相对 / 绝对 / URL / builtin | 交 Node | 交 Node | 不参与 | 不适用 |
 
@@ -91,11 +108,20 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数，主线程与 Harne
 
 #### 表 3：插件被 link 到树外时的主线
 
+插件 `my-plugin` 被 `<profile>/node_modules/my-plugin` 链接到真实目录 R；R 的 manifest 把 `@deepseek-ai/dsh-tools` 声明为 peer 并装成 devDependency，把 `zod` 声明为 dependency。
+
 | import 来源 → 目标 | hook 是否参与 | 结果 |
 |---|---|---|
 | profile → 链接的插件 | 参与到 ② 为止 | ② 的软链接被 Node 跟随，插件以真实路径加载 |
-| 链接插件 → 它自己的第三方依赖 | 不参与 | 真实路径的祖先链，使用开发者自己 `node_modules` 里的版本 |
-| 链接插件 → dsh 本体包 | 不参与 | 开发者自己 `node_modules` 里的副本；没有则 `ERR_MODULE_NOT_FOUND`。让它与运行中的 dsh 是同一份的做法见第三章 |
+| 链接插件 → `zod` | 参与，`R/node_modules` 上 `zod` 未被占据 | `R/node_modules/zod`，开发者自己安装的版本 |
+| 链接插件 → `@deepseek-ai/dsh-tools`（peer） | 参与，`R/node_modules` 上该名被占据 | 运行中的 dsh 的那一份；`R/node_modules` 里的 devDependency 副本不被读到 |
+| 链接插件 → 只声明为 dependency 的有状态 dsh 包 | 参与，未被占据 | `R/node_modules` 里自己的副本，产生第二个实例；与树内把 dsh 包装进 ② 的错误相同，改为 peer 即可 |
+| 链接插件 → 未声明的包名 | 参与，R 不占据该包名 | `R/node_modules` 的物理内容，再沿真实祖先链逐位置应用同一规则 |
+| R 内传递依赖 → 任何包名 | 参与 | 每个位置使用自己的 manifest 的 peer；更近的物理候选先于后续 peer 声明 |
+| link 目标 R 无 manifest → 祖先声明的 peer | 参与 | 从 R 开始查；更近的物理候选优先，否则祖先 peer 可以选中运行时包，即使那里没有物理 `node_modules` |
+| 真实目录在所有 linked root 外的提升依赖 → 任何包名 | 不参与 | 从该依赖真实目录进行原生 Node 查询 |
+| 位于宽链接目录内的 installation 作用域包 → 任何包名 | 不参与 linked 拦截 | 原生查询保留宿主包自身的依赖 |
+| 任意 importer → `require.resolve(pkg, { paths })` | 不参与 | 使用指定路径进行原生 Node 查询 |
 
 ### 三、开发者接入指引
 
@@ -107,12 +133,11 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数，主线程与 Harne
 
 #### 2. 开发模式：插件仓库在 profile 树外
 
-`npm link`，或 `dsh plugin add ../my-plugin` 这类裸目录路径（pnpm 按 `link:` 处理），会让 profile 里的条目成为指向插件仓库的软链接。插件以真实路径加载，hook 不参与它的 import。dsh 本体包必须由插件仓库自己的依赖树解析到与运行中 dsh 同一份，两种布局都满足这一点。
+`npm link`，或 `dsh plugin add ../my-plugin` 这类裸目录路径（pnpm 按 `link:` 处理），会让 profile 里的条目成为指向插件仓库的软链接，仓库目录成为 linked root。插件以真实路径加载。查找到其 manifest 的 peer 位置时，匹配的运行时条目由当前运行的安装提供，无论 dsh 来自 npm 全局安装、Desktop 内置还是源码仓启动。该位置的 devDependency 副本服务编译器，普通请求不会加载它。link 指向无 manifest 的 `src` 目录时，也可以通过同一条祖先查询使用父目录的 peer。
 
-- 布局 A：插件仓库把 `@deepseek-ai/dsh` 以及插件用到的 `@deepseek-ai/dsh-*` peer 装成 devDependency，并用该仓库里的 dsh 启动，例如 `pnpm exec dsh --profile <name>`。运行中的安装就是插件祖先链上的那一份，两者的 runtime resolution 与真实路径一致。
-- 布局 B：插件仓库把用到的 dsh 包 link 到本机的 dsh 源码仓（`link:../deepseek-harness/packages/core/tools` 或 `pnpm link`），并从源码仓启动 `pnpm dsh --profile <name>`。两边加载的都是源码仓里的同一份。
+manifest 的写法与 harness 自身的包相同：需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies`，peer 让 `R/node_modules` 上的位置被占据，dev 副本给编译器和独立测试使用；第三方依赖以及 `@deepseek-ai/dsh-brand`、`@deepseek-ai/dsh-util-values` 这类无状态 dsh 工具包放在 `dependencies`。修改 `peerDependencies` 后，重新加载插件时的新解析会使用新声明；已加载模块的生命周期仍由 Node 和 Cordis 管理。
 
-不提供、不建议的做法：由 hook 为 link 出去的真实路径代理本体包，这需要追踪从 profile 进入的每个真实根目录，Node 自身也不替开发者做这件事；用别处安装的 dsh 启动，同时插件仓库另装一套 dsh devDependency，这会产生两个模块实例，`Symbol()` 键与 `instanceof` 判断都会分裂。
+另两种可用布局：插件仓库自装 `@deepseek-ai/dsh` 并从仓库里启动 `pnpm exec dsh --profile <name>`；或把 dsh 包 link 到本机源码仓并从源码仓启动。两者让运行中的 dsh 与仓库里的副本本来就是同一份，但 linked 插件不要求使用这两种布局。
 
 ## Alternatives considered
 
@@ -126,16 +151,32 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数，主线程与 Harne
 
 **把拦截层所在的物理目录整层隐藏。** 与"其余解析与 Node 一致"冲突：放在 `$DSH_HOME/profiles/node_modules` 的非本体包会对所有 profile 不可见。
 
-**让 hook 覆盖 link 到树外的插件真实目录。** 需要在解析时追踪每个从 profile 进入的真实根目录，并对这些目录下的部分包名改写结果；Node 不为任何 link 出去的包做这种事，第三章的两种布局不需要它。
+**让 runtime resolution 的全部条目占据 `R/node_modules` 上的包目录。** 与 ③ 完全同形，但闭包里的几百个第三方库会遮住插件仓库自己安装的 `zod`、`yaml` 版本，与树内 ①② 赢 ③ 相反。只占据 peer 保住了「插件自己的第三方版本优先」。
+
+**按 importer 最近的 manifest 的 `dependencies` 决定哪些包名走原生。** 这类声明不标识查询位置，也无法描述在祖先找到的未声明包。逐位置的 peer 声明只增加一条资格规则，不替换 Node 的查询顺序。
+
+**只读 linked root 的 peer，或要求它自身有 manifest。** link 可以指向 `src` 目录，更近的包与祖先 manifest 都有各自的查询位置。把拦截固定在 R 会漏掉这些声明，或覆盖更近的物理候选。
+
+**在 runtime resolution 构造时固定 peer 集合。** 开发者每次修改 `peerDependencies` 都得重启 dsh。解析时读取让新查询看到变动，代价是开发模式下要读取所访问的 manifest。已加载的请求是否需要再次解析，仍由 Node 的模块缓存决定。
+
+**拦截指向 profile 内的显式 CommonJS paths。** 显式搜索列表是调用方的选择。原样交给 Node 能保留一个清晰的例外，而不是让各个路径项遵循不同策略。
+
+**把 linked root 之上的主线接回 profile 的 ②③。** 这是 Node `--preserve-symlinks` 的形式，`R/node_modules` 仍是原生的第一层，devDependency 副本照样先被找到，单实例问题原样保留。
 
 ## Verification
 
 - [profile-resolution.spec.ts](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) 中的表驱动矩阵：importer 取 profile 根与 profile 内插件，包名取 installation 条目、bundle-only 条目与表外包名，①②③④ 四层的每一种有无组合，②③ 各含真目录与指向别处的软链接两种形态；每格断言 ESM import、CommonJS require、`require.resolve` 与 `packageDir` 元数据落在同一个目录。
+- 同一文件内的 linked root 用例：`<profile>/node_modules` 的软链接指向树外仓库，仓库 `node_modules` 里放同名 devDependency 副本；包名取声明为 peer 的 installation 条目、声明为 dependency 的 installation 条目、仓库自己的第三方 dependency、未声明的包名，importer 取仓库自身文件与仓库内传递依赖；断言四种解析方式一致、devDependency 副本不被读到，以及改写 `peerDependencies` 后下一次解析立即按新声明进行。
+- [差分矩阵](../../../../packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts)构造独立的原生、拦截与参考目录。只有参考副本把合格 peer 位置替换为运行时包的链接，再让 Node 解析文件。单包与 pnpm monorepo 用例对比入口、文件、目录、import/require、`import.meta.resolve` 与显式路径的结果，覆盖 manifest 缺失、`node_modules` 缺失、错误 peer 声明、React、作用域外 helper 和旧式子路径继续查询。断言比较选包、现存路径、错误码与模块实例；显式 paths 使用未投射的原生参考。
 - 同一文件内的专项用例覆盖表 1 各行：有无 `exports` 的裸包名与子路径、`#alias`、显式 `paths`、包自引用、命中 runtime resolution 后 CommonJS 子路径缺失时跳过 ③ 直接到 ④，以及树外 profile 的拦截位置。
-- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)在 src 与 lib 两种启动、普通目录与 npm-link 两种布局下，放置 ③ 的旧 `@deepseek-ai/dsh-tools` 链接、③ 的外部包及其内嵌依赖，断言 Tools 与 AgentLoop 共用同一模块实例、外部包沿真实路径解析、所有文件与链接目标逐字节不变。
+- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)覆盖 src 与 lib 启动、普通与 npm-link 布局，以及指向无 manifest 的 `src` 目录且其父目录声明 peer 的链接。测试检查 Tools/AgentLoop 共享实例、原生显式路径选中开发者副本、依赖沿真实路径解析，以及文件和链接目标保持不变。源码模式的 CommonJS 检查使用具备现存 JavaScript 入口的 fixture 包；安装中真实的 CommonJS 入口需要相应构建产物。
 
 ## Consequences
 
-买到的：启动不写盘；本体包永远来自当前运行的安装；其余解析与 Node 一致，开发者可以用 Node 的知识预测结果；没有针对任何历史目录形状的识别代码。
+买到的：模块解析无需磁盘投影；命中拦截层的 dsh 本体包来自当前运行的安装，link 到树外的插件声明的 peer 也适用；其余解析保留 Node 的祖先链和包入口规则；解析路径不识别历史投影目录。
 
-付出的：installation 闭包里的第三方库仍占据 ③ 上的包目录，profile 插件把第三方库声明成 peer 或漏声明时会拿到 dsh 内部使用的版本，与磁盘链接时代相同，插件应把第三方库声明成 dependency；link 到树外的插件不能通过 hook 拿到本体包，必须按第三章的布局自行对齐；不经过 hook 的消费者，即插件自己 spawn 的子进程、第三方 Worker、在 profile 目录里运行的外部工具，不再能通过 `$DSH_HOME/profiles/node_modules` 的磁盘链接找到本体包；resolver 继续依赖受支持的 Node Internal 接口。
+付出的：installation 闭包中的第三方库仍占据 ③ 上的包目录；profile 插件没有更近副本时会使用安装中的版本。linked 请求只在匹配的 peer 位置选中运行时包，更近的物理副本仍优先。开发者需要相应安排声明与依赖位置。runtime resolution 不校验 peer 版本范围。
+
+只有 `<profile>/node_modules` 的直接链接成为 linked root；依赖真实目录在所有已记录根之外时使用原生 Node。peer 请求不会回到 profile 的 ②：运行时表不提供的包名必须能在真实祖先链上找到。linked 请求承担实时读取 peer manifest 的成本。同一链接换目标仍需重启；模块缓存失效与自动监视不属于这条规则。
+
+显式 CommonJS paths、插件自行启动的子进程、第三方 Worker 和外部工具不会获得运行时 peer 映射。不经过 hook 的消费者无法通过生成的磁盘链接找到本体包。resolver 继续依赖受支持的 Node Internal 接口。
diff --git a/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.i18n.yaml
new file mode 100644
index 0000000000..d5903d0fc2
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.md
+2026-09-19-remote-duplex-stream.md: 0f1f6a575f6871d37822c5829fe4531261b8e95b
+2026-09-19-remote-duplex-stream.zh.md: d3982aa433aa3ce84b945bb5831cef8064472853
diff --git a/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.md b/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.md
new file mode 100644
index 0000000000..0f1f6a575f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.md
@@ -0,0 +1,597 @@
+# Agent Note: Remote duplex stream: one kind of stream, an uplink channel, and an invocation context
+
+Status: implemented
+
+English | [中文](2026-09-19-remote-duplex-stream.zh.md)
+
+## Problem
+
+### Current state
+
+`dsh-api-gateway` multiplexes every Typert Remote stream over one WebSocket at the fixed path `/api/remote.mux` (`packages/api/gateway/src/stream-protocol.ts`). A Host method decorated with `@Remote({ mode: 'stream' })` that returns an `Iterable` or `AsyncIterable` becomes one Host-to-Client logical stream; the optional final `signal: AbortSignal` is the only reserved parameter, never enters the wire arguments, and is appended by the Gateway after the decoded business parameters (`packages/api/gateway/src/index.ts`). The generated method the Client receives returns a bare `AsyncIterable`.
+
+There are only five wire frames:
+
+| Direction | Frame | Definition |
+| --- | --- | --- |
+| Client to Host | `{ type: 'open', streamId, endpoint, payload }` | `stream-protocol.ts` |
+| Client to Host | `{ type: 'cancel', streamId }` | `stream-protocol.ts` |
+| Host to Client | `{ type: 'item', streamId, value? }` | `stream-protocol.ts` |
+| Host to Client | `{ type: 'error', streamId, error: { code, message, details } }` | `stream-protocol.ts` |
+| Host to Client | `{ type: 'end', streamId }` | `stream-protocol.ts` |
+
+The Client can send only open and cancel. The parser `parseRemoteStreamClientMessage` (`stream-protocol.ts`) throws on any other frame, and a Host connection that receives one closes the whole socket with 1008 (`stream-server.ts`). In short, the Gateway today supports only "a backend iterable sent to the frontend". Every feature that needs the frontend to send data to the backend continuously takes its own detour.
+
+A Host method also has no notion of who initiated this call: `InvokeRemoteRequest = { namespace, method, args, signal }` (`packages/api/gateway/src/types.ts`) has no caller slot, `RemoteStreamOpener` has the signature `(endpoint, payload, signal)` (`stream-server.ts`), and the WebSocket checks the cookie once, at the handshake.
+
+### Three unrelated uplink mechanisms
+
+| Feature | Uplink path | Location | Cost |
+| --- | --- | --- | --- |
+| Web terminal keystrokes | One unary RPC `terminal.write(agent, id, attachmentId, data)` per xterm `onData`; the Client serializes them through a promise chain and caps its own byte budget | `packages/api/terminal-controller/src/client/model.ts`; Host `src/index.ts` | One HTTP round trip and one authentication per keystroke; two carriers correlated by hand through `attachmentId`; `inputFull` when the budget is exhausted |
+| File upload | A `Blob` or `ReadableStream` goes to the native `POST /api/session/uploadFileBinary` outside the Remote layer, with `duplex: 'half'` | `packages/client/file-upload/src/client/runtime.ts`; route `src/index.ts` | Bypasses Typert descriptors; no type projection |
+| Answers to approvals and questions | The Host sends waterfall frames down the `$events` stream, the Client answers through a separate unary RPC `$events/result`, correlated by `clientId` plus `eventId` | `packages/api/gateway/src/client/remote-events.ts`; Host `index.ts` | A second correlation key; `index.ts` records the race this creates |
+
+These three mechanisms solve the same problem: the Client wants to write into a logical stream that is already open.
+
+### Concrete costs
+
+- **Aligning two carriers.** The terminal uses `attachmentId` to correlate the `follow` stream with the `write` RPC and to decide who owns input. Approvals use `clientId` to correlate the `$events` stream with the `$events/result` RPC.
+- **No ordering guarantee.** A unary RPC travels over HTTP and is unordered relative to the WebSocket downlink; the terminal can preserve order only by serializing writes on the Client.
+- **Separate authentication and lookup per uplink.** Every `write(agent, id, attachmentId, data)` resolves `agent`, looks up the terminal, and validates the attachment.
+- **No EOF.** The Client cannot express "I am done writing"; a half-close needs yet another RPC.
+- **Cancellation does not cover both halves.** Cancelling the downlink stream does not cancel queued uplink writes, and vice versa.
+- **Backpressure implemented three times.** The downlink pulls the iterator at the pace of the socket write callback (`stream-server.ts`); the terminal uses a bounded follower that makes a slow consumer fail explicitly (`terminal-controller/src/stream.ts`); the uplink relies on the Client capping `maxInputBytes` itself.
+- **The documentation is already stale.** `docs/api-gateway.md:160` still says Remote handles one request and one result, a sentence that lags the stream mode the README records.
+
+### Relation to background jobs
+
+The process-shaped duplex stream face of background jobs (archived as a draft PR on branch `worktree/job-stdio-stream-pair-archive`) models a job as a pair of mirrored stream faces; for the browser to attach to it, one Remote stream must carry both a downlink and an uplink. It is one motivation for this Note but not in its scope: whether jobs need a dedicated read-write stream is an architecture question for the jobs line itself. This Note covers only the transport layer.
+
+### Goals
+
+1. The transport layer has one kind of stream, duplex by nature: downlink `item` / `end` / `error`, uplink `item` / `end`, one `streamId`, one generation.
+2. The uplink type and the downlink type are written in the same place: the method's return type.
+3. A Host method takes its uplink from the invocation context; the invocation context also carries the caller (the Peer).
+4. The Client receives a handle that can read, write, and close, not a bare `AsyncIterable`.
+5. Upper-layer protocols (snapshot, journal, any business-defined stream) stay out of the transport layer.
+
+## Decision
+
+### In one sentence
+
+Every Remote stream accepts a Client uplink. The method's return type `RemoteStream<Out, In = never>` declares the downlink item type and the uplink item type together; the generator derives two codecs from it. A Host method takes the uplink iterator through `this.ctx.invocation.uplink<In>()` and learns the caller through `this.ctx.invocation.peer`. The generated Client method returns a `RemoteStreamHandle<Out, In>`: `for await` reads the downlink, `send` / `end` write the uplink, `dispose` closes. Reopening after disconnection, cursor resumption, and baseline validation all belong to upper-layer protocols.
+
+```
+                 Client                                             Host
+   ─────────────────────────────────              ───────────────────────────────────────────
+   const s = remote.job.attach(req, signal)
+        │  open { streamId, endpoint, payload } ───────▶  opener(endpoint, payload, uplink, peer, control)
+        │                                                     │ prepareInvocation
+        │  s.send(v1) → item { streamId, v1 }    ───────▶  inbox.push(v1)   │ invocation = { request, service, peer, signal, uplink() }
+        │  s.send(v2) → item { streamId, v2 }    ───────▶  inbox.push(v2)   │ receiverContext.extend({ invocation }).get(service)
+        │  s.end()    → end  { streamId }        ───────▶  inbox.end()      │ method(...args, signal)
+        │                                        ◀───────  item { streamId, o1 }   │   for await (v of this.ctx.invocation.uplink()) …
+        │  for await (o of s) …                  ◀───────  item { streamId, o2 }   │   yield o …
+        │  s.dispose() → cancel { streamId }     ───────▶  control.abort()         │ signal aborts; uplink.return()
+        │                                        ◀───────  end | error
+```
+
+### Terms
+
+| Term | Meaning |
+| --- | --- |
+| Logical stream | One call identified by one `streamId`, spanning `open` to the terminal frame |
+| Generation | One physical lifetime of a logical stream. The transport layer knows exactly one generation; disconnection is failure, and reopening belongs to the upper layer |
+| Downlink | The Host-to-Client `item` sequence, terminated by `end` or `error` |
+| Uplink | The Client-to-Host `item` sequence, terminated by `end` (half-close) or ended together with `cancel` |
+| Half-close | One direction has ended while the other remains open |
+| Item | One business value in one direction; every item is validated by the codec independently |
+| inbox | The bounded uplink queue the Host keeps per logical stream |
+| Peer | The party the connection layer admitted, one `PeerScope`; this Host has exactly one Peer, the operator |
+| Invocation context | `RemoteInvocation`: the request, receiving service, Peer, cancellation signal, and uplink entry of this call |
+
+### Type signatures
+
+```text
+// @deepseek-ai/dsh-typert-protocol
+/**
+ * One Remote stream. Host face: the method returns it, and at runtime it is AsyncIterable<Out>.
+ * On the Client face the generated method returns RemoteStreamHandle<Out, In>; each name has exactly one meaning.
+ * In is the item type the Client may send uplink; the default never means the method reads no uplink.
+ */
+export type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+
+// Host
+@Remote({ mode: 'stream' })
+async *attach(request: JobAttachRequest, signal: AbortSignal): RemoteStream<JobFollowFrame, JobInputFrame> {
+  const uplink = this.ctx.invocation.uplink<JobInputFrame>()
+  void (async () => { for await (const frame of uplink) … })()
+  yield …
+}
+
+// Generated Client signature: same parameters, returns the handle
+attach(request: JobAttachRequest, signal?: AbortSignal): RemoteStreamHandle<JobFollowFrame, JobInputFrame>
+
+// Client usage
+const stream = remote.job.attach(req, signal)
+for await (const frame of stream) …
+stream.send(frame)     // typed as JobInputFrame
+stream.end()
+stream.dispose()
+```
+
+`RemoteStream` is an alias rather than an interface, deliberately: if the transport layer later takes a Node stream form, only the alias definition and the adapters at both ends change; method signatures, descriptors, and upper-layer protocols stay untouched.
+
+### Host face
+
+```text
+/** The context of this Remote call. A method reads it through this.ctx.invocation. */
+export interface RemoteInvocation {
+  readonly request: {
+    readonly namespace: string
+    readonly method: string
+    readonly args: Readonly<Record<string, unknown>>
+  }
+  /** Cordis service key of the receiving service. */
+  readonly service: string
+  /** The Peer that initiated the call. In-process carriers and unadmitted calls are the operator. */
+  readonly peer: PeerScope
+  /** Carrier cancellation: Client cancel, socket closure, uplink failure. */
+  readonly signal: AbortSignal
+  /**
+   * The uplink items of this call. Can be taken once; the second call throws. With an uplink codec
+   * in the descriptor each item is decoded to In; without one, items are delivered as unknown with
+   * only a JSON-safety check.
+   * The iteration ends after the Client's end; when the method ends the downlink, the Gateway calls
+   * its return() and drops unconsumed items.
+   * The generic In is only the caller's type assertion; runtime decodes per the descriptor and does not cross-check.
+   */
+  uplink<In = unknown>(): AsyncIterable<In>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** The Remote call this Context was derived for; undefined on a Context not derived from a Remote call. */
+    readonly invocation: RemoteInvocation | undefined
+  }
+}
+```
+
+Rules:
+
+1. Any `mode: 'stream'` method may call `this.ctx.invocation.uplink()`; a unary method may too, but its stream ends when the method returns, so uplink items are readable only while the method runs.
+2. While `uplink()` has not been called, uplink items accumulate in the inbox until the limit is exceeded (see Backpressure) or the stream ends and they are dropped. This is deliberate: a method that does not read the uplink need not know the uplink exists.
+3. When `In` defaults to `never`, the descriptor has no uplink codec; the Client handle's `send` has type `never`, so nothing can be sent at compile time. If frames still arrive at runtime (from a hand-built client), they are delivered as `unknown`.
+4. `this.ctx.invocation` is `undefined` on a Context not derived from a Remote call; a method that reads it handles the optional as TypeScript requires, or asserts it on the method's first line. The accessor for that property is registered once when the `TypertRemoteService` base class is constructed, so any composition that installs a Remote service can read it.
+
+#### How the invocation context reaches the method
+
+The mechanism relies on two existing Cordis behaviors:
+
+- `ctx.extend(meta)` is `Object.create(parent)` plus own properties (`vendor/cordis/src/context.ts:99-107`): no registration, no fiber, nothing to release, so deriving one per call costs nothing.
+- `ctx.get(service)` returns the `createTraceable(ctx, service)` proxy (`vendor/cordis/src/reflect.ts:233-234`, `utils.ts:117-125`). Reading the `ctx` property returns the accessing Context directly (`utils.ts:175`); reading a method wraps it in `createShadowMethod`, whose `apply` replaces `this` with a shadow receiver whose `ctx` is `ctx.extend({ [symbols.shadow]: origin })` (`utils.ts:149-163`).
+- The Gateway therefore writes `receiverContext.extend({ invocation }).get(descriptor.service)` to obtain a per-call view and calls `Reflect.apply(method, callReceiver, args)`; inside the method body, `this.ctx.invocation` reads this call through the prototype chain. The deferred execution of an async generator body is unaffected, because `this` was bound to the shadow object at call time.
+
+### PeerScope
+
+```text
+/** The opaque identity of one Peer. */
+export type PeerId = Branded<'PeerId'>
+
+/** One Peer's session on this Host: opened and released by the admitting side; ctx owns connection-lifetime registrations. */
+export interface PeerScope {
+  readonly id: PeerId
+  readonly ctx: Context
+  dispose(): Promise<void>
+}
+```
+
+This Host has exactly one Peer: the operator. `@deepseek-ai/dsh-client-connection` creates it with `createScope(connectionCtx, peer)` when the service applies, the same mechanism an Agent uses to create its own scope: the Peer object is the ScopeKey, `peer.ctx` carries connection-lifetime effects, and `dispose()` runs with the Connection's release and quiets the fiber. It is exposed as `connection.operator`.
+
+| Member | Semantics |
+| --- | --- |
+| `connection.operator: PeerScope` | The only Peer; lives and dies with the Connection |
+| `connection.admit(request): PeerAdmission` | Runs the existing `requestRejection`: returns `{ rejection: 401 \| 403 }` when refused, otherwise `{ peer: operator }`. Future admitters plug in here |
+
+The Gateway's `handleUpgrade(req, socket, head, peer)` binds an opener with a fixed Peer to that socket and registers socket closure in `peer.ctx.effect`; when the scope is already inactive, it closes the socket directly with 1001 instead. When `InvokeRemoteRequest.peer?` or the `peer` parameter of `RemoteStreamOpener` is absent, the answer is the operator, so existing in-process callers change nothing; in a composition without a Connection, the operator stand-in the Gateway builds for itself is likewise created through `createScope`, with the same `dispose()` contract. Looking up a Peer by id, associating a carrier with a second Peer, and Peer open and close events all wait until the first consumer that needs multiple Peers appears.
+
+The Peer carries no access model: who the Peer is and what it may do are attached by business plugins on their own through `peer.ctx`.
+
+### Client face
+
+```text
+/** The handle a generated method returns on the Client face. A different name from the Host's RemoteStream, exported from the same entry point. */
+export interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+  /** Send one uplink item. Throws on a value that is not lossless JSON, after termination, or after end. */
+  send(item: In): void
+  /** Half-close the uplink: sends the end frame. Idempotent. */
+  end(): void
+  /** Cancel the whole logical stream: sends the cancel frame (when no terminal frame has arrived); the downlink iterator ends quietly. */
+  dispose(): void
+}
+```
+
+- The handle represents one generation. When the carrier is lost, `for await` fails with `RemoteStreamCarrierError` and the handle ends there; whether to reopen, and with which arguments, belongs to the upper-layer protocol.
+- `send` is synchronous: it runs the `isRemoteJsonValue` check before enqueuing and throws synchronously on a value that is not lossless JSON. The browser's `WebSocket.send` has no write callback, so throttling sends would be meaningless; the Host-side inbox limit is the only backpressure point.
+- When a terminal frame (`end` / `error`) arrives, the mux client stops the pump and closes the uplink queue immediately on the receive path, so later `send` / `end` throw without waiting for the consumer's next read.
+- `dispose()` calls `return()` on the carrier iterator, so the `cancel` frame is sent even when nobody is reading the downlink; afterwards the handle's `next()` ends immediately and buffered items are dropped. A consumer that `break`s out of `for await` early is equivalent to `dispose()`.
+- The `$stream` supervisor, `RemoteSnapshotStream`, and `RemoteJournalStream` are upper-layer tools outside the transport layer. The object their `open` factories receive is the handle itself, with unchanged `for await` behavior; exposing `send` to these upper-layer protocols is deferred.
+
+### Wire frames
+
+```text
+export type RemoteStreamClientMessage =
+  | { readonly type: 'open'; readonly streamId: string; readonly endpoint: string; readonly payload: unknown }
+  | { readonly type: 'item'; readonly streamId: string; readonly value?: unknown }   // new: uplink item
+  | { readonly type: 'end'; readonly streamId: string }                              // new: uplink half-close
+  | { readonly type: 'cancel'; readonly streamId: string }
+
+/** Frames sent by the Host are unchanged. */
+export type RemoteStreamServerMessage =
+  | { readonly type: 'item'; readonly streamId: string; readonly value?: unknown }
+  | { readonly type: 'error'; readonly streamId: string; readonly error: RemoteStreamFailure }
+  | { readonly type: 'end'; readonly streamId: string }
+```
+
+Parsing rules: `item` has exactly the keys `type` and `streamId` plus an optional `value`, and `value` must be a lossless JSON value (`isRemoteJsonValue`); `end` has exactly the keys `type` and `streamId`. Any other frame is a frame-format violation, and the socket closes with 1008. No binary frames are introduced.
+
+### Logical stream state machine
+
+#### Host side
+
+```
+                open frame
+   (none) ───────────────────▶ opening ──── opener resolves ────▶ running
+                                  │                                  │
+                                  │ item frame: inbox.push           │ item frame: inbox.push
+                                  │ end frame: inbox.end             │ end frame: inbox.end (uplink half-close)
+                                  │                                  │ method yield: sends item frame
+                                  │ cancel frame / socket close ────▶│ cancel frame / socket close: control.abort
+                                  ▼                                  ▼
+                               aborted ◀───────────────────────── finished (sends end or error frame)
+```
+
+`item` frames that arrive during `opening` enter the inbox: `receive()` is synchronous and creates the `ActiveStream` and its inbox while handling the `open` frame, whereas the opener is asynchronous. Items the Client sends immediately after `open` are not lost.
+
+#### Client side
+
+```
+   call generated method ──▶ await socket ──▶ send open ──▶ handle usable
+                                                            │ send(v): sends item; end(): sends end
+                                                            │ downlink: inbox.next() → yield; end → ends; error → throws
+                                                            │ downlink terminates first: send/end throw
+                                                            │ dispose or caller signal abort: sends cancel (when no terminal frame has arrived)
+```
+
+### Half-close and termination
+
+| Uplink | Downlink | Result |
+| --- | --- | --- |
+| Client `end` | Still open | The Host's `uplink()` iteration ends; the method keeps producing. This is the stdin EOF form |
+| Still open | The Host method finishes and sends `end` | The Client handle terminates, and later `send` / `end` throw; the Host calls `return()` on the `uplink` iterator and drops unconsumed items |
+| Still open | The Host method throws and sends `error` | Same as above; the Client downlink fails with `RemoteError` |
+| Client `dispose` or signal abort | Any | Sends `cancel`; the Host runs `control.abort()`, `cancellableStream` closes `uplink` first and then calls `return()` on the method iterator; no terminal frame is sent |
+| Socket closes | Any | The Host aborts every stream and awaits `done`; on the Client every stream fails with `RemoteStreamCarrierError` |
+| `item` received after `end` | Any | The stream fails with a `gateway/protocol` error frame and aborts; the socket stays open |
+| `item` / `end` with an unknown `streamId` | Any | Ignored, like `cancel`: after the Host ends a stream and deletes its id, uplink frames still in flight from the Client are normal and must not take down the other streams on the same socket |
+
+### Ordering guarantees
+
+Frames on one socket arrive in total order: a logical stream's `open`, `item`…, `end` reach the Host in send order, and uplink items enter `uplink()` in the order of `send`. There is no cross-direction ordering guarantee between uplink and downlink; a protocol that needs request-response pairing carries its own sequence numbers.
+
+### Backpressure
+
+WebSocket has no per-stream window like HTTP/2: one connection is one serial write chain, and a slow stream holds up the other streams on the same connection. This property of the downlink is unchanged. For the uplink:
+
+**A bounded inbox plus whole-stream failure.** The Host meters each logical stream's inbox in UTF-8 bytes of its frames, with the limit set by the Gateway config `streamInboxBytes` (default 262144) and applied to every stream. On overflow the whole logical stream fails with `gateway/uplink-overflow`: the downlink breaks with it, an `error` frame goes to the Client, and the `uplink()` iterator ends with the same error. No data is discarded; a method that does not read its uplink while the Client keeps sending is a usage error, and the failure exposes it explicitly.
+
+Credit frames wait until a consumer that needs sustained high-volume uplink appears; the inbox limit is the initial credit, and adding them is incremental.
+
+### Security and validation
+
+| Item | Rule |
+| --- | --- |
+| Authentication | Same as today: `connection.requestRejection(req)` at upgrade; descriptor and lookup-parameter validation at open. Uplink items belong to an already authenticated stream and are not authenticated again |
+| Peer | Admitted at upgrade as one `PeerScope`; `invocation.peer` of every stream on that socket is that Peer |
+| Item validation | With an uplink codec, every item is decoded strictly, and a failure fails the whole stream with the existing `gateway/input-invalid` (details `{ endpoint, field: 'uplink' }`); without a codec, only JSON-safety validation applies |
+| Frame size | A single frame keeps the `maxPayload` of `ws`; the inbox limit bounds the accumulated total |
+
+### In-process and worker carriers
+
+| Carrier | Change |
+| --- | --- |
+| `ClientConnectionRpc.open` (`packages/client/connection/src/rpc.ts:245-250`) and `RpcStreamOpen` (`client/rpc.ts:21-25`) | Append an optional `uplink?: AsyncIterable<unknown>`; in process there are no frames and no inbox, the caller's iterator is the source of `uplink()` directly, and backpressure is the pace of the iterator itself |
+| Worker tunnel (`packages/experimental/webworker-runtime`) | The page adds `stream-uplink-item` / `stream-uplink-end` frames; `serveStream` assembles them into an `uplink` handed to `seams.openStream`. Same-origin trusted boundary: no inbox limit, and items after `end` are dropped |
+| `remote-mock` (`packages/test-support/remote-mock`) | `StreamHandle.uplink: AsyncIterable<unknown>`; `rpc.open` passes it through |
+
+An in-process carrier with no `peer` means the operator.
+
+### Relation to `$events`
+
+`$events` is a stream on a reserved endpoint; with uplink frames, waterfall answers can become uplink items on the same `streamId`, `clientId` becomes redundant because `streamId` already identifies the generation, and `$events/result` disappears together with the race at `index.ts:527-529`. Out of scope for this Note; see Deferred.
+
+## Type and wire definitions
+
+### typert protocol (`packages/typert/protocol/src`)
+
+```text
+// types.ts
+export type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+export type PeerId = Branded<'PeerId'>
+export interface PeerScope { readonly id: PeerId; readonly ctx: Context; dispose(): Promise<void> }
+export interface RemoteInvocation { … }              // see Host face
+declare module '@deepseek-ai/cordis' { interface Context { readonly invocation: RemoteInvocation | undefined } }
+
+export interface InvocationDescriptor {
+  // existing fields unchanged; mode still has only 'stream'
+  readonly mode?: 'stream'
+  /** Uplink item codec, generated from In of the return type RemoteStream<Out, In>; absent when In is never. */
+  readonly uplink?: { readonly codec: TypertCodec }
+  readonly cancellation?: { readonly parameter: 'signal' }
+  readonly result: TypertCodec
+}
+```
+
+The `Remote` decorator, `RemoteMethodOptions`, and `RemoteMethodMarker` recognize only `mode: 'stream'`.
+
+### typert generator (`packages/typert/generator/src`)
+
+- `model.ts`: `InvocationModel.uplink?: { boundary: RemoteBoundaryModel }`.
+- `analyzer.ts` `remoteResultType`: for `mode: 'stream'`, the accepted return-type wrappers are `Iterable<Out>`, `AsyncIterable<Out>`, and `RemoteStream<Out, In?>`. `RemoteStream` is recognized the same way as the standard library's `AsyncIterable`: by symbol name plus declaring file (`types.ts` of `@deepseek-ai/dsh-typert-protocol`). The first type argument is the downlink item; when the second is present and is not `never`, an `uplink` boundary is generated under the key `${endpoint}:uplink`.
+- `emitter.ts`: the descriptor literal emits `uplink: { codec }`; the generated Client signature returns `RemoteStreamHandle<Out, In>`.
+- The parameter loop recognizes no parameter named `uplink`.
+
+### Two names, one entry point
+
+A Host method declares a stream with `RemoteStream<Out, In>`; the Client holds a `RemoteStreamHandle<Out, In>`. Both are exported from the main entry point of `@deepseek-ai/dsh-typert-protocol`, and the handle interface has no Host dependency. The generated Client contract writes the return type as `RemoteStreamHandle<Out, In>`. One name has one meaning: the `RemoteStream` that Client code obtains from the main entry point is always the declaration type and is never confused with the handle.
+
+### Gateway Host (`packages/api/gateway/src`)
+
+```text
+// types.ts
+export interface InvokeRemoteRequest {
+  readonly namespace: string
+  readonly method: string
+  readonly args: Readonly<Record<string, unknown>>
+  /** Uplink items; absent is equivalent to an iterator that ends immediately. */
+  readonly uplink?: AsyncIterable<unknown>
+  /** The Peer that initiated the call; absent means the operator. */
+  readonly peer?: PeerScope
+  readonly signal?: AbortSignal
+}
+
+export interface TypertGatewayWireStream {
+  open: (endpoint: string, payload: unknown, uplink: AsyncIterable<unknown>, peer: PeerScope | undefined, signal: AbortSignal) => Promise<AsyncIterable<unknown>>
+  failure: (error: unknown) => RemoteStreamFailure
+}
+
+// stream-server.ts
+export type RemoteStreamOpener = (
+  endpoint: string,
+  payload: unknown,
+  uplink: AsyncIterable<unknown>,
+  peer: PeerScope,
+  control: AbortController,
+) => Promise<AsyncIterable<unknown>>
+
+// index.ts Config addition
+/** Uplink inbox limit per logical stream, in UTF-8 bytes of frames (default 262144). */
+readonly streamInboxBytes?: number
+```
+
+`prepareInvocation`:
+
+```text
+const args = await Promise.all(descriptor.parameters.map(parameter => this.resolveParameter(parameter, request.args, endpoint)))
+const signal = request.signal ?? NEVER_ABORTED_SIGNAL
+const invocation = new GatewayInvocation(
+  { namespace: request.namespace, method: request.method, args: request.args },
+  descriptor.service,
+  request.peer ?? this.operatorPeer(),
+  signal,
+  new UplinkDecoder(request.uplink ?? EMPTY_ASYNC_ITERABLE, descriptor.uplink?.codec, endpoint, control),
+)
+const callReceiver = receiverContext.extend({ invocation }).get(descriptor.service) as object
+if (descriptor.cancellation !== undefined) args.push(signal)
+```
+
+`GatewayInvocation.uplink()` returns the decoder on the first call and throws on the second. `UplinkDecoder` is a hand-written iterator: with a codec it runs `decode(codec, value, endpoint, 'uplink')` per item and, on failure, calls `control.abort(failure)` and throws; without a codec it applies only the `isRemoteJsonValue` check. The `finally` of `cancellableStream` closes the decoder first (`invocation.close()`) and then awaits the method iterator's `return()`, so a method blocked on `uplink.next()` can exit. The mode branches are the existing two, unary and stream. SRC fallback: the descriptor has no `uplink` codec, and `uplink()` delivers `unknown`.
+
+### Gateway Host mux (`stream-server.ts`)
+
+```text
+interface ActiveStream { readonly control: AbortController; readonly inbox: UplinkInbox; done: Promise<void> }
+
+/** Bounded uplink queue; iterated as the source of uplink(). */
+class UplinkInbox implements AsyncIterable<unknown>, AsyncIterator<unknown> {
+  constructor(maxBytes: number, onOverflow: (error: RemoteError) => void)
+  push(value: unknown, frameBytes: number): void   // push after ended fails the stream with gateway/protocol; overflow calls onOverflow
+  end(): void                                        // idempotent
+  fail(error: unknown): void                         // ends the iterator with an error on cancel or carrier closure
+  next() / return()                                  // hand-written: next races failure, return releases immediately
+}
+```
+
+`receive(text)` dispatch:
+
+```
+open   : exists → throw (socket 1008); otherwise create { control, inbox, done } and start the pump
+item   : missing → ignore; otherwise inbox.push(value, bytes)
+end    : missing → ignore; otherwise inbox.end()
+cancel : missing → ignore; otherwise control.abort(new Error('Remote stream cancelled'))
+```
+
+`pump` passes the inbox and the socket's Peer to the opener and calls `inbox.fail(...)` in its `finally`. An abort whose reason is a `RemoteError` is sent by the pump as an `error` frame (a failure raised by the Gateway or the mux); an abort whose reason is a plain `Error` (cancel, socket closure) sends no terminal frame.
+
+### Gateway Client (`packages/api/gateway/src/client`)
+
+- `prepareInvocation` strips no uplink parameter; the positional parameters are the business parameters plus the optional `signal`.
+- `invokeStream` returns a `RemoteStreamHandle`: it holds an uplink queue internally, `send` enqueues and a pump sends the `item` frames, `end` sends the `end` frame, and `dispose` aborts the generation signal. The downlink is still the iterator that `openRemoteStream` returns.
+- `RemoteStreamMuxClient.open(endpoint, payload, signal, uplink?)`: after sending the `open` frame it starts the uplink pump, which sends one `item` per item and `end` when the source ends; when the downlink terminates or the signal aborts, it stops the pump and calls the source's `return()` (without awaiting, so a keyboard-style generator cannot hang it); when the source throws, it calls `inbox.fail(error)`, the downlink fails with that error, and `finally` sends `cancel` under the existing rules. The pump checks `this.socket === socket`, so an old generation never sends frames on a new socket.
+- In-process carrier: `connection.rpc.open(channel, endpoint, payload, signal, uplink)`.
+
+## Placement
+
+| Package | Carries |
+| --- | --- |
+| `dsh-typert-protocol` (`types.ts`, `index.ts`) | `RemoteStream`, `RemoteStreamHandle`, `PeerId`, `PeerScope`, `RemoteInvocation`, the `ctx.invocation` declaration merge, `InvocationDescriptor.uplink`; the decorator recognizes only `mode: 'stream'`; `TypertRemoteService` registers the `invocation` accessor when constructed |
+| `dsh-typert-registry` | Load-time validation that `uplink.codec` is a valid strict codec |
+| `dsh-typert-generator` (`model.ts`, `analyzer.ts`, `emitter.ts`) | `remoteResultType` recognizes `RemoteStream<Out, In>` and generates the `uplink` boundary; the descriptor emits `uplink: { codec }`; the generated Client signature returns `RemoteStreamHandle<Out, In>`; the parameter loop accepts only business parameters and a final `signal` |
+| `dsh-client-connection` (`operator-peer.ts`, `rpc.ts`, `rpc-host.ts`, `index.ts`) | The operator `PeerScope`; `connection.operator` and `admit`; the `/api` and upgrade routes obtain the Peer through `admit`; the optional `uplink` of `rpc.open` |
+| `dsh-api-gateway` Host (`stream-protocol.ts`, `stream-server.ts`, `types.ts`, `index.ts`) | `item` / `end` frames; `UplinkInbox`; `Config.streamInboxBytes`; `GatewayInvocation` and `extend({ invocation })`; `UplinkDecoder`; `handleUpgrade(req, socket, head, peer)`; `operatorPeer()` |
+| `dsh-api-gateway` Client (`client/index.ts`, `client/stream-client.ts`) | `invokeStream` returns the handle; the uplink pump is driven by the handle's queue |
+| `dsh-webworker-runtime`, `dsh-remote-mock` | The worker tunnel's two uplink frames and the `serveStream` assembly; `StreamHandle.uplink`; the direct proxy returns the real handle |
+| Documentation | The READMEs of gateway, the api group, connection, protocol, and generator; `docs/api-gateway`; the type-equiv blocks of `docs/subsystems/typert`; the config and Cordis catalogs |
+
+## Key sequences
+
+### Open, uplink, half-close, downlink end
+
+```
+Client caller      mux client              mux server              gateway                 Host method
+   │ attach(req)        │                       │                     │                         │
+   │───────────────────▶│ open { id, ep, payload } ──────────────────▶│ create inbox            │
+   │ s.send(v1)         │ item { id, v1 } ───────────────────────────▶│ inbox.push(v1)          │
+   │                    │                       │                     │ prepareInvocation       │
+   │                    │                       │                     │ extend({ invocation })  │
+   │                    │                       │                     │── method(req, signal) ─▶│
+   │                    │                       │                     │                         │ uplink() → v1
+   │ s.send(v2)         │ item { id, v2 } ───────────────────────────▶│ inbox.push(v2)          │ → v2
+   │ s.end()            │ end { id } ────────────────────────────────▶│ inbox.end()             │ iteration ends
+   │◀── yield o1 ───────│◀────────────────────── item { id, o1 } ─────│◀── yield o1 ────────────│
+   │◀── ends ───────────│◀────────────────────── end { id } ──────────│◀── method returns ──────│ gateway calls uplink.return()
+```
+
+### Client dispose
+
+```
+Client caller      mux client              mux server              gateway                 Host method
+   │ s.dispose()        │                       │                     │                         │
+   │───────────────────▶│ stop pump; source return() (not awaited)    │                         │
+   │◀── iterator ends ──│ cancel { id } ─────────────────────────────▶│ control.abort()         │
+   │                    │                       │                     │ cancellableStream: invocation.close() closes uplink
+   │                    │                       │                     │ iterator.return() ─────▶│ finally cleanup
+   │                    │                       │ no terminal frame   │                         │
+```
+
+### inbox overflow
+
+```
+Client caller      mux client              mux server                        gateway / Host method
+   │ s.send(vN)         │ item { id, vN } ─────▶│ inbox.push: bytes > streamInboxBytes │
+   │                    │                       │ onOverflow → control.abort(RemoteError uplink-overflow)
+   │                    │                       │                                      │ uplink() ends with that error; method iterator return()
+   │◀── throw ──────────│◀──────────────────────│ error { id, uplink-overflow }: the pump sends an error frame because the reason is a RemoteError
+```
+
+## Boundary matrix
+
+| Event | opening | running | Uplink ended | Downlink terminated |
+| --- | --- | --- | --- | --- |
+| `item` received | Buffered in the inbox | Into the inbox | The stream fails with `gateway/protocol` | Ignored |
+| `end` received | inbox.end | inbox.end | Idempotent | Ignored |
+| `cancel` received | abort | abort | abort | Ignored |
+| inbox overflow | The stream fails with `uplink-overflow` | Same | Impossible | Impossible |
+| Decode failure | Impossible | The stream fails with `input-invalid` | Same | Impossible |
+| Host method finishes | Impossible | Sends `end`; `uplink.return()` | Sends `end` | Already sent |
+| Host method throws | Sends `error` | Sends `error`; `uplink.return()` | Sends `error` | Already sent |
+| Socket closes | abort, await done | Same | Same | Nothing |
+| Client `send` | Queued, sent after open | Sent | Throws | Throws |
+| Client `end` | Recorded, sent after open | Sent | Idempotent | Ignored |
+| Client-side downlink ends first | Impossible | Stop the pump; source `return()`; no `end` sent | Nothing | Nothing |
+
+## Error codes
+
+| Code | When |
+| --- | --- |
+| `gateway/input-invalid` | Existing: a parameter codec fails to decode; new: an uplink item fails to decode |
+| `gateway/uplink-overflow` | New: the inbox exceeds `streamInboxBytes` |
+| `gateway/protocol` | New: an `item` after `end` |
+| `gateway/cancelled` | Existing: `signal` aborted |
+
+New codes are registered in `packages/api/gateway/src/remote-error-codes.ts` and in the README's error-code section.
+
+## Minimal echo method
+
+`packages/api/gateway/tests/echo-stream.host.spec.ts` runs the same method through the WebSocket carrier and through the in-process carrier:
+
+```text
+class EchoService extends TypertRemoteService {
+  constructor(ctx: Context) { super(ctx, 'echo', { namespace: 'echo' }) }
+
+  @Remote({ mode: 'stream' })
+  async *echo(prefix: string, signal: AbortSignal): RemoteStream<string, string> {
+    for await (const item of this.ctx.invocation!.uplink<string>()) {
+      signal.throwIfAborted()
+      yield `${prefix}${item}`
+    }
+  }
+}
+
+// Client
+const stream = remote.echo.echo('> ')
+stream.send('a'); stream.send('b'); stream.end()
+const replies: string[] = []
+for await (const reply of stream) replies.push(reply)   // ['> a', '> b']
+```
+
+## Alternatives considered
+
+**A separate `mode: 'duplex'` plus a reserved parameter `uplink: AsyncIterable<In>` alongside `signal`.** Special logic everywhere: the analyzer must recognize a second reserved parameter and its position rules, the generated signature gains a parameter, load time must validate `duplex ⟺ uplink`, and because the mux does not know the method mode, the Gateway must reject uplink frames on behalf of `'stream'` methods. Duplex is an inherent property of the transport-layer stream, not a mode of the method: the carrier already has `streamId`, `open`, and `cancel`; the uplink adds just two more frames, which any stream can receive and which are simply not sent when unused.
+
+**Declaring the uplink type in a decorator option, `@Remote({ mode: 'stream', uplink: 'JobInputFrame' })`.** A string reference to a type name is not checked by the compiler and breaks on rename. The return-type alias puts both types in one compiler-visible place.
+
+**Passing a schema at runtime: `uplink(schema)`.** Bypasses the generator, the Client loses type projection, and it splits from the "strict codec per item" system. The codec still comes from the generator; the generic in the method is only an assertion.
+
+**Having the analyzer cross-check the hand-written generic of `uplink<In>()` against the return type.** A business-specific check whose mistakes the caller bears, consistent with the other hand-written assertions in the repository; not added.
+
+**A transport-layer handle with reopening, cursors, and a `reopen` hook.** Reopening after disconnection belongs to the upper-layer protocol: a job resumes through an `opened` frame carrying `from` and a client that remembers `next` and calls again; snapshot and journal each have their own anchors and classification. The transport layer knows one generation.
+
+**Putting the Client's `send` on the `AsyncIterable` the generated method returns.** Hanging methods on an `AsyncIterable` is unconventional; the handle type `RemoteStreamHandle` extends it explicitly.
+
+**Copying the Access mechanism.** Access control is business semantics, served by `vouch` and the `remote/invoke` waterfall; this Note only needs "whose stream is this", and `PeerScope` suffices.
+
+**Keeping unary RPC for the uplink.** One HTTP round trip, one authentication, and one lookup per uplink; two carriers with no ordering relation that only Client-side serialization can order; no EOF; cancellation that does not cover both halves; a hand-made correlation key per feature.
+
+**A native HTTP request body stream.** A one-shot request body with no association to the downlink stream, bypassing Typert descriptors, and browser support for full-duplex fetch cannot be relied on.
+
+**One dedicated WebSocket per duplex stream.** Loses the authentication, heartbeat, and multiplexing shared with the existing downlink streams, and every feature manages its own socket lifecycle.
+
+**WebTransport or HTTP/2 bidirectional streams.** They have per-stream flow control, but support on the browser and Node sides, proxy traversal, and the Electron carrier are all immature; adding two frames to the existing mux is orders of magnitude cheaper than replacing the transport layer.
+
+## Consequences
+
+- **Bought**: one stream with two directions, so interactive scenarios such as terminal keystrokes, approval answers, and background-job stdin no longer each build their own "one stream plus one unary"; a Host method knows its caller; the uplink and downlink types are declared in one place, the return type; uplink items come from the browser and are validated strictly per item at the Host, while downlink items are Host-produced typed values that pass straight through; the generated output and wire frames of existing `AsyncIterable<Out>` methods and unary methods are completely unchanged.
+- **`this.ctx.invocation` is `undefined` outside a Remote call**, so a method that reads it must handle the optional; a service method invoked only directly in process correctly reads `undefined`.
+- **The inbox limit applies to every stream**: a method that does not read its uplink fails as a whole when it receives many uplink frames. This is a deliberate explicit failure, recorded in the README.
+- **The operator is the only Peer**, and `admit` is the only admission point; the first consumer that needs a second Peer must add opening, association, and events in `dsh-client-connection`.
+- **No cross-direction ordering guarantee between uplink and downlink**; a protocol that needs request-response pairing carries its own sequence numbers.
+- **Upper-layer protocols do not yet expose `send`**: consumers of `$stream`, snapshot, and journal use only the downlink today; the object they receive is already the handle.
+- **The worker tunnel behaves differently from the WebSocket carrier**: no inbox limit, and items after `end` are dropped, because page to worker is a same-origin trusted boundary.
+
+## Testing
+
+- `packages/api/gateway/tests/echo-stream.host.spec.ts`: the same echo method passes through the WebSocket carrier and through the in-process carrier.
+- Gateway Host: exact-key validation in frame parsing; `UplinkInbox` buffering during opening, `item` after `end`, overflow, ignored unknown `streamId`, and cleanup on socket closure; `UplinkDecoder` delivery with and without a codec and abort on decode failure; `uplink()` taken only once; the `extend({ invocation })` view and the origin of `peer`; `cancellableStream` closing the uplink before `return()`.
+- Gateway Client: the handle's `send` (JSON validation, queued before open, throws after termination), idempotent `end`, `dispose` driving the `cancel` frame and ending later reads; the pump's three exits; the pump stopping as soon as a terminal frame arrives.
+- typert: the analyzer's handling of `RemoteStream<Out, In>`, `RemoteStream<Out>`, `never`, and the existing `AsyncIterable<Out>`; decorator options; registry load-time validation.
+- connection: the three outcomes of `admit`, 401, 403, and the operator; the operator reaching handlers through the bridge and the shared handler; release with the Connection.
+- remote-mock and the worker tunnel: uplink pass-through; the direct proxy returning the real handle.
+- Existing stream and unary method tests pass without changed expectations.
+
+## Deferred
+
+- `$stream` / snapshot / journal expose the handle's `send` to upper-layer protocols.
+- Web terminal: one `attach` stream replaces `follow` plus `write` plus `resize`, and `attachmentId` retires.
+- Duplex `$events`: waterfall answers become uplink items on the same `streamId`, and `$events/result` and `clientId` retire.
+- Credit frames: wait for a consumer that needs sustained high-volume uplink; the inbox limit is the initial credit.
+- The `streamInboxBytes` default of 262144 is far more than keyboard and stdin need; if the first consumer is terminal paste, it may be aligned with the `maxInputBytes` of `terminal-controller`.
+- A Host-initiated half-close frame (the Host stops reading the uplink but keeps writing the downlink): no consumer; not added.
+- `uplink()` on unary methods: it can read items that arrive while the method runs, semantically valid but of doubtful use; allowed, noted in the README.
+
+## Related
+
+- [Remote event delivery](2026-08-10-remote-event-delivery.md): the unary `$events/result` answer path; the duplex `$events` item under Deferred partially supersedes it once it lands.
+- [Session history and event transport](2026-08-18-session-history-and-event-transport.md): the `$stream()` supervisor and the journal / snapshot protocols above it, which this note leaves unchanged.
+- [Web sidebar terminal](../feature/2026-09-09-web-sidebar-terminal.md): the unary terminal `write` and `attachmentId`; the `attach` stream under Deferred replaces it once it lands.
diff --git a/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.zh.md b/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.zh.md
new file mode 100644
index 0000000000..d3982aa433
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-19-remote-duplex-stream.zh.md
@@ -0,0 +1,597 @@
+# Agent Note: Remote 双工流：一种流、上行通道与调用上下文
+
+Status: implemented
+
+[English](2026-09-19-remote-duplex-stream.md) | 中文
+
+## 问题
+
+### 现状
+
+`dsh-api-gateway` 在一条 WebSocket 上复用全部 Typert Remote 流，路径固定为 `/api/remote.mux`（`packages/api/gateway/src/stream-protocol.ts`）。一个 Host 方法用 `@Remote({ mode: 'stream' })` 修饰并返回 `Iterable` 或 `AsyncIterable`，就成为一条 Host 到 Client 的逻辑流；可选的末位 `signal: AbortSignal` 是唯一的保留参数，不进线路参数，由网关在解码后的业务参数之后追加（`packages/api/gateway/src/index.ts`）。客户端拿到的生成方法返回一个裸 `AsyncIterable`。
+
+线路帧只有五种：
+
+| 方向 | 帧 | 定义 |
+| --- | --- | --- |
+| Client 到 Host | `{ type: 'open', streamId, endpoint, payload }` | `stream-protocol.ts` |
+| Client 到 Host | `{ type: 'cancel', streamId }` | `stream-protocol.ts` |
+| Host 到 Client | `{ type: 'item', streamId, value? }` | `stream-protocol.ts` |
+| Host 到 Client | `{ type: 'error', streamId, error: { code, message, details } }` | `stream-protocol.ts` |
+| Host 到 Client | `{ type: 'end', streamId }` | `stream-protocol.ts` |
+
+客户端能发的只有打开与取消。解析器 `parseRemoteStreamClientMessage`（`stream-protocol.ts`）对其他任何帧抛错，Host 连接收到后以 1008 关闭整个 socket（`stream-server.ts`）。结论：网关今天只支持"后端 iterable 发到前端"。需要前端向后端持续发数据的功能，各自绕路。
+
+Host 方法也没有"这次调用是谁发起的"这个概念：`InvokeRemoteRequest = { namespace, method, args, signal }`（`packages/api/gateway/src/types.ts`）没有调用者槽位，`RemoteStreamOpener` 的签名是 `(endpoint, payload, signal)`（`stream-server.ts`），WebSocket 只在握手时校一次 cookie。
+
+### 三套各自为政的上行机制
+
+| 功能 | 上行方式 | 位置 | 代价 |
+| --- | --- | --- | --- |
+| Web 终端按键 | 每次 xterm `onData` 一个 unary RPC `terminal.write(agent, id, attachmentId, data)`，客户端用 promise 链串行化并自限字节预算 | `packages/api/terminal-controller/src/client/model.ts`；Host `src/index.ts` | 一次按键一次 HTTP 往返与鉴权；两条载体靠 `attachmentId` 手工关联；满了报 `inputFull` |
+| 文件上传 | `Blob` 或 `ReadableStream` 走 Remote 层之外的原生 `POST /api/session/uploadFileBinary`，`duplex: 'half'` | `packages/client/file-upload/src/client/runtime.ts`；路由 `src/index.ts` | 不经 Typert 描述符，没有类型投影 |
+| 审批与提问的回答 | Host 在 `$events` 流上下发 waterfall 帧，Client 用一个独立的 unary RPC `$events/result` 回答，靠 `clientId` 加 `eventId` 关联 | `packages/api/gateway/src/client/remote-events.ts`；Host `index.ts` | 第二套关联键；`index.ts` 记录了由此产生的竞态 |
+
+这三套机制解决的是同一个问题：一条已经打开的逻辑流，客户端想往里写。
+
+### 具体代价
+
+- **两条载体对齐**。终端要用 `attachmentId` 把 `follow` 流与 `write` RPC 关联起来，并用它决定谁拥有输入权。审批要用 `clientId` 把 `$events` 流与 `$events/result` RPC 关联起来。
+- **没有顺序保证**。unary RPC 走 HTTP，与 WebSocket 下行互不排序；终端只能在客户端串行化写入来自保顺序。
+- **每次上行单独鉴权与查找**。`write(agent, id, attachmentId, data)` 每次解析 `agent`、查终端、校验 attachment。
+- **没有 EOF**。客户端无法表达"我这边写完了"，半关闭要再加一个 RPC。
+- **取消不覆盖两半**。取消下行流不会取消排队中的上行写；反之亦然。
+- **背压各写一套**。下行按 socket 写回调节拍拉迭代器（`stream-server.ts`）；终端用有界 follower 让慢消费者显式失败（`terminal-controller/src/stream.ts`）；上行靠客户端自限 `maxInputBytes`。
+- **文档已经过时**。`docs/api-gateway.md:160` 仍写着 Remote 只处理一请求一结果，这一句已经落后于 README 记录的 stream 模式。
+
+### 与后台 job 的关系
+
+后台 job 的进程形双工流面（已存档为草稿 PR，分支 `worktree/job-stdio-stream-pair-archive`）把 job 建成一对镜像的流面，浏览器要接它就需要一条既下行又上行的 Remote 流。它是本 Note 的动机之一，但不是本 Note 的范围：job 要不要一种专用的读写流，是 jobs 那条线自己的架构问题。本 Note 只覆盖传输层。
+
+### 目标
+
+1. 传输层只有一种流，天生双工：下行 `item` / `end` / `error`，上行 `item` / `end`，一个 `streamId`，一个代际。
+2. 上行类型与下行类型写在同一个位置：方法的返回类型。
+3. Host 方法通过调用上下文取上行；调用上下文同时携带调用者（Peer）。
+4. 客户端拿到的不再是裸 `AsyncIterable`，而是一个能读、能写、能关的句柄。
+5. 上层协议（snapshot、journal、任何业务自定义的流）不进传输层。
+
+## 决定
+
+### 一句话
+
+所有 Remote 流都允许客户端上行。方法的返回类型 `RemoteStream<Out, In = never>` 同时声明下行项与上行项的类型；生成器从中生成两个 codec。Host 方法通过 `this.ctx.invocation.uplink<In>()` 取上行迭代器，通过 `this.ctx.invocation.peer` 知道调用者。客户端生成方法返回 `RemoteStreamHandle<Out, In>`：`for await` 读下行，`send` / `end` 写上行，`dispose` 关。断线重开、游标续传、基线校验都是上层协议的事。
+
+```
+                 Client                                             Host
+   ─────────────────────────────────              ───────────────────────────────────────────
+   const s = remote.job.attach(req, signal)
+        │  open { streamId, endpoint, payload } ───────▶  opener(endpoint, payload, uplink, peer, control)
+        │                                                     │ prepareInvocation
+        │  s.send(v1) → item { streamId, v1 }    ───────▶  inbox.push(v1)   │ invocation = { request, service, peer, signal, uplink() }
+        │  s.send(v2) → item { streamId, v2 }    ───────▶  inbox.push(v2)   │ receiverContext.extend({ invocation }).get(service)
+        │  s.end()    → end  { streamId }        ───────▶  inbox.end()      │ method(...args, signal)
+        │                                        ◀───────  item { streamId, o1 }   │   for await (v of this.ctx.invocation.uplink()) …
+        │  for await (o of s) …                  ◀───────  item { streamId, o2 }   │   yield o …
+        │  s.dispose() → cancel { streamId }     ───────▶  control.abort()         │ signal aborts; uplink.return()
+        │                                        ◀───────  end | error
+```
+
+### 术语
+
+| 术语 | 含义 |
+| --- | --- |
+| 逻辑流 | 一个 `streamId` 标识的一次调用，跨越 `open` 到终止帧 |
+| 代际 | 一条逻辑流的一次物理生命期。传输层只认一个代际；断线即失败，重开是上层的事 |
+| 下行 | Host 到 Client 的 `item` 序列，以 `end` 或 `error` 终止 |
+| 上行 | Client 到 Host 的 `item` 序列，以 `end` 终止（半关闭），或随 `cancel` 一起结束 |
+| 半关闭 | 一个方向已结束而另一个方向仍开放 |
+| 项 | 一个方向上的一个业务值；每项独立经 codec 校验 |
+| inbox | Host 侧每逻辑流一个的有界上行队列 |
+| Peer | 连接层被接纳的一方，一个 `PeerScope`；本 Host 只有操作者一个 Peer |
+| 调用上下文 | `RemoteInvocation`：本次调用的请求、接收服务、Peer、取消信号与上行入口 |
+
+### 类型签名
+
+```text
+// @deepseek-ai/dsh-typert-protocol
+/**
+ * One Remote stream. Host face: the method returns it, and at runtime it is AsyncIterable<Out>.
+ * On the Client face the generated method returns RemoteStreamHandle<Out, In>; each name has exactly one meaning.
+ * In is the item type the Client may send uplink; the default never means the method reads no uplink.
+ */
+export type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+
+// Host
+@Remote({ mode: 'stream' })
+async *attach(request: JobAttachRequest, signal: AbortSignal): RemoteStream<JobFollowFrame, JobInputFrame> {
+  const uplink = this.ctx.invocation.uplink<JobInputFrame>()
+  void (async () => { for await (const frame of uplink) … })()
+  yield …
+}
+
+// Generated Client signature: same parameters, returns the handle
+attach(request: JobAttachRequest, signal?: AbortSignal): RemoteStreamHandle<JobFollowFrame, JobInputFrame>
+
+// Client usage
+const stream = remote.job.attach(req, signal)
+for await (const frame of stream) …
+stream.send(frame)     // typed as JobInputFrame
+stream.end()
+stream.dispose()
+```
+
+`RemoteStream` 是别名而不是接口，是刻意的：将来若把传输层做成 Node 流形态，只换别名的定义与两端的适配，方法签名、描述符、上层协议都不动。
+
+### Host 面
+
+```text
+/** The context of this Remote call. A method reads it through this.ctx.invocation. */
+export interface RemoteInvocation {
+  readonly request: {
+    readonly namespace: string
+    readonly method: string
+    readonly args: Readonly<Record<string, unknown>>
+  }
+  /** Cordis service key of the receiving service. */
+  readonly service: string
+  /** The Peer that initiated the call. In-process carriers and unadmitted calls are the operator. */
+  readonly peer: PeerScope
+  /** Carrier cancellation: Client cancel, socket closure, uplink failure. */
+  readonly signal: AbortSignal
+  /**
+   * The uplink items of this call. Can be taken once; the second call throws. With an uplink codec
+   * in the descriptor each item is decoded to In; without one, items are delivered as unknown with
+   * only a JSON-safety check.
+   * The iteration ends after the Client's end; when the method ends the downlink, the Gateway calls
+   * its return() and drops unconsumed items.
+   * The generic In is only the caller's type assertion; runtime decodes per the descriptor and does not cross-check.
+   */
+  uplink<In = unknown>(): AsyncIterable<In>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** The Remote call this Context was derived for; undefined on a Context not derived from a Remote call. */
+    readonly invocation: RemoteInvocation | undefined
+  }
+}
+```
+
+规则：
+
+1. 任何 `mode: 'stream'` 方法都可以调用 `this.ctx.invocation.uplink()`；unary 方法也可以，但它的流在方法返回时结束，上行项只在方法运行期间可读。
+2. `uplink()` 未被调用时，上行项在 inbox 里攒着，直到超限（见背压）或流结束被丢弃。这是刻意的：不读上行的方法不用知道上行存在。
+3. `In` 缺省为 `never` 时描述符没有 uplink codec；客户端句柄的 `send` 类型为 `never`，编译期就不能发。运行时若仍有帧到达（手工构造的客户端），按 `unknown` 交付。
+4. `this.ctx.invocation` 在非 Remote 调用的 Context 上是 `undefined`；方法内读它时按 TS 的可选处理，或在方法第一行断言。该属性的 accessor 由 `TypertRemoteService` 基类构造时注册一次，任何装有 Remote 服务的组合都能读它。
+
+#### 调用上下文如何到达方法
+
+机制依赖 Cordis 的两条既有行为：
+
+- `ctx.extend(meta)` 是 `Object.create(parent)` 加自有属性（`vendor/cordis/src/context.ts:99-107`），无注册、无 fiber、不需释放，每次调用派生一个是零成本的。
+- `ctx.get(service)` 返回 `createTraceable(ctx, service)` 代理（`vendor/cordis/src/reflect.ts:233-234`，`utils.ts:117-125`）。读 `ctx` 属性直接返回访问方的 Context（`utils.ts:175`）；读方法时用 `createShadowMethod` 包一层，`apply` 时把 `this` 换成 shadow receiver，shadow 上的 `ctx` 是 `ctx.extend({ [symbols.shadow]: origin })`（`utils.ts:149-163`）。
+- 网关因此写 `receiverContext.extend({ invocation }).get(descriptor.service)` 取一个调用视图，`Reflect.apply(method, callReceiver, args)`；方法体里 `this.ctx.invocation` 沿原型链读到本次调用。async generator 体延后执行不受影响，因为 `this` 在调用时已绑定为 shadow 对象。
+
+### PeerScope
+
+```text
+/** The opaque identity of one Peer. */
+export type PeerId = Branded<'PeerId'>
+
+/** One Peer's session on this Host: opened and released by the admitting side; ctx owns connection-lifetime registrations. */
+export interface PeerScope {
+  readonly id: PeerId
+  readonly ctx: Context
+  dispose(): Promise<void>
+}
+```
+
+本 Host 只有一个 Peer：操作者。`@deepseek-ai/dsh-client-connection` 在服务 apply 时用 `createScope(connectionCtx, peer)` 建它，与 Agent 建自己的 scope 是同一机制：Peer 对象就是 ScopeKey，`peer.ctx` 承接连接期效果，`dispose()` 随 connection 释放让 fiber 静默。它以 `connection.operator` 暴露。
+
+| 成员 | 语义 |
+| --- | --- |
+| `connection.operator: PeerScope` | 唯一的 Peer，随 connection 生灭 |
+| `connection.admit(request): PeerAdmission` | 过既有的 `requestRejection`：被拒返回 `{ rejection: 401 \| 403 }`，否则返回 `{ peer: operator }`。将来的接纳方在这里接入 |
+
+网关 `handleUpgrade(req, socket, head, peer)` 为该 socket 绑一个固定 Peer 的 opener，并在 `peer.ctx.effect` 里登记 socket 关闭；scope 已失效时改为直接以 1001 关闭 socket。`InvokeRemoteRequest.peer?` 与 `RemoteStreamOpener` 的 `peer` 形参缺席时按操作者作答，现有进程内调用方零改动；没有 connection 的组合里网关自建的操作者替身同样经 `createScope` 建立，`dispose()` 契约一致。按 id 查 Peer、把载体关联到第二个 Peer、Peer 的开关事件，都等第一个需要多 Peer 的消费者出现时再加。
+
+Peer 不携带访问模型：Peer 是谁、能做什么，由业务插件通过 `peer.ctx` 自行附加。
+
+### Client 面
+
+```text
+/** The handle a generated method returns on the Client face. A different name from the Host's RemoteStream, exported from the same entry point. */
+export interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+  /** Send one uplink item. Throws on a value that is not lossless JSON, after termination, or after end. */
+  send(item: In): void
+  /** Half-close the uplink: sends the end frame. Idempotent. */
+  end(): void
+  /** Cancel the whole logical stream: sends the cancel frame (when no terminal frame has arrived); the downlink iterator ends quietly. */
+  dispose(): void
+}
+```
+
+- 句柄代表一个代际。载体丢失时 `for await` 以 `RemoteStreamCarrierError` 失败，句柄到此结束；要不要重开、带什么参数重开，是上层协议的事。
+- `send` 是同步的：入队前做 `isRemoteJsonValue` 校验，非无损 JSON 值同步抛错。浏览器 `WebSocket.send` 没有写回调，发送节流没有意义；Host 侧的 inbox 上限是唯一的背压点。
+- 收到终止帧（`end` / `error`）时，mux 客户端在收帧路径上立即停泵并关闭上行队列，之后 `send` / `end` 抛错，不等消费者下一次读。
+- `dispose()` 调用载体迭代器的 `return()`，让 `cancel` 帧在无人读下行时也发出；之后句柄的 `next()` 直接结束，缓冲项丢弃。消费者提前 `break` 出 `for await` 等价于 `dispose()`。
+- `$stream` 监督器、`RemoteSnapshotStream`、`RemoteJournalStream` 是上层工具，不在传输层内。它们的 `open` 工厂拿到的对象现在就是句柄，`for await` 行为不变；把 `send` 透出到这些上层协议是后续的事。
+
+### 线路帧
+
+```text
+export type RemoteStreamClientMessage =
+  | { readonly type: 'open'; readonly streamId: string; readonly endpoint: string; readonly payload: unknown }
+  | { readonly type: 'item'; readonly streamId: string; readonly value?: unknown }   // new: uplink item
+  | { readonly type: 'end'; readonly streamId: string }                              // new: uplink half-close
+  | { readonly type: 'cancel'; readonly streamId: string }
+
+/** Frames sent by the Host are unchanged. */
+export type RemoteStreamServerMessage =
+  | { readonly type: 'item'; readonly streamId: string; readonly value?: unknown }
+  | { readonly type: 'error'; readonly streamId: string; readonly error: RemoteStreamFailure }
+  | { readonly type: 'end'; readonly streamId: string }
+```
+
+解析规则：`item` 精确键 `type` `streamId` 加可选 `value`，`value` 须为无损 JSON 值（`isRemoteJsonValue`）；`end` 精确键 `type` `streamId`。其余形状是帧格式违规，socket 以 1008 关闭。不引入二进制帧。
+
+### 逻辑流状态机
+
+#### Host 侧
+
+```
+                open frame
+   (none) ───────────────────▶ opening ──── opener resolves ────▶ running
+                                  │                                  │
+                                  │ item frame: inbox.push           │ item frame: inbox.push
+                                  │ end frame: inbox.end             │ end frame: inbox.end (uplink half-close)
+                                  │                                  │ method yield: sends item frame
+                                  │ cancel frame / socket close ────▶│ cancel frame / socket close: control.abort
+                                  ▼                                  ▼
+                               aborted ◀───────────────────────── finished (sends end or error frame)
+```
+
+`opening` 期间到达的 `item` 帧进入 inbox：`receive()` 是同步的，`open` 帧处理时就创建 `ActiveStream` 与 inbox，而 opener 是异步的。客户端在 `open` 之后立刻发的项不会丢。
+
+#### Client 侧
+
+```
+   call generated method ──▶ await socket ──▶ send open ──▶ handle usable
+                                                            │ send(v): sends item; end(): sends end
+                                                            │ downlink: inbox.next() → yield; end → ends; error → throws
+                                                            │ downlink terminates first: send/end throw
+                                                            │ dispose or caller signal abort: sends cancel (when no terminal frame has arrived)
+```
+
+### 半关闭与结束语义
+
+| 上行 | 下行 | 结果 |
+| --- | --- | --- |
+| 客户端 `end` | 仍开放 | Host 的 `uplink()` 迭代结束；方法继续产出。这是 stdin EOF 的形状 |
+| 仍开放 | Host 方法结束，发 `end` | 客户端句柄终止，之后 `send` / `end` 抛错；Host 调用 `uplink` 迭代器的 `return()`，未消费项丢弃 |
+| 仍开放 | Host 方法抛错，发 `error` | 同上；客户端下行以 `RemoteError` 失败 |
+| 客户端 `dispose` 或 signal 中止 | 任意 | 发 `cancel`；Host `control.abort()`，`cancellableStream` 先关 `uplink`，再调方法迭代器的 `return()`；不发终止帧 |
+| socket 关闭 | 任意 | Host 中止全部流并等待 `done`；客户端每条流以 `RemoteStreamCarrierError` 失败 |
+| `end` 之后又收到 `item` | 任意 | 该流以 `gateway/protocol` 错误帧失败并中止；socket 不关闭 |
+| 未知 `streamId` 的 `item` / `end` | 任意 | 忽略，与 `cancel` 相同：Host 结束流并删除 id 后，客户端在途的上行帧属正常现象，不能连累同一 socket 上的其他流 |
+
+### 顺序保证
+
+同一条 socket 上的帧全序到达：一条逻辑流的 `open`、`item`…、`end` 按发送顺序到达 Host；上行项进入 `uplink()` 的顺序就是 `send` 的顺序。上行与下行之间没有跨方向顺序保证；需要请求应答配对的协议自带序号。
+
+### 背压
+
+WebSocket 没有 HTTP/2 那样的每流窗口，一个连接一条串行写链，慢流会拖住同连接的其他流。下行的这一性质不变。上行：
+
+**有界 inbox 加整流失败。** Host 每条逻辑流的 inbox 按帧的 UTF-8 字节计量，上限为网关配置 `streamInboxBytes`（默认 262144），对所有流生效。超限时整条逻辑流以 `gateway/uplink-overflow` 失败：下行一起断，向客户端发 `error` 帧，`uplink()` 迭代器以同一错误结束。数据不丢弃；一个方法不读上行而客户端持续发，是用法错误，由失败显式暴露。
+
+credit 帧留待需要持续大流量上行的消费者出现时再加；inbox 上限就是初始授信，加法是增量。
+
+### 安全与校验
+
+| 项 | 规则 |
+| --- | --- |
+| 鉴权 | 与今天相同：升级时 `connection.requestRejection(req)`；打开时描述符与查找参数校验。上行项属于一条已鉴权的流，不重复鉴权 |
+| Peer | 升级时接纳为一个 `PeerScope`，该 socket 上所有流的 `invocation.peer` 都是它 |
+| 项校验 | 有 uplink codec 时逐项严格解码，失败即整条流以既有的 `gateway/input-invalid` 失败（details `{ endpoint, field: 'uplink' }`）；无 codec 时只做 JSON 安全校验 |
+| 帧大小 | 单帧沿用 `ws` 的 `maxPayload`；inbox 上限限制累计量 |
+
+### 进程内与 worker 载体
+
+| 载体 | 改为 |
+| --- | --- |
+| `ClientConnectionRpc.open`（`packages/client/connection/src/rpc.ts:245-250`）与 `RpcStreamOpen`（`client/rpc.ts:21-25`） | 追加可选 `uplink?: AsyncIterable<unknown>`；进程内没有帧也没有 inbox，调用方迭代器直接作为 `uplink()` 的源，背压就是迭代器本身的节拍 |
+| worker 隧道（`packages/experimental/webworker-runtime`） | 页面新增 `stream-uplink-item` / `stream-uplink-end` 帧；`serveStream` 把它们组装成 `uplink` 交给 `seams.openStream`。同源可信边界：没有 inbox 上限，`end` 之后的项丢弃 |
+| `remote-mock`（`packages/test-support/remote-mock`） | `StreamHandle.uplink: AsyncIterable<unknown>`；`rpc.open` 透传 |
+
+进程内载体的 `peer` 缺席即操作者。
+
+### 与 `$events` 的关系
+
+`$events` 是一条保留端点的流；有了上行帧，waterfall 的回答可以成为同一 `streamId` 上的上行项，`clientId` 因 `streamId` 已标识代际而多余，`$events/result` 与 `index.ts:527-529` 的竞态一起消失。不在本 Note 范围，见「后续」。
+
+## 类型与线路定义
+
+### typert protocol（`packages/typert/protocol/src`）
+
+```text
+// types.ts
+export type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+export type PeerId = Branded<'PeerId'>
+export interface PeerScope { readonly id: PeerId; readonly ctx: Context; dispose(): Promise<void> }
+export interface RemoteInvocation { … }              // see Host face
+declare module '@deepseek-ai/cordis' { interface Context { readonly invocation: RemoteInvocation | undefined } }
+
+export interface InvocationDescriptor {
+  // existing fields unchanged; mode still has only 'stream'
+  readonly mode?: 'stream'
+  /** Uplink item codec, generated from In of the return type RemoteStream<Out, In>; absent when In is never. */
+  readonly uplink?: { readonly codec: TypertCodec }
+  readonly cancellation?: { readonly parameter: 'signal' }
+  readonly result: TypertCodec
+}
+```
+
+`Remote` 修饰器、`RemoteMethodOptions`、`RemoteMethodMarker` 恢复为只认 `mode: 'stream'`。
+
+### typert generator（`packages/typert/generator/src`）
+
+- `model.ts`：`InvocationModel.uplink?: { boundary: RemoteBoundaryModel }`。
+- `analyzer.ts` `remoteResultType`：对 `mode: 'stream'`，接受的返回类型包装器为 `Iterable<Out>`、`AsyncIterable<Out>`、`RemoteStream<Out, In?>`。识别 `RemoteStream` 的方式与识别标准库 `AsyncIterable` 相同：符号名加声明所在文件（`@deepseek-ai/dsh-typert-protocol` 的 `types.ts`）。第一个类型参数是下行项，第二个存在且不是 `never` 时生成 `uplink` boundary，键名 `${endpoint}:uplink`。
+- `emitter.ts`：描述符字面量输出 `uplink: { codec }`；生成的 Client 签名返回 `RemoteStreamHandle<Out, In>`。
+- 参数循环不再识别任何名为 `uplink` 的参数。
+
+### 两个名字，一个入口
+
+Host 方法用 `RemoteStream<Out, In>` 声明一条流；Client 持有的是 `RemoteStreamHandle<Out, In>`。两者都从 `@deepseek-ai/dsh-typert-protocol` 主入口导出，句柄接口没有任何 Host 依赖。生成的 Client 契约把返回类型写成 `RemoteStreamHandle<Out, In>`。一个名字只有一个含义：Client 代码从主入口拿到的 `RemoteStream` 永远是声明类型，不会与句柄混淆。
+
+### 网关 Host（`packages/api/gateway/src`）
+
+```text
+// types.ts
+export interface InvokeRemoteRequest {
+  readonly namespace: string
+  readonly method: string
+  readonly args: Readonly<Record<string, unknown>>
+  /** Uplink items; absent is equivalent to an iterator that ends immediately. */
+  readonly uplink?: AsyncIterable<unknown>
+  /** The Peer that initiated the call; absent means the operator. */
+  readonly peer?: PeerScope
+  readonly signal?: AbortSignal
+}
+
+export interface TypertGatewayWireStream {
+  open: (endpoint: string, payload: unknown, uplink: AsyncIterable<unknown>, peer: PeerScope | undefined, signal: AbortSignal) => Promise<AsyncIterable<unknown>>
+  failure: (error: unknown) => RemoteStreamFailure
+}
+
+// stream-server.ts
+export type RemoteStreamOpener = (
+  endpoint: string,
+  payload: unknown,
+  uplink: AsyncIterable<unknown>,
+  peer: PeerScope,
+  control: AbortController,
+) => Promise<AsyncIterable<unknown>>
+
+// index.ts Config addition
+/** Uplink inbox limit per logical stream, in UTF-8 bytes of frames (default 262144). */
+readonly streamInboxBytes?: number
+```
+
+`prepareInvocation`：
+
+```text
+const args = await Promise.all(descriptor.parameters.map(parameter => this.resolveParameter(parameter, request.args, endpoint)))
+const signal = request.signal ?? NEVER_ABORTED_SIGNAL
+const invocation = new GatewayInvocation(
+  { namespace: request.namespace, method: request.method, args: request.args },
+  descriptor.service,
+  request.peer ?? this.operatorPeer(),
+  signal,
+  new UplinkDecoder(request.uplink ?? EMPTY_ASYNC_ITERABLE, descriptor.uplink?.codec, endpoint, control),
+)
+const callReceiver = receiverContext.extend({ invocation }).get(descriptor.service) as object
+if (descriptor.cancellation !== undefined) args.push(signal)
+```
+
+`GatewayInvocation.uplink()` 第一次调用返回解码器，第二次抛错。`UplinkDecoder` 是手写迭代器：有 codec 时逐项 `decode(codec, value, endpoint, 'uplink')`，失败即 `control.abort(failure)` 并抛出；无 codec 时只做 `isRemoteJsonValue` 校验。`cancellableStream` 的 `finally` 先关闭解码器（`invocation.close()`）再等待方法迭代器的 `return()`，阻塞在 `uplink.next()` 上的方法得以退出。unary 与 stream 的模式分支恢复为今天的两分支。SRC 回退：描述符无 `uplink` codec，`uplink()` 交付 `unknown`。
+
+### 网关 Host mux（`stream-server.ts`）
+
+```text
+interface ActiveStream { readonly control: AbortController; readonly inbox: UplinkInbox; done: Promise<void> }
+
+/** Bounded uplink queue; iterated as the source of uplink(). */
+class UplinkInbox implements AsyncIterable<unknown>, AsyncIterator<unknown> {
+  constructor(maxBytes: number, onOverflow: (error: RemoteError) => void)
+  push(value: unknown, frameBytes: number): void   // push after ended fails the stream with gateway/protocol; overflow calls onOverflow
+  end(): void                                        // idempotent
+  fail(error: unknown): void                         // ends the iterator with an error on cancel or carrier closure
+  next() / return()                                  // hand-written: next races failure, return releases immediately
+}
+```
+
+`receive(text)` 分派：
+
+```
+open   : exists → throw (socket 1008); otherwise create { control, inbox, done } and start the pump
+item   : missing → ignore; otherwise inbox.push(value, bytes)
+end    : missing → ignore; otherwise inbox.end()
+cancel : missing → ignore; otherwise control.abort(new Error('Remote stream cancelled'))
+```
+
+`pump` 把 inbox 与该 socket 的 Peer 传给 opener；`finally` 里 `inbox.fail(...)`。以 `RemoteError` 为 reason 的中止由 pump 作为 `error` 帧发出（网关或 mux 发起的失败）；以普通 `Error` 为 reason 的中止（cancel、socket 关闭）不发终止帧。
+
+### 网关 Client（`packages/api/gateway/src/client`）
+
+- `prepareInvocation` 不再剥离任何上行参数；位置参数仍是业务参数加可选 `signal`。
+- `invokeStream` 返回 `RemoteStreamHandle`：内部持有一个上行队列，`send` 入队并由泵发 `item` 帧，`end` 发 `end` 帧，`dispose` 中止代际 signal。下行仍是 `openRemoteStream` 返回的迭代器。
+- `RemoteStreamMuxClient.open(endpoint, payload, signal, uplink?)`：在发出 `open` 帧后启动上行泵，逐项发 `item`，源结束发 `end`；下行终止或 signal 中止时停泵并调用源的 `return()`（不等待，避免键盘类生成器卡死）；源抛错时 `inbox.fail(error)`，下行以该错误失败，`finally` 按既有规则发 `cancel`。泵检查 `this.socket === socket`，旧代际不往新 socket 上发帧。
+- 进程内载体：`connection.rpc.open(channel, endpoint, payload, signal, uplink)`。
+
+## 落点
+
+| 包 | 承载 |
+| --- | --- |
+| `dsh-typert-protocol`（`types.ts`、`index.ts`） | `RemoteStream`、`RemoteStreamHandle`、`PeerId`、`PeerScope`、`RemoteInvocation`、`ctx.invocation` 声明合并、`InvocationDescriptor.uplink`；修饰器只认 `mode: 'stream'`；`TypertRemoteService` 构造时注册 `invocation` accessor |
+| `dsh-typert-registry` | 加载校验 `uplink.codec` 为有效的严格 codec |
+| `dsh-typert-generator`（`model.ts`、`analyzer.ts`、`emitter.ts`） | `remoteResultType` 识别 `RemoteStream<Out, In>` 并生成 `uplink` boundary；描述符输出 `uplink: { codec }`；生成的 Client 签名返回 `RemoteStreamHandle<Out, In>`；参数循环只认业务参数与末位 `signal` |
+| `dsh-client-connection`（`operator-peer.ts`、`rpc.ts`、`rpc-host.ts`、`index.ts`） | 操作者 `PeerScope`；`connection.operator` 与 `admit`；`/api` 与升级路由经 `admit` 取 Peer；`rpc.open` 的可选 `uplink` |
+| `dsh-api-gateway` Host（`stream-protocol.ts`、`stream-server.ts`、`types.ts`、`index.ts`） | `item` / `end` 帧；`UplinkInbox`；`Config.streamInboxBytes`；`GatewayInvocation` 与 `extend({ invocation })`；`UplinkDecoder`；`handleUpgrade(req, socket, head, peer)`；`operatorPeer()` |
+| `dsh-api-gateway` Client（`client/index.ts`、`client/stream-client.ts`） | `invokeStream` 返回句柄；上行泵由句柄的队列驱动 |
+| `dsh-webworker-runtime`、`dsh-remote-mock` | worker 隧道的两种上行帧与 `serveStream` 组装；`StreamHandle.uplink`；直接代理返回真句柄 |
+| 文档 | gateway、api 组、connection、protocol、generator 的 README；`docs/api-gateway`；`docs/subsystems/typert` 的 type-equiv 块；config 与 Cordis 目录 |
+
+## 关键流程时序
+
+### 打开、上行、半关闭、下行结束
+
+```
+Client caller      mux client              mux server              gateway                 Host method
+   │ attach(req)        │                       │                     │                         │
+   │───────────────────▶│ open { id, ep, payload } ──────────────────▶│ create inbox            │
+   │ s.send(v1)         │ item { id, v1 } ───────────────────────────▶│ inbox.push(v1)          │
+   │                    │                       │                     │ prepareInvocation       │
+   │                    │                       │                     │ extend({ invocation })  │
+   │                    │                       │                     │── method(req, signal) ─▶│
+   │                    │                       │                     │                         │ uplink() → v1
+   │ s.send(v2)         │ item { id, v2 } ───────────────────────────▶│ inbox.push(v2)          │ → v2
+   │ s.end()            │ end { id } ────────────────────────────────▶│ inbox.end()             │ iteration ends
+   │◀── yield o1 ───────│◀────────────────────── item { id, o1 } ─────│◀── yield o1 ────────────│
+   │◀── ends ───────────│◀────────────────────── end { id } ──────────│◀── method returns ──────│ gateway calls uplink.return()
+```
+
+### 客户端 dispose
+
+```
+Client caller      mux client              mux server              gateway                 Host method
+   │ s.dispose()        │                       │                     │                         │
+   │───────────────────▶│ stop pump; source return() (not awaited)    │                         │
+   │◀── iterator ends ──│ cancel { id } ─────────────────────────────▶│ control.abort()         │
+   │                    │                       │                     │ cancellableStream: invocation.close() closes uplink
+   │                    │                       │                     │ iterator.return() ─────▶│ finally cleanup
+   │                    │                       │ no terminal frame   │                         │
+```
+
+### inbox 超限
+
+```
+Client caller      mux client              mux server                        gateway / Host method
+   │ s.send(vN)         │ item { id, vN } ─────▶│ inbox.push: bytes > streamInboxBytes │
+   │                    │                       │ onOverflow → control.abort(RemoteError uplink-overflow)
+   │                    │                       │                                      │ uplink() ends with that error; method iterator return()
+   │◀── throw ──────────│◀──────────────────────│ error { id, uplink-overflow }: the pump sends an error frame because the reason is a RemoteError
+```
+
+## 边界矩阵
+
+| 事件 | opening | running | 上行已 end | 下行已终止 |
+| --- | --- | --- | --- | --- |
+| 收到 `item` | 入 inbox 缓冲 | 入 inbox | 流以 `gateway/protocol` 失败 | 忽略 |
+| 收到 `end` | inbox.end | inbox.end | 幂等 | 忽略 |
+| 收到 `cancel` | abort | abort | abort | 忽略 |
+| inbox 超限 | 流以 `uplink-overflow` 失败 | 同 | 不可能 | 不可能 |
+| 解码失败 | 不可能 | 流以 `input-invalid` 失败 | 同 | 不可能 |
+| Host 方法结束 | 不可能 | 发 `end`；`uplink.return()` | 发 `end` | 已发 |
+| Host 方法抛错 | 发 `error` | 发 `error`；`uplink.return()` | 发 `error` | 已发 |
+| socket 关闭 | abort，等 done | 同 | 同 | 无事 |
+| Client `send` | 入队，open 后发 | 发 | 抛错 | 抛错 |
+| Client `end` | 记录，open 后发 | 发 | 幂等 | 忽略 |
+| Client 侧下行先结束 | 不可能 | 停泵；源 `return()`；不发 `end` | 无事 | 无事 |
+
+## 错误码
+
+| 错误码 | 何时 |
+| --- | --- |
+| `gateway/input-invalid` | 既有：参数 codec 解码失败；新增：上行项解码失败 |
+| `gateway/uplink-overflow` | 新增：inbox 超过 `streamInboxBytes` |
+| `gateway/protocol` | 新增：`end` 之后的 `item` |
+| `gateway/cancelled` | 既有：`signal` 中止 |
+
+新码登记在 `packages/api/gateway/src/remote-error-codes.ts` 与 README 的错误码一节。
+
+## 最小 echo 方法
+
+`packages/api/gateway/tests/echo-stream.host.spec.ts` 让同一个方法分别穿过 WebSocket 载体与进程内载体：
+
+```text
+class EchoService extends TypertRemoteService {
+  constructor(ctx: Context) { super(ctx, 'echo', { namespace: 'echo' }) }
+
+  @Remote({ mode: 'stream' })
+  async *echo(prefix: string, signal: AbortSignal): RemoteStream<string, string> {
+    for await (const item of this.ctx.invocation!.uplink<string>()) {
+      signal.throwIfAborted()
+      yield `${prefix}${item}`
+    }
+  }
+}
+
+// Client
+const stream = remote.echo.echo('> ')
+stream.send('a'); stream.send('b'); stream.end()
+const replies: string[] = []
+for await (const reply of stream) replies.push(reply)   // ['> a', '> b']
+```
+
+## 考虑过的替代方案
+
+**独立的 `mode: 'duplex'` 加一个与 `signal` 同级的保留参数 `uplink: AsyncIterable<In>`。** 每一处都是特殊逻辑：analyzer 要认第二个保留参数及其位置规则，生成签名多一个参数，加载期要校验 `duplex ⟺ uplink`，mux 不知道方法模式所以网关要替 `'stream'` 方法拒绝上行帧。双工是传输层流的固有性质，不是方法的一种模式：载体本来就有 `streamId`、`open`、`cancel`，上行只是再加两种帧，任何流都能收，不用就不发。
+
+**用装饰器选项声明上行类型，`@Remote({ mode: 'stream', uplink: 'JobInputFrame' })`。** 字符串引用类型名不受编译器约束，重命名即断。返回类型别名把两个类型写在同一个编译器可见的位置。
+
+**运行时传 schema：`uplink(schema)`。** 不经生成器，客户端失去类型投影，与"每项严格 codec"的体系分裂。codec 的来源仍是生成器，方法里的泛型只是断言。
+
+**analyzer 交叉校验 `uplink<In>()` 手填的泛型与返回类型一致。** 业务特化的校验，写错后果由调用方承担，与仓库其他处手填断言一致；不加。
+
+**传输层句柄带重开、游标、`reopen` 钩子。** 断线重开是上层协议的事：job 的续传是 `opened` 帧带 `from`、客户端记住 `next` 再调一次；snapshot 与 journal 各有自己的锚点与分类。传输层只认一个代际。
+
+**客户端 `send` 放在生成方法返回的 `AsyncIterable` 上。** `AsyncIterable` 上挂方法不常规；句柄类型 `RemoteStreamHandle` 显式扩展它。
+
+**照搬 Access 机制。** 访问控制是业务语义，`vouch` 与 `remote/invoke` waterfall 为它服务；本 Note 只需要"这条流是谁的"，`PeerScope` 就够。
+
+**继续用 unary RPC 做上行。** 每次上行一次 HTTP 往返、一次鉴权、一次查找；两条载体没有顺序关系，只能靠客户端串行化；没有 EOF；取消不覆盖两半；每个功能各造一套关联键。
+
+**原生 HTTP 请求体流。** 一次性请求体，与下行流没有关联，不经 Typert 描述符，浏览器对全双工 fetch 的支持不可依赖。
+
+**每条双工流一个独立 WebSocket。** 失去与现有下行流共享的鉴权、心跳与多路复用，每个功能要自己管一条 socket 的生命周期。
+
+**WebTransport 或 HTTP/2 双向流。** 有每流流控，但浏览器与 Node 两侧的支持、代理穿透与 Electron 载体都不成熟；在现有 mux 上加两种帧比换传输层便宜几个量级。
+
+## 后果
+
+- **买到的**：一条流两个方向，终端按键、审批回答、后台任务 stdin 这类交互式场景不再各造一套"一条流加一个 unary"；Host 方法知道调用者；上行类型与下行类型在返回类型里一处声明，上行项来自浏览器，在 Host 逐项严格校验，下行项是 Host 自产的类型值，直接透传；既有 `AsyncIterable<Out>` 方法与 unary 方法的生成物与线路帧完全不变。
+- **`this.ctx.invocation` 在非 Remote 调用下是 `undefined`**，方法读它要处理可选；一个只被进程内直接调用的服务方法读到 `undefined` 是正确行为。
+- **inbox 上限对所有流生效**：一个不读上行的方法收到大量上行帧会整流失败。这是刻意的显式失败，README 记明。
+- **Peer 只有操作者一个**，`admit` 是唯一的接纳点；第一个需要第二个 Peer 的消费者要在 `dsh-client-connection` 加上打开、关联与事件。
+- **上行与下行之间没有跨方向顺序保证**；需要请求应答配对的协议自带序号。
+- **上层协议尚未透出 `send`**：`$stream`、snapshot、journal 的消费者今天只用下行；它们拿到的对象已经是句柄。
+- **worker 隧道与 WebSocket 载体行为不同**：没有 inbox 上限，`end` 之后的项丢弃，因为页面到 worker 是同源可信边界。
+
+## 测试
+
+- `packages/api/gateway/tests/echo-stream.host.spec.ts`：同一个 echo 方法分别穿过 WebSocket 载体与进程内载体。
+- 网关 Host：帧解析的精确键校验；`UplinkInbox` 的 opening 缓冲、`end` 后 `item`、超限、未知 `streamId` 忽略、socket 关闭时的收尾；`UplinkDecoder` 有无 codec 两种交付与解码失败中止；`uplink()` 只能取一次；`extend({ invocation })` 视图与 `peer` 的来源；`cancellableStream` 先关 uplink 再 `return()`。
+- 网关 Client：句柄的 `send`（JSON 校验、open 前入队、终止后抛错）、`end` 幂等、`dispose` 驱动 `cancel` 帧并结束后续读取；泵的三种退出；终止帧到达即停泵。
+- typert：analyzer 对 `RemoteStream<Out, In>`、`RemoteStream<Out>`、`never` 与既有 `AsyncIterable<Out>` 的处理；修饰器选项；registry 加载校验。
+- connection：`admit` 的 401、403 与操作者三种结果；操作者经桥与共享处理器到达；随 connection 释放。
+- remote-mock、worker 隧道：上行透传；直接代理返回真句柄。
+- 既有 stream 与 unary 方法的测试不改期望值即通过。
+
+## 后续
+
+- `$stream` / snapshot / journal 把句柄的 `send` 透出给上层协议。
+- Web 终端：一条 `attach` 流取代 `follow` 加 `write` 加 `resize`，`attachmentId` 退场。
+- 双工 `$events`：waterfall 的回答成为同一 `streamId` 上的上行项，`$events/result` 与 `clientId` 退场。
+- credit 帧：等需要持续大流量上行的消费者出现；inbox 上限就是初始授信。
+- `streamInboxBytes` 默认值 262144 对键盘与 stdin 远超需要；若第一个消费者是终端粘贴，可能与 `terminal-controller` 的 `maxInputBytes` 对齐。
+- Host 发起的半关闭帧（Host 不再读上行但继续写下行）：没有消费者，不加。
+- unary 方法的 `uplink()`：能读到方法运行期间到达的项，语义成立但用处存疑；允许，README 注明。
+
+## 相关
+
+- [Remote 事件投递](2026-08-10-remote-event-delivery.zh.md)：`$events/result` 的 unary 回答路径；「后续」里的双工 `$events` 落地后部分取代它。
+- [会话历史与事件传输](2026-08-18-session-history-and-event-transport.zh.md)：`$stream()` 监督器与其上的 journal / snapshot 协议，本 Note 不改它们。
+- [Web 侧边栏终端](../feature/2026-09-09-web-sidebar-terminal.zh.md)：终端按键的 unary `write` 与 `attachmentId`；「后续」里的 `attach` 流落地后取代它。
diff --git a/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.i18n.yaml
new file mode 100644
index 0000000000..061872368c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.md
+2026-09-20-sidebar-retained-tab-layout.md: 9579a0ba47c56f1d533f066fddd37e7ddf443346
+2026-09-20-sidebar-retained-tab-layout.zh.md: 365ad5682c8610cab5dc855984e58b4303bfae49
diff --git a/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.md b/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.md
new file mode 100644
index 0000000000..9579a0ba47
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.md
@@ -0,0 +1,82 @@
+# Agent Note: Stable Sidebar tab mounting and Session retention
+
+Status: implemented
+
+English | [中文](2026-09-20-sidebar-retained-tab-layout.zh.md)
+
+## Problem
+
+Restoring Session-specific tab records and URLs does not preserve a live browsing context. Unmounting a body or changing its DOM ancestors during tab, pane or Session transitions disconnects its page. Electron 44's `WebViewElement.disconnectedCallback` detaches and resets its guest, so preserving a React key or caching an element reference cannot compensate for disconnected ancestors. Content size, clipping and overlap must also follow the actual parent layout.
+
+## Decision
+
+Sidebar owns live-body retention, independently of Browser navigation and Workspace storage. A retained page's DOM ancestors remain connected and unchanged during Session switches, tab selection, pane moves, collapse, floating and docking back. Browser Presentation attaches directly inside its content container and performs no placeholder measurement or overlay positioning.
+
+### Layout ownership
+
+- `DockLayout` renders the Sidebar's one or two horizontal panes with stable tab siblings. The existing recursive `DockSurface` and separate `FloatLayer` remain available for general split-tree rendering; the layout engine and serialized format are unchanged.
+- Every tab has a stable Grid cell, frame, Header container and Body container. Explicit Grid columns determine docking placement; Flex assigns Header and Body height. Floating changes that same frame to `position: fixed` without changing its parent or replacing Body.
+- A floating frame's zero-sized Grid cell establishes a stacking context at the float layer. CSS `order` expresses float depth within that layer; DOM order stays sorted by tab identity. Raising many floats cannot increment their layer past menus. Selection and strip order never reorder the content-node list.
+- Common ancestors have no transform, clipping or enclosing stacking context. Docked cells own collapse transforms and visibility; each frame clips its content. Fullscreen changes the same root's width and docked layer. Existing window-drag region pulses remain, but no RAF copies content positions.
+- Split and float gestures retain their existing measurements and operation state. These update user-selected split fractions and float rectangles, not a second Browser rectangle. Browser resize and content sizing use normal CSS layout.
+
+### Session and tab lifetime
+
+`SidebarRightTabDefinition.keepMounted` enables lazy retention for a type. Desktop Browser enables it; other types keep visibility-based body mounting. A retained body is first created on display, then survives hiding until its occurrence or provider lifetime ends. The policy is not persisted and does not select a storage partition.
+
+`SidebarSessionView` acquires and releases one `SessionReference` using the independent `sidebarView` source, and owns its committed-mount count and retained-Body holds. `SidebarSessionViews` manages selection, retention policy and view indexes; it delegates lifetime operations to the view rather than mutating its counts or releasing its reference. `RightbarRoot` receives `SidebarSessionViewSnapshot` values and the existing injected callbacks, not resource-owner objects. It renders each through its own explicit `SessionProvider`, with a stable Session key; the renderer's general Session-remount semantics remain unchanged.
+
+Tabs contribute Body-retention holds rather than independent Session references. The View's stable `retainTab` callback reaches its seat through owner props, so replacing Session injection bindings does not release and reacquire those holds. Those holds follow the existing occurrence signal, including a new signal after close-and-undo; the view does not create a second tab lifetime. A retired view stays in the collection's reference index until its own disposal removes it, so plugin shutdown can also reach views whose React mounts have not finished.
+
+Only the selected Session reports frame occupancy or binds public Sidebar navigation. Background tab actions still address their own adopted store. `tab.visible` includes Session and global-panel visibility; floating does not make a background Session visible. A Session change or global panel hides its whole content tree, while Sidebar collapse hides only docked cells and leaves foreground floats visible. Hidden content is inaccessible to pointer and keyboard input, and hidden body focus is blurred.
+
+A background Session with no initialized retained body leaves the view list. Its reference releases after its committed React root unmounts, avoiding scope disposal underneath a mounted subtree. Plugin disposal releases all references, including retired views awaiting unmount. The Sidebar plugin depends on `sessions` and `uiSession`, so Cordis unloads it when either dependency ends; `ui-session` owns binding invalidation. Views do not register disposal callbacks on the shared Session Context. Catalog absence alone is not treated as deletion. Unvisited Browser tabs and unrelated Sessions are not eagerly opened.
+
+### Provider responsibilities
+
+`BrowserFrame` remains navigation and observable page state. Presentation creates and attaches the carrier DOM, without pane, clipping or stacking knowledge. Electron's provider receives physical attach/detach callbacks: hiding retained content emits neither, while an actual unmount cancels pending attachment and releases the guest. A subsequent physical mount recreates it from its known address. Disposal waits for pending creation and guest releases; an acquisition completing after cancellation is released rather than attached.
+
+The [Desktop Browser decision](../feature/2026-09-20-desktop-browser-webview.md) retains guest security, shared IPC declarations and Workspace partition ownership. Separate tabs and Sessions never share one page instance merely because they share a storage partition. Web remains disabled by default and retains its iframe carrier when explicitly enabled.
+
+### Retention versus recovery
+
+| Operation | Content handling |
+|---|---|
+| Switch tabs | Hide the old retained cell; display the target's existing body. |
+| Split, reorder or move to another pane | Change logical placement and Grid assignment, without moving Body. |
+| Float, dock back or raise | Change the same frame's CSS mode or cell paint order. |
+| Collapse Sidebar | Hide docked cells; foreground floats remain visible. |
+| Session A → B → A | Hide and reshow A's original tree instead of loading its saved URL. |
+| Close, provider unload or actual generation termination | Release the body and guest; undo creates a new occurrence. |
+| Application restart or window reload | Show the saved title and URL; load only after an explicit restore or address submission. |
+| Guest crash | Retry through the provider; page memory and native history are not durable. |
+
+[Layout and provider recovery](2026-09-14-sidebar-layout-provider-recovery.md) remains independent: persisted tab identity, placement and address support cold starts, not DOM serialization. A hidden page may continue scripts, media and networking.
+
+## Alternatives considered
+
+**Hide panes only.** Collapse works, but moving between panes or into another floating portal still changes content ancestors.
+
+**Retain bodies only in the foreground Session.** Session-slot remounting disconnects the page and loses its live state on Session switches.
+
+**Give each tab its own Session reference.** A view's tabs share one `SessionProvider`, whose reference must exist before their bodies render. Per-view ownership covers that parent and its children without an additional reference lifecycle for each tab.
+
+**Cache and reparent DOM.** Ordinary reparenting invokes Electron disconnection. Atomic-move dependencies, private attachment APIs and lifecycle monkey-patches are not used.
+
+**Position Browser content in a separate overlay.** Measurement or CSS anchors can align an overlay, but its content remains outside the parent Grid/Flex layout that must own its sizing and clipping.
+
+**Use native popovers.** Top-layer elements cannot be covered by ordinary Portal content through `z-index`. Migrating menus and dialogs into another stacking system expands the work beyond Sidebar; the implementation preserves the existing Portal and layer model.
+
+**Raise floats by increasing their root z-index.** An unbounded float count can cross menu and modal layers. Equal-layer Grid cells with CSS paint order retain both stacking and DOM identity.
+
+**Save the URL and rebuild when hidden.** This cannot preserve forms, script state, scroll position or native history. It is recovery after loss, not live retention.
+
+## Consequences
+
+Layout correctness belongs to Sidebar/DockKit rather than Browser. The cost is stable content containers and explicit Session-reference ownership: background retention holds Session scopes and subscriptions as well as page memory. There is no implicit LRU or idle timeout; future reclamation requires an explicit suspension/recovery policy. Other tab types do not automatically acquire these costs.
+
+Sidebar/DockKit own chrome, float stacking, focus and platform styles as well as retained content placement. The [docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) owns the layout engine, persistence and tab-type navigation; the [Desktop Browser decision](../feature/2026-09-20-desktop-browser-webview.md) owns guest navigation, storage and security.
+
+## Verification
+
+Focused tests cover retained bodies across Session-source registration and removal, persisted-layout validation, and existing Sidebar presentation. Host and Client TypeScript compilation passes. The user manually accepted a rebuilt Electron cold start; no GIF was recorded. Dedicated real-Electron evidence for guest identity, form and history retention, multi-float paint order, resizing, clipping, drop hints, focus and platform window controls remains separate from these unit tests.
diff --git a/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.zh.md b/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.zh.md
new file mode 100644
index 0000000000..365ad5682c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-20-sidebar-retained-tab-layout.zh.md
@@ -0,0 +1,82 @@
+# Agent Note: Sidebar 的稳定 Tab 挂载与会话保活
+
+Status: implemented
+
+[English](2026-09-20-sidebar-retained-tab-layout.md) | 中文
+
+## Problem
+
+恢复各会话的 Tab 记录和 URL, 并不能保留活的浏览上下文. 在 Tab、Pane 或会话切换期间卸载 Body 或改变其 DOM 祖先, 都会断开页面. Electron 44 的 `WebViewElement.disconnectedCallback` 会 detach 并重置 guest, 因此保持 React key 或缓存元素引用不能抵消祖先断开. 内容尺寸、裁剪与重叠也必须遵循真实父节点布局.
+
+## Decision
+
+Sidebar 负责活 Body 的保留，不依赖 Browser 导航和 Workspace 存储。保活页面的 DOM 祖先在切会话、选 Tab、跨 Pane 移动、收起、浮动和回停靠时保持连接与身份不变。Browser Presentation 直接挂载到内容容器内，不做占位元素测量或浮层定位。
+
+### 布局所有权
+
+- `DockLayout` 用稳定的 Tab 兄弟节点渲染 Sidebar 的一个或两个水平 Pane。现有递归 `DockSurface` 和独立 `FloatLayer` 仍可用于通用分割树渲染；布局引擎和序列化格式不变。
+- 每个 Tab 都有稳定的 Grid cell、frame、Header 容器和 Body 容器。显式 Grid 列决定停靠归属，Flex 分配 Header 与 Body 的高度。浮动只把同一个 frame 改为 `position: fixed`，不改父节点或替换 Body。
+- 浮动 frame 的零尺寸 Grid cell 在浮窗层建立层叠上下文。CSS `order` 表达该层内的浮窗深度，DOM 顺序始终按 Tab 身份排序。大量浮窗置顶不会把层级递增到菜单之上；选中项和 Tab 条排序均不重排内容节点列表。
+- 共同祖先不设置 transform、裁剪或包住全部内容的层叠上下文。停靠 cell 负责收起 transform 和显隐，各 frame 裁剪自身内容。Fullscreen 修改同一个根的宽度和停靠层级。窗口拖动区域的既有脉冲仍保留，但没有 RAF 复制内容位置。
+- 分栏与浮窗手势沿用原有测量和操作状态，更新用户选择的分栏比例与浮窗矩形，而非维护第二份 Browser 矩形。窗口缩放和内容尺寸变化由普通 CSS 布局处理。
+
+### 会话与 Tab 生命周期
+
+`SidebarRightTabDefinition.keepMounted` 为类型启用懒保活。Desktop Browser 启用它，其他类型继续按可见性挂载 Body。保活 Body 在首次显示时创建，随后隐藏不卸载，直到 occurrence 或提供方生命周期结束。该策略不持久化，也不选择存储分区。
+
+`SidebarSessionView` 使用独立的 `sidebarView` 来源申请、释放一个 `SessionReference`，并管理自己的已提交挂载计数和 Body 保活持有。`SidebarSessionViews` 管理选中、保留策略和视图索引，将生命周期操作委托给视图，而不修改其计数或释放其引用。`RightbarRoot` 接收 `SidebarSessionViewSnapshot` 和已有注入回调，不接收资源所有者对象；它为各视图分别渲染显式 `SessionProvider`，保持会话 key 稳定，渲染器通用的会话重挂载语义不变。
+
+Tab 提供 Body 保活持有，而不独立申请会话引用。View 的稳定 `retainTab` 回调通过 owner props 传给席位，因此替换 Session injection binding 不会释放再重新获取这些持有。这些持有跟随已有 occurrence signal，包括关闭后撤销恢复得到的新 signal；视图不创建第二套 Tab 生命周期。退出视图列表的视图仍留在集合的引用索引中，直到自行释放时移除索引，因此插件关闭时也能清理尚未结束 React 挂载的视图。
+
+只有选中的会话向 frame 报告占位、绑定公共 Sidebar 导航。后台 Tab actions 仍指向自己的已接管存储。`tab.visible` 包含会话和全局面板的可见性，浮动不会让后台会话变成可见。切会话或打开全局面板隐藏整个内容树，收起 Sidebar 则只隐藏停靠 cell，前台浮窗仍可见。隐藏内容不可通过指针或键盘访问，隐藏 Body 内的焦点会被移除。
+
+后台会话没有已初始化的保活 Body 时，从视图列表移除；等已提交的 React 根卸载后再释放引用，避免仍挂载的子树下方先销毁会话 scope。插件释放会清理全部引用，包括等待卸载的已移除视图。Sidebar 插件依赖 `sessions` 和 `uiSession`，任一依赖结束时由 Cordis 卸载它，绑定失效由 `ui-session` 负责。视图不向共享会话 Context 注册销毁回调。仅在目录列表中缺项不视为删除。未访问的 Browser Tab 和无关会话不会提前打开。
+
+### 提供方职责
+
+`BrowserFrame` 仍只负责导航与可观察页面状态。Presentation 创建、挂载载体 DOM，不了解 Pane、裁剪或层叠。Electron 提供方接收物理 attach/detach 回调：隐藏保活内容不触发这些回调，真正卸载则取消未完成的挂载并释放 guest；之后再次物理挂载时从已知地址重建。dispose（资源释放）会等待未完成的创建和 guest 释放，取消后才完成的申请只释放、不挂载。
+
+[Desktop Browser 决策](../feature/2026-09-20-desktop-browser-webview.zh.md)继续负责 guest 安全、共享 IPC 声明和 Workspace 分区所有权。不同 Tab 和会话不能因为共享存储分区就共享一个页面实例。Web 默认仍关闭，显式启用时继续使用 iframe 载体。
+
+### 保活与恢复
+
+| 操作 | 内容处理 |
+|---|---|
+| 切换 Tab | 隐藏旧的保活 cell，显示目标已有 Body。 |
+| 分栏、排序或移到另一个 Pane | 改逻辑归属和 Grid 分配，不搬移 Body。 |
+| 浮动、回停靠或置顶 | 改同一个 frame 的 CSS 模式或 cell 绘制顺序。 |
+| 收起 Sidebar | 隐藏停靠 cell，前台浮窗保持可见。 |
+| 会话 A → B → A | 隐藏并重新显示 A 的原内容树，而非加载已保存 URL。 |
+| 关闭、提供方卸载或真实 generation 结束 | 释放 Body 和 guest；撤销关闭创建新 occurrence。 |
+| 应用重启或窗口刷新 | 展示保存的标题和 URL，显式恢复或提交地址后才加载。 |
+| guest 崩溃 | 通过提供方重试；页面内存和原生 history 不持久化。 |
+
+[布局与提供方恢复](2026-09-14-sidebar-layout-provider-recovery.zh.md)仍然独立：持久化的 Tab 身份、位置和地址支持冷启动，而不是序列化 DOM。隐藏页面可能继续执行脚本、播放媒体或联网。
+
+## Alternatives considered
+
+**只隐藏 Pane。** 可以覆盖收起，但跨 Pane 移动或进入独立浮动 Portal 仍会改变内容祖先。
+
+**只保留前台会话的 Body.** 会话 slot 重挂载会断开页面, 导致切会话时丢失页面运行状态.
+
+**每个 Tab 独立持有会话引用。** 同一视图的 Tab 共用一个 `SessionProvider`，它的引用必须先于这些 Body 渲染而存在。按视图持有即可覆盖父级及其子节点，无须再为每个 Tab 管理一份引用生命周期。
+
+**缓存并搬移 DOM。** 普通 reparent 会触发 Electron 断开处理；实现不依赖原子搬移、私有挂载 API 或生命周期补丁。
+
+**把 Browser 内容放在独立浮层中.** 测量或 CSS 锚点可以对齐浮层, 但内容仍处于负责其尺寸与裁剪的父级 Grid/Flex 布局之外.
+
+**使用原生 popover。** 普通 Portal 内容无法通过 `z-index` 覆盖 top layer 元素。把菜单、对话框迁移到另一套层叠体系会扩大 Sidebar 之外的改动；实现保留既有 Portal 和层级模型。
+
+**通过递增根 z-index 置顶浮窗。** 不设上限的浮窗数量可能越过菜单和模态层。同层 Grid cell 的 CSS 绘制顺序同时保留层叠与 DOM 身份。
+
+**隐藏时保存 URL 再重建。** 无法保留表单、脚本状态、滚动位置和原生 history。这是丢失实例后的恢复，不是活页面保留。
+
+## Consequences
+
+布局正确性由 Sidebar/DockKit 负责，而不是 Browser。代价是稳定的内容容器与显式会话引用所有权：后台保活不仅持有页面内存，也持有会话 scope 和订阅。没有隐式 LRU 或空闲超时，未来回收需要明确的暂停与恢复策略；其他 Tab 类型不会自动承担这些成本。
+
+Sidebar/DockKit 除了负责保活内容布局, 还负责控件、浮窗层级、焦点和平台样式. [停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)负责布局引擎、持久化和 Tab 类型导航; [Desktop Browser 决策](../feature/2026-09-20-desktop-browser-webview.zh.md)负责 guest 导航、存储和安全.
+
+## Verification
+
+定向测试覆盖 Session 数据源注册与注销期间的正文保活、存档布局校验和既有 Sidebar 呈现。Host 与 Client TypeScript 编译通过。用户已手动验收重新构建后的 Electron 冷启动；未录制 GIF。guest 身份、表单与 history 保留、多浮窗绘制顺序、缩放、裁剪、放置提示、焦点和平台窗口控件仍需独立于这些单元测试的真实 Electron 证据。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
new file mode 100644
index 0000000000..154afe129e
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages 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-09-15-client-session-blank-reconciliation.md
+2026-09-15-client-session-blank-reconciliation.md: 7213636e32702c4c51887adba3da019f49b8703c
+2026-09-15-client-session-blank-reconciliation.zh.md: 4b50340fea668b6d850c1d00787dda3874b61e0c
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
new file mode 100644
index 0000000000..7213636e32
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md
@@ -0,0 +1,43 @@
+# Agent Note: Keep accepted Session presentation across list refreshes
+
+Status: implemented
+
+English | [中文](2026-09-15-client-session-blank-reconciliation.zh.md)
+
+## Problem
+
+A successful prompt response converts the Client's `New Session` row before a turn necessarily starts. A later `session.list` response can still report `blank: true` and undo that conversion. Reconnect triggers the same refresh. Keeping the conversion only inside a Session object also loses it when that object is replaced.
+
+## Decision
+
+The [Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) retains accepted/running observations in a private set keyed by Session id. List rows and the existing Session blank updates use `summary.blank && !engagedSessions.has(sessionId)`, with `sessionListMetadata` hints still applied on top. The existing summary mutations, Session snapshot fields, constructor, and projection stores retain their responsibilities.
+
+Every successful prompt response invokes the existing `onEngaged` callback, including from a replaced Session object. The Manager updates its retained observation, the list row, and the currently resident Session by id. Rejection records no engagement. A `running: true` status, addition, or list baseline also records engagement; a baseline predating removal cannot restore that observation, even if the row is re-added during the pull.
+
+The observation survives refresh, reconnect, and object replacement. Removal, drop, and successful list refresh forget it only when no list row, Session object, or child address retains the identity. Refresh evaluates retention after replaying in-flight mutations; failed and superseded pulls do not prune observations. Late acceptance cannot recreate a removed row or a Session object. Manager disposal clears the set and prevents late acceptance and outstanding list responses from publishing.
+
+Engagement is display memory, not proof that a turn started, work remains queued, or a message reached durable storage. It is not persisted across page reload. Historical `sessionListMetadata.blank` and the Host summary defaults are unchanged.
+
+## Alternatives considered
+
+**Preserve every previously false summary bit.** A previous Host summary is not evidence of local acceptance or running. Making all false values permanent would also suppress later Host corrections without either observation.
+
+**Introduce a shared Session record.** Combining this memory with projection stores requires constructor and cache-lifetime changes. Those changes are independent of preventing a blank rollback and are excluded.
+
+**Wait for history before converting the row.** This changes the existing acceptance-time display rule and is a separate UI decision.
+
+## Consequences
+
+Accepted or observed-running Sessions retain their existing display conversion, including when accepted input never starts a turn. Drafts, submission-error recovery, sidebar filtering and title rules, creation/reuse, UUIDs, Host protocol, persistence, and projection-cache lifetimes are unchanged. Reverting this Client-only fix needs no data migration.
+
+The Manager owns one additional per-id display flag. It does not replace Session-local presentation fields or implement a history/draft/presentation redesign.
+
+For an identity with neither subagent origin nor a retained child address, a removal notification discards its projection store unless that store already carries a non-empty `subagentCatalog`; a retained Session object keeps the store it was constructed with — for example a current row removed while its Session is still staged. If its projection store was discarded and that identity returns to the list before its Session object is dropped, the Manager creates and seeds a second store that the resident object never reads, so list rows and that object's projection readers can disagree until a replacement instance adopts the current store. Repairing that projection ownership is deferred to its own change; blank display does not depend on it.
+
+## Verification
+
+Manager tests cover refresh without a turn, running-to-idle updates, object replacement, late acceptance, removal through notifications or list reconciliation, retained instances and child addresses, failed and superseded pulls, and disposal. They check both list and Session state where an instance exists. Session tests retain first-send rejection and later-send behavior. Browser verification uses the recorded first-turn scenario with acceptance held before `turn/start` and a same-page reconnect. A timestamp substituted only in the reconnect list response provides a visible synchronization marker; the Host's blank/running values and durable log remain unchanged.
+
+## Related decisions
+
+The [scope and provisioning decision](../architecture/2026-07-25-web-client-session-scope-and-provide-channel.md) owns Session scope, creation/reuse, and the visible blank row. The [Session/Conversation ownership decision](../architecture/2026-08-20-client-session-conversation-ownership.md) owns transport, assembly, and snapshot contents.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
new file mode 100644
index 0000000000..4b50340fea
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md
@@ -0,0 +1,43 @@
+# Agent Note: 在列表刷新后保留已受理会话的展示状态
+
+Status: implemented
+
+[English](2026-09-15-client-session-blank-reconciliation.md) | 中文
+
+## 问题
+
+提示词请求成功后，客户端会把 `New Session` 行转换为普通会话，但此时轮次不一定已经开始。后续 `session.list` 响应仍可能返回 `blank: true`，从而撤销该转换。重连会触发同样的刷新。若只在 Session 对象内保留转换状态，对象被替换时也会丢失。
+
+## 决策
+
+[Manager](../../../../packages/api/session-controller/src/client/sessions/manager.ts) 使用按 Session id 索引的私有集合，保留已观察到的受理/运行。列表行与既有 Session blank 更新使用 `summary.blank && !engagedSessions.has(sessionId)`，其上仍叠加 `sessionListMetadata` 提示。既有摘要变更、Session 快照字段、构造函数和投影存储保留原有职责。
+
+每个成功的提示词响应都会调用既有 `onEngaged` 回调，包括来自已被替换的 Session 对象的响应。Manager 按 id 更新其保留的观察、列表行和当前驻留 Session。拒绝不会记录受理/运行。`running: true` 状态、添加事件或列表基线也会记录运行；早于移除的基线不能恢复该观察，即使该行在拉取期间重新加入。
+
+该观察跨刷新、重连和对象替换保留。移除、drop 和成功的列表刷新仅在列表行、Session 对象及子会话地址均不再保留该身份时清除它。刷新在重放请求期间的变更后判断保留资格；失败及被替代的请求不会清理观察。迟到的受理不能重建已移除的行或 Session 对象。Manager 销毁会清空集合，并阻止迟到的受理和未完成的列表响应发布。
+
+受理/运行是展示记忆，不证明轮次已经开始、工作仍在排队，或消息已经写入持久存储。它不会跨页面重载持久化。历史 `sessionListMetadata.blank` 与 Host 摘要默认值保持不变。
+
+## 考虑过的替代方案
+
+**保留所有曾为 false 的摘要位。** 先前的 Host 摘要不能证明客户端观察过受理或运行。将所有 false 永久保留，也会在两种观察均不存在时阻止后续 Host 校正。
+
+**引入共享 Session 记录。** 将这份记忆与投影存储合并，需要修改构造参数及缓存生命周期。这些改动独立于防止 blank 回退，因此不纳入。
+
+**等待历史后再转换行。** 这会改变现有的受理时展示规则，属于独立的 UI 决策。
+
+## 后果
+
+已受理或观察过运行的 Session 保持既有展示转换，包括已受理输入始终没有开始轮次的情况。草稿、发送错误恢复、侧边栏筛选与标题规则、创建/复用、UUID、Host 协议、持久化及投影缓存生命周期保持不变。回退这项纯客户端修复不需要数据迁移。
+
+Manager 额外维护一个按 id 保存的展示标记。它不替代 Session 本地展示字段，也不实施历史/草稿/展示状态重构。
+
+对于来源不是 subagent、也没有保留子会话地址的身份，移除通知会丢弃它的投影存储——除非该存储已带有非空的 `subagentCatalog`；而仍被保留的 Session 对象继续持有构造时采用的存储，例如当前行被移除而它的 Session 仍留在舞台上。若投影存储已被丢弃，且该身份在其 Session 对象被销毁前回到列表，Manager 会新建并写入第二个存储，而常驻对象从不读取它，因此在替换实例采用当前存储之前，列表行与该对象的投影读取方可能不一致。该投影归属的修复延期到独立的改动；blank 展示不依赖它。
+
+## 验证
+
+Manager 测试覆盖无轮次刷新、运行转空闲、对象替换、迟到受理、通过通知或列表对账移除、保留实例与子会话地址、失败及被替代的请求，以及销毁。在存在实例的场景中，测试同时检查列表和 Session 状态。Session 测试保留首发拒绝及后续发送行为。浏览器验证使用已有首轮录制场景，在受理后、`turn/start` 前暂停并进行同页重连。测试仅替换重连列表响应中的时间戳，用其显示结果作为同步标记；Host 的 blank/running 值及持久日志保持不变。
+
+## 相关决策
+
+[作用域与供给决策](../architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md) 拥有 Session 作用域、创建/复用及可见 blank 行。[Session/Conversation 归属决策](../architecture/2026-08-20-client-session-conversation-ownership.zh.md) 拥有传输、装配及快照内容。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.i18n.yaml
index e63305ebf1..106b30af30 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-15-messages-v1-base-url.md
-2026-09-15-messages-v1-base-url.md: 97f7294c28988e6f115963033cdac6794d70d6f3
-2026-09-15-messages-v1-base-url.zh.md: ccb8c5930dbbfa6274770cc03087b4d8077fe27b
+2026-09-15-messages-v1-base-url.md: d9014756eacd1752495bfecb52860634ece08ae1
+2026-09-15-messages-v1-base-url.zh.md: 8f5803e4bdc68195164e187d1aa8cd537f71c5d6
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.md b/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.md
index 97f7294c28..d9014756ea 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.md
@@ -12,7 +12,7 @@ The Messages transport appends the Anthropic-standard `/v1` namespace to a confi
 
 The shared Messages API owner trims trailing slashes and treats only a final path segment exactly equal to `v1` as the existing API version. It preserves that root and appends `/messages` or `/files`; every other base receives `/v1/messages` or `/v1/files`. The same resolved root scopes cached file uploads. The official `https://api.deepseek.com/anthropic` base therefore resolves to `/anthropic/v1`, and an explicit `/anthropic/v1` base remains unchanged.
 
-Chat Completions retains its independent URL behavior. The Messages rule does not infer support for `v1beta`, `v2`, `v4`, or other version-like suffixes; deployments that include those segments receive the standard `/v1` namespace beneath them.
+The Messages rule does not infer support for `v1beta`, `v2`, `v4`, or other version-like suffixes; deployments that include those segments receive the standard `/v1` namespace beneath them.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.zh.md
index ccb8c5930d..8f5803e4bd 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-15-messages-v1-base-url.zh.md
@@ -12,7 +12,7 @@ Messages 传输会在配置的基址后追加 Anthropic 标准 `/v1` 命名空
 
 共享 Messages API 所有者移除末尾斜线，仅把严格等于 `v1` 的最后路径段视为已有 API 版本。它保留该根地址并追加 `/messages` 或 `/files`；其他基址均追加 `/v1/messages` 或 `/v1/files`。缓存文件上传也使用同一个解析后的根地址划分作用域。因此，官方 `https://api.deepseek.com/anthropic` 基址解析为 `/anthropic/v1`，显式 `/anthropic/v1` 基址保持不变。
 
-Chat Completions 保留独立的 URL 行为。Messages 规则不会推断对 `v1beta`、`v2`、`v4` 或其他版本式后缀的支持；包含这些路径段的部署会在其下获得标准 `/v1` 命名空间。
+Messages 规则不推断 `v1beta`、`v2`、`v4` 或其他类似版本后缀的支持；包含这些路径段的部署会在其下接收标准 `/v1` 命名空间。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml
index a5158a3994..9c2cdd061a 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-16-desktop-window-menus.md
-2026-09-16-desktop-window-menus.md: 85ac42aa287b1cd9e595ade7cb44b965dea787dd
-2026-09-16-desktop-window-menus.zh.md: 1376b90058ceafa7e378b4fd543d261064f5d8aa
+2026-09-16-desktop-window-menus.md: 8a5343404e0cb3d2e7c4e20248a8b29f3bfbec47
+2026-09-16-desktop-window-menus.zh.md: d6ee6412462aecf49557a7994a683d37bf8e7253
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md
index 85ac42aa28..8a5343404e 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.md
@@ -12,7 +12,7 @@ The Desktop shell replaces Electron's default application menu with a custom tem
 
 On macOS the template declares `{ role: 'fileMenu' }` before the Edit menu and `{ role: 'windowMenu' }` after it, and a separator-delimited run of `hide`, `hideOthers`, and `unhide` before Quit in the application submenu. Those roles contribute only the standard items; no Services submenu, window list, or other macOS default is declared. Windows and Linux keep the application and Edit menus.
 
-Electron's role labels are English string literals inside Electron (`lib/browser/api/menu-item-roles.ts`, `filemenu`, `windowmenu`, `close`, `minimize`, `hide`) with no locale lookup, and Electron re-applies them to the native menu items before the menu is shown, so a non-English Desktop shows them in English; the existing Edit menu behaves the same way. No custom close, minimize, or hide code is added: ⌘W destroys the window through Electron's own role.
+Electron supplies English defaults for the File, Window, and Edit roles. Explicit labels override role defaults while retaining native actions and shortcuts; the localized application commands are documented in the [Desktop README](../../../../apps/desktop/README.md). No custom close, minimize, or hide code is added: ⌘W destroys the window through Electron's own role.
 
 ## Alternatives considered
 
@@ -28,8 +28,8 @@ Electron's role labels are English string literals inside Electron (`lib/browser
 
 ## Consequences
 
-macOS regains the window and application commands the custom menu suppressed, at the cost of four menu roles. The labels stay English on a non-English Desktop.
+macOS regains the window and application commands the custom menu suppressed. File, Window, and Edit retain Electron’s default English labels; application commands use the Desktop locale.
 
 ## Testing
 
-A `apps/desktop/tests/main-startup.spec.ts` case pins the declared menu roles per platform, including the macOS hide commands. Role-based menu items execute natively, so a programmatic `click()` and the vitest Electron mock cannot exercise the shortcuts; a real Electron 44 run of the same template showed the standard File, Window, and application items present only after this change, with the same English labels while `app.getLocale()`, `getSystemLocale()`, and `getPreferredSystemLanguages()` all reported `zh-CN`.
+`apps/desktop/tests/main-startup.spec.ts` verifies the declared menu roles per platform and records English and Chinese application-label snapshots. Role-based menu items execute natively, so a programmatic `click()` and the Vitest Electron mock cannot exercise the shortcuts. The isolated Electron 44 demo confirms that explicit application labels appear in native menus; the template snapshots do not qualify native shortcut execution.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md
index 1376b90058..d6ee641246 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-desktop-window-menus.zh.md
@@ -12,7 +12,7 @@ Desktop shell 用自定义模板替换了 Electron 的默认应用菜单，该
 
 macOS 上的模板在 Edit 菜单之前声明 `{ role: 'fileMenu' }`，在其之后声明 `{ role: 'windowMenu' }`，并在应用子菜单的 Quit 之前声明由分隔符隔开的 `hide`、`hideOthers` 和 `unhide`。这些 role 只提供标准菜单项；不声明 Services 子菜单、窗口列表或其他 macOS 默认项。Windows 和 Linux 保留应用菜单和 Edit 菜单。
 
-这些 role 的标签是 Electron 内部的英文常量（`lib/browser/api/menu-item-roles.ts` 的 `filemenu`、`windowmenu`、`close`、`minimize`、`hide`），没有语言查询，而且 Electron 在菜单显示前会把这些标签重新写到本机菜单项上，因此在非英文的 Desktop 上它们仍是英文；现有的 Edit 菜单同样如此。这里不新增任何自定义的关闭、最小化或隐藏代码：⌘W 通过 Electron 自身的 role 销毁窗口。
+Electron 为 File、Window 和 Edit role 提供英文默认标签。显式标签会覆盖 role 的默认标签，同时保留原生命令和快捷键；本地化的应用命令见 [Desktop README](../../../../apps/desktop/README.zh.md)。这里不新增任何自定义的关闭、最小化或隐藏代码：⌘W 通过 Electron 自身的 role 销毁窗口。
 
 ## 考虑过的替代方案
 
@@ -28,8 +28,8 @@ macOS 上的模板在 Edit 菜单之前声明 `{ role: 'fileMenu' }`，在其之
 
 ## 影响
 
-macOS 恢复了自定义菜单压掉的窗口和应用命令，代价是四个菜单 role。在非英文的 Desktop 上这些标签仍是英文。
+macOS 恢复了自定义菜单压掉的窗口和应用命令。File、Window 和 Edit 保留 Electron 的默认英文标签；应用命令使用 Desktop 的语言。
 
 ## 测试
 
-`apps/desktop/tests/main-startup.spec.ts` 中的一个用例固定了各平台声明的菜单 role，包括 macOS 的隐藏命令。基于 role 的菜单项由本机执行，因此程序化的 `click()` 和 vitest 的 Electron mock 都无法触达这些快捷键；用真实 Electron 44 运行同一模板显示，只有在本改动之后才出现标准的 File、Window 和应用菜单项，并且在 `app.getLocale()`、`getSystemLocale()` 和 `getPreferredSystemLanguages()` 都报告 `zh-CN` 时标签保持不变。
+`apps/desktop/tests/main-startup.spec.ts` 验证各平台声明的菜单 role，并记录中英文应用标签快照。基于 role 的菜单项由本机执行，因此程序化的 `click()` 和 Vitest 的 Electron mock 都无法触达这些快捷键。独立 Electron 44 demo 确认显式应用标签会显示在原生菜单中；模板快照不能验证原生快捷键的执行。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.i18n.yaml
index 6bb2fcf803..e6974943f5 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-16-messages-historical-tool-input.md
-2026-09-16-messages-historical-tool-input.md: 201b0f21ad041395a4c4101d6919b2878e22c9ab
-2026-09-16-messages-historical-tool-input.zh.md: bcc637982420124b401ef65c668b068394b6d915
+2026-09-16-messages-historical-tool-input.md: 85e4047bb5274eb7c7adb458d564e1268d4ea81e
+2026-09-16-messages-historical-tool-input.zh.md: 5a8c31dbee32094f124102ccac9ffb7b8b81b177
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.md b/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.md
index 201b0f21ad..85e4047bb5 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.md
@@ -10,7 +10,7 @@ Chat Completions retains tool arguments as strings, including malformed JSON fro
 
 ## Decision
 
-The [Messages serializer](../../../../packages/llm/llm-deepseek/src/protocols/messages/serialize.ts) follows the [pi-ai history conversion](../../../../packages/llm/llm-pi-ai/src/replay.ts): malformed JSON and non-object values become `{}` only in the outgoing historical tool input. Call ids, names, results, and original Session records remain intact. This applies with valid, absent, or unusable native replay metadata and does not execute the historical call again.
+The [Messages serializer](../../../../packages/llm/llm-deepseek/src/serialize.ts) follows the [pi-ai history conversion](../../../../packages/llm/llm-pi-ai/src/replay.ts): malformed JSON and non-object values become `{}` only in the outgoing historical tool input. Call ids, names, results, and original Session records remain intact. This applies with valid, absent, or unusable native replay metadata and does not execute the historical call again.
 
 This supersedes the historical argument rejection in the [Messages adapter decision](../feature/2026-09-07-deepseek-messages-adapter.md). New Messages responses still require valid object arguments before successful completion; output-limit truncation retains its existing pruning behavior. No Session event, persistence type, or protocol configuration changes.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.zh.md b/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.zh.md
index bcc6379824..5a8c31dbee 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-16-messages-historical-tool-input.zh.md
@@ -10,7 +10,7 @@ Chat Completions 将工具参数保留为字符串，其中可能包含失败调
 
 ## 决策
 
-[Messages 序列化器](../../../../packages/llm/llm-deepseek/src/protocols/messages/serialize.ts) 遵循 [pi-ai 历史转换](../../../../packages/llm/llm-pi-ai/src/replay.ts)的做法：只在发出的历史工具输入中，将非法 JSON 和非对象值替换为 `{}`。调用 ID、名称、结果和原始 Session 记录保持不变。原生回放元数据有效、缺失或不可用时均采用此规则，也不会重新执行历史调用。
+[Messages 序列化器](../../../../packages/llm/llm-deepseek/src/serialize.ts) 遵循 [pi-ai 历史转换](../../../../packages/llm/llm-pi-ai/src/replay.ts)的做法：只在发出的历史工具输入中，将非法 JSON 和非对象值替换为 `{}`。调用 ID、名称、结果和原始 Session 记录保持不变。原生回放元数据有效、缺失或不可用时均采用此规则，也不会重新执行历史调用。
 
 这取代了 [Messages 适配器决策](../feature/2026-09-07-deepseek-messages-adapter.zh.md)中的历史参数拒绝规则。新生成的 Messages 响应在成功完成前仍要求工具参数是有效对象；达到输出上限时仍按现有规则裁剪。不改变 Session 事件、持久化类型或协议配置。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.i18n.yaml
index 0898823b35..259613bc28 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-18-messages-input-history-compatibility.md
-2026-09-18-messages-input-history-compatibility.md: 1775276deec6180f1fd186b11cb7a757a3328a54
-2026-09-18-messages-input-history-compatibility.zh.md: 50367e33c29df0679a44aca1fe680d2bedc8c263
+2026-09-18-messages-input-history-compatibility.md: dd974fb1ae883716002a1381f4c374dee792b3b3
+2026-09-18-messages-input-history-compatibility.zh.md: 6e850328db63d5ae5cb508aa3529e9f2507182b0
diff --git a/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.md b/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.md
index 1775276dee..dd974fb1ae 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.md
@@ -10,7 +10,7 @@ Saved subagent settlement notices can contain child reasoning and tool calls in
 
 ## Decision
 
-The [Messages serializer](../../../../packages/llm/llm-deepseek/src/protocols/messages/serialize.ts) omits `reasoning` and `tool-call` blocks from user and tool-result input. This matches Chat Completions and pi-ai for these two block types, without changing Session records or converting child reasoning into parent user text. The [provider README](../../../../packages/llm/llm-deepseek/README.md#model-experience) owns the input rules, including empty user messages, empty tool results, and rejection of other unsupported blocks.
+The [Messages serializer](../../../../packages/llm/llm-deepseek/src/serialize.ts) omits `reasoning` and `tool-call` blocks from user and tool-result input. This matches Chat Completions and pi-ai for these two block types, without changing Session records or converting child reasoning into parent user text. The [provider README](../../../../packages/llm/llm-deepseek/README.md#model-experience) owns the input rules, including empty user messages, empty tool results, and rejection of other unsupported blocks.
 
 This partially supersedes the settlement decision's rejection of serializer tolerance and the [Messages adapter decision](../feature/2026-09-07-deepseek-messages-adapter.md)'s input rejection. Notice construction still projects nonempty child text for every parent provider. Canonical child output and ordinary assistant reasoning and tool calls remain available to their existing consumers. The omission is based on input role and block type, not the notice source or creation date, so it also applies to newly supplied user and tool-result content.
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.zh.md b/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.zh.md
index 50367e33c2..6e850328db 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[Messages 序列化器](../../../../packages/llm/llm-deepseek/src/protocols/messages/serialize.ts)省略用户与工具结果输入中的 `reasoning` 和 `tool-call` 块。这两类块的处理与 Chat Completions、pi-ai 一致，不改变 Session 记录，也不把子级推理转换成父级用户文本。[提供方 README](../../../../packages/llm/llm-deepseek/README.zh.md#model-experience)统一说明输入规则，包括空用户消息、空工具结果，以及对其他不支持块的拒绝。
+[Messages 序列化器](../../../../packages/llm/llm-deepseek/src/serialize.ts)省略用户与工具结果输入中的 `reasoning` 和 `tool-call` 块。这两类块的处理与 Chat Completions、pi-ai 一致，不改变 Session 记录，也不把子级推理转换成父级用户文本。[提供方 README](../../../../packages/llm/llm-deepseek/README.zh.md#model-experience)统一说明输入规则，包括空用户消息、空工具结果，以及对其他不支持块的拒绝。
 
 这部分取代了结算决策对序列化器容错的拒绝，以及 [Messages 适配器决策](../feature/2026-09-07-deepseek-messages-adapter.zh.md)中的输入拒绝规则。通知构建仍为每种父级提供方投影子级的非空文本。子级的规范输出以及普通助手推理和工具调用仍可供现有消费者使用。省略依据是输入角色和块类型，而不是通知来源或创建日期，因此也适用于新提供的用户和工具结果内容。
 
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
new file mode 100644
index 0000000000..e2f0f66dda
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages 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-09-19-session-local-subagent-migration.md
+2026-09-19-session-local-subagent-migration.md: 26911ea6e2cb31126d13e4c8c6488ff3b45563e6
+2026-09-19-session-local-subagent-migration.zh.md: 673040a3dc73d3665e42013a4704ef2d5911b23d
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
new file mode 100644
index 0000000000..26911ea6e2
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.md
@@ -0,0 +1,33 @@
+# Agent Note: Complete parent catalogs without migrating child catalogs
+
+Status: implemented
+
+English | [中文](2026-09-19-session-local-subagent-migration.zh.md)
+
+## Problem
+
+Opening a historical parent requires discovery facts from its direct children. A child's corrupt body or invalid descriptor, or an unreadable header elsewhere in the root, could reject the parent's V4 preparation and hide otherwise readable history.
+
+## Decision
+
+Opening A discovers candidate B Sessions through headers, reads their own descriptors, and completes A's catalog. Historical child reads use the V0–V3 catalog; current child reads use native validation. These reads neither prepare B's own catalog nor publish B's successor. Opening B separately performs B's migration and catalog preparation. Frontend discovery retains its parent-catalog source. Unknown-mode rows remain browsable; `list_agents` continues to select only known continuable children.
+
+JSONL omits unreadable or unsupported headers from discovery. A child-body or descriptor-field failure produces a warning with the child path and retains the child's header identity. If the parent lacks a complete entry, migration appends `subagent/catalog`, projected as `mode: 'unknown'` alongside healthy siblings. Existing complete entries remain authoritative. Cancellation and source-consistency failures still stop the operation. Inspected child revisions, including failed decodes, are rechecked before reuse and publication so repairs cannot silently reuse stale evidence. Released predecessors remain byte-identical.
+
+This partially supersedes child-failure propagation in [released migrations](../architecture/2026-08-31-released-session-format-migrations.md) and [incomplete child evidence](2026-09-19-v3-incomplete-child-catalog-evidence.md). Their format conversion, descriptor cardinality, conflict validation, and immutable publication rules remain active.
+
+## Alternatives considered
+
+**Skip catalog completion and discover children in each consumer.** This introduces incomplete tool results and additional UI states despite the parent's readable child descriptors. The parent catalog already serves these consumers.
+
+**Drop unreadable children from the catalog.** Published parents would lose their navigation entries. Header identity is sufficient to retain membership without inventing a mode or label.
+
+**Recursively prepare child catalogs.** A only needs B's own descriptor. Preparing B's descendants adds unrelated work and failure dependencies.
+
+**Refuse A when one child cannot be read.** The child's discovery metadata does not justify withholding the parent's healthy history. Warnings retain the child location without inventing mode or label fields.
+
+## Consequences
+
+Initial parent preparation still scans headers and reads direct-child bodies one at a time. It does not claim to eliminate this I/O. Published V4 parents use their catalog without rescanning children. Unknown entries are not automatically rewritten after publication. Opening a child retries its log and determines browsing capabilities from its actual descriptor, or reports the child-local error. Catalog payload v0 retains its two known modes; v1 also supports `unknown`. Readers support both versions; healthy creation and complete historical facts retain v0, while unknown migration facts use v1. The V4 Session header is unchanged, and older readers reject the new payload version.
+
+Raw and compressed tests cover catalog completion, child-local errors, source changes and repairs, unchanged child generations, and deferred child-catalog preparation. The shipped Web migration snapshot checks the parent catalog with a corrupt sibling, then opens the child independently. Its additional historical child raises the corpus budget from ten to eleven roles; the guard rejects a twelfth role.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
new file mode 100644
index 0000000000..673040a3dc
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-session-local-subagent-migration.zh.md
@@ -0,0 +1,33 @@
+# Agent Note：补齐父目录而不迁移子目录
+
+Status: implemented
+
+[English](2026-09-19-session-local-subagent-migration.md) | 中文
+
+## 问题
+
+打开历史父会话需要直属子会话的发现事实。子日志正文损坏、descriptor 无效，或根目录其他位置的 header 不可读，都可能拒绝父会话的 V4 准备，使原本可读的历史无法打开。
+
+## 决策
+
+打开 A 时通过 header 发现候选 B Session，读取其自身 descriptor，并补齐 A 的 catalog。历史子日志使用 V0–V3 catalog 读取，当前子日志使用原生校验。这些读取不准备 B 自己的 catalog，也不发布 B 的后继。单独打开 B 时才执行 B 的迁移与目录准备。前端发现继续读取父 catalog。模式未知的条目仍可浏览；`list_agents` 继续只选择已知可继续的子会话。
+
+JSONL 在发现时跳过不可读或不支持的 header。子正文或 descriptor 字段失败会产生带子路径的警告，并保留该子的 header 身份。父目录没有完整条目时，迁移追加 `subagent/catalog`，与健康兄弟项一同投影为目录条目，其模式为 `mode: 'unknown'`。已有完整条目仍具有权威性。取消与来源一致性失败仍中止操作。复用和发布前会重新检查已检查子日志的修订，包括解码失败的日志，使修复不能静默复用旧证据。已发布前驱保持逐字节不变。
+
+本决策部分取代[已发布迁移](../architecture/2026-08-31-released-session-format-migrations.zh.md)和[不完整子证据](2026-09-19-v3-incomplete-child-catalog-evidence.zh.md)中的子错误传播规则。其格式转换、descriptor 数量、冲突校验和不可变发布规则仍有效。
+
+## 考虑过的替代方案
+
+**跳过目录补齐，让每个消费者发现子项。** 父会话明明有可读的子 descriptor，却会因此产生不完整工具结果和额外 UI 状态。父 catalog 已经服务这些消费者。
+
+**从目录删除不可读子会话。** 已发布父会话会丢失相应导航入口。Header 身份足以保留成员关系，无须编造模式或标签。
+
+**递归准备子目录。** A 只需要 B 自身的 descriptor。准备 B 的后代会增加无关工作与失败依赖。
+
+**一个子会话不可读就拒绝 A。** 子会话的发现元数据不足以成为阻断健康父历史的理由。警告保留子位置，不虚构 mode 或 label 字段。
+
+## 后果
+
+首次父准备仍扫描 header 并逐个读取直属子正文，不宣称消除此 I/O。已发布 V4 父会话使用其 catalog，不重新扫描子日志。发布后不自动重写未知条目。打开子会话会重试其日志，根据实际 descriptor 确定浏览能力，或报告该子会话的错误。Catalog 载荷 v0 保留两种已知模式，v1 另支持 `unknown`。读取器支持两版；正常创建及完整历史事实继续使用 v0，未知迁移事实使用 v1。V4 Session header 不变，旧读取器拒绝新载荷版本。
+
+原始和压缩测试覆盖目录补齐、子会话错误隔离、来源变化与修复、子代际不变和延后的子目录准备。随产品 Web 迁移快照在损坏兄弟存在时检查父目录，再独立打开子会话。额外的历史子角色使语料预算由十个增加到十一个；守卫拒绝第十二个角色。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
index 4ede5bd457..bf6d6c2fd0 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-19-v3-incomplete-child-catalog-evidence.md
-2026-09-19-v3-incomplete-child-catalog-evidence.md: 22ca91502425257ed30aa4962f5a38497b8a8a92
-2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: c11e6de2c27b9892a72c28f327b6d06834d84038
+2026-09-19-v3-incomplete-child-catalog-evidence.md: 400a84f376a7babc0a95492ca33a3bcd0761cd79
+2026-09-19-v3-incomplete-child-catalog-evidence.zh.md: 535951630bc600647724d50107e74e83ab626739
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
index 22ca915024..400a84f376 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.md
@@ -10,9 +10,9 @@ A valid V3 child log can have no own descriptor, an unsupported descriptor versi
 
 ## Decision
 
-The V3→V4 migration appends a missing parent catalog entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions contribute no new catalog fact. Existing parent entries and child events remain intact. This replaces only the missing-evidence refusal in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
+The V3→V4 migration appends a complete missing parent catalog entry only when exactly one supported own child descriptor supplies its discovery fields. Other descriptor counts and unsupported versions retain unknown-mode membership through [session-local catalog preparation](2026-09-19-session-local-subagent-migration.md). Existing parent entries and child events remain intact. This replaces only the missing-evidence refusal in the [adjacent migration decision](../architecture/2026-08-31-released-session-format-migrations.md).
 
-Known child creation times must still match existing parent entries. Mode/label and descriptor fields are checked only for exactly one supported own descriptor. Invalid fields in that descriptor, corrupt logs, unreadable membership, unsupported selected generations, and changed source revisions retain their existing failures.
+The JSONL failure-propagation rules below are partially superseded by [session-local catalog preparation](2026-09-19-session-local-subagent-migration.md); the converter still validates supplied facts and conflicts. Known child creation times must still match existing parent entries. Mode/label and descriptor fields are checked only for exactly one supported own descriptor. JSONL isolates invalid descriptor fields and corrupt child bodies while retaining known header identity; unreadable or unsupported headers are excluded from discovery. Changed source revisions still refuse publication.
 
 ## Alternatives considered
 
@@ -24,6 +24,6 @@ Known child creation times must still match existing parent entries. Mode/label
 
 ## Consequences
 
-A historical child without a usable descriptor remains readable by id but may be absent from its parent's direct-child catalog. Existing catalog entries remain visible. Once a V4 successor is published, opening it does not rescan historical children; automatic later catalog repair is outside this migration. Preparation still rechecks child revisions before publication, so newly available evidence cannot silently bypass source consistency checks.
+A historical child with a readable header but no usable descriptor retains unknown-mode membership in its parent's direct-child catalog. Existing catalog entries remain visible. Once a V4 successor is published, opening it does not rescan historical children; automatic later mode backfill is outside this migration. Preparation still rechecks child revisions before publication, so newly available evidence cannot silently bypass source consistency checks.
 
 Unit, JSONL read/write, and Preview packing tests cover unavailable evidence, unchanged source bytes, retained entries, identity conflicts, and evidence changes before publication.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
index c11e6de2c2..535951630b 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-19-v3-incomplete-child-catalog-evidence.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## Decision
 
-V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字段时，追加缺失的父目录项。其他 descriptor 数量及不受支持的版本不贡献新的目录事实。已有父目录项和子事件保持完整。这只替代[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)中的证据缺失拒绝规则。
+V3→V4 迁移仅在恰好一个受支持的自身子 descriptor 提供发现字段时，追加完整的缺失父目录项。其他 descriptor 数量和不支持的版本通过[逐会话目录准备](2026-09-19-session-local-subagent-migration.zh.md)保留模式未知的成员关系。已有父目录项和子事件保持不变。这取代[相邻迁移决策](../architecture/2026-08-31-released-session-format-migrations.zh.md)中对缺失证据的拒绝。
 
-已知子创建时间仍必须与已有父目录项一致。只有恰好一个受支持的自身 descriptor 时，才校验其字段并比较 mode／label。该 descriptor 字段无效、日志损坏、成员关系不可读、所选代际不受支持以及源修订变化仍保留原有失败行为。
+JSONL 错误传播规则由[逐会话目录准备](2026-09-19-session-local-subagent-migration.zh.md)部分取代；转换器仍校验已提供事实及冲突。已知子创建时间必须匹配已有父目录项。只有恰好一个受支持的自身 descriptor 时才检查 mode／label 和 descriptor 字段。JSONL 隔离无效 descriptor 字段和损坏子正文，并保留已知 header 身份；不可读或不支持的 header 不参与发现。来源修订变化仍拒绝发布。
 
 ## Alternatives considered
 
@@ -24,6 +24,6 @@ V3→V4 迁移只在恰好一个受支持的自身子 descriptor 提供发现字
 
 ## Consequences
 
-没有可用 descriptor 的历史子 Session 仍可按 id 读取，但可能不出现在其父级的直属子目录中。已有目录项仍可见。V4 后继发布后，打开它不会重新扫描历史子日志；后续自动修复目录不属于本迁移。准备过程仍会在发布前复查子修订，因此新出现的证据无法悄悄绕过源一致性检查。
+历史子会话具有可读 header 但没有可用 descriptor 时，在父直属子目录中保留未知模式成员关系。已有目录项仍可见。V4 后继发布后，打开它不重新扫描历史子日志；自动补齐后续模式不属于本迁移。准备过程仍在发布前重新检查子修订，因此新出现的证据不能静默绕过来源一致性检查。
 
 单元、JSONL 读写和 Preview 打包测试覆盖不可用证据、源字节不变、条目保留、身份冲突以及发布前的证据变化。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.i18n.yaml
new file mode 100644
index 0000000000..802ab740bd
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages 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-09-20-session-open-read-coordination.md
+2026-09-20-session-open-read-coordination.md: a4907df1d7dd38e4c532c38fb6ff10362a4a3898
+2026-09-20-session-open-read-coordination.zh.md: 759a45d8c52a62ea7a0b30ceed4003f8804a42c3
diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.md b/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.md
new file mode 100644
index 0000000000..a4907df1d7
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.md
@@ -0,0 +1,88 @@
+# Agent Note: Session opening cache identity and read ordering
+
+Status: implemented
+
+English | [中文](2026-09-20-session-open-read-coordination.zh.md)
+
+## Problem
+
+Opening a historical Session can make `session.follow`, composer catalog prewarming, and RPCs with Agent parameters access the same cold log concurrently. `skills/list` requests a complete observation itself; `commands/list`, `goals/get`, `fileReferences/list`, and `sessionReferenceResolver/candidates` can initiate resume through the Agent lookup during parameter resolution. Auxiliary requests that do not wait for the history opening snapshot compete with the main conversation for reading, parsing, and projection computation instead of reusing completed results.
+
+Reuse of completed observations has a separate problem: Cordis can return different proxy objects for accesses to the same service. Comparing the object references returned by `ctx.get('sessionPersistence')` can mistake one underlying service for different instances. Removing instance identity checks entirely is also unsafe because persistence revisions are comparable only within the corresponding service instance and Session identity.
+
+Subagent navigation combines two needs: displaying a conversation at a known address, and discovering its parent or descendant catalogs. Refreshing parent projections before navigating through an existing parent-child address adds prerequisite work and can reject an address that the Host could validate and open when the Client catalog cache is absent.
+
+## Decision
+
+### Identify the cache producer with a service-owned Symbol
+
+`SessionPersistence.identity` is a `Symbol('sessionPersistence')` created once per service instance. Proxy access preserves that value, while a replacement service instance receives a different value. The prepared observation cache looks up the Session id and compares both `persistence.identity` and `stat().revision`; the same instance and revision can reuse a completed preparation.
+
+This identity exists only within the process and does not enter Session headers, events, or persisted files. Existing cache capacity, leases, live precedence, and revision invalidation remain unchanged. This fix does not merge Promises for unfinished cold reads; stable identity prevents false invalidation after completion, not duplicate concurrent work across all callers.
+
+### Auxiliary RPCs wait for the current conversation's initial open to succeed
+
+The Client uses the existing `sessions.using()` at the actual RPC call site, rather than only delaying prewarm hooks. Menu candidates, explicit reference queries, and later catalog refreshes therefore use the same waiting entry point. Each operation first checks that its target already has a Client binding, so background prewarming does not reopen a closed Session.
+
+| Client consumer | RPC after waiting | Temporary reference source |
+| --- | --- | --- |
+| Skill catalog | `skills/list` | `skillCatalog` |
+| Command catalog | `commands/list` | `commandCatalog` |
+| Goal activation state | `goals/get` | `goalActivation` |
+| `@` file and Session candidates | `fileReferences/list`, `sessionReferenceResolver/candidates` | Shared `referenceCandidates` |
+
+`sessions.using()` waits for `reference.ready`, then for the operation's returned Promise, and finally releases its reference. `ready` means that the initial `Session.open()` attempt has settled, not that it succeeded; these consumers also require `openState === 'open'` and send no auxiliary RPC after a failed open. The Goal reader additionally checks that its captured binding has not been replaced and logs rejected reads without clearing existing display state.
+
+Skills retain the shared catalog request's own cancellation signal; `@` queries use the current candidate request's signal for the history wait and both RPCs. Unquoted `@` queries still fetch files and Sessions concurrently after waiting, while quoted paths still query files only. Commands and Goals gain no new cancellation protocol. These references retain Client data and follow streams, grant no new Host Agent authority, and do not prohibit normal Agent resume after the opening snapshot.
+
+### Conversations use follow; catalog branches retain explicit reads
+
+The main conversation's opening `follow` snapshot already carries that Session's complete projection baseline. Later changes to shared projection values notify subscribers, so switching Sessions or opening a menu does not require another read of the same baseline.
+
+- Main-view navigation does not separately refresh the selected Session's projections; restoring a saved subagent address does not prewarm its parent.
+- The Sidebar retains the target child directly from its complete parent-child address, without making a parent-catalog read a prerequisite for opening the conversation.
+- The header dropdown's `changeOpen` only changes presentation state and does not refresh `rootSessionId`. Child expansion and failed-read retries retain explicit refreshes under the UI callback name `refreshProjection`; the underlying `sessions.refreshProjections` API is not renamed.
+- Team navigation uses the existing Lead and roster member ids to open `{ parentSessionId, childSessionId, mode: 'continuable' }` directly. It neither refreshes the parent catalog nor requires the target to be present in the Client catalog; member-role and main-view ownership checks, plus the UI restrictions on provisioning and failed members, remain unchanged.
+
+A known address does not waive authorization checks. When opening child history, the Host still checks the target's own header parent and origin, plus the mode and descriptor ownership in its own `subagent` projection. Later continuation remains subject to the existing direct-parent authorization rules.
+
+## Implementation scope
+
+- Session formats, migrations, the Host observation's `all | none` policy, and the response fields of `session.projections` are unchanged.
+- There is no global cold-read singleflight, and Agent lookups are not universally replaced with read-only lookups.
+- `SessionManager.handleConnected()` still refreshes previously requested catalogs in bulk; this decision does not guarantee one cold read on reconnect.
+- Tool-side `listDescendants` can still read child Sessions on cache misses, and expanding a child node in the Client can still cold-read that node. Ordinary main-session opening is not equivalent to every descendant-enumeration scenario.
+- `@` Session candidates still enumerate headers and obtain names from live projections or projection caches, falling back to ids on misses. Existing ranking, the default limit of 50, and direct-subagent grouping remain unchanged; discovery does not recursively traverse `subagentCatalog`.
+
+## Alternatives considered
+
+**Remove persistence-instance comparison.** Rejected. A matching Session id and revision cannot establish that two persistence services provide the same data; replacing a service must still invalidate old preparations.
+
+**Unwrap Cordis proxies in callers or cache service objects per Context.** Rejected. The cache needs the producer's identity, not the identity of an object returned by a particular service access. A per-instance Symbol expresses that requirement without propagating proxy implementation details.
+
+**Add shared singleflight for every cold read.** Outside this implementation. It could merge more concurrent calls, but would require separate rules for independent waiter cancellation, leases, and task ownership during service replacement. It also would not replace the ordering requirement that auxiliary RPCs must not resume an Agent ahead of the opening snapshot.
+
+**Delay only warm hooks, or merely await the extra projection request.** Rejected. Explicit menu queries could still bypass warm hooks, and serializing a redundant projection request does not remove its work. The wait belongs at the actual auxiliary RPC entry point; reads already supplied by follow are removed.
+
+**Keep Team's parent-catalog presence check.** Rejected. The Team roster already provides member identity, and the existing Host history entry point can validate an explicit address. Requiring a Client catalog cache hit for navigation mistakes data that has not loaded for a child that does not exist.
+
+## Consequences
+
+An ordinary main Session completes its own history and projection read before auxiliary operations reuse the completed observation or attached state. The Client's direct-child list consumes the main Session's catalog without reading each child's log merely to display its row. Catalog and conversation opening are separate operations, so navigating to a known child no longer adds parent-projection prewarming.
+
+Auxiliary catalogs become available after the conversation's opening snapshot, and operations retain temporary Client references until they finish. This wait covers only the current Client generation's initial open, not readiness after every underlying follow replacement. Reconnect and exceptional retry scenarios still require their own verification.
+
+A missing header root catalog remains a specific coverage gap: if it belongs to an unopened parent and no other source supplies the catalog, opening the dropdown alone does not fetch it, and the current UI may continue to display a loading notice. This implementation adds neither a new parent-catalog loading entry point nor a shared unknown-state interaction protocol.
+
+## Verification and known gaps
+
+During local navigation to a long historical main Session, the user observed repeated `readColdSessionLog` calls converge to one using temporary timers and call stacks, and verified direct teammate navigation. This result describes that operation's cold-read helper invocation count, not every underlying file I/O, every reconnect scenario, or a single unit of end-to-end cost. Private Session content and identities from diagnosis are not test fixtures.
+
+Focused TypeScript builds and bundles were run for affected packages during development; the complete change has no gate, behavior-test, or assembled Web snapshot verification result. Existing tests have only partial callback renames and still contain old fixture names, root-menu-opening refresh expectations, Sidebar parent-refresh prerequisites, and Team rejection of missing catalogs. These are known verification gaps, not passing checks.
+
+## Relationship to existing records
+
+- [Session observations and projection-owned Client state](../architecture/2026-08-25-session-observations-and-projection-owned-client-state.md) retains ownership of read cuts and shared values. This record adds cache-producer identity and opening-snapshot consumption order; the older claim of sharing unfinished cold loads does not match the current reader and is not evidence that this change implements singleflight.
+- [Client Session references, reference sources, and UI state](../architecture/2026-09-15-client-session-references.md) retains ownership of `retain`, `ready`, `using`, and explicit-address semantics. This record limits temporary references to four classes of auxiliary reads as independent asynchronous operations, rather than adding references to every UI action.
+- [Web subagent catalogs consume shared projections](../simplification/2026-09-08-web-subagent-catalog-projections.md) retains ownership of the generic projection store, explicit catalog reads, and control updates. This implementation applies its rule that opening a conversation uses the follow baseline, without replacing the catalog mechanism.
+- [Web subagent catalogs and human continuation](../feature/2026-07-27-web-subagent-conversations.md) retains ownership of presentation and continuation authorization. This record changes only prerequisite navigation reads and root-menu refresh timing, not the child's own Host validation; the older description of interactive loading for missing root catalogs must be reconciled with the coverage gap recorded here.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.zh.md b/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.zh.md
new file mode 100644
index 0000000000..759a45d8c5
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-20-session-open-read-coordination.zh.md
@@ -0,0 +1,88 @@
+# Agent Note: 会话首帧读取的缓存身份与调用时序
+
+Status: implemented
+
+[English](2026-09-20-session-open-read-coordination.md) | 中文
+
+## 问题
+
+打开历史会话时，`session.follow`、输入框目录预热和依赖 Agent 参数的 RPC 可能同时访问同一份冷日志。`skills/list` 自行请求完整 observation；`commands/list`、`goals/get`、`fileReferences/list` 与 `sessionReferenceResolver/candidates` 则可以在参数解析阶段经 Agent lookup 发起恢复。辅助请求不等待历史首帧，会与主对话争用读取、解析和 projection 计算，而不是复用已经完成的结果。
+
+完成后的 observation 复用还有一个独立问题：Cordis 对同一服务的访问可以返回不同代理对象。以 `ctx.get('sessionPersistence')` 返回对象的引用相等性判断服务身份，会把同一底层服务误判成另一个实例。另一方面，彻底去掉实例身份检查也不安全，因为持久化 revision 只在对应服务实例和 Session 身份内可比较。
+
+子会话导航混合了两种需求：展示一个已知地址的对话，以及发现该会话的父目录或后代目录。已有父子地址的导航再次刷新 parent projection，既增加前置工作，也会在目录缓存缺席时拒绝一个本可由 Host 校验并打开的地址。
+
+## 决策
+
+### 用服务自身的 Symbol 标识缓存生产者
+
+`SessionPersistence.identity` 是每个服务实例创建一次的 `Symbol('sessionPersistence')`。代理访问保留这个值，服务被替换后新实例获得不同值。Prepared observation cache 按 Session id 查找，并同时比较 `persistence.identity` 与 `stat().revision`；相同实例、相同 revision 可以复用已完成的 preparation。
+
+该身份只存在于进程内，不进入 Session header、事件或持久化文件。现有缓存容量、lease、live 优先级和 revision 失效规则不变。这个修复不增加尚未完成的冷读取之间的 Promise 合并；稳定身份解决的是完成后的误失效，不是所有调用方的并发去重。
+
+### 辅助 RPC 等待当前对话的首次打开成功
+
+Client 在实际 RPC 发送位置使用既有 `sessions.using()`，不只延迟预热钩子。菜单候选、显式引用查询和后续目录刷新因而经过相同的等待入口。每个操作先确认目标已经有 Client binding，不因后台预热重新打开一个已经关闭的会话。
+
+| Client 消费方 | 等待后的 RPC | 临时引用来源 |
+| --- | --- | --- |
+| Skill 目录 | `skills/list` | `skillCatalog` |
+| Command 目录 | `commands/list` | `commandCatalog` |
+| Goal 激活状态 | `goals/get` | `goalActivation` |
+| `@` 文件与会话候选 | `fileReferences/list`、`sessionReferenceResolver/candidates` | 共用 `referenceCandidates` |
+
+`sessions.using()` 先等待 `reference.ready`，再等待操作返回的 Promise，最后释放自己的引用。`ready` 表示首次 `Session.open()` 尝试已结算，不保证成功；这些消费方还检查 `openState === 'open'`，失败时不发送辅助 RPC。Goal 读方还确认捕获的 binding 未被替代，并记录读取拒绝而不清除已有展示状态。
+
+Skill 保留共享目录请求自己的取消信号；`@` 查询将当前候选请求的信号用于历史等待和两个 RPC。未加引号的 `@` 在等待后仍并行查询文件和会话，加引号的路径仍只查询文件。Command 与 Goal 不新增取消协议。这里的引用持有 Client 数据和跟随流，不赋予 Host Agent 新权限，也不禁止首帧之后发生正常 Agent 恢复。
+
+### 对话使用 follow，目录分支保留显式读取
+
+主对话的 `follow` 首帧已经携带该 Session 的完整 projection baseline。后续共享 projection 值变化会通知订阅者，不需要在切换会话或打开菜单时再次读取相同 baseline。
+
+- 主视图切换不再额外刷新所选 Session 的 projection；恢复保存的子会话地址不再预先刷新其 parent。
+- 侧栏从完整父子地址直接保留目标子会话，不把父目录读取作为打开对话的前提。
+- Header 下拉菜单的 `changeOpen` 只改变展示状态，不刷新 `rootSessionId`。展开子节点和失败重试仍调用显式刷新，UI 回调命名为 `refreshProjection`；底层 `sessions.refreshProjections` API 不改名。
+- Team 点击使用已有 lead 与 roster 成员 id，直接打开 `{ parentSessionId, childSessionId, mode: 'continuable' }`。它不刷新 parent catalog，也不要求目标预先出现在 Client catalog 中；成员角色、主视图持有检查及 UI 对 provisioning、failed 成员的限制保持不变。
+
+已知地址不等于免除授权校验。Host 在打开子会话历史时，仍检查目标自身 header 的 parent、origin，以及自身 `subagent` projection 的 mode 和描述符归属。后续 continuation 仍受直接 parent 的既有授权规则约束。
+
+## 实现边界
+
+- 没有修改 Session 格式、迁移、Host observation 的 `all | none` 策略或 `session.projections` 返回字段。
+- 没有实现全局 cold-read singleflight，也没有把所有 Agent lookup 改成只读 lookup。
+- 没有删除 `SessionManager.handleConnected()` 对此前请求目录的批量刷新；本决策不保证重连只有一次冷读。
+- 工具侧 `listDescendants` 的缓存缺失仍可能读取子会话；前端展开一个子节点也仍可能冷读该节点。普通主会话首开不等于所有后代枚举场景。
+- `@` 会话候选仍枚举 header，并从 live projection 或 projection cache 取名称；缓存缺失回退到 id。原有排序、默认 50 条上限和直接 subagent 分组规则不变，没有改成沿 `subagentCatalog` 递归发现。
+
+## 考虑过的替代方案
+
+**取消 persistence 实例比较。** 不采用。同一个 Session id 和 revision 不能证明两个持久化服务提供同一份数据；服务替换仍必须使旧 preparation 失效。
+
+**在调用方解包 Cordis 代理或按 Context 缓存服务对象。** 不采用。缓存需要的是生产者身份，而不是某次服务访问返回对象的身份；每实例 Symbol 足够表达这个要求，不需要传播代理实现细节。
+
+**为所有冷读增加统一 singleflight。** 未纳入本次实现。它可以合并更多并发调用，但需要另外定义独立等待方取消、lease 和服务替换期间的任务归属；它也不能代替“辅助 RPC 不抢在首帧前恢复 Agent”的时序要求。
+
+**只延迟 warm，或只给额外 projection 请求补 await。** 不采用。显式菜单查询仍能绕过 warm；串行执行一个重复 projection 请求也没有删除重复工作。等待放在实际辅助 RPC 入口，已有 follow 能提供的读取直接取消。
+
+**保留 Team 的父目录存在性检查。** 不采用。Team roster 已给出成员身份，显式地址可以由现有 Host 历史入口验证；把 Client catalog 缓存命中作为导航前提，会把数据尚未加载误当成子会话不存在。
+
+## 后果
+
+普通主会话先完成自己的历史和 projection 读取，辅助操作再复用已完成的 observation 或已挂载状态。前端直接子代列表消费主会话的 catalog，不为显示每一行读取对应子会话正文。目录与对话的打开入口分开，导航到一个已知子会话不再附带 parent projection 预热。
+
+代价是辅助目录首次可用时间晚于对话首帧；操作还会持有临时 Client 引用直到结束。该等待只对应当前 Client generation 的首次打开，不是每次底层 follow 重建的就绪屏障。所有重连和异常重试场景仍需各自验证。
+
+Header 根目录缺失仍是明确的覆盖缺口：若它属于未打开的 parent，且没有其他来源提供 catalog，仅打开下拉菜单不会补读；现有 UI 仍可能显示加载提示。本次没有增加新的父目录加载入口，也没有实现统一的 unknown 交互协议。
+
+## 验证与已知缺口
+
+用户在本地长历史主会话切换流程中，通过临时 `readColdSessionLog` 计时和调用栈观察到重复调用收敛为一次，并验证了 teammate 直接导航。这个结果只描述该操作的冷读辅助函数调用次数，不代表所有底层文件 I/O、全部重连场景或端到端性能都只有一次成本。诊断期间的私有 Session 内容和身份不作为测试 fixture。
+
+开发期对相关包执行过定向 TypeScript 构建与打包；尚无这批完整变更的门禁、行为测试或组装 Web 快照验证结果。现有测试只完成部分回调改名，仍有旧 fixture 名称、打开根菜单即刷新、侧栏先刷新 parent，以及 Team 拒绝缺失 catalog 的预期需要调整。这些是已知验证缺口，不是已经通过的检查。
+
+## 与既有记录的关系
+
+- [Session observation 与 projection 所有的客户端状态](../architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md)继续拥有读取切面和共享值的职责划分。本记录补充缓存生产者身份与首帧消费顺序；旧记录中“包括未完成冷加载的共享”描述与当前 reader 实现不一致，不能作为本次 singleflight 已实现的依据。
+- [Client Session 引用、引用来源与 UI 状态](../architecture/2026-09-15-client-session-references.zh.md)继续拥有 `retain`、`ready`、`using` 与显式地址语义。本记录限定四类辅助读取作为独立异步操作持有临时引用，不把额外引用扩展到所有 UI 动作。
+- [Web 子代理目录消费共享 projection](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md)继续拥有通用 projection store、显式目录读取和 control 更新。本次实现落实“打开会话使用 follow baseline”的规则，不替换整个目录机制。
+- [Web subagent 目录与用户继续交互](../feature/2026-07-27-web-subagent-conversations.zh.md)继续拥有展示和 continuation 授权。本记录只调整导航前置读取及根菜单刷新时机，不取消子会话自身的 Host 校验；旧记录对缺失根目录交互加载的描述需与这里的覆盖缺口一起核对。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.i18n.yaml
new file mode 100644
index 0000000000..259202f1a0
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages 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-09-20-windows-embedded-mandatory-update.md
+2026-09-20-windows-embedded-mandatory-update.md: 99577a4d85adc3fe13ea0ae262d5aa1af6128237
+2026-09-20-windows-embedded-mandatory-update.zh.md: abe4a9577d8e11d8de2089dc53ef07433e10bbdb
diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.md b/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.md
new file mode 100644
index 0000000000..99577a4d85
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.md
@@ -0,0 +1,25 @@
+# Agent Note: Windows embedded mandatory update
+
+Status: implemented
+
+English | [中文](2026-09-20-windows-embedded-mandatory-update.zh.md)
+
+## Problem
+
+A second native Windows window does not resize atomically with its parent, producing a detached overlay during maximization (#4566). Native modality also disables the parent controls that users need to exit.
+
+## Decision
+
+Windows uses one native window and a shell-origin frame below the caption. This partially supersedes the presentation decision in the [mandatory-update client](../feature/2026-09-11-desktop-mandatory-update-client.md); that note retains policy and installation ownership. macOS retains its native overlay.
+
+The isolated application preload transfers a private MessageChannel endpoint directly to the shell frame. Only messages on the paired private port authorize update IPC; synthetic window events cannot invoke actions. The main process validates the current application main frame and rebinds state delivery when the main window changes. Destroyed windows receive neither state nor focus operations.
+
+## Alternatives considered
+
+**Synchronize a second native window.** Parent movement, maximization and restoration expose independently scheduled geometry updates; removing the second window removes that synchronization problem.
+
+**Treat source and origin on window events as authentication.** Product scripts can construct those event fields. A private port keeps action authority outside the shared product document.
+
+## Consequences
+
+Caption menus and Web controls remain reachable. The DOM overlay blocks ordinary background input but cannot prevent product scripts from hiding or imitating presentation; it is not a tamper-proof security surface. Main-process policy and installation authorization remain separate from that display. Regression coverage requires forged-event rejection, real channel delivery, caption keyboard operation, and destroyed/replacement-window lifecycle cases.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.zh.md b/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.zh.md
new file mode 100644
index 0000000000..abe4a9577d
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-20-windows-embedded-mandatory-update.zh.md
@@ -0,0 +1,25 @@
+# Agent Note: Windows 内嵌强更弹窗
+
+Status: implemented
+
+[English](2026-09-20-windows-embedded-mandatory-update.md) | 中文
+
+## 问题
+
+Windows 的第二个原生窗口无法与父窗口原子地缩放，最大化时会出现脱离的蒙层（#4566）。原生模态还会禁用用户退出应用所需的父窗口控件。
+
+## 决策
+
+Windows 使用一个原生窗口和顶栏下方的壳源站 frame。此决策部分取代[强更客户端](../feature/2026-09-11-desktop-mandatory-update-client.zh.md)的展示决策；该说明继续负责策略与安装归属。macOS 保留原生蒙层。
+
+隔离的应用预加载将私有 MessageChannel 端点直接传给壳 frame。只有配对私有端口上的消息才能授权更新 IPC；合成的 window 事件不能调用操作。主进程校验当前应用主 frame，并在主窗口变化时重新绑定状态投递。已销毁窗口不再接收状态或焦点操作。
+
+## 考虑过的替代方案
+
+**同步第二个原生窗口。** 父窗口移动、最大化与还原会暴露独立调度的几何更新；去掉第二个窗口即可消除这一同步问题。
+
+**把 window 事件的 source 和 origin 当作身份认证。** 产品脚本可以构造这些事件字段。私有端口将操作权限保留在共享产品文档之外。
+
+## 后果
+
+顶栏菜单和 Web 控件仍可触达。DOM 蒙层阻止普通背景输入，但不能阻止产品脚本隐藏或仿造展示；它不是防篡改的安全界面。主进程策略和安装授权与展示相互独立。回归覆盖要求包括拒绝伪造事件、真实通道投递、顶栏键盘操作，以及窗口销毁和替换的生命周期用例。
diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml
index 8cf2e53343..ed1df3a4fe 100644
--- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-web-background-job-display.md
-2026-08-08-web-background-job-display.md: 4b8396c1c0504ddf8494a03c22b9af094c4eed17
-2026-08-08-web-background-job-display.zh.md: 03a43b87c47d0ef4d9c08d32facd91ceb76dda38
+2026-08-08-web-background-job-display.md: 049785e9cd5dea2d92d9fc5a14dfeddac9b64469
+2026-08-08-web-background-job-display.zh.md: 1dd7ee9215fa034a0a7abbe75bd5f6eb6907e9ee
diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md
index 4b8396c1c0..049785e9cd 100644
--- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md
+++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md
@@ -2,6 +2,10 @@
 
 Status: implemented
 
+Superseded: the roster this note put on the session control stream (`jobsBySession`, `onJobsChanged`) now streams from the job controller's `job.list` into `ctx.jobs` — see [the jobs seam consolidation](../architecture/2026-09-03-jobs-seam-consolidation.md). The display decisions below (one roster, sections, durations, no kill control) still hold.
+
+Update: the output phase this note deferred now ships as the per-job observation record on `ctx.jobs` — see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md).
+
 English | [中文](2026-08-08-web-background-job-display.zh.md)
 
 ## Problem
@@ -64,7 +68,7 @@ The listener is owner-granular rather than task-granular. The only consumer push
 
 `onJobDone` is not a subset of this. It delivers the terminal record with the exact owner `Agent` under first-wins semantics that `dsh-tool-jobs` couples to `reported`; `onJobsChanged` is pure observation with no delivery meaning and marks nothing reported. Listener throws are contained and never awaited, matching `onJobDone`, and each registration is an effect on the calling fiber.
 
-Service disposal deliberately announces nothing. Every `onJobsChanged` registration is an effect on the registry's own fiber, so the listeners are already gone by the time teardown clears the store; an observer learns the registry left through its own disposal, not through a final empty set.
+Service disposal announces each removal: after the registry has cancelled and awaited its jobs, it drops every record and emits one `removed` event per job, so a subscriber on a longer-lived fiber sees the roster empty out instead of keeping a stale set (a subscriber on the registry's own fiber is already gone by then).
 
 ### The Session Controller carrier
 
@@ -87,7 +91,7 @@ Two replacement points keep it honest. Each control-stream generation clears the
 
 ### The header action
 
-[`@deepseek-ai/dsh-client-ui-jobs`](../../../../packages/client/ui-jobs/README.md) registers one entry in `conversation.session.header.actions`, ordered after the subagent catalog. Its own README owns the presentation contract; the decisions worth recording here are that the control does not render at all until the session has a task, that the live badge is omitted at zero so a history-only session keeps a quiet entry point, and that settled rows stay visible because a failed task's `detail` is the only place its failure is legible.
+`@deepseek-ai/dsh-client-ui-jobs` registers one entry in `conversation.session.header.actions`, ordered between the preset label and the subagent catalog (`order: 20` against the catalog's 30). Its own README owns the presentation contract; the decisions worth recording here are that the control does not render at all until the session has a task, that the live badge is omitted at zero so a history-only session keeps a quiet entry point, and that settled rows stay visible because a failed task's `detail` is the only place its failure is legible.
 
 A running one-shot background subagent therefore appears both there and in the subagent catalog. The two answer different questions — the catalog navigates into the child's transcript, this list is the only handle a cancellation can ever attach to — and suppressing `kind: 'subagent'` here would leave the cancellation phase with no entry point for exactly those tasks.
 
@@ -117,7 +121,7 @@ A running one-shot background subagent therefore appears both there and in the s
 
 The [web e2e scenario](../../../../apps/web/tests/background-job-list.e2e.ts) is the end-to-end proof and runs keyless: a real `run_in_background` bash call registers with `ctx.jobs`, the header count and row appear with no user interaction, and killing the task through the registry flips the open list to its producer detail. It asserts the whole delivery path rather than any single layer.
 
-Below it, [`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) pins the change feed at all four commit points, its containment of a throwing observer, and its removal on both explicit disposal and fiber teardown; [`control-jobs`](../../../../packages/api/session-controller/tests/control-jobs.host.spec.ts) pins the complete baseline, three change pushes, dropped internal fields, unowned fan-out, no-resume guarantee, registry-absent composition, and the prohibition on consuming model output; and the client suites pin baseline replacement, the last-wins fold, the absent-key representation, removal cleanup, and the component's ordering, duration, and dismissal behavior.
+Below it, [`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) pins the change feed at all four commit points, its containment of a throwing observer, and its removal on both explicit disposal and fiber teardown; [`rows`](../../../../packages/api/job-controller/tests/rows.host.spec.ts) pins the roster stream that replaced the control-stream fan-out: the complete visible set on open, a refresh after each lifecycle commit and none per append, owner removal, and a clean abort; and the client suites pin baseline replacement, the last-wins fold, the absent-key representation, removal cleanup, and the component's ordering, duration, and dismissal behavior.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md
index 03a43b87c4..1dd7ee9215 100644
--- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md
@@ -2,6 +2,10 @@
 
 Status: implemented
 
+Superseded：本文放在会话控制流上的名册（`jobsBySession`、`onJobsChanged`）现在从 job 控制器的 `job.list` 流入 `ctx.jobs`——见 [jobs seam 收敛](../architecture/2026-09-03-jobs-seam-consolidation.zh.md)。下文的展示决策（单一名册、分组、时长、没有 kill 控件）仍然成立。
+
+Update：本文推迟的输出阶段现已作为 `ctx.jobs` 上的逐 job 观测 record 交付——见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。
+
 [English](2026-08-08-web-background-job-display.md) | 中文
 
 ## 问题
@@ -64,7 +68,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void
 
 `onJobDone` 不是它的子集。后者按 first-wins 语义投递终态记录和确切的 owner `Agent`，`dsh-tool-jobs` 把这套语义与 `reported` 绑在一起；`onJobsChanged` 是纯观察，不含任何投递含义，也不把任何东西标为已上报。监听器抛错被包住且从不 await，与 `onJobDone` 一致，每次注册都是调用方 fiber 上的 effect。
 
-服务销毁刻意什么都不通告。每个 `onJobsChanged` 注册都是注册表自身 fiber 上的 effect，等到 teardown 清空 store 时监听器早已消失；观察者通过自己的销毁而不是一份最终空集来得知注册表离开了。
+服务销毁逐条通告移除：注册表取消并等完自己的 job 之后，丢弃每条记录并对每个 job 发出一个 `removed` 事件，因此注册在更长命 fiber 上的订阅者看到名册逐条清空而不是留着陈旧集合（注册在注册表自身 fiber 上的订阅者此时早已消失）。
 
 ### Session Controller 载体
 
@@ -87,7 +91,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void
 
 ### header 入口
 
-[`@deepseek-ai/dsh-client-ui-jobs`](../../../../packages/client/ui-jobs/README.zh.md) 在 `conversation.session.header.actions` 注册一个条目，排在 subagent 目录之后。呈现契约归它自己的 README；值得记在这里的决策是：会话没有任务时控件根本不渲染；活跃角标为零时省略，让只剩历史的会话保留一个安静的入口；终态行保持可见，因为失败任务的 `detail` 是其失败唯一可读之处。
+`@deepseek-ai/dsh-client-ui-jobs` 在 `conversation.session.header.actions` 注册一个条目，排在 preset 标签与 subagent 目录之间（`order: 20`，目录为 30）。呈现契约归它自己的 README；值得记在这里的决策是：会话没有任务时控件根本不渲染；活跃角标为零时省略，让只剩历史的会话保留一个安静的入口；终态行保持可见，因为失败任务的 `detail` 是其失败唯一可读之处。
 
 因此一个运行中的一次性后台 subagent 会同时出现在那里和 subagent 目录里。两者回答不同的问题——目录负责进入子会话的 transcript，而这个列表是中断能力唯一可能附着的句柄——在这里屏蔽 `kind: 'subagent'` 会让中断那一期恰好对这批任务没有入口。
 
@@ -117,7 +121,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void
 
 [web e2e 场景](../../../../apps/web/tests/background-job-list.e2e.ts)是端到端的证据，且无需密钥：一次真实的 `run_in_background` bash 调用注册进 `ctx.jobs`，header 的计数与行在没有任何用户操作的情况下出现，通过注册表杀掉该任务后打开着的列表翻到生产者给出的 detail。它断言的是整条投递链路，而不是其中某一层。
 
-在它之下，[`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) 钉住变更订阅的全部四个提交点、对抛错观察者的包容，以及显式销毁与 fiber 拆除两条路径上的注销；[`control-jobs`](../../../../packages/api/session-controller/tests/control-jobs.host.spec.ts) 钉住完整 baseline、三次变更推送、被丢弃的内部字段、无主扇出、不 resume 的保证、没有注册表的组合，以及不得消费模型输出；客户端各套件钉住 baseline 替换、last-wins 折叠、缺失键表示、移除清理，以及组件的排序、时长与关闭行为。
+在它之下，[`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) 钉住变更订阅的全部四个提交点、对抛错观察者的包容，以及显式销毁与 fiber 拆除两条路径上的注销；[`rows`](../../../../packages/api/job-controller/tests/rows.host.spec.ts) 钉住取代控制流扇出的名册流：打开时的完整可见集、每次生命周期提交后刷新一次且追加不刷新、拥有者移除，以及干净的中止；客户端各套件钉住 baseline 替换、last-wins 折叠、缺失键表示、移除清理，以及组件的排序、时长与关闭行为。
 
 ## 影响
 
diff --git a/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.i18n.yaml b/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.i18n.yaml
index 086b337437..0c51d4b42e 100644
--- a/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal 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-11-background-job-completion-wakes-an-idle-owner.md
-2026-08-11-background-job-completion-wakes-an-idle-owner.md: cb724d95f85900b3c55fdebfdc335e9da6439d29
-2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md: 1107fa2c8fdd9d3e4e45031c54fb87f5aac8ea18
+2026-08-11-background-job-completion-wakes-an-idle-owner.md: b8a10a2150ead02036cb97506a25c3a51202adcf
+2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md: adc0770cd00adeb3b13c95dcc386464493dcd943
diff --git a/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.md b/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.md
index cb724d95f8..b8a10a2150 100644
--- a/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.md
+++ b/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+Update: the `reported` bit and `onJobDone` this note relies on left the registry with the [jobs seam consolidation](../architecture/2026-09-03-jobs-seam-consolidation.md): `dsh-tool-jobs` now keeps the delivery ledger (a wait or an accepted `job_kill` claims the task) and skips teardown settlements by their `settled` cause, so the wake-or-inject decision below stands while the mechanism it names is the tool's ledger, not a registry flag.
+
 English | [中文](2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md)
 
 ## Problem
diff --git a/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md b/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md
index 1107fa2c8f..adc0770cd0 100644
--- a/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-11-background-job-completion-wakes-an-idle-owner.zh.md
@@ -2,6 +2,8 @@
 
 Status: implemented
 
+Update：本文依赖的 `reported` 位与 `onJobDone` 已随 [jobs seam 收敛](../architecture/2026-09-03-jobs-seam-consolidation.zh.md)离开注册表：`dsh-tool-jobs` 现在持有投递台账（等待或被接受的 `job_kill` 认领任务），并按 `settled` 事件的 cause 跳过 teardown 结算，因此下文唤醒或注入的决策仍然成立，只是它提到的机制是工具的台账而非注册表标志。
+
 [English](2026-08-11-background-job-completion-wakes-an-idle-owner.md) | 中文
 
 ## 问题
diff --git a/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.i18n.yaml b/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.i18n.yaml
index df9b8b6339..4f9e640fe2 100644
--- a/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.md
-2026-08-20-unified-image-request-pipeline.md: 7431a474b55a9dae82b1c9cd36b770b31fe39602
-2026-08-20-unified-image-request-pipeline.zh.md: 247a57b8017f513c552204d951ef6931f7f9d045
+2026-08-20-unified-image-request-pipeline.md: b79eeb7d908d664362851c28bda64dab163aac89
+2026-08-20-unified-image-request-pipeline.zh.md: 444234715256c48167b0b45dbd8843a9c80079f7
diff --git a/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.md b/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.md
index 7431a474b5..b79eeb7d90 100644
--- a/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.md
+++ b/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.md
@@ -34,7 +34,7 @@ Every retained request image is preceded by its display name or complete attachm
 
 ### DeepSeek Files lifecycle
 
-The direct `deepseek-official` adapter normally uploads every retained request version through its selected protocol’s Files API and sends file-id references. [Messages](2026-09-07-deepseek-messages-adapter.md) and Chat Completions share the lifecycle while retaining their own endpoint and wire formats. A [bounded inline fallback](../../archived/bug-fix/2026-08-21-deepseek-files-inline-fallback.md) sends the same deterministic request versions when file resolution fails. The default catalog advertises `deepseek-v4-flash-vision-exp` as image-capable. Uploaded ids are indexed by Files endpoint and API-key scope plus `variantId`. Uploads request seven days by default. Chat records the returned `expires_at`; Messages metadata omits expiry, so its local reuse deadline uses the original upload time plus the configured lifetime without promising remote deletion. A mapping with no more than one hour of reuse remaining is replaced without a preceding retrieve call. The index never stores the API key.
+The direct `deepseek-official` adapter uploads every retained request version through the [Messages Files API](2026-09-07-deepseek-messages-adapter.md) and sends file-id references. A [bounded inline fallback](../../archived/bug-fix/2026-08-21-deepseek-files-inline-fallback.md) sends the same deterministic request versions when file resolution fails. Uploaded ids are indexed by Files endpoint and API-key scope plus `variantId`. Uploads request seven days by default. Messages metadata omits expiry, so local reuse uses the original upload time plus the configured lifetime without promising remote deletion. A mapping with no more than one hour of reuse remaining is replaced without a preceding retrieve call. The index never stores the API key.
 
 An upload is indexed only after the response returns a valid native file object with a matching byte count and the client establishes the protocol’s reuse deadline. A missing or inconsistent response leaves no local mapping, so a later request uploads again. Concurrent upload resolution for one scoped `variantId` shares one provider operation; one waiter cannot cancel another, and the upload stops when every waiter has cancelled. A malformed upload index is an empty cache and is replaced on the next successful upload; filesystem I/O failures remain errors. If the model endpoint reports expired, deleted, missing, or invalid ids and names one or more ids used by the request, only those mappings are removed. A stale-file response without a specific id removes every mapping used by that model request. The affected request bytes are uploaded again and the model request is retried once. A second stale rejection clears the mappings identified by its response and returns the error without a third model request. One upload quota error first lists the configured number of oldest harness-owned `dsh-` files, then deletes that collected set and retries once; deleting after pagination keeps provider cursors valid. Public file operations expose list, retrieve, delete, one-variant release, and namespace-wide release. Every Files request carries the shared Harness `User-Agent`. The client enforces a 128MiB upload limit, a 32MiB request-image limit, 10,000-file and 25GiB quotas, and one-hour to 30-day expiry range.
 
diff --git a/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.zh.md b/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.zh.md
index 247a57b801..4442347152 100644
--- a/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-20-unified-image-request-pipeline.zh.md
@@ -34,7 +34,7 @@ Status: implemented
 
 ### DeepSeek Files 生命周期
 
-直接 `deepseek-official` 适配器通常通过所选协议的 Files API 上传每张保留的请求版本，并发送 file-id 引用。[Messages](2026-09-07-deepseek-messages-adapter.zh.md) 与 Chat Completions 共享生命周期，各自保留端点和协议格式。文件解析失败时，[有界内联回退](../../archived/bug-fix/2026-08-21-deepseek-files-inline-fallback.md)会发送相同的确定性请求版本。默认 catalog 把 `deepseek-v4-flash-vision-exp` 公布为支持图片。上传 ID 按 Files 端点和 API key 作用域以及 `variantId` 写入索引。上传默认请求 7 天有效期。Chat 记录返回的 `expires_at`；Messages 元数据不含过期时间，因此本地复用期限使用原始上传时间加配置的生存期，但不保证远端文件删除。本地映射剩余复用时间不超过一小时时会直接替换，不会先查询远端文件。索引绝不存储 API key。
+直连 `deepseek-official` 适配器通过 [Messages Files API](2026-09-07-deepseek-messages-adapter.zh.md) 上传每个保留的请求版本，并发送 file-id 引用。文件解析失败时，[有界内联回退](../../archived/bug-fix/2026-08-21-deepseek-files-inline-fallback.md)发送相同的确定性请求版本。上传 id 按 Files 端点、API-key 作用域及 `variantId` 建立索引。上传默认请求七天有效期。Messages 元数据不含过期时间，因此本地复用使用原始上传时间加配置的有效期，不承诺远端删除。剩余复用时间不超过一小时的映射会直接替换，不先调用 retrieve。索引从不存储 API 密钥。
 
 只有上传响应返回有效的原生文件对象、字节数匹配，且客户端确定了该协议的复用期限时，上传结果才会写入索引。缺失或不一致的响应不会留下本地映射，后续请求会重新上传。同一作用域和 `variantId` 的并发解析共享一次提供方上传；单个等待方无法取消其他等待方，全部等待方取消时才会停止上传。格式损坏的上传索引按空缓存处理，并在下一次成功上传时替换；文件系统 I/O 失败仍是错误。如果模型端点报告 ID 已过期、删除、缺失或无效，并指出本次请求使用的一个或多个 ID，适配器只删除这些映射。如果响应只说明文件状态失效而没有指出具体 ID，适配器会删除该次模型请求使用的全部映射。受影响的请求字节会重新上传，模型请求只重试一次。第二次仍报告文件失效时，适配器会按响应清理映射并返回错误，不会发起第三次模型请求。一次上传配额错误会先列出配置数量的最旧 `dsh-` 文件，再删除收集到的文件并重试一次；分页完成后才删除，避免游标失效。公开文件操作提供列表、查询、删除、单个变体释放和整个作用域释放。每个 Files 请求都携带 Harness 的共享 `User-Agent`。客户端执行 Files 单次上传 128MiB、请求单图 32MiB、10,000 个文件、25GiB，以及一小时到 30 天有效期限制。
 
diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml
new file mode 100644
index 0000000000..548e9f5b36
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md
+2026-08-24-activity-observation-seam.md: 21fe08fd21ad95eec7a83f6f29b9b94514358bb9
+2026-08-24-activity-observation-seam.zh.md: ffb6766b3e5d226d324ea2894a6e3f758cf1932a
diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md
new file mode 100644
index 0000000000..21fe08fd21
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md
@@ -0,0 +1,53 @@
+# Agent Note: The activity observation seam (`ctx.activities`) and live output streaming to the Web client
+
+Status: implemented
+
+Superseded: the standalone seam described here was folded into `ctx.jobs` as the per-job observation record — see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md); the durable-vs-live analysis below still holds.
+
+English | [中文](2026-08-24-activity-observation-seam.zh.md)
+
+## Problem
+
+Every incremental reader in the shell, terminal, and jobs layers is single-consumer and consuming: `ShellProcess.readOutput()`, `TerminalSendOperation.readOutput()`, and `JobRegistry.read()` all destroy the delta they return, because the owning model is the intended reader. The [web background-job display](2026-08-08-web-background-job-display.md) shipped the roster on those terms — its carrier is test-pinned to never call `ctx.jobs.read()`, since a browser read would silently steal bytes the model's `job_output` would never see — and explicitly deferred the output phase to "a separate non-consuming observation API". So a human watching the Web client saw that a background build was running but never a line of its output, and the `workflow/log` / `workflow/phase` events scripts are told to narrate with had no consumer at all.
+
+The substrate below bash already had the right shape: `SubprocessOutputReader.readFrom(fromByte)` is offset-based and explicitly non-consuming, and `bash-local` narrows it to a single cursor pair at the shell seam.
+
+## Decision
+
+A new capability seam, `packages/activity/`, is the non-consuming observation plane. An **activity** is one observable unit of long-running work: an append-only bounded output stream plus live status. The seam is pure observation — it starts nothing, cancels nothing, and is invisible to the model. Model-visible facts stay exactly where they were (tool results, `ctx.jobs` cursors), so the "model-visible ⟺ logged" invariant is untouched and a composition without the seam loses only live observation.
+
+- **`@deepseek-ai/dsh-activity` (Service Definition)** — abstract `ActivityRegistry` on `ctx.activities`: `open(spec) → ActivityHandle { append, updateDetail, end }`, fenced `get`/`list`, non-consuming `read(id, from)` over absolute UTF-8 byte offsets, owner-relative `onActivitiesChanged` (roster) and `onOutput` (advancement signal, id only). `ActivityCorrelation { callId?, jobId? }` links a row to its tool call and job. `pumpActivityOutput` is the shared pull-substrate pump.
+- **`@deepseek-ai/dsh-activity-local` (Service Provider)** — in-memory chunk ring per activity. Offsets stay absolute across eviction (`outputEarliest` marks the oldest retained byte; a read below it is `lossy`, never an error); a single over-cap chunk keeps its UTF-8-safe tail with `gapBefore`. Config `retainBytes` (256 KiB) live, trimmed to `settledRetainBytes` (16 KiB) at settlement. Records outlive producer fibers; owner disposal force-ends and removes; `end` is first-wins and post-end writes log-and-drop so a producer's trailing flush cannot break its own teardown.
+- **`@deepseek-ai/dsh-api-activity-controller`** — the wire, in the workspace-controller shape: `activity.control` streams one roster baseline then whole-bucket replacement frames per owner session (the jobs-frame self-healing semantics), and `activity.observe({ activityId, from? })` streams one `opened` anchor, coalesced `output` frames (`flushMs` window, `maxFrameBytes` soft budget), then the terminal `status` on the same stream before closing — so settlement can never race a still-open output channel. Reconnects resume from the last frame's `next`. The client half installs `ctx.activityFeed` (roster mirror plus reference-counted observation streams with a bounded render tail).
+- **`@deepseek-ai/dsh-client-ui-activity`** — the session-header task list ([unified with the job rows](../../archived/feature/2026-08-25-unified-task-list.md)); expanding a row opens its observation stream into a `TerminalBlock` panel, collapsing closes it, so output only flows while someone is watching. `TerminalBlock` itself gained live rendering: a running block with supplied `output` shows the text under the running state instead of the historical prompt-only frame.
+
+Producers mirror best-effort behind `ctx.get('activities')`, never a declared inject, and every observation failure is logged and swallowed — the seam is strictly optional and can never break the work it observes:
+
+- `ShellProcess` gained optional `observed` — the substrate's non-consuming offset readers re-exposed (bash-local and pwsh-local return `handle.collected`; the e2b subprocess provider satisfies the same contract). `dsh-tool-bash` / `dsh-tool-pwsh` open a correlated activity after `jobs.start()` commits and pump `observed` at `activityPollMs` (default 150 ms).
+- `dsh-tool-workflow` mirrors each recorded top-level run as a push-mode `workflow` activity, giving the previously unconsumed `workflow/phase` / `workflow/log` events their consumer.
+
+### Why not durable session events, the control stream, or the jobs seam
+
+Peer products converge on the same split (Codex marks every exec-output delta "Transient, non-durable" in its rollout policy; Claude Code persists a file path, never deltas; Kimi's envelope has a first-class `volatile: true`; OpenCode's V2 corrected V1's per-chunk durable part updates to "stream fragments are live-only"). In this repository the durable route is also concretely bad: chunk-run packing is hardcoded to the three `assistant/chunk` shapes so a new output event gets zero compression, each event is one uncoalesced WebSocket frame, and reconnect gap-repair re-reads the window — and the job-display note already rejected it ("spill exists precisely so oversized tool output stays out of the log"). The session control stream's whole-snapshot frames are self-healing for rosters but quadratic for streams. Extending the jobs seam would cover only jobs — not workflow narration, not a future foreground stream — and would re-litigate the settled "producers own their buffers" decision; the activity plane instead recovers the substrate's existing offsets.
+
+### Two cursor regimes, kept separate
+
+The model keeps its consuming cursors (`job_output` semantics unchanged, zero prompt or tool changes anywhere in this work); observers get absolute offsets any number of readers can hold. This mirrors the strongest peer pattern (Codex: destructive drain for the model, seq-cursor reads for infrastructure) and is what makes the wire path provably non-stealing.
+
+## Alternatives considered
+
+**Durable `activity/output` session events with a conversation node.** Replay for free, but the log-growth math above, plus retention pressure on every follower, killed it; the transcript's durable story remains the producers' tool results.
+
+**Extending `SessionControlFrame` with output.** One fewer stream, but whole-snapshot semantics resend the accumulated buffer per chunk — O(n²) on exactly the data that grows.
+
+**A signal frame plus RPC pull.** The subagent-catalog shape; rejected for the split-authority apparatus the job-display note documents, and it fails worst at settlement (running row, dead stream).
+
+**Observation inside the jobs seam.** One integration point, but only for jobs; foreground runs, terminals, and workflow narration would each need another mechanism, and the registry would grow a second buffer beside the producers' own.
+
+## Testing
+
+Unit suites pin the registry (offsets, eviction, UTF-8-safe tail trims, lossy reads, first-wins settlement, owner cleanup, scoped delivery, listener containment, HMR disposal, Loader composition with row config), the pump (cadence, per-source cursors, lossy `gapBefore`, settlement drain, timer hygiene), the controller (baseline/bucket frames, anchor/output/status ordering, resume, frame splitting, fenced owned reads, abort), the client model and reference-counted streams, and both producer taps (real subprocess output for bash including the never-steals-the-model's-cursor assertion; scripted readers for pwsh; event-driven mirror for workflow, including the throwing-registry containment the optionality promise requires). The keyless web e2e drives a real `run_in_background` bash through the full composition and pins ARIA goldens for the streaming panel while the command still runs and for the settled panel after a registry kill.
+
+## Consequences
+
+The Web client now shows live output for background bash/pwsh and workflow narration with zero model-facing change, and any plugin can join with three calls (`open`/`append`/`end`) against an optional service. Bought at the cost of one more seam family and a per-producer tap; the initial two-header-list duplication was folded into [one task list](../../archived/feature/2026-08-25-unified-task-list.md). Deferred, recorded on the package READMEs: foreground streaming (needs a shell-seam run/observe variant), terminal `pty-send` observation (needs a non-consuming face on terminal buffers), a human kill control (blocked on the jobs `reported` contract), SDK/ACP consumers, and durable replay after restart.
diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md
new file mode 100644
index 0000000000..ffb6766b3e
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md
@@ -0,0 +1,53 @@
+# Agent Note：activity 观察 seam（`ctx.activities`）与 Web 客户端实时输出流
+
+状态：implemented
+
+Superseded：本文描述的独立 seam 已折入 `ctx.jobs`，成为逐 job 的观测 record——见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)；下文关于持久化与实时通道的分析仍然成立。
+
+[English](2026-08-24-activity-observation-seam.md) | 中文
+
+## 问题
+
+shell、terminal 与 jobs 各层的增量读取器全都是单读者且消费型的：`ShellProcess.readOutput()`、`TerminalSendOperation.readOutput()` 与 `JobRegistry.read()` 返回即销毁增量，因为预期读者就是持有模型。[Web 后台任务显示](2026-08-08-web-background-job-display.zh.md)在这一前提下交付了 roster——其载体被测试钉死绝不调用 `ctx.jobs.read()`，否则浏览器读取会无声偷走模型 `job_output` 永远看不到的字节——并把输出阶段明确推迟给"一个独立的非消费观察 API"。于是人在 Web 客户端只能看到后台构建"在跑"，看不到一行输出；脚本被告知用来叙述进度的 `workflow/log` / `workflow/phase` 事件更是全无消费者。
+
+bash 之下的底座其实早有正确形态：`SubprocessOutputReader.readFrom(fromByte)` 是按 offset、明确非消费的，`bash-local` 在 shell seam 把它窄化成了单游标对。
+
+## 决策
+
+新建能力 seam `packages/activity/`，作为非消费观察面。**activity** 是一个可观察的长时工作单元：一条 append-only 的有界输出流加实时状态。该 seam 是纯观察——不启动、不取消任何工作，对模型不可见。模型可见事实原地不动（工具结果、`ctx.jobs` 游标），"模型可见 ⟺ 已记录"不变量不受影响；不装该 seam 的组合只失去实时观察。
+
+- **`@deepseek-ai/dsh-activity`（Service Definition）**——`ctx.activities` 上的抽象 `ActivityRegistry`：`open(spec) → ActivityHandle { append, updateDetail, end }`、有栅栏的 `get`/`list`、按绝对 UTF-8 字节 offset 的非消费 `read(id, from)`、owner 相对投递的 `onActivitiesChanged`（roster）与 `onOutput`（推进信号，只带 id）。`ActivityCorrelation { callId?, jobId? }` 把行关联到工具调用与 job。`pumpActivityOutput` 是 pull 型底座的共享泵。
+- **`@deepseek-ai/dsh-activity-local`（Service Provider）**——每个 activity 一个内存 chunk 环。offset 跨淘汰稳定（`outputEarliest` 指明最老保留字节；低于它的读取是 `lossy` 而非错误）；单个超上限 chunk 保留 UTF-8 安全尾部并带 `gapBefore`。配置 `retainBytes`（256 KiB）存活，结算时裁到 `settledRetainBytes`（16 KiB）。记录存续期长于生产者 fiber；owner 销毁强制终结并移除；`end` first-wins，end 后写入记日志后丢弃，生产者的收尾 flush 砸不掉自己的 teardown。
+- **`@deepseek-ai/dsh-api-activity-controller`**——wire 层，取 workspace-controller 的形态：`activity.control` 流出一份 roster baseline 加按 owner 会话的整桶替换帧（jobs 帧的自愈语义）；`activity.observe({ activityId, from? })` 流出一帧 `opened` 锚点、合并的 `output` 帧（`flushMs` 窗口、`maxFrameBytes` 软预算）、再在同一条流上发终态 `status` 后关闭——结算永远不会与仍开着的输出通道竞态。重连以上一帧的 `next` 续传。客户端半区安装 `ctx.activityFeed`（roster 镜像 + 按引用计数的观察流与有界渲染尾巴）。
+- **`@deepseek-ai/dsh-client-ui-activity`**——会话头部任务列表（[与 job 行合并](../../archived/feature/2026-08-25-unified-task-list.md)）；展开某行即把其观察流打开进 `TerminalBlock` 面板，收起即关——只有有人在看时输出才流动。`TerminalBlock` 本身获得实时渲染能力：running 且提供了 `output` 的块在 running 状态下显示文本，而非历史上的仅提示行画面。
+
+生产者一律经 `ctx.get('activities')` 尽力镜像，绝不声明 inject，一切观察失败只记日志并吞掉——该 seam 严格可选，永远不能破坏它所观察的工作：
+
+- `ShellProcess` 新增可选 `observed`——底座的非消费 offset 读取器复出（bash-local 与 pwsh-local 返回 `handle.collected`；e2b subprocess provider 满足同一契约）。`dsh-tool-bash` / `dsh-tool-pwsh` 在 `jobs.start()` 提交后打开带关联的 activity，并以 `activityPollMs`（默认 150 ms）泵取 `observed`。
+- `dsh-tool-workflow` 把每个被记录的顶层运行镜像为 push 形态的 `workflow` activity，让此前无人消费的 `workflow/phase` / `workflow/log` 事件有了消费者。
+
+### 为何不用持久会话事件、control 流或 jobs seam
+
+同行产品收敛于同一切分（Codex 在 rollout policy 里把所有 exec 输出 delta 标为 "Transient, non-durable"；Claude Code 持久化文件路径而非 delta；Kimi 的信封有一等的 `volatile: true`；OpenCode V2 把 V1 逐 chunk 持久化 part 更新纠正为 "stream fragments are live-only"）。在本仓库持久路线还有具体的坏处：chunk-run 打包只认三种 `assistant/chunk` 形态，新输出事件零压缩；每事件一条未合并的 WebSocket 帧；重连缺口修复要重读窗口——且 job 显示 note 已否决过它（"spill 的存在就是为了让超大工具输出不进日志"）。session control 流的整值帧对 roster 自愈、对流则是二次方开销。扩 jobs seam 只覆盖 jobs——workflow 叙述与未来的前台流都覆盖不到——还要重翻已定案的"生产者拥有自己的缓冲"；activity 面转而复用底座既有的 offset。
+
+### 两套游标制，各归其位
+
+模型保留消费游标（`job_output` 语义不变，本次工作零 prompt/工具改动）；观察者拿任意多读者可共持的绝对 offset。这正是最强的同行范式（Codex：模型用破坏性 drain，基础设施用 seq 游标读取），也是 wire 路径可证明"不偷字节"的原因。
+
+## 曾考虑的替代方案
+
+**持久 `activity/output` 会话事件 + conversation node。** 回放免费，但上述日志膨胀账加上对每个 follower 的保留压力否掉了它；transcript 侧的持久故事仍是生产者的工具结果。
+
+**给 `SessionControlFrame` 加输出。** 少一条流，但整值语义会按 chunk 重发累计缓冲——恰好在会增长的数据上 O(n²)。
+
+**信号帧 + RPC 拉取。** subagent catalog 的形态；因 job 显示 note 记录的权威割裂机制而否决，且它在结算时刻失效得最难看（行还在跑、流已死）。
+
+**在 jobs seam 内做观察。** 一个集成点，但只对 jobs；前台运行、terminal 与 workflow 叙述各需另一套机制，注册表还得在生产者自己的缓冲旁再养一份。
+
+## 测试
+
+单测钉住注册表（offset、淘汰、UTF-8 安全裁尾、lossy 读取、first-wins 结算、owner 清理、scope 投递、监听容错、HMR 可逆、带行配置的 Loader 组合）、泵（节奏、每源游标、lossy `gapBefore`、结算排干、定时器卫生）、controller（baseline/桶帧、锚点/输出/状态排序、续传、帧切分、有栅栏的有主读取、abort）、客户端模型与引用计数流，以及两类生产者接入（bash 用真实子进程输出，含"绝不偷模型游标"断言；pwsh 用脚本化读取器；workflow 用事件驱动镜像，含可选性承诺要求的 throwing-registry 容错）。无钥 web e2e 经完整组合驱动真实 `run_in_background` bash，钉住命令仍在运行时流式面板与注册表 kill 后已结算面板的 ARIA golden。
+
+## 后果
+
+Web 客户端在零模型面改动下获得后台 bash/pwsh 实时输出与 workflow 叙述；任何插件对着一个可选服务用三个调用（`open`/`append`/`end`）即可接入。代价是多一个 seam 家族与每生产者一个接入点；最初的双头部列表重复已折并为[单一任务列表](../../archived/feature/2026-08-25-unified-task-list.md)。暂缓项记录在各包 README：前台流式（需 shell seam 的 run/observe 变体）、terminal `pty-send` 观察（需给 terminal 缓冲加非消费面）、人工 kill 控件（被 jobs `reported` 契约阻塞）、SDK/ACP 消费端、重启后的持久回放。
diff --git a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml
index 5e501e5f46..137c5eba63 100644
--- a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
-2026-09-04-right-sidebar-docking-infrastructure.md: 3ebfe4b3a95ab5820682098be2a4c43f172d1a02
-2026-09-04-right-sidebar-docking-infrastructure.zh.md: dc6516324a368dd86b3e01afb4051a4b20697363
+2026-09-04-right-sidebar-docking-infrastructure.md: c5bfb75730f2037826723bc7fd0aa2bb01005d1e
+2026-09-04-right-sidebar-docking-infrastructure.zh.md: 4959032b53f84654205a1973aee781acb356f999
diff --git a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
index 3ebfe4b3a9..c5bfb75730 100644
--- a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
+++ b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
@@ -16,6 +16,8 @@ The right column is a per-session docking surface — split panes, tabs, floatin
 
 ### Package topology
 
+The [stable Sidebar mounting decision](../architecture/2026-09-20-sidebar-retained-tab-layout.md) owns one retained tab-content tree for docking, floating and Session switches. The engine, layout state and gesture ownership in this note remain applicable.
+
 | Package | Kind | Owns |
 |---|---|---|
 | `packages/client/ui-dockkit` | static-linked library, zero DSH dependencies | the layout engine and the React components that render and drive it; consumers compile its sources, and it keeps exactly one stylesheet because a consumer de-duplicates injected sheets by file name |
@@ -33,7 +35,7 @@ Components render a snapshot and report settled intents, one per gesture: a drag
 
 [Responsive Sidebar and tab information](../architecture/2026-09-07-sidebar-responsive-tab-info.md) supersedes this note's no-concession layout, overlay presentation and product pane limit. `ui-layout` still owns three-column geometry and pixel width preferences; the Sidebar occupant reports presentation through `ctx.layout.openRightbar(track, fullscreen)` and `closeRightbar()`, without the frame injecting the Sidebar package. Exact width rules belong to [ui-layout](../../../../packages/client/ui-layout/README.md).
 
-The right Sidebar uses one mounted content tree in normal and fullscreen modes; hiding preserves tab state, and fullscreen covers the viewport while retaining underlying column reservation. Floats still use viewport coordinates through a portal and remain open when the Sidebar closes. The product limits docking to two horizontal panes and a 20–80% divider; the generic engine keeps its own defaults.
+The right Sidebar uses one mounted content tree in normal and fullscreen modes; hiding preserves retained tab state, and fullscreen covers the viewport while retaining underlying column reservation. `DockLayout` renders stable Grid cells with fixed-position floating frames in the same tree; foreground floats remain open when the Sidebar closes. The product limits docking to two horizontal panes and a 20–80% divider; the generic engine keeps its own defaults.
 
 ### State
 
@@ -86,7 +88,7 @@ The surface renders tabs whose bodies it does not know: each tab carries a `kind
 - The Detail panel and its duplicate card presentation are gone (a net removal of roughly 1,400 lines); cards are read in place, and `inspect` opens the trajectory view.
 - The frame has no centre floor: a viewport narrower than the two edge columns squeezes the conversation toward zero instead of closing a column.
 - The kit is compiled by its consumers, so a kit change requires a shell rebuild and a page reload; there is no HMR for it.
-- The panel, the float host, and the portalled tab menu use hard-coded z-index values; the client still has no z-index token layer.
+- Docked cells, floating cells and the portalled tab menu use fixed stacking levels; floating cells use CSS paint order within their level. The client still has no global z-index token layer.
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md
index dc6516324a..4959032b53 100644
--- a/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md
@@ -16,6 +16,8 @@ Agent 产出的文件是最尖锐的案例。产出文件 chip 或 `read` 行的
 
 ### 包拓扑
 
+[Sidebar 稳定挂载决策](../architecture/2026-09-20-sidebar-retained-tab-layout.zh.md)负责停靠、浮动与会话切换共用的一棵保活 Tab 内容树。本文的引擎、布局状态与手势所有权仍然适用。
+
 | 包 | 形态 | 所有物 |
 |---|---|---|
 | `packages/client/ui-dockkit` | 静态链接库，零 DSH 依赖 | 布局引擎与渲染/驱动它的 React 组件；消费方编译其源码，且它只保留一张样式表，因为消费方按文件名去重注入的样式表 |
@@ -33,7 +35,7 @@ Agent 产出的文件是最尖锐的案例。产出文件 chip 或 `read` 行的
 
 [响应式 Sidebar 与标签信息](../architecture/2026-09-07-sidebar-responsive-tab-info.zh.md)取代本记录中的无让步布局、覆盖模式与产品窗格上限。`ui-layout` 仍拥有三列几何与像素宽度偏好，Sidebar 占位项通过 `ctx.layout.openRightbar(track, fullscreen)` 和 `closeRightbar()` 报告呈现方式，框架不注入 Sidebar 包。具体宽度规则见 [ui-layout](../../../../packages/client/ui-layout/README.zh.md)。
 
-右栏在普通与全屏模式下使用同一棵已挂载内容树；隐藏保留标签状态，全屏覆盖视口并保留底层列占位。浮窗仍经 portal 使用视口坐标，不随右栏关闭。产品限制为两个水平窗格与 20–80% 分割比例，通用引擎保留自己的默认值。
+右栏在普通与全屏模式下使用同一棵已挂载内容树；隐藏保留已保活的标签状态，全屏覆盖视口并保留底层列占位。`DockLayout` 在同一棵树中渲染稳定 Grid cell 与 fixed 定位的浮动 frame，前台浮窗不随右栏关闭。产品限制为两个水平窗格与 20–80% 分割比例，通用引擎保留自己的默认值。
 
 ### 状态
 
@@ -86,7 +88,7 @@ Agent 产出的文件是最尖锐的案例。产出文件 chip 或 `read` 行的
 - Detail 面板及其重复的卡片展示消失（净删约 1,400 行）；卡片就地阅读，`inspect` 打开 trajectory 视图。
 - 框架没有中列下限：视口窄于两侧列之和时会话区被挤向零，而不是关掉某一列。
 - 库由消费方编译，改库须重建壳并刷新页面；它没有 HMR。
-- 面板、浮层宿主与 portal 出去的 tab 菜单使用硬编码 z-index；客户端仍没有 z-index token 层。
+- 停靠 cell、浮动 cell 和 portal 菜单使用固定层级，浮动 cell 在所属层内通过 CSS 绘制顺序排序；客户端仍没有全局 z-index token 层。
 
 ## Testing
 
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
index 702e3bf1fc..0d328978e1 100644
--- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
-2026-09-05-sidebar-text-preview-and-file-tree.md: 8ddb1a336307011d8f6ce9bbe927f00642a83e60
-2026-09-05-sidebar-text-preview-and-file-tree.zh.md: 294a2b456008837882f7f82e55e8e9e435254554
+2026-09-05-sidebar-text-preview-and-file-tree.md: e978043545b7f172f2b67053fe44b5936ea9b529
+2026-09-05-sidebar-text-preview-and-file-tree.zh.md: 088d4a58c973843ac5085cfaa1ca9980387bcc8f
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
index 8ddb1a3363..e978043545 100644
--- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
@@ -34,7 +34,7 @@ The [Document Preview decision](../architecture/2026-09-08-document-preview-oper
 
 A tab uses `dsh-resource://file/session/<sessionId>/<path>`, where the path may be relative or absolute ([Workspace Files](../architecture/2026-09-05-workspace-files-service.md) owns the grammar and the `fileAddressFor` / `parseFileAddress` helpers). `hostFileOf` accepts only this Session scope and takes both Session and path from the address; a Session-less `absolute` address is not claimed. A malformed claimed address throws as a programming error.
 
-Metadata and content come from different places. `useResource<'file'>(tab.contentId)`, the global standard hook from the [client resource model](../architecture/2026-09-05-client-resource-model.md), yields `WorkspaceFileStat`; the body compares that observed version with the version of its loaded content. The Preview face reads text through `remote.workspaceFiles.read` and complete bytes through `readAll`. A later text page from a newer version restarts from page one, and a retired request cannot write after reload or tab disposal. The [Document Preview decision](../architecture/2026-09-08-document-preview-operations.md) owns renderer-specific loading.
+Metadata and content come from different places. `useResource<'file'>(tab.contentId)`, the global standard hook from the [client resource model](../architecture/2026-09-05-client-resource-model.md), yields `WorkspaceFileStat`; the body compares that observed version with the version of its loaded content. The Preview face reads text through `remote.workspaceFiles.read` and complete bytes through `readBytes` with `{}` options. A later text page from a newer version restarts from page one, and a retired request cannot write after reload or tab disposal. The [Document Preview decision](../architecture/2026-09-08-document-preview-operations.md) owns renderer-specific loading.
 
 The store is Slot-standard: one exclusive instance per session, bucketed by tab id, holding `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`. Bucketing by tab, not by file, is deliberate — two tabs of one file scroll independently. The face (`loadPage`, `reloadPages`) is the only asynchronous half: it marks a read in flight, awaits the Remote result, and writes a page or a failure through the store's actions, writing nothing if the owner's `signal` has fired. The `signal` also ends the bucket: the face arms one abort listener per tab at the tab's first read, and that listener forgets the bucket — not the body, which mounts and unmounts as tabs switch; a tab that never read has no bucket and no listener, and a record can end while its body is unmounted behind another tab. Scroll offset, wrap, and the navigation already answered therefore outlive the body: a tab comes back where the reader left it rather than re-reading or jumping again. Nothing persists across a page reload.
 
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
index 294a2b4560..088d4a58c9 100644
--- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
@@ -34,7 +34,7 @@ Sidebar 随包交付三个 tab 类型：**引导页**（`ui-sidebar-right`）、
 
 tab 使用 `dsh-resource://file/session/<sessionId>/<path>`，其中路径可以是相对路径或绝对路径（[Workspace Files](../architecture/2026-09-05-workspace-files-service.zh.md)负责该语法与 `fileAddressFor` / `parseFileAddress` 辅助函数）。`hostFileOf` 只接受这种 Session scope，并从地址取得 Session 与路径；不认领不带 Session 的 `absolute` 地址。被认领的地址若格式错误，则作为程序错误抛出。
 
-元数据与内容来自不同的地方。`useResource<'file'>(tab.contentId)`——[client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)提供的全局标准 hook——产生 `WorkspaceFileStat`；正文把其观察版本与已加载内容版本比较。Preview face 通过 `remote.workspaceFiles.read` 读取文本，通过 `readAll` 读取完整字节。后续文本页若来自更新版本，则从第一页重新开始；被重载或 tab 销毁淘汰的请求不能再写入。[Document Preview 决议](../architecture/2026-09-08-document-preview-operations.zh.md)负责各渲染器的加载方式。
+元数据与内容来自不同的地方。`useResource<'file'>(tab.contentId)`——[client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)提供的全局标准 hook——产生 `WorkspaceFileStat`；正文把其观察版本与已加载内容版本比较。Preview face 通过 `remote.workspaceFiles.read` 读取文本，通过带 `{}` 选项的 `readBytes` 读取完整字节。后续文本页若来自更新版本，则从第一页重新开始；被重载或 tab 销毁淘汰的请求不能再写入。[Document Preview 决议](../architecture/2026-09-08-document-preview-operations.zh.md)负责各渲染器的加载方式。
 
 store 是 Slot 标准件：每会话一个独占实例，按 tab id 分桶，持有 `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`。按 tab 而非按文件分桶是有意的——同一文件的两个 tab 各自滚动。face（`loadPage`、`reloadPages`）是唯一的异步半边：它标记读取进行中，等待 Remote 结果，再经 store 的 action 写入一页或一次失败；若 owner 的 `signal` 已触发则什么也不写。`signal` 同时终结这个桶：face 在 tab 首次读取时挂一个 abort 监听器，由它忘掉桶——不是体，体随 tab 切换反复挂载卸载；从未读过的 tab 没有桶也没有监听器，而 tab 记录可能在其体被另一 tab 挡住而卸载时结束。因此滚动位置、换行与已答过的导航都活得比体久：tab 回来时停在读者离开的地方，而不是重读或再跳一次。刷新页面后什么都不保留。
 
diff --git a/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.i18n.yaml
index d726d38ae1..13e41b76da 100644
--- a/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.md
-2026-09-07-deepseek-messages-adapter.md: b79c2526461843a9534d6a997029281a584e0bed
-2026-09-07-deepseek-messages-adapter.zh.md: 49a967828e22803296ae3d4c8eef943b9ec8e3c5
+2026-09-07-deepseek-messages-adapter.md: 29f712e57c8048ddb0c05b5f56fd4793c52bec5f
+2026-09-07-deepseek-messages-adapter.zh.md: 3cf60fc2101fb835423b74a6532e5edcc5bee911
diff --git a/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.md b/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.md
index b79c252646..29f712e57c 100644
--- a/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.md
+++ b/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.md
@@ -6,29 +6,29 @@ English | [中文](2026-09-07-deepseek-messages-adapter.zh.md)
 
 ## Problem
 
-Deployments expose DeepSeek through Anthropic Messages gateways as well as chat-completions. Messages represents thinking, signatures, tool calls, tool results, and cumulative usage differently. Translating only the endpoint or flattening assistant history loses information needed by subsequent tool turns.
+Messages represents thinking, signatures, tool calls, tool results, and cumulative usage as native protocol fields. Translating only the endpoint or flattening assistant history loses information needed by subsequent tool turns.
 
 ## Decision
 
-The [DeepSeek adapter](../../../../packages/llm/llm-deepseek/README.md) serves multiple protocols under one `deepseek-official` route and `llm-deepseek` settings namespace. `common/` shares configuration, the model catalog, capability resolution, and Files lifecycle; `protocols/chat-completions/` and `protocols/messages/` own serialization, stream conversion, and transport. Cordis YAML selects the implementation through `protocol`, defaulting to `messages`; shipped first-party compositions inherit that default. The existing `PreparedAdapterCall` freezes protocol, endpoint, credential reference, and model capabilities; retries retain that generation while subsequent calls read new configuration.
+The [DeepSeek adapter](../../../../packages/llm/llm-deepseek/README.md) serves Messages under one `deepseek-official` route and `llm-deepseek` settings namespace. The [single-protocol decision](../simplification/2026-09-19-deepseek-messages-only.md) owns the transport scope. `PreparedAdapterCall` freezes the endpoint, credential reference, and model capabilities; retries retain that generation while subsequent calls read new configuration.
 
-The adapter follows the [DeepSeek compatibility documentation](https://api-docs.deepseek.com/zh-cn/guides/anthropic_api) and [Anthropic streaming protocol](https://platform.claude.com/docs/en/build-with-claude/streaming). The pi-ai Anthropic implementation informed the handling of adjacent user messages, cumulative usage, fragmented tool arguments, and optional thinking signatures. DeepSeek effort uses `output_config.effort`; an Anthropic thinking token budget does not control DeepSeek effort. Both protocols forward explicit `temperature` values; DeepSeek accepts that parameter with thinking enabled and ignores its value, so callers retain their existing thinking configuration.
+The adapter follows the [DeepSeek compatibility documentation](https://api-docs.deepseek.com/zh-cn/guides/anthropic_api) and [Anthropic streaming protocol](https://platform.claude.com/docs/en/build-with-claude/streaming). The pi-ai Anthropic implementation informed the handling of adjacent user messages, cumulative usage, fragmented tool arguments, and optional thinking signatures. DeepSeek effort uses `output_config.effort`; an Anthropic thinking token budget does not control DeepSeek effort. The adapter forwards explicit `temperature` values; DeepSeek accepts that parameter with thinking enabled and ignores its value, so callers retain their existing thinking configuration.
 
 Assistant blocks remain the durable model-visible content. A versioned `ReplayEnvelope` stores only the protocol format, model identity, aligned block kinds, and signatures absent from those blocks. Same-model Messages continuation restores signatures verbatim, including empty signatures; foreign history carries no invented signature. Unusable metadata follows the existing [replay degradation rule](../architecture/2026-07-14-provider-routed-llm-adapters.md): the request omits signatures with a warning while preserving durable content; historical tool arguments use the [empty-input fallback](../bug-fix/2026-09-16-messages-historical-tool-input.md) when Messages cannot represent them. This keeps provider replay data opaque to the loop while preserving it through Session persistence and block pruning.
 
-Both protocols prefer Files references for deterministic request images and share upload caching, refresh, quota recovery, and attachment offload. The Files client retains the selected protocol and configured endpoint: Messages follows the [exact `/v1` root rule](../bug-fix/2026-09-15-messages-v1-base-url.md), while Chat Completions appends `/files`. Messages Files requests carry the required beta header. Cached ids remain scoped by the resolved Files root and credential, so equivalent `/v1` and unversioned Messages roots share uploads. Messages metadata omits expiry, so local reuse is bounded from the original upload time without asserting remote deletion. A Files-resolution failure rebuilds the complete request under the independent inline-image budget; caller cancellation stops it. The shared image policy preserves the 128 MiB retained-image budget, 20 MiB inline base64 budget, and oldest-prefix offload in both requests and token measurement.
+The adapter prefers Files references for deterministic request images, with upload caching, refresh, quota recovery, and attachment offload. The Files client follows the [exact `/v1` root rule](../bug-fix/2026-09-15-messages-v1-base-url.md) and sends the required beta header. Cached ids remain scoped by the resolved Files root and credential, so equivalent `/v1` and unversioned roots share uploads. Metadata omits expiry, so local reuse is bounded from the original upload time without asserting remote deletion. A Files-resolution failure rebuilds the complete request under the independent inline-image budget; caller cancellation stops it. The image policy preserves the 128 MiB retained-image budget, 20 MiB inline base64 budget, and oldest-prefix offload in both requests and token measurement.
 
 JSON syntax failure after a successful HTTP response does not establish a transport failure. Files decoding uses the existing `INVALID_RESPONSE` code with operation context instead of relabeling the failure as `TRANSPORT` or adding a retry; the [provider README](../../../../packages/llm/llm-deepseek/README.md) owns the error fields.
 
 System updates use the existing [route capability](2026-09-02-in-history-system-prompt-replacement.md) when explicitly declared for an endpoint/model. Messages retains the initial top-level system and emits later snapshots as native system turns after the corresponding user/tool-result turn, preserving previously sent prefixes. This placement differs from the loop's system-before-user admission; serialization changes neither the durable log nor conversation-turn order. Undeclared routes consolidate the latest snapshot at the top level, including direct compaction calls. Capability inference from protocol or model names is insufficient because support and update semantics depend on the deployed endpoint.
 
-Web always displays DeepSeek without a protocol selector. Both protocols share `baseURL` and `apiKeyEnv`, with no nested per-protocol configuration map. Without an endpoint override, resolution uses the selected protocol’s official default; Messages uses `https://api.deepseek.com/anthropic`. Switching retains existing endpoint overrides, whose compatibility belongs to the deployment. Messages follows the exact `/v1` root rule rather than inferring compatibility from other version-like suffixes. One model catalog includes `deepseek-flash` text/image and in-history system capabilities and retains the V4 entries. Explicit `chat-completions` remains supported with its own official default and appends `/chat/completions` without adding a version segment.
+Web displays DeepSeek with an endpoint and credential reference. Without an endpoint override, resolution uses `https://api.deepseek.com/anthropic`. Overrides must support Messages. The adapter follows the exact `/v1` root rule rather than inferring compatibility from other version-like suffixes. One model catalog advertises the capabilities declared by its entries.
 
-Both transports use the existing [request-extension registry](../architecture/2026-08-21-deepseek-llm-api-request-extensions.md) after native serialization and accept captured contributions after HTTP 2xx, before reading the stream. Session-log delivery and plugin inventory retain their owners and remain outside model input. The auxiliary [web-search provider](../../../../packages/web/web-search-deepseek/README.md) retains its separate endpoint, request, and settings.
+The adapter uses the existing [request-extension registry](../architecture/2026-08-21-deepseek-llm-api-request-extensions.md) after native serialization and accepts captured contributions after HTTP 2xx, before reading the stream. Session-log delivery and plugin inventory retain their owners and remain outside model input. The auxiliary [web-search provider](../../../../packages/web/web-search-deepseek/README.md) retains its separate endpoint, request, and settings.
 
 ## Alternatives considered
 
-**Separate plugins per protocol.** This duplicates credentials, catalogs, settings cards, and provider identities, and forces users to reselect models when the wire protocol changes. Protocol folders inside one plugin retain implementation isolation; Responses can add an implementation without changing the user configuration structure.
+**Separate Messages provider identity.** This duplicates credentials, catalogs, and settings cards, and forces users to reselect models when adopting Messages. The `deepseek-official` identity keeps those user choices stable.
 
 **Delegate the new route to pi-ai or the Anthropic SDK.** Both provide maintained protocol implementations, but the requested direct adapter needs DeepSeek-specific configuration, attachment policy, credential resolution, and retry ownership. A small stream translator with a maintained SSE parser keeps these responsibilities explicit; the library-backed adapter remains available independently.
 
@@ -38,6 +38,6 @@ Both transports use the existing [request-extension registry](../architecture/20
 
 ## Consequences
 
-The package owns wire validation, stop-reason mapping, cancellation, and error classification, so protocol changes require adapter maintenance. User and tool-result input follows the [saved-input compatibility rule](../bug-fix/2026-09-18-messages-input-history-compatibility.md); other unsupported content and incomplete streams fail explicitly. The existing retry consumer owns retries; the existing assembler drops incomplete tool calls at the output limit. Messages defaults cover the shared base, Web, and standalone first-party compositions. Protocol changes preserve the provider id and saved model selections, but an explicit endpoint override must support the selected protocol.
+The package owns wire validation, stop-reason mapping, cancellation, and error classification, so protocol changes require adapter maintenance. User and tool-result input follows the [saved-input compatibility rule](../bug-fix/2026-09-18-messages-input-history-compatibility.md); other unsupported content and incomplete streams fail explicitly. The existing retry consumer owns retries; the existing assembler drops incomplete tool calls at the output limit. Messages serves the shared base, Web, and standalone first-party compositions. Explicit endpoint overrides must support Messages.
 
 Verification covers wire fixtures, real Loader composition, per-file unit coverage, [recorded Session replay](../../../../snapshots/session/deepseek-messages-replay/snapshot.yml) with [unknown replay versions](../../../../snapshots/session/deepseek-messages-degraded-replay/snapshot.yml), a Web Messages Session replay, and credential-gated text, thinking, tool continuation, image, and cancellation requests. Live gateway checks establish compatibility with the configured gateway; they do not establish compatibility with every Anthropic proxy.
diff --git a/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.zh.md b/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.zh.md
index 49a967828e..3cf60fc210 100644
--- a/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-deepseek-messages-adapter.zh.md
@@ -6,29 +6,29 @@ Status: implemented
 
 ## 问题
 
-部署可以通过 Anthropic Messages 网关或 chat-completions 调用 DeepSeek。Messages 对思考、签名、工具调用、工具结果和累计用量的表示不同。仅替换端点或压平助手历史会丢失后续工具轮次需要的信息。
+Messages 以原生协议字段表示思考、签名、工具调用、工具结果和累计用量。仅替换端点或压平助手历史会丢失后续工具轮次需要的信息。
 
 ## 决策
 
-[DeepSeek 适配器](../../../../packages/llm/llm-deepseek/README.zh.md)通过一个 `deepseek-official` 路由和 `llm-deepseek` 设置命名空间支持多个协议。`common/` 共享配置、模型目录、能力解析和 Files 生命周期；`protocols/chat-completions/` 与 `protocols/messages/` 分别负责协议序列化、流转换和传输。`protocol` 配置在 Cordis YAML 中选择实现，默认 `messages`；随产品交付的官方组合继承该默认值。已有 `PreparedAdapterCall` 冻结协议、端点、凭据引用与模型能力，重试保持同一代配置，后续调用读取新配置。
+[DeepSeek 适配器](../../../../packages/llm/llm-deepseek/README.zh.md)在唯一的 `deepseek-official` 路由和 `llm-deepseek` 设置命名空间下提供 Messages。[单协议决策](../simplification/2026-09-19-deepseek-messages-only.zh.md)拥有传输范围。`PreparedAdapterCall` 固定端点、凭据引用与模型能力；重试保留该代配置，后续调用读取新配置。
 
-适配器遵循 [DeepSeek 兼容文档](https://api-docs.deepseek.com/zh-cn/guides/anthropic_api) 和 [Anthropic 流协议](https://platform.claude.com/docs/en/build-with-claude/streaming)。pi-ai 的 Anthropic 实现为相邻用户消息、累计用量、工具参数分片和可选思考签名的处理提供参考。DeepSeek 通过 `output_config.effort` 设置思考强度；Anthropic 思考 token 预算不控制 DeepSeek 思考强度。两种协议都转发显式 `temperature` 值；DeepSeek 在启用思考时接受该参数但忽略其值，因此调用方可以保留已有思考配置。
+适配器遵循 [DeepSeek 兼容文档](https://api-docs.deepseek.com/zh-cn/guides/anthropic_api) 和 [Anthropic 流协议](https://platform.claude.com/docs/en/build-with-claude/streaming)。pi-ai 的 Anthropic 实现为相邻用户消息、累计用量、工具参数分片和可选思考签名的处理提供参考。DeepSeek 通过 `output_config.effort` 设置思考强度；Anthropic 思考 token 预算不控制 DeepSeek 思考强度。适配器转发显式 `temperature` 值；DeepSeek 在启用思考时接受该参数但忽略其值，因此调用方可以保留已有思考配置。
 
 助手内容块保留持久化的模型可见内容。带版本的 `ReplayEnvelope` 仅保存协议格式、模型标识、对齐的块类型以及内容块未包含的签名。同模型续接原样恢复签名，包括空签名；外部历史不生成虚构签名。不可用的元数据遵循现有[回放降级规则](../architecture/2026-07-14-provider-routed-llm-adapters.zh.md)：请求省略签名并记录警告，保留持久化内容；Messages 无法表示历史工具参数时使用[空输入兜底](../bug-fix/2026-09-16-messages-historical-tool-input.zh.md)。提供者回放数据对循环保持不透明，同时能够随 Session 持久化和内容块裁剪保留。
 
-两种协议均优先为确定性请求图片使用 Files 引用，并共享上传缓存、刷新、配额恢复和附件卸载。Files 客户端保留所选协议与已配置端点：Messages 遵循[严格匹配 `/v1` 的根地址规则](../bug-fix/2026-09-15-messages-v1-base-url.zh.md)，Chat Completions 则追加 `/files`。Messages Files 请求携带必需的 beta 标头。缓存 id 按解析后的 Files 根地址和凭据限定作用域，因此等价的 `/v1` 与无版本 Messages 根地址可以复用上传。Messages 元数据不含过期时间，因此本地复用从原始上传时间起受限，但不宣称远端文件已删除。Files 解析失败会按独立的内联图片预算重建完整请求；调用方取消则停止请求。共享图片策略在请求与 token 计量中保留 128 MiB 的保留图片预算、20 MiB 的内联 base64 预算，以及最旧前缀卸载。
+适配器优先使用确定性请求图片的 Files 引用，并管理上传缓存、刷新、配额恢复与附件省略。Files 客户端遵循[精确 `/v1` 根地址规则](../bug-fix/2026-09-15-messages-v1-base-url.zh.md)并发送必需的 beta 标头。缓存 id 按解析后的 Files 根地址与凭据限定作用域，因此等价的 `/v1` 与无版本根地址共用上传。元数据不含过期时间，因此本地复用以原始上传时间为界，不断言远端删除。Files 解析失败会按独立内联图片预算重建完整请求；调用方取消会停止它。图片策略在请求和 token 计量中保留 128 MiB 保留图片预算、20 MiB 内联 base64 预算及最旧前缀省略。
 
 成功 HTTP 响应之后的 JSON 语法错误不足以证明传输故障。Files 解码复用已有的 `INVALID_RESPONSE` code 并补充操作上下文，不将其改标为 `TRANSPORT` 或添加重试；错误字段由 [provider README](../../../../packages/llm/llm-deepseek/README.zh.md) 维护。
 
 系统提示词更新在端点与模型显式声明支持时，使用现有[路由能力](2026-09-02-in-history-system-prompt-replacement.zh.md)。Messages 保留初始顶层 system，在对应的用户或工具结果轮次之后，将后续快照发送为原生 system 轮次，保留此前发送的前缀。这个位置不同于循环先 system、后 user 的接纳顺序；序列化既不改写持久化日志，也不改变对话轮次的顺序。未声明能力的路由将最新快照归并到顶层，直接压缩调用也如此。仅凭协议或模型名称推断能力并不充分，因为支持情况和更新语义取决于实际部署的端点。
 
-Web 始终显示 DeepSeek，不提供协议选择器。两个协议共用 `baseURL` 与 `apiKeyEnv`，没有嵌套的协议配置表。未提供地址覆盖时使用当前协议的官方默认值；Messages 为 `https://api.deepseek.com/anthropic`。切换协议保留已有端点覆盖，部署者负责其兼容性。Messages 遵循严格匹配 `/v1` 的根地址规则，不根据其他版本式后缀推断兼容性。模型目录只维护一份，包含 `deepseek-flash` 的文本/图片和历史内 system 更新能力，也保留 V4 条目。显式 `chat-completions` 仍受支持，并使用自己的官方默认值，追加 `/chat/completions` 而不增加版本段。
+Web 显示 DeepSeek，并提供端点与凭据引用。没有端点覆盖时，解析使用 `https://api.deepseek.com/anthropic`。覆盖地址必须支持 Messages。适配器遵循精确 `/v1` 根地址规则，不从其他类似版本的后缀推断兼容性。单一模型目录公布各条目声明的能力。
 
-两种传输都在原生序列化后使用现有[请求扩展注册表](../architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md)，并在 HTTP 2xx 后、读取流之前接受已捕获贡献。会话日志投递和插件清单仍由原有包负责，并留在模型输入之外。辅助 [web 搜索提供方](../../../../packages/web/web-search-deepseek/README.zh.md)保留独立的端点、请求与设置。
+适配器在原生序列化后使用现有[请求扩展注册表](../architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md)，并在 HTTP 2xx 后、读取流之前接受已捕获贡献。会话日志投递和插件清单仍由原有包负责，并留在模型输入之外。辅助 [web 搜索提供方](../../../../packages/web/web-search-deepseek/README.zh.md)保留独立的端点、请求与设置。
 
 ## 考虑过的替代方案
 
-**每个协议独立插件。** 这会重复凭据配置、模型目录、设置卡片和 provider ID，并迫使用户在底层协议变化时重选模型。单插件中的协议目录保留实现隔离；Responses 可以增加自己的实现而不改变用户配置结构。
+**独立的 Messages 提供方身份。** 这会重复凭据、目录与设置卡，并迫使用户在采用 Messages 时重新选择模型。`deepseek-official` 身份使这些用户选择保持稳定。
 
 **把新路由委托给 pi-ai 或 Anthropic SDK。** 两者均提供持续维护的协议实现，但所需的直接适配器需要 DeepSeek 专属配置、附件策略、凭证解析和重试所有权。小型流转换器配合持续维护的 SSE 解析器使这些职责保持明确；库实现适配器仍可独立使用。
 
@@ -38,6 +38,6 @@ Web 始终显示 DeepSeek，不提供协议选择器。两个协议共用 `baseU
 
 ## 结果
 
-该包负责协议校验、停止原因映射、取消和错误分类，因此协议变化需要维护适配器。用户与工具结果输入遵循[已保存输入兼容规则](../bug-fix/2026-09-18-messages-input-history-compatibility.zh.md)；其他不支持的内容和不完整的流会明确报错。现有重试消费者负责重试；现有装配器在输出达到上限时丢弃未完成的工具调用。Messages 默认配置覆盖共享 base、Web 和独立的官方组合。协议变化保留 provider id 与已保存的模型选择，但显式端点覆盖必须支持所选协议。
+该包负责协议校验、停止原因映射、取消和错误分类，因此协议变化需要维护适配器。用户与工具结果输入遵循[已保存输入兼容规则](../bug-fix/2026-09-18-messages-input-history-compatibility.zh.md)；其他不支持的内容和不完整的流会明确报错。现有重试消费者负责重试；现有装配器在输出达到上限时丢弃未完成的工具调用。Messages 服务共享 base、Web 和独立的官方组合。显式端点覆盖必须支持 Messages。
 
 验证覆盖协议夹具、真实 Loader 组合、逐文件单元覆盖率、[已记录 Session 回放](../../../../snapshots/session/deepseek-messages-replay/snapshot.yml)与[未知回放版本](../../../../snapshots/session/deepseek-messages-degraded-replay/snapshot.yml)，Web Messages Session 回放，以及凭证控制的文本、思考、工具续接、图片和取消请求。真实网关检查证明与已配置网关的兼容性，不能证明与所有 Anthropic 代理兼容。
diff --git a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml
index cfbf30d80a..76ed3e8786 100644
--- a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
-2026-09-09-web-sidebar-terminal.md: 5ed920d744f847cc97b08645592f0be221f18b8d
-2026-09-09-web-sidebar-terminal.zh.md: c3ceb0214c2f4db42b2fefb8b65619e198d9dc7e
+2026-09-09-web-sidebar-terminal.md: 09be4a142f615750799e01106eac7a9b52cbad48
+2026-09-09-web-sidebar-terminal.zh.md: c2ac1468756ee08c713855979119662390ffeadb
diff --git a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
index 5ed920d744..09be4a142f 100644
--- a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
+++ b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
@@ -49,3 +49,7 @@ A kept-open terminal retains a process and bounded screen memory. Reload restore
 The implementation retains the Agent-terminal and portable-execution notes because their ownership and provider decisions remain independently useful; neither is superseded by browser terminals.
 
 The [two-hour unattended-terminal reclamation](2026-09-14-unattended-browser-terminal-reclamation.md) adds an idle grace period after all frontend holders disconnect, preserving busy or uncertain work.
+
+## Related
+
+- [Remote duplex stream](../architecture/2026-09-19-remote-duplex-stream.md): the transport-layer uplink under which one `attach` stream replaces the unary `write` and `resize` calls and the `attachmentId` correlation; that terminal change is listed under its Deferred section.
diff --git a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md
index c3ceb0214c..c2ac146875 100644
--- a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md
@@ -49,3 +49,7 @@ Web 用户需要在 Session 旁使用交互式 shell 检查工作区和运行命
 Agent 终端和可移植执行环境两篇记录仍保留，其所有权与 provider 决策继续独立有效，不被浏览器终端取代。
 
 [无人连接终端的两小时回收](2026-09-14-unattended-browser-terminal-reclamation.zh.md)在全部前端持有者断开后设置空闲宽限期，保留忙碌或状态不确定的工作。
+
+## 相关
+
+- [Remote 双工流](../architecture/2026-09-19-remote-duplex-stream.zh.md)：传输层上行，让一条 `attach` 流取代 unary `write`、`resize` 与 `attachmentId` 关联；该终端改动列在其「后续」中。
diff --git a/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.i18n.yaml b/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.i18n.yaml
index 16d943e2a3..32ae05e725 100644
--- a/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.md
-2026-09-11-desktop-mandatory-update-client.md: d66d3257360270a72d5e774282d9f7c61981929f
-2026-09-11-desktop-mandatory-update-client.zh.md: fd6e751a4082578cc4d54746e0fc584104a89226
+2026-09-11-desktop-mandatory-update-client.md: ff55f30836a37e49229adac6414cb3a98bca4d6c
+2026-09-11-desktop-mandatory-update-client.zh.md: 6c17a9fbd0ce2741b635b742be682d4c5fd9f8c6
diff --git a/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.md b/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.md
index d66d325736..ff55f30836 100644
--- a/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.md
+++ b/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.md
@@ -14,11 +14,11 @@ The shell polls the guest protocol in the [API proposal](../../proposed/feature/
 
 A coordinator owns one immutable installed-client identity, one in-flight request, a deadline, interval jitter, and bounded failure backoff. Manual checks bypass scheduling but join in-flight work. Disposal aborts the request, awaits settlement, and prevents late publication. A flattened `40005` establishes blocking independently of optional title, detail, and download-page fields; localized fallback text and a retry action remain available, while an absent or unapproved page is not offered. Transport, JSON, business-code, or HTTP failures cannot clear a known block. Only a valid fresh no-force response clears it. Same-version offline persistence is not implemented because its product behavior remains undecided.
 
-User-initiated ordinary checks trigger an independent policy refresh without waiting for or presenting its failures. A confirmed block alone cancels ordinary dialogs and transfers presentation to the mandatory window. Test authentication waits until an active ordinary dialog finishes; cancellation and failure leave the updater result intact. Concurrent callers reuse the active ordinary or authentication operation instead of creating competing windows.
+User-initiated ordinary checks trigger an independent policy refresh without waiting for or presenting its failures. A confirmed block alone cancels ordinary dialogs and transfers presentation to the mandatory dialog. Test authentication waits until an active ordinary dialog finishes; cancellation and failure leave the updater result intact. Concurrent callers reuse the active ordinary or authentication operation instead of creating competing windows.
 
-A shell-owned modal uses a separate sandboxed preload with dependency-free IPC names. The main process verifies its exact document URL and WebContents identity. Server title/detail are text, never HTML. Close, Esc, ordinary updater prompts, plugin-window entry, plugin mutations, and recovery actions cannot bypass the policy. The Host keeps existing work running; the existing updater's task-aware confirmation alone authorizes installation teardown. Closing the application remains available.
+On macOS a shell-owned modal uses a separate sandboxed preload, and the main process verifies its exact document URL and WebContents identity. Windows embeds the shell-origin dialog in the main document below the caption so maximization and resizing have one native owner; a second native window caused visibly unsynchronized resizing (#4566). The isolated application preload owns a private MessageChannel to the frame and forwards actions to main-process IPC, which verifies the current app origin and main-frame identity. Product scripts share the DOM and can hide or imitate presentation, but cannot obtain the privileged port, clear main-process policy, or approve task teardown through window message events. The caption and its Web controls remain reachable by design. Server title/detail are text, never HTML. Esc and ordinary updater prompts cannot dismiss the block; main-process guards refuse plugin-window entry and plugin mutations while it is active. The Host keeps existing work running; task-aware installation confirmation remains separate from policy. Closing the application remains available. Windows presentation and its trust limits are owned by the [embedded-update decision](../bug-fix/2026-09-20-windows-embedded-mandatory-update.md).
 
-The modal exposes user-initiated download and separate installation through the ordinary coordinator. Successful preparation and task inspection turn the same modal into installation confirmation without creating another window. Deferral retains the block and package; a retry inspects tasks and requests fresh confirmation. File verification and preparation share one visible phase. Restart feedback describes stopping tasks only after affected tasks are observed. Both dialog types require the owned document and main frame; closing, aborting, or losing an ordinary renderer cancels its approval.
+The modal exposes user-initiated download and separate installation through the ordinary coordinator. Successful preparation and task inspection turn the same modal into installation confirmation without creating another window. Deferral retains the block and package; a retry inspects tasks and requests fresh confirmation. File verification and preparation share one visible phase. Restart feedback describes stopping tasks only after affected tasks are observed. Both dialog types require the owned IPC sender; closing, aborting, or losing an ordinary renderer cancels its approval.
 
 The recovery layout keeps localized errors and folded technical details inside the block. Page actions appear only for failure or absent-artifact recovery, not beside the normal action. Exact HTTPS origins are checked before browser or clipboard use. A browser request immediately exposes copy recovery; its completion cannot prove external page loading. Only copy failure reveals the complete validated address for manual copying. Navigation and copy results are independent of updater errors and ignore completion after a changed policy destination. Neither browser opening, readiness, nor installer handoff clears policy or changes the updater target.
 
diff --git a/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.zh.md b/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.zh.md
index fd6e751a40..6c17a9fbd0 100644
--- a/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-11-desktop-mandatory-update-client.zh.md
@@ -14,11 +14,11 @@ Status: implemented
 
 协调器拥有一份不可变的已安装客户端身份、单一在途请求、截止时间、间隔抖动和有上限的失败退避。手动检查绕过调度，但复用在途请求。dispose（资源释放）中止请求、等待结算，并阻止迟到发布。扁平化 `40005` 建立阻塞不依赖可选的标题、详情和下载页面字段；本地化兜底文案与重试操作仍可使用，缺失或未获批准的页面地址不会展示。传输、JSON、业务码或 HTTP 错误都不能清除已知阻塞。只有新的有效无需强更响应才能清除它。同版本离线持久化未实现，因为其产品行为尚未确定。
 
-用户发起常规检查时会触发独立的策略刷新，但不会等待或展示策略失败。只有已确认的强更决定会取消常规弹窗，并把展示移交给强更窗口。测试环境鉴权会等待当前常规弹窗结束；取消和失败会保留 updater 结果。并发调用方复用当前常规操作或鉴权操作，不创建相互竞争的窗口。
+用户发起常规检查时会触发独立的策略刷新，但不会等待或展示策略失败。只有已确认的强更决定会取消常规弹窗，并把展示移交给强更弹窗。测试环境鉴权会等待当前常规弹窗结束；取消和失败会保留 updater 结果。并发调用方复用当前常规操作或鉴权操作，不创建相互竞争的窗口。
 
-壳拥有的模态窗口使用独立沙箱预加载和无依赖的 IPC 名称。主进程校验其精确文档 URL 和 WebContents 身份。服务端标题／详情按文本展示，绝不作为 HTML。关闭、Esc、常规更新弹窗、插件窗口入口、插件修改和恢复操作都不能绕过策略。Host 保持现有工作运行；只有现有 updater 的任务影响确认才能授权安装收尾。仍可退出应用。
+macOS 的壳模态窗口使用独立沙箱预加载，主进程校验其精确文档 URL 和 WebContents 身份。Windows 将壳源站弹窗嵌入主文档顶栏下方，让最大化与缩放只有一个原生窗口负责；第二个原生窗口曾造成可见的缩放不同步（#4566）。隔离的应用预加载拥有通向 frame 的私有 MessageChannel，将操作转发至校验当前应用源站和主 frame 身份的主进程 IPC。产品脚本共享 DOM，可以隐藏或仿造展示，但不能获得特权端口、清除主进程策略，或通过 window 消息事件批准任务收尾。顶栏及其中的 Web 控件按设计保持可触达。服务端标题／详情按文本展示，绝不作为 HTML。Esc 和常规更新弹窗不能解除阻塞；阻塞期间主进程拒绝插件窗口入口和插件修改。Host 保持现有工作运行，任务影响安装确认独立于策略。仍可退出应用。 Windows 展示及其信任限制由[内嵌强更决策](../bug-fix/2026-09-20-windows-embedded-mandatory-update.zh.md)负责。
 
-模态窗口通过常规协调器提供用户发起的下载和独立安装。准备和任务检查成功后，同一弹窗转为安装确认，不创建另一个窗口。稍后更新保留阻塞与安装包；重试会检查任务并要求重新确认。文件校验与准备共用一个可见阶段。只有观测到受影响任务后，重启提示才描述正在停止任务。两类弹窗均要求所属文档与主 frame；关闭、中止或失去常规渲染进程会取消其批准。
+模态窗口通过常规协调器提供用户发起的下载和独立安装。准备和任务检查成功后，同一弹窗转为安装确认，不创建另一个窗口。稍后更新保留阻塞与安装包；重试会检查任务并要求重新确认。文件校验与准备共用一个可见阶段。只有观测到受影响任务后，重启提示才描述正在停止任务。两类弹窗均要求所属 IPC 发送者；关闭、中止或失去常规渲染进程会取消其批准。
 
 恢复界面在阻塞窗口内保留本地化错误和折叠技术详情。页面操作仅在失败或没有可用产物时出现，不与正常操作并列。浏览器或剪贴板使用前校验精确 HTTPS 源站。请求打开浏览器后立即提供复制恢复入口；请求完成不能证明外部网页加载。仅在复制失败时展示完整、经过校验的地址供手动复制。导航和复制结果独立于 updater 错误，策略目标地址改变后忽略迟到结果。打开浏览器、下载就绪和安装器交接均不清除策略或改变 updater 目标。
 
diff --git a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml
index 50233385bf..27bbadb4ae 100644
--- a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-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/feature/2026-09-14-desktop-primary-runtime.md
-2026-09-14-desktop-primary-runtime.md: 51bbaac89c5c2ec9a3a016030e7b320d2b5566b8
-2026-09-14-desktop-primary-runtime.zh.md: 4f27d61b5e713f66e2f478894dbd547cd7ecfff4
+2026-09-14-desktop-primary-runtime.md: a1491ca0c47e40c6d5b885c9f6a42ccf8180b78c
+2026-09-14-desktop-primary-runtime.zh.md: 6447086a6948ed262699b62061eb44af8d6071d7
diff --git a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
index 51bbaac89c..a1491ca0c4 100644
--- a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
+++ b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
@@ -12,9 +12,9 @@ Desktop agents need predictable Python data-processing libraries and an independ
 
 Desktop ships Python, Node.js, pnpm, data-processing libraries and Office authoring libraries as one release-bound payload. The path-query tool installs the payload from application resources into the fixed Harness-home directory and returns absolute paths and the bundled Python distribution versions. The version report excludes packages added by users. It does not change PATH, environment variables or package-manager configuration. pnpm uses its native global-install rules.
 
-The application version, component versions, Python distribution versions and locked-input digest live in `runtime.json`, not the directory name. The digest covers the selected target's interpreter and wheel archives, shared wheel inputs, Python distribution versions, pnpm version and assembly format; other targets do not invalidate it. Key order within the selected target, wheel records and distribution map, plus wheel-entry order, participates in this identity; top-level lock key order does not. Extraction or assembly changes that alter payload bytes without changing locked inputs require an explicit format bump. Installation publishes a completed staged copy and retains the previous directory until replacement succeeds. Matching payloads reuse installed files; replacements also replace user-added Python dependencies inside the managed tree. Older manifests without a digest remain readable and differ from the current payload. Distribution names use PEP 503 normalization; duplicate normalized names are rejected, and present numpy/pandas distribution versions must agree with their component versions. The Desktop single-instance owner and the tool's shared installation promise serialize normal installation requests.
+The application version, top-level interpreter/package-manager versions, Python distribution map and locked-input digest live in `runtime.json`, not the directory name. The digest covers the selected target's interpreter and wheel archives, shared wheel inputs, Python distribution versions, pnpm version and assembly format; other targets do not invalidate it. Key order within the selected target, wheel records and distribution map, plus wheel-entry order, participates in this identity; top-level lock key order does not. Extraction or assembly changes that alter payload bytes without changing locked inputs require an explicit format bump. Installation publishes a completed staged copy and retains the previous directory until replacement succeeds. Matching payloads reuse installed files; replacements also replace user-added Python dependencies inside the managed tree. Older manifests without a digest remain readable and differ from the current payload. Distribution names use PEP 503 normalization; duplicate normalized names are rejected. The reader normalizes legacy `components` files and retains their numpy/pandas consistency checks; current manifests carry Python libraries only in the distribution map. The Desktop single-instance owner and the tool's shared installation promise serialize normal installation requests.
 
-Node downloads and hash-verifies the complete locked wheel set and unpacks library files into site-packages. This avoids build-host Python and pip version selection without implementing dependency resolution or general wheel installation. Auxiliary scripts, including XlsxWriter's VBA extraction script, remain under the wheel's `.data/scripts` directory; command-line entry-point wrappers are outside this library payload. Other `.data` installation schemes are rejected. Native smoke executes the final payload after temporary files are removed, checking the exact locked distribution set plus bundled pip, Python and pinned wheel versions, dependency completeness and editable Office document round trips, so interpreter links must survive relocation. Smoke checks disable bytecode writes to keep validation artifacts out of the shipped payload.
+The shared Node build entry downloads and hash-verifies the complete locked wheel set and unpacks library files into site-packages. This avoids build-host Python and pip version selection without implementing dependency resolution or general wheel installation. Auxiliary scripts, including XlsxWriter's VBA extraction script, remain under the wheel's `.data/scripts` directory; command-line entry-point wrappers are outside this library payload. Other `.data` installation schemes are rejected. Native smoke executes the final payload after temporary files are removed, checking the exact locked distribution set plus bundled pip, Python and pinned wheel versions, dependency completeness and editable Office document round trips, so interpreter links must survive relocation. Smoke checks disable bytecode writes to keep validation artifacts out of the shipped payload.
 
 macOS grants `com.apple.security.cs.allow-jit` only to the standalone Node executable. Hardened-runtime signing without that entitlement prevents V8 from allocating its code region. Interpreter and library smoke checks run after signing as well as after staging cleanup; a valid signature alone does not establish executable behavior.
 
@@ -22,6 +22,8 @@ Windows signed packaging separates materialization from execution with supervise
 
 Desktop ZIP extraction pins `extract-zip` to `yauzl` 3.4.0 through a scoped dependency override. The 2.x reader can leave large deflate entries unfinished on Node 26 ([upstream issue](https://github.com/thejoshwolfe/yauzl/issues/176)); retaining the existing extractor preserves its path validation and wheel-entry checks. The development launcher uses top-level await so unfinished preparation cannot exit successfully. A large compressed wheel regression checks the complete extracted bytes.
 
+The [shared-runtime decision](../architecture/2026-09-17-shared-office-runtime.md) owns builder, lock and query-package placement for Desktop and SDK carriers, including GNU/Linux x64 and Python-only payloads. Desktop retains the installation and signing behavior described here and requires the full Python, Node.js and pnpm payload.
+
 ## Alternatives considered
 
 **System interpreters only.** They do not provide predictable availability or preinstalled numpy and pandas.
diff --git a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md
index 4f27d61b5e..6447086a69 100644
--- a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md
@@ -12,9 +12,9 @@ Desktop 代理需要在没有开发环境的机器上获得确定的 Python 数
 
 Desktop 将 Python、Node.js、pnpm、数据处理库和 Office 创作库作为绑定应用版本的产物交付。路径查询工具从应用资源将产物安装到 Harness home 下的固定目录，并返回绝对路径与内置 Python 分发包版本。版本报告不包含用户自行添加的包。它不修改 PATH、环境变量或包管理器配置。pnpm 使用原生全局安装规则。
 
-应用版本、组件版本、Python 分发包版本和锁定输入摘要记录在 `runtime.json` 中，不放在目录名里。摘要涵盖所选目标的解释器与 wheel 压缩包、共享 wheel 输入、Python 分发包版本、pnpm 版本和组装格式；其他目标不会使其失效。所选目标、wheel 记录及分发包映射内部的键顺序，以及 wheel 条目顺序参与该身份计算；锁文件顶层键的顺序不参与。解压或组装逻辑在锁定输入不变时改变产物字节，必须显式提升格式版本。安装发布完整的暂存副本，并在替换成功前保留之前的目录。相同产物复用已安装文件；替换也会移除受管目录内用户添加的 Python 依赖。不含摘要的旧清单仍可读取，并与当前产物区分。分发包名称按 PEP 503 归一化，归一化后重复的名称会被拒绝；清单包含 numpy/pandas 分发包版本时，必须与相应组件版本一致。Desktop 单实例所有者和工具共享的安装 Promise 串行处理正常安装请求。
+应用版本、顶层解释器和包管理器版本、Python 分发包版本表和锁定输入摘要记录在 `runtime.json` 中，不放在目录名里。摘要涵盖所选目标的解释器与 wheel 压缩包、共享 wheel 输入、Python 分发包版本、pnpm 版本和组装格式；其他目标不会使其失效。所选目标、wheel 记录及分发包映射内部的键顺序，以及 wheel 条目顺序参与该身份计算；锁文件顶层键的顺序不参与。解压或组装逻辑在锁定输入不变时改变产物字节，必须显式提升格式版本。安装发布完整的暂存副本，并在替换成功前保留之前的目录。相同产物复用已安装文件；替换也会移除受管目录内用户添加的 Python 依赖。不含摘要的旧清单仍可读取，并与当前产物区分。分发包名称按 PEP 503 归一化，归一化后重复的名称会被拒绝。读取器归一化旧 `components` 文件并保留其 numpy/pandas 一致性校验；当前清单仅在分发包版本表中记录 Python 库。Desktop 单实例所有者和工具共享的安装 Promise 串行处理正常安装请求。
 
-Node 下载并校验完整锁定 wheel 集的哈希，将库文件解压到 site-packages。这避免选择构建主机的 Python 和 pip 版本，也无需实现依赖解析或通用 wheel 安装。XlsxWriter 的 VBA 提取脚本等辅助脚本保留在 wheel 的 `.data/scripts` 目录中；命令行入口包装器不属于该库产物。其他 `.data` 安装方案会被拒绝。本机 smoke 在临时文件删除后执行最终产物，检查精确锁定的分发包集合与内置 pip、Python 与固定 wheel 版本、依赖完整性及可编辑 Office 文档的写入和读取，因此解释器链接必须在迁移后仍有效。Smoke 检查禁用字节码写入，避免把验证产物纳入分发内容。
+共享 Node 构建入口下载并校验完整锁定 wheel 集的哈希，将库文件解压到 site-packages。这避免选择构建主机的 Python 和 pip 版本，也无需实现依赖解析或通用 wheel 安装。XlsxWriter 的 VBA 提取脚本等辅助脚本保留在 wheel 的 `.data/scripts` 目录中；命令行入口包装器不属于该库产物。其他 `.data` 安装方案会被拒绝。本机 smoke 在临时文件删除后执行最终产物，检查精确锁定的分发包集合与内置 pip、Python 与固定 wheel 版本、依赖完整性及可编辑 Office 文档的写入和读取，因此解释器链接必须在迁移后仍有效。Smoke 检查禁用字节码写入，避免把验证产物纳入分发内容。
 
 macOS 仅向独立 Node 可执行文件授予 `com.apple.security.cs.allow-jit`。缺少此权限的强化运行时签名会阻止 V8 分配代码区域。解释器和库的 smoke 检查在签名后以及暂存清理后执行；签名有效本身不能证明程序可运行。
 
@@ -22,6 +22,8 @@ Windows 签名打包通过受监督的签名阶段覆盖第一方运行时和应
 
 Desktop ZIP 解压通过定向依赖覆盖为 `extract-zip` 固定 `yauzl` 3.4.0。2.x 读取器在 Node 26 上可能无法完成较大 deflate 条目的读取（[上游问题](https://github.com/thejoshwolfe/yauzl/issues/176)）；保留现有解压器可保留其路径校验和 wheel 条目检查。开发启动器使用顶层 await，避免准备未完成却成功退出。大压缩 wheel 回归测试检查完整的解压字节。
 
+[共享运行时决策](../architecture/2026-09-17-shared-office-runtime.zh.md)持有 Desktop 与 SDK 载体的构建器、锁文件和查询包归属，覆盖 GNU/Linux x64 与 Python-only payload。Desktop 保留本文的安装与签名行为，并要求完整的 Python、Node.js 和 pnpm payload。
+
 ## Alternatives considered
 
 **只使用系统解释器。** 无法保证可用性或预装 numpy 和 pandas。
diff --git a/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.i18n.yaml b/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.i18n.yaml
index b261e98e5b..fac9746b09 100644
--- a/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-16-sidebar-browser.md
-2026-09-16-sidebar-browser.md: 3fa4e1dbb70dee97dbe6052d925271d093f2877c
-2026-09-16-sidebar-browser.zh.md: 69d78dbf2b959d660c9397c7bf7634547a109a9e
+2026-09-16-sidebar-browser.md: eff143cc042da7c6455152f684ec83dfa654a1ec
+2026-09-16-sidebar-browser.zh.md: a037c2fb54be745a3a85f43561c0bd587873c008
diff --git a/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.md b/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.md
index 3fa4e1dbb7..eff143cc04 100644
--- a/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.md
+++ b/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.md
@@ -18,17 +18,21 @@ A parent page cannot inspect or drive a cross-origin iframe's internal history.
 
 The address parser accepts `http:` and `https:`, including loopback targets; a host name without a scheme becomes HTTPS. It rejects embedded credentials, the application's own origin, malformed addresses, `file:` URLs, and every other scheme. Document Preview remains the local-file surface.
 
-The current carrier is an iframe in both Web and Desktop. Its default Web policy is `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"`; the frame has no direct download or top-navigation flag. Popups escape the sandbox, and a Web popup retains its opener and can use that chain to navigate the top-level application. Same-origin lets the visited origin use its own cookies and Web storage; it does not make a cross-origin target same-origin with DSH. The iframe sends no referrer and adds no package-owned Permissions Policy, so browser defaults and user grants apply. A rightmost toolbar toggle removes the sandbox attribute for that tab occurrence; the mode is not persisted and renders a warning while active. An unsandboxed page can navigate the top-level application under browser activation rules and use downloads, modal dialogs, and input locks. The package performs no Host-side URL probe or proxy.
+The Web carrier is an iframe; Desktop uses the [retained webview carrier](2026-09-20-desktop-browser-webview.md). Its default Web policy is `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"`; the frame has no direct download or top-navigation flag. Popups escape the sandbox, and a Web popup retains its opener and can use that chain to navigate the top-level application. Same-origin lets the visited origin use its own cookies and Web storage; it does not make a cross-origin target same-origin with DSH. The iframe sends no referrer and adds no package-owned Permissions Policy, so browser defaults and user grants apply. A rightmost toolbar toggle removes the sandbox attribute for that tab occurrence; the mode is not persisted and renders a warning while active. An unsandboxed page can navigate the top-level application under browser activation rules and use downloads, modal dialogs, and input locks. The package performs no Host-side URL probe or proxy.
 
-Each tab receives one `BrowserController` class. Its command interface contains only `loadUrl`, `goBack`, `goForward`, and `reload`; it owns address validation and the `BrowserNavigation` state machine. The `BrowserFrame` interface owns transient sandbox and document state plus carrier operations, and `IframeImpl` implements it for the current iframe carrier. Slot injection exposes keyed frame state through `useBrowserFrame` and supplies plain callbacks, so the React body receives neither the controller nor an observable source; it owns only the editable draft and iframe DOM. A future `ElectronWebViewImpl` can implement the same interface without putting URL or carrier state in the component.
+Each tab receives one `BrowserController` for address validation and carrier-independent commands. `BrowserFrame` exposes navigation, observable address/loading/history/error state, and an optional sandbox control; `BrowserPresentation` owns DOM attachment. `pages.ts` composes these two objects into a `BrowserPage`. `IframeImpl` owns application-known `BrowserNavigation`, while `ElectronWebViewImpl` observes native history. Slot injection exposes keyed controller state through `useBrowserState` and plain callbacks; the React body owns its draft and content container, with no carrier branch, controller instance or observable source.
 
-`BrowserNavigation` keeps the canonical current URL, controlled-load revision, navigation state, and a bounded sequence with its index. A new address drops the forward branch; Back and Forward move the index; Reload recreates the last application-known URL without adding history. A remounted body reloads the latest application-known URL and consults its optional initial URL only before the first controlled target. The Session-scoped store only persists immutable snapshots from that class for title rendering and application reload. An occurrence abort removes its bucket; `TabDomain` uses that same abort for both tab removal and `ui-sidebar-right` unload, so unloading or hot-reloading the Sidebar clears Browser history even when DockKit later restores the tab record.
+For the iframe carrier, `BrowserNavigation` keeps the canonical current URL, controlled-load revision, navigation state, and a bounded sequence with its index. A new address drops the forward branch; Back and Forward move the index; Reload recreates the last application-known URL without adding history. Within a live controller, remounting a body reloads its last requested URL. The Session-scoped store persists immutable checkpoints for tab titles and cold-start recovery; it does not serialize a live page.
+
+A controller created from a saved checkpoint offers its last title and URL with a Restore page button. The provider starts idle: mounting the restored tab neither creates a browsing guest nor requests the saved site. Restore, toolbar Reload or address submission starts navigation; a fresh typed-open URL remains an explicit navigation request and loads directly. Before a page is requested, Back and Forward remain disabled, while Reload restores the saved address through the same controller action as Restore. Changing an idle iframe's sandbox does not restore it. This offer belongs to `BrowserControllerState`, not the live `BrowserFrame` interface or the persisted navigation status.
+
+Occurrence cancellation releases the controller. It removes the saved checkpoint only when the Sidebar's authoritative `openTabs` inventory no longer contains that tab. The inventory publishes layout removal before `TabDomain` aborts its occurrence; plugin unload also aborts occurrences but leaves saved tab membership intact. Cleanup therefore does not interpret plugin unload as a request to erase recovery data.
 
 Browser state is presentation state. It does not enter the Session log, model request, resource model, or DockKit layout operations. The existing [right Sidebar infrastructure](2026-09-04-right-sidebar-docking-infrastructure.md), [tab type contract](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md), [resource model](../architecture/2026-09-05-client-resource-model.md), and [Document Preview operations](../architecture/2026-09-08-document-preview-operations.md) retain their existing responsibilities.
 
 ## Web navigation states
 
-The Web carrier treats only the first iframe `load` for a controlled revision as confirmation of the application-known URL. A later `load` for that revision proves that the document changed but cannot reveal the new cross-origin URL. Events carrying an older revision are ignored.
+The Web carrier treats only the first iframe `load` for a controlled revision as confirmation of the application-known URL. A later `load` for that revision proves that the document changed but cannot reveal the new cross-origin URL. Events carrying an older revision are ignored. These states describe active navigation; an unrequested saved checkpoint remains a separate restore offer.
 
 | State | Entry | Address and controls |
 |---|---|---|
@@ -37,22 +41,16 @@ The Web carrier treats only the first iframe `load` for a controlled revision as
 | `known` | The first iframe `load` arrives for the current revision. | The requested URL remains authoritative even when that first load includes an HTTP redirect. The controls follow the same known-target rules as `loading`. |
 | `unknown` | A second or later iframe `load` arrives for the current revision. | The last controlled URL is muted and marked `URL changed`. Back and Forward are disabled because iframe exposes no cross-origin `canGoBack` or `canGoForward`; external-open is disabled. Reload starts a new revision at the last controlled URL. |
 
-Address editing is available in every state. An invalid draft reports an address failure without changing the current navigation state. Focusing the unknown address hides its marker and reveals Go; Enter and Go both start a controlled load. Changing sandbox mode reloads the last controlled Web target under a new revision. An iframe `error` event marks only the current `BrowserFrame` revision with a transient load-failure notice; it does not change URL history, and the next controlled document clears it. Browsers do not reliably emit this event for DNS, TLS, mixed-content, CSP, or `X-Frame-Options` failures. `pushState`, `replaceState`, and fragment changes that emit no iframe `load` remain unobservable.
+Address editing is available in every state. An invalid draft reports an address failure without changing the current navigation state. Focusing the unknown address hides its marker and reveals Go; Enter and Go both start a controlled load. For an already requested page, changing sandbox mode reloads the last controlled Web target under a new revision. An iframe `error` event marks only the current `BrowserFrame` revision with a transient load-failure notice; it does not change URL history, and the next controlled document clears it. Browsers do not reliably emit this event for DNS, TLS, mixed-content, CSP, or `X-Frame-Options` failures. `pushState`, `replaceState`, and fragment changes that emit no iframe `load` remain unobservable.
 
-## Deferred Electron carrier
+## Electron carrier
 
-Electron `<webview>` support is designed but is not registered or tested. The controller keeps the same four commands, while a separate per-tab view object owns attachment, detachment, state observation, and target identity. This follows Playwright's Android WebView split: `AndroidWebView` is a target and lifecycle handle identified by package, process, and debugging socket, while `page()` returns the regular `Page` that owns Web navigation and DOM commands; device-level input remains on `AndroidDevice`.
-
-The Desktop design enables `webviewTag` only on the application window. Its isolated preload receives an unguessable per-window capability, and every Browser tab appends a fresh UUID to form a distinct non-persistent partition. The main process accepts only an initial `about:blank` guest carrying that capability, removes any preload, and forces sandbox, context isolation, disabled Node integration in all frames, Web security, secure-content checks, disabled nested webviews, and disabled plugins.
-
-The main process allows page-initiated main-frame navigation and redirects only to credential-free HTTP(S). Requests may use HTTP(S), WebSocket, data, and Blob URLs; direct file, custom-protocol, extension, and privileged requests are cancelled. Permission checks and requests, display capture, device grants, downloads, popup windows, and drag-and-drop navigation are denied.
-
-The view object keeps an inactive guest connected in an owned hidden DOM host and moves it back into the visible placeholder without recreation. This retains page and target identity across Sidebar body remounts. Because `<webview>` participates in renderer layout and compositing, ordinary DOM dialogs, menus, tooltips, and drag previews can cover it. `WebContentsView` remains unsuitable because it is a native child surface: CSS cannot cover it, and every overlay or animation would require main-process visibility and bounds synchronization.
-
-Each guest is a distinct WebContents and CDP target. Development may expose Electron's process-wide remote-debugging port and select the guest target explicitly. Production keeps that endpoint disabled; browser-use or computer-use requires an authenticated broker that binds one authorized tab to its WebContents and uses `webContents.debugger` or an equivalently scoped transport without publishing every application target.
+The [Desktop webview decision](2026-09-20-desktop-browser-webview.md) owns native page lifetime, Workspace storage sharing, guest policy, and runtime verification gaps. The iframe behavior in this note remains independently useful; its cross-origin limitations do not describe the Desktop carrier.
 
 ## Alternatives considered
 
+**Automatically reload saved pages when their tabs mount.** This resumes third-party requests and scripts merely by restoring the layout. An explicit restore action preserves the saved address without opening the site.
+
 **Add a Host embeddability probe and persist the sandbox preference.** Rejected because fetching arbitrary targets on the Host adds an SSRF path, the probe can disagree with later redirects, and a persistent global escape makes later tabs inherit an unsafe choice. Browser instead offers an explicit per-tab, non-persistent sandbox toggle with a visible warning.
 
 **Treat parent-owned history as the complete Web model.** Rejected because it silently leaves a stale address and enabled actions after an in-frame navigation. The bounded parent-owned history remains useful while the current controlled URL is known; the explicit `unknown` state removes claims that the iframe API cannot support.
@@ -67,8 +65,10 @@ Each guest is a distinct WebContents and CDP target. Development may expose Elec
 
 Unit tests cover protocol parsing, delegated Markdown links, controller commands and lifecycle, deterministic navigation-state transitions, bounded history, best-effort iframe errors, and plugin disposal. Keyless Web scenarios boot the shipped composition and exercise message-link routing, HTTP(S), Back, Forward, sandbox control, unknown navigation, and protocol refusal.
 
+Manual cold-start restoration and checkpoint retention across plugin unload have no runtime verification yet.
+
 ## Consequences
 
-The Browser adds no Electron privilege and behaves identically in current Web and Desktop builds. Many sites refuse iframe embedding or require downloads or top-level navigation withheld from the frame by the default sandbox. An HTTPS application can block public HTTP pages as mixed content or restrict private-network requests, and disabling the sandbox does not bypass those browser policies. Disabling the sandbox otherwise trades its protections for compatibility: the frame can navigate the top-level application under browser activation rules and use downloads, modal dialogs, and input locks. A Web popup that escapes the sandbox retains its opener and can navigate the top-level application through that chain. Neither path adds Electron or Node APIs. The URL gate cannot prevent an embedded page from choosing its own destination. A later iframe load exposes that navigation occurred but not its cross-origin URL; History API and fragment changes can remain completely invisible. The deferred Electron carrier requires real packaged-app verification before it can become current behavior.
+The iframe carrier exposes no Electron or Node APIs. Many sites refuse iframe embedding or require downloads or top-level navigation withheld from the frame by the default sandbox. An HTTPS application can block public HTTP pages as mixed content or restrict private-network requests, and disabling the sandbox does not bypass those browser policies. Disabling the sandbox otherwise trades its protections for compatibility: the frame can navigate the top-level application under browser activation rules and use downloads, modal dialogs, and input locks. A Web popup that escapes the sandbox retains its opener and can navigate the top-level application through that chain. Neither path adds Electron or Node APIs. The URL gate cannot prevent an embedded page from choosing its own destination. A later iframe load exposes that navigation occurred but not its cross-origin URL; History API and fragment changes can remain completely invisible.
 
-Site-cookie behavior follows the user's browser and is not isolated per Browser tab. Local files are rejected and remain owned by Document Preview. Persisted URLs can contain sensitive query or fragment values, so users must not enter credentials they do not want retained in application-local browser storage.
+Web site-cookie behavior follows the user's browser and is not isolated per Browser tab. Local files are rejected and remain owned by Document Preview. Persisted URLs can contain sensitive query or fragment values, so users must not enter credentials they do not want retained in application-local browser storage.
diff --git a/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.zh.md b/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.zh.md
index 69d78dbf2b..a037c2fb54 100644
--- a/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-16-sidebar-browser.zh.md
@@ -18,17 +18,21 @@ Status: implemented
 
 地址解析器接受 `http:` 与 `https:`，包括 loopback 目标；不带 scheme 的主机名补为 HTTPS。它拒绝内嵌凭据、应用自身 origin、畸形地址、`file:` URL，以及所有其他 scheme。本地文件继续由 Document Preview 负责。
 
-当前 Web 与 Desktop 都使用 iframe 载体。它的默认 Web 策略是 `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"`；frame 没有直接的下载或顶层导航 flag。popup 会脱离 sandbox，Web popup 会保留 opener，并可以通过该链导航顶层应用。same-origin 允许被访问的 origin 使用自己的 Cookie 与 Web storage；它不会让跨域目标与 DSH 变成同源。iframe 不发送 referrer，也不添加包自有的 Permissions Policy，因此浏览器默认策略与用户授权生效。最右侧 toolbar 开关会为当前 tab occurrence 移除 sandbox attribute；该模式不持久化，启用期间持续显示警告。未受 sandbox 约束的页面可以按浏览器 activation 规则导航顶层应用，并使用下载、模态对话框和输入锁定。本包不执行 Host 侧 URL probe 或代理。
+Web 使用 iframe 载体；Desktop 使用[保持页面实例的 webview 载体](2026-09-20-desktop-browser-webview.zh.md)。它的默认 Web 策略是 `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"`；frame 没有直接的下载或顶层导航 flag。popup 会脱离 sandbox，Web popup 会保留 opener，并可以通过该链导航顶层应用。same-origin 允许被访问的 origin 使用自己的 Cookie 与 Web storage；它不会让跨域目标与 DSH 变成同源。iframe 不发送 referrer，也不添加包自有的 Permissions Policy，因此浏览器默认策略与用户授权生效。最右侧 toolbar 开关会为当前 tab occurrence 移除 sandbox attribute；该模式不持久化，启用期间持续显示警告。未受 sandbox 约束的页面可以按浏览器 activation 规则导航顶层应用，并使用下载、模态对话框和输入锁定。本包不执行 Host 侧 URL probe 或代理。
 
-每个 tab 获得一个 `BrowserController` class。它的命令接口只有 `loadUrl`、`goBack`、`goForward` 与 `reload`；它负责地址校验和 `BrowserNavigation` 状态机。`BrowserFrame` 接口负责临时 sandbox 与 document 状态以及载体操作，`IframeImpl` 为当前 iframe 载体实现该接口。Slot injection 通过 `useBrowserFrame` 提供按 key 索引的 frame 状态，并提供普通 callback，因此 React body 不接收 controller 或 observable source；它只负责可编辑草稿与 iframe DOM。未来的 `ElectronWebViewImpl` 可以实现相同接口，而不把 URL 或载体状态放进组件。
+每个 tab 获得一个 `BrowserController`，负责地址校验与载体无关的命令。`BrowserFrame` 提供导航、可观察的地址/加载/history/错误状态和可选 sandbox 控制，`BrowserPresentation` 负责 DOM 挂载。`pages.ts` 把两个对象组装成 `BrowserPage`。`IframeImpl` 持有应用已知的 `BrowserNavigation`，`ElectronWebViewImpl` 则观察原生 history。Slot injection 通过 `useBrowserState` 提供按 key 索引的控制器状态和普通回调；React body 只持有草稿与内容容器，没有载体分支、控制器实例或可观察源。
 
-`BrowserNavigation` 保存 canonical 当前 URL、受控加载 revision、导航状态，以及有上限的序列与当前位置。新地址丢弃 forward 分支；后退和前进移动 index；刷新重建应用最后已知的 URL 且不增加 history。body 重挂载时会重新加载应用最后已知的 URL，并且仅在尚无受控目标时使用可选初始 URL。Session-scoped store 只持久化该 class 的 immutable snapshot，供标题渲染与应用刷新恢复。occurrence abort 会删除其 bucket；`TabDomain` 对 tab 删除与 `ui-sidebar-right` 卸载使用同一个 abort，因此卸载或热重载 Sidebar 会清空 Browser history，即使 DockKit 随后恢复 tab record。
+对于 iframe 载体，`BrowserNavigation` 保存 canonical 当前 URL、受控加载 revision、导航状态，以及有上限的序列与当前位置。新地址丢弃 forward 分支；后退和前进移动 index；刷新重建应用最后已知的 URL 且不增加 history。在仍存活的控制器内，body 重挂载会重新加载最后请求的 URL。Session-scoped store 持久化不可变检查点，供 Tab 标题与冷启动恢复使用，不序列化活页面。
+
+从已保存检查点创建的控制器展示上次标题、URL 和“恢复页面”按钮。提供方初始为空闲状态：挂载恢复的 Tab 既不创建浏览 guest，也不请求保存的站点。恢复、工具栏刷新或提交地址才启动导航；新打开 Tab 时显式传入的 URL 仍是主动导航请求，会直接加载。页面尚未请求时，后退和前进仍禁用，刷新则通过与“恢复页面”相同的控制器操作加载保存的地址。切换空闲 iframe 的沙箱也不会恢复页面。恢复提示属于 `BrowserControllerState`，不进入活页面的 `BrowserFrame` 接口或持久化导航状态。
+
+occurrence 取消会释放控制器。只有 Sidebar 的权威 `openTabs` 清单已不再包含该 Tab 时，才删除保存的检查点。清单先发布布局中的 Tab 移除，再由 `TabDomain` abort 对应 occurrence；插件卸载也会 abort occurrence，但仍保留已保存的 Tab 成员信息。因此清理不会把插件卸载当成删除恢复数据的请求。
 
 Browser 状态只属于呈现层，不进入 Session log、模型请求、resource model 或 DockKit layout operation。现有的[右侧 Sidebar 基础设施](2026-09-04-right-sidebar-docking-infrastructure.zh.md)、[tab 类型契约](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)、[resource model](../architecture/2026-09-05-client-resource-model.zh.md)和[文档预览操作](../architecture/2026-09-08-document-preview-operations.zh.md)继续负责各自现有职责。
 
 ## Web 导航状态
 
-对于一个受控 revision，Web 载体只把 iframe 的第一次 `load` 当作应用已知 URL 的确认。同一 revision 后续发生 `load`，只能证明文档已经变化，无法给出新的跨域 URL。携带旧 revision 的事件会被忽略。
+对于一个受控 revision，Web 载体只把 iframe 的第一次 `load` 当作应用已知 URL 的确认。同一 revision 后续发生 `load`，只能证明文档已经变化，无法给出新的跨域 URL。携带旧 revision 的事件会被忽略。这些状态描述活动导航；尚未请求的已保存检查点仍是独立的恢复提示。
 
 | 状态 | 进入条件 | 地址与控件 |
 |---|---|---|
@@ -37,22 +41,16 @@ Browser 状态只属于呈现层，不进入 Session log、模型请求、resour
 | `known` | 当前 revision 收到 iframe 的第一次 `load`。 | 即使第一次加载包含 HTTP redirect，请求 URL 仍是权威地址。控件规则与 `loading` 的已知目标规则相同。 |
 | `unknown` | 当前 revision 收到 iframe 的第二次或后续 `load`。 | 最后一个受控 URL 变灰，并标记 `URL 已变化`。iframe 不提供跨域 `canGoBack` 或 `canGoForward`，因此后退和前进禁用；外部打开禁用。刷新以最后一个受控 URL 启动新的 revision。 |
 
-每个状态都允许编辑地址。无效草稿只报告地址错误，不改变当前导航状态。聚焦 unknown 地址会隐藏标记并显示前往按钮；回车与前往都会启动受控加载。切换 sandbox 模式会使用新的 revision 重新加载最后一个受控 Web 目标。iframe `error` event 只会为当前 `BrowserFrame` revision 标记临时加载失败 notice；它不改变 URL history，下一个受控 document 会清除它。浏览器不会为 DNS、TLS、mixed-content、CSP 或 `X-Frame-Options` 失败可靠触发该 event。不产生 iframe `load` 的 `pushState`、`replaceState` 与 fragment 变化仍不可观察。
+每个状态都允许编辑地址。无效草稿只报告地址错误，不改变当前导航状态。聚焦 unknown 地址会隐藏标记并显示前往按钮；回车与前往都会启动受控加载。对于已经请求的页面，切换 sandbox 模式会使用新的 revision 重新加载最后一个受控 Web 目标。iframe `error` event 只会为当前 `BrowserFrame` revision 标记临时加载失败 notice；它不改变 URL history，下一个受控 document 会清除它。浏览器不会为 DNS、TLS、mixed-content、CSP 或 `X-Frame-Options` 失败可靠触发该 event。不产生 iframe `load` 的 `pushState`、`replaceState` 与 fragment 变化仍不可观察。
 
-## Deferred Electron carrier
+## Electron carrier
 
-Electron `<webview>` 支持已经完成设计，但当前不注册也不测试。controller 保持相同的四个命令，独立的 per-tab view 对象负责 attachment、detachment、状态观察与 target identity。这沿用 Playwright 的 Android WebView 划分：`AndroidWebView` 是由 package、process 与调试 socket 标识的 target 和生命周期 handle，`page()` 返回负责 Web 导航与 DOM 命令的普通 `Page`；设备级输入仍属于 `AndroidDevice`。
-
-Desktop 设计只在应用窗口启用 `webviewTag`。其隔离 preload 获得不可猜的 per-window capability，每个 Browser tab 再追加新的 UUID，形成独立非持久化 partition。主进程只接受携带该 capability 且初始地址为 `about:blank` 的 guest，删除任何 preload，并强制启用 sandbox 与 context isolation、在所有 frame 禁用 Node integration、启用 Web security 与安全内容检查、禁用嵌套 webview 和 plugin。
-
-主进程只允许页面发起的 main-frame 导航与重定向前往不含凭据的 HTTP(S)。请求可以使用 HTTP(S)、WebSocket、data 与 Blob URL；直接 file、自定义协议、extension 与特权请求都会被取消。permission 检查与请求、显示捕获、设备授权、下载、弹窗和拖放导航全部拒绝。
-
-view 对象把非活动 guest 保持连接并停放在自有隐藏 DOM host 中，再把它移回可见占位符而不重建。这会在 Sidebar body remount 后保留页面与 target identity。因为 `<webview>` 参与 renderer 布局与合成，普通 DOM dialog、menu、tooltip 与拖拽预览可以覆盖它。`WebContentsView` 仍不合适，因为它是原生 child surface：CSS 无法覆盖它，每个 overlay 或动画都需要主进程同步 visibility 与 bounds。
-
-每个 guest 都是独立 WebContents 和 CDP target。开发环境可以开放 Electron 的进程级 remote-debugging port，并明确选择 guest target。生产环境保持该 endpoint 关闭；browser-use 或 computer-use 需要一个经过认证的 broker，把一个已授权 tab 绑定到其 WebContents，并使用 `webContents.debugger` 或等价的 scoped transport，而不公开全部应用 target。
+[Desktop webview 决策](2026-09-20-desktop-browser-webview.zh.md)负责原生页面生命周期、Workspace 存储共享、guest 策略与运行时验证缺口。本文的 iframe 行为仍具有独立价值；其跨域限制不描述 Desktop 载体。
 
 ## Alternatives considered
 
+**Tab 挂载时自动重新加载已保存页面。** 这会仅因恢复布局就恢复第三方请求与脚本执行。显式恢复操作保留已保存地址，但不会自行打开站点。
+
 **增加 Host embeddability probe 并持久化 sandbox 偏好。** 不采用，因为由 Host 请求任意目标会新增 SSRF 路径，probe 可能与后续重定向结果不一致，而持久化的全局逃生开关会让后续 tab 继承不安全选择。Browser 改为提供显式、按 tab、非持久化的 sandbox 开关，并持续显示警告。
 
 **把 parent-owned history 当成完整 Web 模型。** 不采用，因为 iframe 内导航后，地址会悄然陈旧，而相关操作仍显示可用。当前受控 URL 已知时，有上限的 parent history 仍然有用；显式 `unknown` 状态会移除 iframe API 无法支持的能力声明。
@@ -67,8 +65,10 @@ view 对象把非活动 guest 保持连接并停放在自有隐藏 DOM host 中
 
 单元测试覆盖协议解析、Markdown 链接委托、controller 命令与生命周期、确定性导航状态转换、有界 history、best-effort iframe error 和插件 disposal。Keyless Web 场景启动随附 composition，并覆盖消息链接路由、HTTP(S)、后退、前进、sandbox 控制、unknown 导航和协议拒绝。
 
+手动冷启动恢复和跨插件卸载保留检查点尚无运行时验证。
+
 ## Consequences
 
-Browser 不增加 Electron 权限，并在当前 Web 与 Desktop 构建中保持相同行为。很多站点拒绝 iframe 嵌入，或者依赖默认 sandbox 不向 frame 提供的下载或顶层导航。HTTPS 应用可能按 mixed-content 策略阻止公共 HTTP 页面，或限制 private-network 请求；关闭 sandbox 也无法绕过这些浏览器策略。关闭 sandbox 在其他方面会用自身保护换取兼容性：frame 可以按浏览器 activation 规则导航顶层应用，并使用下载、模态对话框和输入锁定。逃逸出 sandbox 的 Web popup 会保留 opener，并可以通过该链导航顶层应用。这两条路径都不会增加 Electron 或 Node API。URL 检查无法阻止 iframe 内页面自行选择目标。后续 iframe load 能表明已经发生导航，但无法给出跨域 URL；History API 与 fragment 变化可能完全不可见。延期的 Electron 载体必须通过真实打包应用验证，才能成为当前行为。
+iframe 载体不暴露 Electron 或 Node API。很多站点拒绝 iframe 嵌入，或者依赖默认 sandbox 不向 frame 提供的下载或顶层导航。HTTPS 应用可能按 mixed-content 策略阻止公共 HTTP 页面，或限制 private-network 请求；关闭 sandbox 也无法绕过这些浏览器策略。关闭 sandbox 在其他方面会用自身保护换取兼容性：frame 可以按浏览器 activation 规则导航顶层应用，并使用下载、模态对话框和输入锁定。逃逸出 sandbox 的 Web popup 会保留 opener，并可以通过该链导航顶层应用。这两条路径都不会增加 Electron 或 Node API。URL 检查无法阻止 iframe 内页面自行选择目标。后续 iframe load 能表明已经发生导航，但无法给出跨域 URL；History API 与 fragment 变化可能完全不可见。
 
-站点 Cookie 行为遵循用户浏览器，并不按 Browser tab 隔离。本地文件会被拒绝，并继续由 Document Preview 负责。持久化 URL 可能含敏感 query 或 fragment，因此用户不应在地址栏输入不希望保留在应用本地浏览器存储中的凭据。
+Web 站点 Cookie 行为遵循用户浏览器，并不按 Browser tab 隔离。本地文件会被拒绝，并继续由 Document Preview 负责。持久化 URL 可能含敏感 query 或 fragment，因此用户不应在地址栏输入不希望保留在应用本地浏览器存储中的凭据。
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
index 69db5487b8..af257a325c 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-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 .agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
-2026-09-17-developer-tools-settings.md: e76cb7f367faff71ef916d8a263dc523583f1cd2
-2026-09-17-developer-tools-settings.zh.md: 5a7d6d59db686f57ef4945b572ea65ffe54b7f9c
+2026-09-17-developer-tools-settings.md: 7819b2a2df3c9eaf2db1e1271d7b419768affaff
+2026-09-17-developer-tools-settings.zh.md: 5ff9f2c1e2380f086969cc392bf649edd13e2893
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
index e76cb7f367..7819b2a2df 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
@@ -10,9 +10,9 @@ Diagnostic views, preset selection and changed-file summaries add complexity to
 
 ## Decision
 
-The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference, defaulting off. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
+The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference. The initial default-off choice reduces routine-task complexity; [Developer tools default on after preference resolution](2026-09-20-developer-tools-default-on.md) supersedes that default and owns startup enablement. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
 
-Off exposes only Chat, hides tool Inspect actions when no visible View declares tool-call inspection, removes the conversation View tab bar, hides the new-session preset chip, and omits the changed-files card and its summary read. Turning it off from another View activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
+Off hides the Trajectory View, hides tool Inspect actions when no visible View declares tool-call inspection, hides the conversation View tab bar while fewer than two Views are available, hides the new-session preset chip and the settings row that allows switching Agent modes, and omits the changed-files card and its summary read. Views registered by other plugins stay available. Turning it off while Trajectory is active activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
 
 Plugin assembly translates the shared preference into component-specific capabilities (`showCodeDiff`, `showPresetPicker`, and `interactivePreview`). Conversation supplies the inspection callback using the visible target's `toolCallFocus`; Chat does not name the target. The builtin HTML renderer uses DOMPurify for complete-document sanitization and parser-mutation defenses. Off preserves root styling, removes active documents, resource hints, SVG animation and all `href` attributes, and mounts an iframe with no sandbox permissions and a CSP denying scripts and external resources. It reads no related files. On retains the opaque scripted Blob renderer and its bounded related-file reads. Switching modes replaces the browsing context and disposes pending reads. The [document-preview decision](../architecture/2026-09-08-document-preview-operations.md) and [filesystem-read authority](../architecture/2026-09-09-workspace-file-read-authority.md) remain authoritative for advanced rendering and Host read access.
 
@@ -26,4 +26,4 @@ Plugin assembly translates the shared preference into component-specific capabil
 
 Basic HTML sacrifices JavaScript, external and related resources, and link navigation; inline styles and data images remain available. Advanced mode retains normal browser networking and does not gain parent-origin, popup, form or top-navigation privileges. The setting does not constrain third-party preview implementations or revoke Host filesystem authority.
 
-Component and settings tests cover defaulting, schema rejection, accepted-state updates, chip disclosure, changed-file visibility and iframe disposal. The recorded-session [document preview](../../../../apps/web/tests/document-preview.e2e.ts) and [changed-files](../../../../apps/web/tests/changed-files-turn.e2e.ts) scenarios exercise the real settings control and the shared renderer. The browser scaffold enables developer tools by default. Only settings chrome, document preview, changed-files and developer-tools scenarios explicitly retain the shipped default; together they cover hidden diagnostic controls, static previews, and switching back to Chat. Refused Host writes recover accepted state and show the localized retry message. Native Electron execution remains unverified.
+Component and settings tests cover defaulting, schema rejection, accepted-state updates, chip disclosure, changed-file visibility and iframe disposal. The recorded-session [document preview](../../../../apps/web/tests/document-preview.e2e.ts) and [changed-files](../../../../apps/web/tests/changed-files-turn.e2e.ts) scenarios exercise the real settings control and the shared renderer. The browser scaffold uses the shipped default unless a scenario specifies a preference. Settings chrome, document preview and changed-files scenarios explicitly disable developer tools; together they cover hidden diagnostic controls, static previews, and switching back to Chat. Refused Host writes recover accepted state and show the localized retry message. Native Electron execution remains unverified.
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
index 5a7d6d59db..5ff9f2c1e2 100644
--- a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
@@ -10,9 +10,9 @@ Status: implemented
 
 ## Decision
 
-设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好，默认关闭。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
+设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好。最初默认关闭的选择用于降低日常任务的复杂度；[偏好解析后默认开启开发者工具](2026-09-20-developer-tools-default-on.zh.md)取代该默认值并负责启动时的启用策略。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
 
-关闭时仅展示 Chat，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，移除会话 View 标签栏，隐藏新会话预设入口，并省略改动文件卡片及其摘要读取。在其他 View 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
+关闭时隐藏 Trajectory View，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，可见 View 少于两个时隐藏会话 View 标签栏，隐藏新会话预设入口和「允许切换agent模式」设置行，并省略改动文件卡片及其摘要读取。其他插件注册的 View 保持可用。在 Trajectory 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
 
 插件组装层将共享偏好转换为组件自身的能力（`showCodeDiff`、`showPresetPicker` 和 `interactivePreview`）。Conversation 根据可见目标的 `toolCallFocus` 提供检查回调；Chat 不再指定目标名称。内置 HTML 渲染器使用 DOMPurify 清理完整文档并防护解析变异。关闭时保留根节点样式，移除主动文档、资源提示、SVG 动画及所有 `href` 属性，再放入不授予沙箱权限的 iframe，并通过 CSP 禁止脚本和外部资源。不读取关联文件。开启时保留不透明源的脚本 Blob 渲染器及其有界关联文件读取。切换模式会替换浏览上下文并清理待处理读取。[文档预览决策](../architecture/2026-09-08-document-preview-operations.zh.md)和[文件系统读取权限](../architecture/2026-09-09-workspace-file-read-authority.zh.md)继续定义高级渲染与 Host 读取访问。
 
@@ -26,4 +26,4 @@ Status: implemented
 
 基础 HTML 放弃 JavaScript、外部与关联资源和链接导航；行内样式与 data 图片仍可用。高级模式保留正常浏览器网络能力，不增加父源、弹窗、表单或顶层导航权限。此设置不约束第三方预览实现，也不撤销 Host 文件系统读取权限。
 
-组件和设置测试覆盖默认值、schema 拒绝、已接受状态更新、入口折叠、改动文件展示和 iframe 清理。基于已记录 Session 的[文档预览](../../../../apps/web/tests/document-preview.e2e.ts)与[改动文件](../../../../apps/web/tests/changed-files-turn.e2e.ts)场景验证真实设置控件及共用渲染器。浏览器脚手架默认开启开发者工具，仅设置外壳、文档预览、改动文件和开发者工具场景显式保留产品默认值；这些场景共同覆盖诊断控件隐藏、静态预览和切回 Chat。Host 拒绝写入后会恢复已接受状态，并显示本地化重试提示。原生 Electron 执行尚未验证。
+组件和设置测试覆盖默认值、schema 拒绝、已接受状态更新、入口折叠、改动文件展示和 iframe 清理。基于已记录 Session 的[文档预览](../../../../apps/web/tests/document-preview.e2e.ts)与[改动文件](../../../../apps/web/tests/changed-files-turn.e2e.ts)场景验证真实设置控件及共用渲染器。浏览器脚手架使用产品默认值，除非场景指定偏好。设置外壳、文档预览和改动文件场景显式关闭开发者工具；这些场景共同覆盖诊断控件隐藏、静态预览和切回 Chat。Host 拒绝写入后会恢复已接受状态，并显示本地化重试提示。原生 Electron 执行尚未验证。
diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml
index 70ee32d07a..bee0b26a39 100644
--- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md
-2026-09-17-sidebar-file-and-directory-auto-refresh.md: f33be6a8d45756d3bac83d0a6e21a4110543e3b2
-2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md: 88fe6e7abb4027ec8b5c4fab4f1ad07477aef6fa
+2026-09-17-sidebar-file-and-directory-auto-refresh.md: f509a8cf2642d3ca816d40e9e9817d3c962c79a6
+2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md: ff7a950aa86c663d4f5d2fb8e20d64bb2b077f6b
diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md
index f33be6a8d4..f509a8cf26 100644
--- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md
+++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md
@@ -38,11 +38,11 @@ Notifications invoke existing reload/list operations; a failed reload does not r
 
 | Class or type | File | Responsibility |
 |---|---|---|
-| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | Declare abstract single-target `watch(target, changed, signal)`: a file observes itself; a directory observes its direct entries. Resolve with an async close function once ready. Unsupported providers explicitly throw, without a new FS error code |
+| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | Declare single-target `watch(target, changed, signal)`: a file observes itself; a directory observes its direct entries. Resolve with an async close function once ready. The base implementation rejects `FS_IO_ERROR`, so a provider without watching states nothing and adds no FS error code |
 | `FsTarget` | [fs/src/types.ts](../../../../packages/fs/fs/src/types.ts) | Reuse the existing target type, without another FS watch-event system or upper-layer parsing of `targetKey` |
 | `LocalFileSystem` | [fs-local/src/index.ts](../../../../packages/fs/fs-local/src/index.ts) | Watches a file's parent with target-only filtering, or the directory itself for directory targets; awaits Chokidar readiness and closure; owns the Chokidar dependency |
 | `SandboxedFileSystem` | [fs-sandbox/src/index.ts](../../../../packages/fs/fs-sandbox/src/index.ts) | Inherit local read-only observation without duplicating the watcher; retain its write and edit policy checks |
-| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | `watch()` explicitly throws an ordinary exception; the Host converts it to a `workspace-file/watch-unsupported` `RemoteError`, without importing or checking an `FsError` runtime class across packages or passing remote `processPath()` values to local Chokidar |
+| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | Inherits the base `FS_IO_ERROR` rejection; the Host converts it to a `workspace-file/watch-unsupported` `RemoteError`, without importing or checking an `FsError` runtime class across packages or passing remote `processPath()` values to local Chokidar |
 | `WorkspaceFiles` | [workspace-files/src/index.ts](../../../../packages/api/workspace-files/src/index.ts) | Use `changes(scope, path, signal)` with only the target path. Host stat determines whether directory containment applies, including after type changes; ordinary files retain file-read authority |
 | `WorkspaceChangeFeed` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | Establish the target watch in the existing follow path and emit readiness and changes. Retain the queue and operation-observation input; filter by target before emission without rewriting dispatch |
 | `ChangeFollower` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | Receive operation observations and OS notifications; handle watch errors, close independently of generator pulls, and await watcher closure |
diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md
index 88fe6e7abb..ff7a950aa8 100644
--- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md
@@ -38,11 +38,11 @@ Sidebar 的 Document Preview 和 Files 面板都需要反映磁盘上的最新
 
 | 类或类型 | 所在文件 | 职责 |
 |---|---|---|
-| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | 声明抽象的单目标 `watch(target, changed, signal)` 方法；文件观察自身，目录观察直接子项；就绪后返回异步关闭函数，不支持的提供方显式抛异常，不新增 FS 错误码 |
+| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | 声明单目标 `watch(target, changed, signal)` 方法；文件观察自身，目录观察直接子项；就绪后返回异步关闭函数，基类以 `FS_IO_ERROR` 拒绝，不支持监听的提供方无需覆写，也不新增 FS 错误码 |
 | `FsTarget` | [fs/src/types.ts](../../../../packages/fs/fs/src/types.ts) | 沿用现有目标类型，不单独增加 FS 监听事件体系，也不让上层解析 `targetKey` |
 | `LocalFileSystem` | [fs-local/src/index.ts](../../../../packages/fs/fs-local/src/index.ts) | 文件监听其父目录并过滤到目标，目录监听自身；等待 Chokidar 就绪和关闭；依赖声明在 `fs-local` |
 | `SandboxedFileSystem` | [fs-sandbox/src/index.ts](../../../../packages/fs/fs-sandbox/src/index.ts) | 继承本地只读监听能力，不复制 watcher 实现；保留自身对写入、编辑的策略检查 |
-| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | `watch()` 显式抛出普通异常；Host 转成 `workspace-file/watch-unsupported` 的 `RemoteError`，不跨包导入或判断 `FsError` 实体，也不把远端 `processPath()` 传给本机 Chokidar |
+| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | 继承基类的 `FS_IO_ERROR` 拒绝；Host 将其转换为 `workspace-file/watch-unsupported` 的 `RemoteError`，不跨包导入或判断 `FsError` 实体，也不把远端 `processPath()` 传给本机 Chokidar |
 | `WorkspaceFiles` | [workspace-files/src/index.ts](../../../../packages/api/workspace-files/src/index.ts) | 使用仅携带目标路径的 `changes(scope, path, signal)`；Host stat 决定是否执行目录包含检查，目标类型变化后也检查，普通文件沿用文件读取权限 |
 | `WorkspaceChangeFeed` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | 在现有 follow 中建立目标 watch，发送就绪和变化；保留原队列与操作观察入口，出流前过滤目标，不重写整套分发逻辑 |
 | `ChangeFollower` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | 接收操作观察与 OS 通知，处理监听错误；关闭独立于生成器拉取进度，并等待 watcher 关闭完成 |
diff --git a/.agents/notes/implemented/feature/2026-09-20-default-workspace.i18n.yaml b/.agents/notes/implemented/feature/2026-09-20-default-workspace.i18n.yaml
new file mode 100644
index 0000000000..89b4d5dabf
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-default-workspace.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-20-default-workspace.md
+2026-09-20-default-workspace.md: 1674079403b17fb1bd984052a85975609179cad0
+2026-09-20-default-workspace.zh.md: 81a7c96efa3d8b8d4673b684b59babe339706f29
diff --git a/.agents/notes/implemented/feature/2026-09-20-default-workspace.md b/.agents/notes/implemented/feature/2026-09-20-default-workspace.md
new file mode 100644
index 0000000000..1674079403
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-default-workspace.md
@@ -0,0 +1,33 @@
+# Agent Note: First-use default Workspace
+
+Status: implemented
+
+English | [中文](2026-09-20-default-workspace.zh.md)
+
+## Problem
+
+A new installation requires a directory choice before the user can send a first message. Removing that prerequisite must preserve the Session's fixed working directory and must not treat hidden or archived history as a new installation.
+
+## Decision
+
+Startup waits for complete Workspace and Session baselines. When both lists are empty, the Client asks the Host to prepare the default Workspace, then creates or reuses and selects its blank Session. Input stays unavailable until a Session exists and uses the ordinary composer pipeline thereafter. [Session scope and provisioning](../architecture/2026-07-25-web-client-session-scope-and-provide-channel.md) owns blank-Session reuse and provisioning rationale.
+
+The [Workspace registry](../../../../packages/workspace/workspace/README.md#first-use-workspace) owns eligibility and directory preparation. All live Sessions, persisted headers, and archived identities count, including entries absent from the sidebar. The operation shares the registry mutation queue and rechecks Session history after directory preparation because Sessions can start independently.
+
+The Client resolves the initial directory name and title from its language at startup. The Host controller resolves the Documents location; the registry receives a directory resolver with no locale dependency. The resolver runs inside the mutation queue only for eligible creation, so repeated requests reuse the durable Workspace without another OS lookup. A durable Workspace id records successful initialization independently of that name. Renaming, changing language, restarting, or deleting the registration cannot initialize another default. The marker commits with the registration, so a failed registration can retry. Directory contents remain subject to the existing [metadata-only deletion policy](2026-07-27-workspace-registration-deletion.md).
+
+Ineligible first use returns no Workspace without a failure dialog. Preparation failure offers the existing folder picker; startup does not retry on later list notifications. A successful registration survives Session creation or prompt failure. Selecting either the default or a manually picked Workspace never submits a message.
+
+## Alternatives considered
+
+- Creating only when sending avoids unused directories but requires a separate local draft, transfer into a Session, and coordination of the first submission. Startup creation accepts the early filesystem effect and uses ordinary Session input throughout.
+- Falling back to `<home>/Documents` when system lookup is unavailable would choose an unverified Documents location; deployments that need another directory use the explicit Host override.
+- Inferring first use from visible sidebar rows would ignore archived, hidden, and cwd-less Sessions.
+- Using the localized path as the initialization marker would allow language changes or deletion to create another default.
+- Changing a Session's cwd after creation would change the meaning of its recorded tools and attachments.
+
+## Consequences
+
+Opening a new installation can create a directory and blank Session before the user sends a message. Directory authorization and preparation failures can appear during startup. Preparation remains a Host responsibility for both Desktop and remote Web clients, so remote users use the Host account's Documents location. Unavailable Documents lookup fails with the same folder-selection recovery as directory creation failure.
+
+The feature preserves [reference-owned Client Session lifetimes](../architecture/2026-09-15-client-session-references.md) and requires no agent-loop or Session-event change. Registry and client tests cover retries, hidden history, concurrency, and startup cancellation; the [browser scenario](../../../../apps/web/tests/default-workspace.e2e.ts) verifies the assembled startup, reload, first-send, and picker paths with an isolated Documents directory and recorded Session replay.
diff --git a/.agents/notes/implemented/feature/2026-09-20-default-workspace.zh.md b/.agents/notes/implemented/feature/2026-09-20-default-workspace.zh.md
new file mode 100644
index 0000000000..81a7c96efa
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-default-workspace.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 首次使用默认 Workspace
+
+Status: implemented
+
+[English](2026-09-20-default-workspace.md) | 中文
+
+## Problem
+
+新安装的应用要求用户先选目录才能发送第一条消息。去掉这一步前置操作时，必须保留 Session 的固定工作目录，也不能把隐藏或已归档的历史误判为新安装。
+
+## Decision
+
+启动时等待完整的 Workspace 和 Session 基线。两份列表均为空时，Client 请求 Host 准备默认 Workspace，随后创建或复用并选中其空白 Session。Session 存在前不可输入，之后使用常规 composer 流程。[Session scope 与供给通道](../architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md)负责 blank Session 复用与供给通道的理由。
+
+[Workspace registry](../../../../packages/workspace/workspace/README.zh.md#first-use-workspace)负责资格判断和目录准备。所有 live Session、持久化 header 和已归档身份都计入判断，包括侧栏中不可见的条目。操作共用 registry 修改队列，并在目录准备后重新检查 Session 历史，因为 Session 可以独立启动。
+
+Client 在启动时按其语言解析初始目录名和标题。Host 控制器解析 Documents 位置；注册表接收不依赖 locale 的目录解析器。解析器仅在允许创建时于变更队列内运行，因此重复请求直接复用持久化的 Workspace，无需再次查询操作系统目录。持久化 Workspace id 独立于名称记录初始化成功。改名、切换语言、重启或删除登记均不能再次初始化默认工作区。标记与登记一起提交，因此登记失败可以重试。目录内容仍遵循已有的[仅删除元数据策略](2026-07-27-workspace-registration-deletion.zh.md)。
+
+不符合首次使用条件时不返回 Workspace，也不显示失败弹窗。准备失败时提供现有文件夹选择器；后续列表通知不会触发启动流程重试。成功的登记会在 Session 创建或提示词发送失败后保留。选中默认或手动选择的 Workspace 均不会提交消息。
+
+## Alternatives considered
+
+- 仅在发送时创建可以避免未使用的目录，但需要独立的本地草稿、向 Session 转移草稿及首次提交协调逻辑。启动时创建接受提前写入文件系统的副作用，始终使用普通 Session 输入。
+- 系统查询不可用时回退到 `<home>/Documents`，会选择未经确认的 Documents 位置；需要其他目录的部署使用显式 Host 覆盖配置。
+- 根据侧栏可见行推断首次使用，会忽略已归档、隐藏和无 cwd 的 Session。
+- 将本地化路径作为初始化标记，会允许切换语言或删除后再次创建默认工作区。
+- 在 Session 创建后更改 cwd，会改变其已记录工具和附件的含义。
+
+## Consequences
+
+打开新安装的应用即可在用户发送消息前创建目录和空白 Session。目录授权与准备失败提示可能在启动期间出现。Desktop 和远程 Web 客户端均由 Host 准备目录，因此远程用户使用 Host 账户的 Documents 位置。Documents 查询不可用时，采用与目录创建失败相同的文件夹选择恢复路径。
+
+该功能保留[由引用持有的 Client Session 生命周期](../architecture/2026-09-15-client-session-references.zh.md)，无需修改 agent-loop 或 Session 事件。Registry 和客户端测试覆盖重试、隐藏历史、并发及启动取消；[浏览器场景](../../../../apps/web/tests/default-workspace.e2e.ts)通过隔离的 Documents 目录和已录制 Session 回放验证完整装配下的启动、刷新、首次发送与选择器路径。
diff --git a/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.i18n.yaml b/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.i18n.yaml
new file mode 100644
index 0000000000..254189ee9f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.md
+2026-09-20-desktop-browser-webview.md: e69114a90f50d51542e9b6a0d40daef05a93001f
+2026-09-20-desktop-browser-webview.zh.md: b0ab8b1a7058ae9cbb1258977cb4c4e2d8c40614
diff --git a/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.md b/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.md
new file mode 100644
index 0000000000..e69114a90f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.md
@@ -0,0 +1,59 @@
+# Agent Note: Retained Desktop browser webviews
+
+Status: implemented
+
+English | [中文](2026-09-20-desktop-browser-webview.zh.md)
+
+## Problem
+
+An iframe cannot expose cross-origin navigation or render sites that refuse embedding. An Electron guest loses forms, scroll position and native history if its tab body unmounts on selection or container changes. Page lifetime must therefore remain independent of visibility and layout changes.
+
+Independent per-tab storage also prevents related pages in one Workspace from sharing site login state. Page lifetime and storage ownership need different owners.
+
+## Decision
+
+Desktop uses `<webview>` through `ElectronWebViewImpl`; Web retains its opt-in iframe carrier. The [Sidebar Browser decision](2026-09-16-sidebar-browser.md) owns shared tab behavior and iframe limitations; this note owns the Desktop carrier and Workspace-keyed partitions.
+
+The [stable Sidebar mounting decision](../architecture/2026-09-20-sidebar-retained-tab-layout.md) owns retained Session and tab containers in real CSS layout. Workspace storage ownership and baseline guest security remain with this note.
+
+- `BrowserController` owns address commands and recoverable presentation state. Native history stays in the guest; actual URL and title observations update the persisted address.
+- Controller registries are keyed by DSH Session, independently of presentation bindings. Rebinding replaces the store writer without recreating the page.
+- `electron/pages.ts` composes the Electron navigation provider and presentation object. `ElectronWebViewImpl` owns guest leases and native navigation; `ElectronWebviewPresentation` creates the tag and attaches it inside the Sidebar-owned content container.
+- The Desktop Browser type declares `keepMounted`. Sidebar retains its DOM ancestors across hiding and docking; CSS owns layout and clipping. Docking gestures disable guest pointer input, and body-local drop hints use normal stacking. A physical unmount cancels pending attachment and releases the guest; a later mount recreates it from the known address.
+- Tab occurrence cancellation, plugin unload and window destruction release guests. Guest crashes leave a retryable failure; Reload creates a new guest. Application restart offers the saved title and URL for explicit restoration; it creates no guest until the user restores or submits an address. Page memory and native history are not restored.
+
+The standard `./types` subpath exports the shared lease, reservation, open-request and bridge declarations through a declaration-only `types` condition; Desktop consumers use `import type`. There is no runtime default, extra JavaScript artifact or early Host bundling for these declarations. Preload exposes scoped operations and callbacks, not raw IPC or Electron objects.
+
+Browser has separate Host and Client compiler programs. Desktop and the Host aggregate reference only `tsconfig.host.json`, which compiles the package root and shared bridge declarations; the Client aggregate references `tsconfig.client.json` for the browser implementation. The package root tsconfig is solution-only. This keeps Client consumers of generated `/remote` declarations out of the Host compilation that precedes Typert generation.
+
+### Storage ownership
+
+`DesktopBrowserGuests` assigns a random, non-persistent Electron partition to each canonical CWD account. The Client uses the Host-normalized `WorkspaceView.path`, not the Workspace record UUID, so recreating a Workspace at the same directory does not change its storage account key. Browser tabs whose DSH Sessions resolve to that CWD share the account; Sessions without a resolved Workspace remain separately isolated. Workspace membership is resolved after the Client receives its authoritative baseline and is fixed for a guest occurrence. The CWD key controls sharing, not disk persistence.
+
+Closing a tab releases its guest, not its account's cookies or storage. Cookies, localStorage, IndexedDB, Service Workers and cache remain partition-owned and subject to normal origin rules. DOM, native history and sessionStorage remain page-owned. Account partitions survive window recreation within the Electron process but do not persist across application exit.
+
+### Initial guest policy
+
+Only the primary application window enables `webviewTag`. The main process accepts guest reservations only from that window's application top frame and validates a one-use lease, partition and inert initial `about:blank` document before allowing the guest. The main process replaces renderer-supplied preferences: no Node integration, guest preload, nested webviews, plugins, insecure content, dialogs or drag navigation; sandbox, context isolation and Web security stay enabled.
+
+Guest Sessions do not register the application protocol or inherit the application's authenticated request forwarding. Permission requests and checks, device access, display capture, downloads, native popup windows and HTTP authentication prompts are denied. Approved direct HTTP(S) popup requests without a POST body are routed through their live lease to a new Sidebar tab; scripted blank-window and POST popup flows remain unsupported. Navigation accepts credential-free HTTP(S); request filtering rejects local-file and privileged schemes and the known DSH Host endpoint, including common loopback aliases. This is not a general private-network or DNS-rebinding firewall.
+
+The Desktop toolbar has no sandbox-disable switch. The implementation adds no remote-debugging endpoint or browser-use integration. A future automation provider requires an authenticated, target-scoped broker rather than access to every application target. The separation of a target/lifetime handle from navigation commands follows the same distinction as Playwright's Android WebView and Page objects; device-level input is a separate responsibility.
+
+## Alternatives considered
+
+**Render the guest in a visibility-mounted tab body.** Unmounting disconnects the guest. Direct mounting requires the Sidebar's retained body and stable ancestor mechanism.
+
+**Move the guest between visible and hidden DOM containers.** Electron 44's `WebViewElement.disconnectedCallback` detaches the guest and resets its internal instance. Retaining the element reference or React key does not preserve that instance; the parent stays fixed instead.
+
+**Use one partition per tab.** This isolates site accounts between related pages. Workspace ownership provides the requested sharing without sharing the application Session; a tab still owns its own guest.
+
+**Change the partition of an active webview.** Electron fixes the partition before first navigation. Selecting another isolation scope requires a replacement guest and an explicit policy for existing site data, not a live attribute toggle.
+
+## Consequences
+
+Sidebar-owned stable ancestors preserve the page without Browser-owned geometry or occlusion handling. Hidden guests retain page memory and may continue network activity; there is no idle eviction policy. Persistent storage, selectable isolation scopes and permission-grant UI remain separate work. Temporary Workspace partitions are the current policy, not a promise that Workspace isolation always implies temporary storage.
+
+Focused tests cover native navigation error recovery, preload listener scoping and migrated iframe behavior. They do not establish real Electron attachment timing, overlap, focus, platform styling or storage isolation; those remain runtime verification gaps. No GUI recording accompanies the change. This implementation is not evidence that the complete browser security policy is ready for release.
+
+The package's Electron provider, presentation, page factory and Workspace storage resolver live in `src/client/electron/`. That directory is temporarily excluded from per-file coverage until a native Electron harness covers guest behavior; its unit tests still run. Shared Browser controllers, restoration UI, iframe code and Sidebar retention remain subject to the existing coverage requirements.
diff --git a/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.zh.md b/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.zh.md
new file mode 100644
index 0000000000..b0ab8b1a70
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.zh.md
@@ -0,0 +1,59 @@
+# Agent Note: 保持页面实例的 Desktop 浏览器 webview
+
+Status: implemented
+
+[English](2026-09-20-desktop-browser-webview.md) | 中文
+
+## Problem
+
+iframe 无法提供跨域导航状态, 也无法显示拒绝嵌入的站点. 如果 Tab Body 因选中项或容器变化而卸载, Electron guest 就会丢失表单、滚动位置与原生 history. 页面生命周期因此必须独立于可见性和布局变化.
+
+独立的 per-tab 存储也会阻止同一 Workspace 内相关页面共享站点登录态。页面生命周期与存储需要不同的所有者。
+
+## Decision
+
+Desktop 通过 `ElectronWebViewImpl` 使用 `<webview>`; Web 保留显式启用的 iframe 载体. [Sidebar Browser 决策](2026-09-16-sidebar-browser.zh.md)负责共享 Tab 行为与 iframe 限制; 本文负责 Desktop 载体和按 Workspace 共享的分区.
+
+[Sidebar 稳定挂载决策](../architecture/2026-09-20-sidebar-retained-tab-layout.zh.md)负责真实 CSS 布局中的保活会话与 Tab 容器。Workspace 存储所有权与 guest 基础安全配置仍由本文负责。
+
+- `BrowserController` 负责地址命令与可恢复的展示状态。原生 history 留在 guest 内；真实 URL 与标题观察更新持久化地址。
+- 控制器注册表按 DSH Session 索引，不依赖呈现绑定的存活期。重新绑定只替换存储写入方，不重建页面。
+- `electron/pages.ts` 组装 Electron 导航提供方和呈现对象. `ElectronWebViewImpl` 负责 guest 租约与原生导航; `ElectronWebviewPresentation` 创建标签并挂载到 Sidebar 持有的内容容器内.
+- Desktop Browser 类型声明 `keepMounted`。Sidebar 在隐藏和停靠切换时保留其 DOM 祖先，CSS 负责布局与裁剪。停靠手势期间禁用 guest 指针输入，Body 内的放置提示使用普通层叠。物理卸载会取消未完成的挂载并释放 guest，之后重新挂载时从已知地址重建。
+- tab occurrence 取消、插件卸载与窗口销毁会释放 guest。guest 崩溃留下可重试的失败状态；刷新创建新 guest。应用重启展示保存的标题与 URL，等待显式恢复；用户恢复或提交地址之前不创建 guest。不恢复页面内存或原生 history。
+
+标准 `./types` 子路径通过仅指向声明文件的 `types` 条件导出共享的租约、申请结果、打开请求与桥接声明，Desktop 消费方使用 `import type`。这些声明没有运行时 default、额外 JavaScript 产物或提前进行的 Host 打包。preload 只暴露限定范围的操作与回调，不暴露原始 IPC 或 Electron 对象。
+
+Browser 分别拥有 Host 与 Client 编译程序。Desktop 和 Host 聚合配置只引用 `tsconfig.host.json`，编译包根与共享桥接声明；Client 聚合配置通过 `tsconfig.client.json` 编译浏览器实现。包根 tsconfig 只作为 solution。这样，依赖生成 `/remote` 声明的 Client 消费方不会进入 Typert 生成之前的 Host 编译阶段。
+
+### Storage ownership
+
+`DesktopBrowserGuests` 为每个规范化 CWD 存储账号分配随机、非持久化的 Electron partition。Client 使用 Host 规范化后的 `WorkspaceView.path`，不使用 Workspace 记录 UUID，因此在同一目录重建 Workspace 不改变存储账号 key。DSH Session 解析到同一 CWD 的 Browser Tab 共享账号；没有可解析 Workspace 的 Session 仍单独隔离。Workspace 归属在 Client 收到权威基线后解析，并在一次 guest occurrence 内保持不变。CWD key 控制共享关系，不决定是否落盘。
+
+关闭 tab 只释放它的 guest，不清空账号的 Cookie 或存储。Cookie、localStorage、IndexedDB、Service Worker 与缓存由 partition 持有，并继续遵循普通 origin 规则。DOM、原生 history 与 sessionStorage 仍由页面持有。账号 partition 在同一 Electron 进程内重建窗口后仍保留，但不跨应用退出持久化。
+
+### Initial guest policy
+
+只有主应用窗口启用 `webviewTag`。主进程只接受该窗口应用顶层 frame 发起的 guest 申请，并在放行前校验一次性租约、partition 与无活动内容的初始 `about:blank` 文档。主进程替换 renderer 提供的偏好：不启用 Node integration、guest preload、嵌套 webview、plugin、不安全内容、模态对话框或拖放导航；sandbox、context isolation 与 Web security 保持开启。
+
+guest Session 不注册应用协议，也不继承应用的认证请求转发。权限请求与检查、设备访问、屏幕捕获、下载、原生弹窗与 HTTP 认证提示全部拒绝。通过检查且不带 POST body 的直接 HTTP(S) 弹窗请求，通过活动租约路由为新 Sidebar Tab；脚本操作空白窗口和 POST 弹窗流程仍不支持。导航接受不带内嵌凭据的 HTTP(S)；请求过滤拒绝本地文件、特权协议与已知 DSH Host 地址，包括常见 loopback 别名。这不是通用的私有网络或 DNS rebinding 防火墙。
+
+Desktop toolbar 没有关闭 sandbox 的开关。实现不增加远程调试端口或 browser-use 集成。未来的自动化提供方需要经过认证、限定 target 的 broker，而不是访问全部应用 target。把 target/生命周期句柄与导航命令分开的方式，与 Playwright 的 Android WebView 和 Page 对象区分相同；设备级输入属于另一项职责。
+
+## Alternatives considered
+
+**在按可见性挂载的 tab body 内渲染 guest。** 卸载会断开 guest；直接挂载需要 Sidebar 提供 Body 保活与稳定祖先机制。
+
+**在可见与隐藏 DOM 容器之间搬移 guest。** Electron 44 的 `WebViewElement.disconnectedCallback` 会 detach guest 并重置内部实例。保留元素引用或 React key 不能保留该实例，因此父节点保持固定。
+
+**每个 tab 使用独立 partition。** 这会隔离相关页面的站点账号。Workspace 所有权提供所需的共享，同时不共享应用 Session；每个 tab 仍拥有独立 guest。
+
+**修改活动 webview 的 partition。** Electron 在首次导航前确定 partition。选择其他隔离粒度需要替换 guest，并明确已有站点数据的处置策略，而不是实时切换属性。
+
+## Consequences
+
+Sidebar 持有的稳定祖先保留页面，无需 Browser 自行处理几何或遮挡。隐藏 guest 保留页面内存，也可能继续联网；当前没有空闲回收策略。持久化存储、可选择的隔离级别与权限授权 UI 留作独立工作。临时 Workspace partition 是当前策略，并不意味着 Workspace 隔离必然要求临时存储。
+
+定向测试覆盖原生导航错误恢复、preload 监听范围和已迁移的 iframe 行为。这些测试不能确认真实 Electron 的挂载时序、遮挡、焦点、平台样式或存储隔离；这些仍是运行时验证缺口。本次变更不附带 GUI 录像。此实现不构成完整浏览器安全策略已经可以发布的证据。
+
+包内的 Electron 提供方、呈现适配器、页面工厂与 Workspace 存储解析集中在 `src/client/electron/`. 在原生 Electron 测试环境覆盖 guest 行为之前, 该目录暂时不参与逐文件覆盖率门禁; 其单元测试仍然运行. 共享 Browser 控制器、恢复 UI、iframe 代码和 Sidebar 保活仍遵循现有覆盖率要求.
diff --git a/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.i18n.yaml b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.i18n.yaml
new file mode 100644
index 0000000000..aa7199eff4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md
+2026-09-20-developer-tools-default-on.md: 42c89faed11b966ac8ea0882236af9bf13557702
+2026-09-20-developer-tools-default-on.zh.md: a684844f5ba53a0bebdd1c3a3a3ade1ed150cc31
diff --git a/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md
new file mode 100644
index 0000000000..42c89faed1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.md
@@ -0,0 +1,31 @@
+# Agent Note: Developer tools default on after preference resolution
+
+Status: implemented
+
+English | [中文](2026-09-20-developer-tools-default-on.zh.md)
+
+## Problem
+
+New installations need access to developer views, preset selection, change summaries and interactive HTML previews without first finding a Settings switch. A saved disabled preference must still prevent those features from activating during startup, including script execution that cannot be undone after it occurs.
+
+## Decision
+
+The Host schema defaults `ui-developer-tools.enabled` to `true`. Remote browsers with process-local preferences also start enabled. Saved Host values take precedence, including `false`. This supersedes only the initial default-off choice in [Shared developer-tool settings](2026-09-17-developer-tools-settings.md); that note retains ownership of shared persistence and rendering policy.
+
+Host-backed clients publish disabled until an accepted schema-resolved value arrives. Loading, failed initial reads and an unavailable namespace do not grant interactive-preview capabilities. The Host supplies the default for an absent stored field; the client does not interpret an absent response as consent to enable scripts. An accepted value remains authoritative during later refreshes.
+
+Only the Trajectory tab follows the developer-tools preference; third-party Views remain available. The conversation shell retains the explicit Trajectory id because the requested rule names that View. No current requirement makes arbitrary diagnostic Views share the switch.
+
+## Alternatives considered
+
+**Keep the default off.** This minimizes the initial interface but requires a separate opt-in for the features new installations now expose. Users can still save the disabled preference.
+
+**Default the Host client to enabled before settings arrive.** This makes rendering immediate, but briefly activates features for users who disabled them. Unmounting a scripted HTML iframe cannot undo scripts or requests already executed.
+
+**Add a generic developer-tool flag to View registration.** This expands the plugin API and allows other Views to join a switch whose current requirement is specific to Trajectory. A future requirement can justify that API separately.
+
+## Consequences
+
+Fresh profiles expose developer features after settings resolve; users with a saved disabled choice retain the simpler presentation. New users also receive interactive HTML previews with the capabilities documented by the [filesystem-read authority](../architecture/2026-09-09-workspace-file-read-authority.md). Host initialization can briefly withhold developer controls even when the eventual preference is enabled.
+
+Settings tests cover initial withholding, unavailable namespaces, explicit disabled values and process-local defaults. HTML renderer coverage checks that pending and disabled preferences neither read related files nor create script-enabled frames. Browser settings coverage verifies the default and a disabled choice across reload; document-preview replay pins the explicitly disabled scenario.
diff --git a/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md
new file mode 100644
index 0000000000..a684844f5b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-20-developer-tools-default-on.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: 偏好解析后默认开启开发者工具
+
+Status: implemented
+
+[English](2026-09-20-developer-tools-default-on.md) | 中文
+
+## Problem
+
+新安装需要直接使用开发者视图、预设选择、改动摘要和交互式 HTML 预览，无需先寻找设置开关。已保存的关闭偏好仍必须阻止这些功能在启动期间激活，包括发生后无法撤销的脚本执行。
+
+## Decision
+
+Host schema 将 `ui-developer-tools.enabled` 默认为 `true`。使用进程内偏好的远程浏览器也从开启状态启动。已保存的 Host 值优先，包括 `false`。这仅取代[共享开发者工具设置](2026-09-17-developer-tools-settings.zh.md)中最初默认关闭的选择；该记录继续负责共享持久化和渲染策略。
+
+使用 Host 偏好的客户端在收到经过 schema 解析并接受的值之前发布关闭状态。加载中、首次读取失败和命名空间不可用均不授予交互式预览能力。缺少存储字段时由 Host 提供默认值；客户端不会把缺少响应解释为允许开启脚本。后续刷新期间，已接受的值继续有效。
+
+只有 Trajectory 标签页受开发者工具偏好控制；第三方 View 保持可用。对话外壳保留显式 Trajectory id，因为当前需求明确指定此 View。没有现行需求要求任意诊断 View 共用该开关。
+
+## Alternatives considered
+
+**保持默认关闭。** 这可简化初始界面，但新安装现在直接提供的功能将需要额外启用。用户仍可保存关闭偏好。
+
+**在设置到达前让 Host 客户端默认开启。** 这可以立即渲染，却会短暂激活用户已关闭的功能。卸载可执行脚本的 HTML iframe 无法撤销已经执行的脚本或请求。
+
+**在 View 注册中增加通用开发者工具标记。** 这会扩展插件 API，并允许其他 View 加入当前仅针对 Trajectory 的开关。未来需求可以单独论证该 API。
+
+## Consequences
+
+新 profile 在设置解析后展示开发者功能；已保存关闭选择的用户保留简化展示。新用户也会获得带有[文件系统读取权限](../architecture/2026-09-09-workspace-file-read-authority.zh.md)所述能力的交互式 HTML 预览。即使最终偏好为开启，Host 初始化期间也可能短暂不展示开发者控件。
+
+设置测试覆盖首次等待、命名空间不可用、显式关闭值和进程内默认值。HTML 渲染器覆盖验证等待中及关闭偏好均不读取关联文件，也不创建允许脚本的 frame。浏览器设置覆盖验证默认值和关闭选择在刷新后保持；文档预览回放固定显式关闭的场景。
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index 11b7e048f6..c92bdd5546 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
-2026-07-30-generated-third-party-notices.md: 2b0bd012c23c873b3003916491daad467cf757b3
-2026-07-30-generated-third-party-notices.zh.md: 0c7b4df8edb60f2f70781e179edc7377da930128
+2026-07-30-generated-third-party-notices.md: 71f1fd0a5b650d53c5ef21438e17e0a6e162bdf5
+2026-07-30-generated-third-party-notices.zh.md: e3adb43e4b407945a8cca88105de689407b5908b
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
index 2b0bd012c2..71f1fd0a5b 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
@@ -12,13 +12,13 @@ A hand-written inventory answers none of those durably. Roughly a hundred rows o
 
 ## Decision
 
-[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, `pnpm-workspace.yaml`, and the [Desktop runtime lock](../../../../apps/desktop/scripts/primary-runtime-lock.json). The root README pair links the file from its License section.
+[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) is generated by [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) from the workspace manifests, `vendor/README.md`, the `pyproject.toml` files, `pnpm-workspace.yaml`, and the [shared runtime lock](../../../../scripts/primary-runtime/lock.json). The root README pair links the file from its License section.
 
-**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, a workspace declaration, the root or Desktop runtime lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check.
+**Freshness is maintained, not merely enforced.** A pre-commit job regenerates the file and stages it whenever a generator input is staged — any manifest, a workspace declaration, the root or shared runtime lock file, `vendor/README.md`, a `pyproject.toml`, the generator itself, or the script holding the build-time pin — so an unrelated dependency edit never has to come back and rerun a generator. The committed bytes are then asserted inside [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts), which the test lane already runs — the check adds no gate process, no scheduler slot, and no separate CI step. `pnpm run verify-third-party-notices` remains available for a standalone check.
 
 One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case.
 
-The file discloses **direct** dependencies by default; complete npm and Python SDK closures remain in their lock files. Two separately distributed payload sets receive explicit entries: the official Claude executable packages declared by `@anthropic-ai/claude-agent-sdk`, and every distribution in the Desktop runtime lock's `pythonPackages`. Desktop entries include normalized names, exact versions, and recorded license metadata; missing metadata, duplicate normalized names and conflicting normalized versions fail generation. The Desktop wheel set is independent of the `python/` manifests, so scanning only those manifests would omit the packaged Office libraries. Desktop distributions also pass the runtime license check, including the permissive `MIT-CMU` and `PSF-2.0` identifiers declared by Pillow and typing-extensions.
+The file discloses **direct** dependencies by default; complete npm and Python SDK closures remain in their lock files. Two separately distributed payload sets receive explicit entries: the official Claude executable packages declared by `@anthropic-ai/claude-agent-sdk`, and every distribution in the shared runtime lock's `pythonPackages`. Bundled entries include normalized names, exact versions, and recorded license metadata; missing metadata, duplicate normalized names and conflicting normalized versions fail generation. The shared wheel set is independent of the `python/` manifests, so scanning only those manifests would omit the packaged Office libraries. Bundled distributions also pass the runtime license check, including the permissive `MIT-CMU` and `PSF-2.0` identifiers declared by Pillow and typing-extensions.
 
 **Tiering follows distribution, not manifest section.** Installed runtime libraries are identified by `dependencies` or `optionalDependencies` outside `DEV_ONLY_AREAS` — the root manifest, `packages/test-support/`, `packages/test-support/client-runtime/`, `website/`, `native/`. Browser inputs resolved by the shipping tsdown and Vite configurations also count as runtime, even in `devDependencies`; [browser third-party build inputs](2026-09-08-browser-third-party-build-inputs.md) owns that classification. Test-support dependencies do not ship merely because their manifest says `dependencies`, and the generator explicitly discloses `tsx` because source launches execute through its ESM hook.
 
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 0c7b4df8ed..e3adb43e4b 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -12,13 +12,13 @@ Status: implemented
 
 ## 决策
 
-[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区 manifest、`vendor/README.md`、`pyproject.toml`、`pnpm-workspace.yaml` 与 [Desktop 运行时锁文件](../../../../apps/desktop/scripts/primary-runtime-lock.json)生成。根 README 双语两侧都从「许可证」一节链到该文件。
+[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 由 [`scripts/gen-third-party-notices.ts`](../../../../scripts/gen-third-party-notices.ts) 依据各工作区 manifest、`vendor/README.md`、`pyproject.toml`、`pnpm-workspace.yaml` 与 [共享运行时锁文件](../../../../scripts/primary-runtime/lock.json)生成。根 README 双语两侧都从「许可证」一节链到该文件。
 
-**新鲜度会得到维护，而非仅靠校验。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件或 Desktop 运行时锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
+**新鲜度会得到维护，而非仅靠校验。** 只要暂存了生成器的任一输入——任何 manifest、工作区声明、根锁文件或共享运行时锁文件、`vendor/README.md`、某个 `pyproject.toml`、生成器自身，或持有构建期 pin 的脚本——pre-commit 任务就会重新生成该文件并将其暂存，改依赖的人不必事后再折返跑一次生成器。已提交的字节随后由 [`scripts/gen-third-party-notices.spec.ts`](../../../../scripts/gen-third-party-notices.spec.ts) 断言，而测试 lane 本就会跑这个文件——这项校验不增加门禁进程、不占调度位、也不新增 CI 步骤。需要单独校验时，`pnpm run verify-third-party-notices` 仍然可用。
 
 有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除** manifest 不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
-文件默认只披露**直接**依赖；完整的 npm 与 Python SDK 闭包保留在各自锁文件中。两组独立分发的载荷会明确列出：`@anthropic-ai/claude-agent-sdk` 声明的官方 Claude 可执行包，以及 Desktop 运行时锁文件 `pythonPackages` 中的每个分发包。Desktop 条目包含归一化名称、精确版本和已记录的许可证元数据；元数据缺失、归一化后名称重复或版本冲突都会使生成失败。Desktop wheel 集合独立于 `python/` 下的 manifest，仅扫描后者会遗漏已打包的 Office 库。Desktop 分发包同样通过运行时许可证检查，其中包括 Pillow 与 typing-extensions 声明的宽松许可证标识 `MIT-CMU` 和 `PSF-2.0`。
+文件默认只披露**直接**依赖；完整的 npm 与 Python SDK 闭包保留在各自锁文件中。两组独立分发的载荷会明确列出：`@anthropic-ai/claude-agent-sdk` 声明的官方 Claude 可执行包，以及共享运行时锁文件 `pythonPackages` 中的每个分发包。内置条目包含归一化名称、精确版本和已记录的许可证元数据；元数据缺失、归一化后名称重复或版本冲突都会使生成失败。共享 wheel 集合独立于 `python/` 下的 manifest，仅扫描后者会遗漏已打包的 Office 库。内置分发包同样通过运行时许可证检查，其中包括 Pillow 与 typing-extensions 声明的宽松许可证标识 `MIT-CMU` 和 `PSF-2.0`。
 
 **分层依据是分发内容，而非 manifest 字段名。** 安装的运行时库由 `DEV_ONLY_AREAS` 之外的 `dependencies` 或 `optionalDependencies` 识别；排除区域为根 manifest、`packages/test-support/`、`packages/test-support/client-runtime/`、`website/`、`native/`。发布所用的 tsdown 与 Vite 配置解析到的浏览器输入也属于运行时，即使它们位于 `devDependencies`；[浏览器第三方构建输入](2026-09-08-browser-third-party-build-inputs.zh.md)拥有这项分类。测试支撑依赖不会仅因字段写成 `dependencies` 就被交付，而生成器显式披露 `tsx`，因为源码启动通过其 ESM 钩子执行。
 
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
index 94e92c9bac..969ab3fd9e 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages 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-09-11-persistence-type-history.md
-2026-09-11-persistence-type-history.md: c7cddea5ecc479a64ad5f24f5447e869779b7f9e
-2026-09-11-persistence-type-history.zh.md: 001ce197c4cd12dc64a5e2bd710e39cb2b61f23a
+2026-09-11-persistence-type-history.md: 87e87041dd44c4f671409a75c1b374312736342a
+2026-09-11-persistence-type-history.zh.md: cfe5c4f7bd1998d4329dc422607cfe33273d1a5a
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
index c7cddea5ec..87e87041dd 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
@@ -14,7 +14,7 @@ One normalized type model supplies the readable persistence catalog, the complet
 
 The dedicated [persistence-change records](../../../../docs/persistence-changes/README.md) bind acknowledgement to the after digest of each affected root. A generated companion stores complete after schemas. The initial record covers all roots; later records name each root's predecessor. A predecessor's after schema supplies the next before schema. Verification rejects ambiguous history and requires current source to match the terminal recorded state without consulting Git history or remote services.
 
-Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. Other structural changes require a version-bump decision that includes an increasing header version in that record. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) continues to own adjacent migration work. Every structural difference requires an explicit record, including additions allowed within the same version.
+Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. The [event-payload version rule](../../../../docs/persistence-changes/README.md#compatibility-rules) admits higher numeric payload versions when every old alternative remains unchanged and records the older-reader limitation. Other structural changes require a version-bump decision that includes an increasing header version in that record. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) continues to own adjacent migration work. Every structural difference requires an explicit record, including additions allowed within the same version.
 
 The new document kind preserves the compatibility reasoning and evidence for a historical type transition. Agent Notes retain mechanism-level decisions; they do not become a growing inventory of individual acknowledgements. Machine declarations remain identical across the bilingual pair and are parsed once.
 
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
index 001ce197c4..cfe5c4f7bd 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 专用的[持久化变更记录](../../../../docs/persistence-changes/README.zh.md)将确认绑定到每个受影响根的变更后摘要。生成的伴随文件保存完整的变更后 schema。初始记录覆盖所有根；后续记录为每个根指定前驱。前驱的变更后 schema 提供下一次的变更前 schema。验证拒绝有歧义的历史，并要求当前源码匹配最终记录状态，无需查询 Git 历史或远端服务。
 
-自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。其他结构变更需要升版本决策，并在该记录中包含递增的头部版本。[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)继续负责相邻迁移工作。每个结构差异都需要显式记录，包括允许保持同一版本的新增。
+自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。[事件载荷版本规则](../../../../docs/persistence-changes/README.zh.md#compatibility-rules) 允许在原样保留所有旧分支时增加更高的数字载荷版本，并记录旧读取器限制。其他结构变更需要升版本决策，并在该记录中包含递增的头部版本。[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)继续负责相邻迁移工作。每个结构差异都需要显式记录，包括允许保持同一版本的新增。
 
 新文档类型保留历史类型转换的兼容性说明和证据。Agent Note 保留机制层面的决策，不积累单次确认清单。双语对中的机器声明保持相同，且只解析一次。
 
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
index b2f71a9f4d..0ace5db1f2 100644
--- a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
-2026-09-17-windows-runtime-signature-cache.md: 911e0277199bac55165fbc4adebb22e2599043b9
-2026-09-17-windows-runtime-signature-cache.zh.md: bb8cdd6bdca445c94e8e77cddb68008d7b27f7ad
+2026-09-17-windows-runtime-signature-cache.md: e9229e47929664984a92499e54f87bb2166bde9d
+2026-09-17-windows-runtime-signature-cache.zh.md: 53b6182170d807843345fa90f962ee18807f2cf2
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
index 911e027719..e9229e4792 100644
--- a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
@@ -20,6 +20,8 @@ Serialize each complete signing stage and cache-maintenance operation with an ex
 
 Group public-key inspection into bounded batches of 32 files with at most four processes. Require one ordered result for every requested path and await every process in a failed batch. Preserve verification immediately after each hardware signature, before the next signing request.
 
+Within the stage lock, restore distinct cache-hit targets with a bounded worker pool and complete their post-verification before serially signing misses. Stop dispatch on the first restore, verification or audit failure and drain active workers before releasing ownership. Four workers are the configurable default: warm-cache experiments on 134 primary-runtime and 228 application files reduce combined median restore-plus-post-verification time from 226.18 seconds at one worker to 63.22 seconds at four; eight takes 42.18 seconds but increases measured CPU by 25.5% and peak committed memory from 387 to 631 MiB. These three-repeat measurements use exact reconstructed unsigned inputs, real Windows verification and a rejecting hardware callback; they exclude full packaging, cold trust state and hardware misses.
+
 The [primary-runtime decision](../feature/2026-09-14-desktop-primary-runtime.md) continues to own runtime contents, vendor-signature preservation and execution checks. The [release decision](../architecture/2026-08-25-electron-desktop-packaging-and-updates.md) continues to own release identity and signing. Neither is superseded. The cache must preserve their supervised preflight, per-user signing interlock, single-file hardware calls, signed inventory and final packaged-runtime validation.
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
index bb8cdd6bdc..53b6182170 100644
--- a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
@@ -20,6 +20,8 @@ Windows 打包每次都会重新生成未签名的原生依赖。为未变化的
 
 公钥验签按每批 32 个文件分组，最多同时运行四个进程。要求每个请求路径都有一条顺序对应的结果，并等待失败批次中的所有进程退出。每次硬件签名后仍立即验签，通过后才开始下一个签名请求。
 
+在阶段锁内，使用有界工作池恢复不同的缓存命中目标，完成后置验签后才串行签署未命中项。首次恢复、验签或审计失败时停止派发，并在释放所有权前等待在途任务结束。可配置的默认并发为四：对 134 个主要运行时文件及 228 个应用文件的热缓存实验中，恢复加后置验签的合计中位耗时从单任务的 226.18 秒降至四任务的 63.22 秒；八任务为 42.18 秒，但实测 CPU 消耗增加 25.5%，峰值提交内存从 387 增至 631 MiB。这些三轮测量使用精确重建的未签名输入、真实 Windows 验签和拒绝硬件调用的回调；不包含完整打包、冷信任状态或硬件未命中。
+
 [主要运行时决策](../feature/2026-09-14-desktop-primary-runtime.zh.md) 继续定义运行时内容、厂商签名保留和执行检查。[发布决策](../architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md) 继续定义发布身份和签名。两者均未被取代。缓存必须保留受监督预检、每用户签名互锁、单文件硬件调用、已签名内容清单和最终打包运行时验证。
 
 ## Alternatives considered
diff --git a/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.i18n.yaml
new file mode 100644
index 0000000000..07287b00f8
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.md
+2026-09-19-deepseek-messages-only.md: c10ecae950bb12f4556021de21c9716ad2906227
+2026-09-19-deepseek-messages-only.zh.md: 3cfadac6ebc0b4bb1587a8b72e9b169d2ade2ee9
diff --git a/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.md b/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.md
new file mode 100644
index 0000000000..c10ecae950
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.md
@@ -0,0 +1,25 @@
+# Agent Note: One Messages transport for the official DeepSeek route
+
+Status: implemented
+
+English | [中文](2026-09-19-deepseek-messages-only.zh.md)
+
+## Problem
+
+The official DeepSeek route needs Messages thinking replay, image uploads, and in-history updates. Selecting a second transport duplicates serializers, stream handling, Files wire formats, configuration branches, and fixtures without adding a required capability to this route.
+
+## Decision
+
+`dsh-llm-deepseek` uses Messages exclusively. One adapter resolves a request-local configuration snapshot and performs the request. Configuration exposes one endpoint and no protocol selector. The Files client uses Messages authentication, metadata, and pagination directly; quota cleanup scans every page before selecting the oldest owned files.
+
+The [Messages adapter decision](../feature/2026-09-07-deepseek-messages-adapter.md) continues to own native thinking replay, system-message placement, image recovery, and request-extension acceptance. Replay discriminators and upload-index namespaces identify durable data and retain their existing values. The separate pi-ai adapter retains its provider-specific protocols.
+
+## Alternatives considered
+
+**Keep Chat Completions behind an optional selector.** This retains the duplicated implementation and test matrix even though the official route requires only Messages.
+
+**Keep a generic protocol dispatcher with one implementation.** The dispatcher adds a second dependency representation and forwards every adapter operation without selecting anything.
+
+## Consequences
+
+The official route requires a Messages-compatible endpoint. Its mock-backed recovery, Loader, CLI, and Web tests exercise Messages; removing a wire implementation does not remove those behavior checks. Committed Session generations remain readable through provider-neutral content and the retained Messages replay metadata.
diff --git a/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.zh.md b/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.zh.md
new file mode 100644
index 0000000000..3cfadac6eb
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-09-19-deepseek-messages-only.zh.md
@@ -0,0 +1,25 @@
+# Agent Note: One Messages transport for the official DeepSeek route
+
+Status: implemented
+
+[English](2026-09-19-deepseek-messages-only.md) | 中文
+
+## 问题
+
+官方 DeepSeek 路由需要 Messages 思考回放、图片上传与历史内更新。选择第二种传输会重复序列化器、流处理、Files 协议格式、配置分支与夹具，却没有为这条路由增加必需能力。
+
+## 决策
+
+`dsh-llm-deepseek` 仅使用 Messages。一个适配器解析请求局部的配置快照并执行请求。配置暴露一个端点，不提供协议选择器。Files 客户端直接使用 Messages 认证、元数据与分页；配额清理扫描全部页面后再选择最旧的自有文件。
+
+[Messages 适配器决策](../feature/2026-09-07-deepseek-messages-adapter.zh.md)继续拥有原生思考回放、系统消息位置、图片恢复与请求扩展接受规则。回放判别值和上传索引命名空间标识持久数据，并保留现有值。独立的 pi-ai 适配器保留各提供方协议。
+
+## 考虑过的替代方案
+
+**在可选选择器后保留 Chat Completions。** 即使官方路由只需要 Messages，这仍会保留重复实现与测试矩阵。
+
+**保留只有一个实现的通用协议分派器。** 分派器增加第二种依赖表示，并转发每个适配器操作，却没有进行任何选择。
+
+## 后果
+
+官方路由要求兼容 Messages 的端点。其基于 mock 的恢复、Loader、CLI 与 Web 测试使用 Messages；移除一种协议实现不会移除这些行为检查。已提交的 Session 代际继续通过提供方无关内容与保留的 Messages 回放元数据读取。
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 e50f4af442..b55464949e 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: b218d77f0817416b01459fbb70f5cacffe048ee8
-2026-06-19-real-api-e2e-ci.zh.md: 52c988dad00ddb3ee7f0cd2d23da9771f0900808
+2026-06-19-real-api-e2e-ci.md: bdb20b3d5413077a4ddf1c1d9293b3b808cd6c8c
+2026-06-19-real-api-e2e-ci.zh.md: b95f7df62e0a57d4c58fc5c12a83905dd848c55e
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 b218d77f08..bdb20b3d54 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
@@ -49,7 +49,7 @@ The repo secret is named `DEEPSEEK_API_KEY_EXTERNAL`; it is mapped to the `DEEPS
 
 - **Step-scoped secret.** `DEEPSEEK_API_KEY` is set in the `env:` of only the preflight and e2e steps, never job-level — so checkout/setup-node/install never see it. A compromised install-time lifecycle script in a dependency cannot read a secret that isn't in its environment.
 - **`permissions: contents: read`.** The job only reads the repo to run tests; it needs no write scopes (no PR comments, no status writes), so the `GITHUB_TOKEN` is dropped to least privilege.
-- **`DEEPSEEK_BASE_URL` pinned** to `https://api.deepseek.com` on the e2e step. The adapter would default to this when unset ([packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts) `PUBLIC_BASE_URL`), but pinning is self-documenting and hermetic — a stray repo-root `.env` (which `vitest.e2e.config.ts` loads if present) cannot silently redirect the run to another endpoint.
+- **`DEEPSEEK_BASE_URL` pinned** to `https://api.deepseek.com/anthropic` on the e2e step. The adapter would default to this when unset ([packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts) `PUBLIC_BASE_URL`), but pinning is self-documenting and hermetic — a stray repo-root `.env` (which `vitest.e2e.config.ts` loads if present) cannot silently redirect the run to another endpoint.
 - **No secret echoed.** The preflight prints only `DEEPSEEK_API_KEY present.` — not the value or its length.
 
 ### Scope, runtime shape
diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
index 52c988dad0..b95f7df62e 100644
--- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
+++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.zh.md
@@ -49,7 +49,7 @@ repo secret 命名为 `DEEPSEEK_API_KEY_EXTERNAL`；映射到适配器和测试
 
 - **步骤级 secret。** `DEEPSEEK_API_KEY` 仅在 preflight 和 e2e 步骤的 `env:` 中设置，从不在 job 级设置——因此 checkout/setup-node/install 永远看不到它。依赖中被入侵的安装时生命周期脚本无法读取不在其环境中的 secret。
 - **`permissions: contents: read`。** job 仅读取仓库以运行测试；不需要写权限（无 PR 评论、无 status 写入），因此 `GITHUB_TOKEN` 降至最小权限。
-- **`DEEPSEEK_BASE_URL` 固定**为 e2e 步骤上的 `https://api.deepseek.com`。适配器在未设置时会默认使用此值（[packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts) `PUBLIC_BASE_URL`），但显式固定具有自文档性和密封性——仓库根目录的 `.env`（如果存在，`vitest.e2e.config.ts` 会加载它）无法静默地将运行重定向到其他端点。
+- **`DEEPSEEK_BASE_URL` 固定**为 e2e 步骤上的 `https://api.deepseek.com/anthropic`。适配器在未设置时会默认使用此值（[packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts) `PUBLIC_BASE_URL`），但显式固定具有自文档性和密封性——仓库根目录的 `.env`（如果存在，`vitest.e2e.config.ts` 会加载它）无法静默地将运行重定向到其他端点。
 - **不回显 secret。** preflight 仅打印 `DEEPSEEK_API_KEY present.`——不打印值或长度。
 
 ### 范围与运行时形态
diff --git a/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.i18n.yaml b/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.i18n.yaml
new file mode 100644
index 0000000000..bb3a7b1cbe
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both 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-09-20-chat-presentation-policy-and-step-groups.md
+2026-09-20-chat-presentation-policy-and-step-groups.md: df0397a0568967c920994192b370e9fe1d063229
+2026-09-20-chat-presentation-policy-and-step-groups.zh.md: 1bf9cf95174a1de0c7d0576bdd9fbb842d980ae7
diff --git a/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.md b/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.md
new file mode 100644
index 0000000000..df0397a056
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.md
@@ -0,0 +1,286 @@
+# Agent Note: Chat presentation policy channel and process-group architecture
+
+Status: proposed
+
+English | [中文](2026-09-20-chat-presentation-policy-and-step-groups.zh.md)
+
+## Problem
+
+At the start of this proposal, Chat's display setting had two modes: `normal` did not fold content, while `compact` folded process rows behind a whole-Turn control after completion. `TranscriptViewPolicy.mode` was injected into ChatView as an observable. ChatView read it through `useTranscriptView`, converted it to the boolean `compactTranscript`, and passed that prop through `ChatNodeList` to every `ChatNodeSeat`. The global `hasMore` boolean followed the same path as `historyIncomplete`. Either change re-rendered every seat, even when only a few foldable rows changed their output.
+
+The product requires three modes—Compact, Detailed, and Expanded—with consecutive process rows between replies collected into collapsible groups in Compact and Detailed. PR #4565 implemented the full feature, but was reverted eight minutes after merging because of performance regressions. The recorded local before/after comparison found long-session pagination +27%, DOM nodes +23%, heap +14%, and Trajectory switching +10%, all within CI budgets. None of the six existing repository benchmarks covered the new hot path: reasoning or tool chunks entering an active group during streaming, group reprojection, and seat re-rendering.
+
+The review identified implementation choices, not the product requirements, as the problem:
+
+- The mode became an input to list structure. `ChatNodeList` subscribed to the entire `layout` and generated wrapper components from ranges; Expanded removed those wrappers. Switching modes remounted the list, and regrouping rebuilt wrapper keys.
+- The mode entered `ChatNodeOwnerProps`. Every seat's owner object changed with the mode, re-rendering all business renderers, including unrelated user messages, tool rows, and compaction markers.
+- A seat split one Assistant node into derived reasoning and response objects solely to wrap the former in the DOM. Master's `AssistantMarkdown` already had `reasoningHidden` and `revealProcess`, which could hide reasoning independently.
+- Consumers repeated infrastructure-row filtering in four places, although nodes already had a Definition-owned `visibility` field.
+
+The deeper difficulty is information ownership: a group header must exist before its members as soon as the group opens, but its content requires a view of the entire Turn. Each event-driven Context receives only its own events. Only a turn-level Context can observe the whole Turn, and it can produce only one node.
+
+This proposal supplies an architecture for three modes and grouping that satisfies the constraints below and confines later product changes to a small set of nodes.
+
+The three settings, presentation policy channel, and per-Turn folding eligibility are implemented; step-group remains proposed. The [migration progress table](../feature/2026-09-20-chat-work-details-migration.md) owns current implementation, committed scope, and incomplete items. The grouping state machine and change inventory below do not describe delivered work.
+
+## Goals and constraints
+
+The following decisions were confirmed during design review and are inputs to this proposal.
+
+| Number | Decision | Meaning |
+|---|---|---|
+| 1 | Definitions own group structure | A Definition matching multiple events in the Turn folds group opening, closing, member ranges, and summaries; renderers do not derive them by scanning nodes |
+| 2 | Limit seat re-rendering | Mode changes re-render only seats whose presentation changes; streaming chunks re-render only their seat and group header; user messages, replies, and turn-tail do not re-render for either change |
+| 3 | One node per Context | Do not introduce multiple nodes per Context; most Contexts have one element, and arrays would fragment memory further |
+| 4 | Modes do not toggle Definitions | Registry changes rebuild and replay all Contexts, refreshing every seat; Definitions must be mode-independent |
+| 5 | Decide folding per Turn | A Turn can fold when its own `turn/start` is loaded; the oldest partial Turn stays open and is not optimized here |
+| 6 | ui-conversation may change | Engine changes are allowed only where needed for this design to work correctly |
+| 7 | Initial implementation scope | Initially change only code and this note; add tests and other documentation during CI repair |
+
+Accepting a full-page browser layout on mode changes does not mean accepting every seat re-rendering. Layout is a geometric result; a seat re-render executes a React component function. This proposal constrains the latter.
+
+## Viable approaches
+
+There are five approaches to group-header identity and content ownership.
+
+**Approach A: the first member's seat renders the header.** Keep the list unchanged. The builder derives membership and tells the first member's seat to render a title above itself; other member seats use the existing `hidden` mechanism. This adds no new concept, but creates a third seat state—visible with only a title—and attaches the header to a business node's seat.
+
+**Approach α: one Context per step supplies a header.** Add a Definition identified by `turn:step`. During construction, read the preceding `assistant-step` data to decide whether this is a new group start and emit a header node if so. Another turn-level Definition publishes the group's content as Turn data for the renderer.
+
+**Approach β: one Context emits multiple nodes.** A turn-level Definition emits the whole-Turn control and N group headers.
+
+**Approach γ: a parent Context derives child Contexts.** When a group opens, the turn-level fold creates a `step-group` child Context and forwards later events to it. Each child owns one node. The engine needs forwarding and cascaded replay primitives.
+
+**Approach δ: Definitions own structure; the builder materializes rows.** A turn-level Definition folds the group list and publishes Turn data. The Chat builder materializes header nodes and assigns membership. Seats use combined selectors for visibility. `ViewBuilder.apply` receives the Location data whose references changed in the flush.
+
+## Alternatives considered
+
+**One Context per group cannot satisfy the matching rules.** The engine requires `match(event)` to derive an id from one event. A group number depends on whether a reply preceded the event; one event cannot determine it. This is incompatible with the matching contract, not merely difficult to implement.
+
+**Approach α conflicts with decision 2.** Header identity is derivable, but every header reads the same Turn data, so one group's change refreshes all headers in that Turn. Reading later steps through `turn.steps` instead leaves stale references because a header node is not rebuilt when later steps arrive.
+
+**Decision 3 rules out approach β.** See the table above.
+
+**Approach γ is not justified yet.** It has the clearest ownership, but forwarding and cascaded replay would add hundreds of lines to the assembler core. It remains an alternative under the conditions at the end of this note.
+
+**Approach A remains the fallback.** If builder-owned materialization is rejected in practice, use A. Both share the same structural source and differ only in what carries the header row.
+
+Choose approach δ.
+
+## Proposal
+
+### Data flow
+
+```
+事件流
+  ──▶ step-groups Definition（turn 级 fold，多重匹配本轮事件）
+        ──▶ Turn 数据 step-groups：组列表，每组一个对象
+              ──▶ Chat builder
+                    ├─ 物化组头节点：一组一个 key，data 即组对象
+                    └─ 成员归属：按 step 映射到 key，写进 per-key presentation
+                          ──▶ seat：hidden = f(策略字段, 角色, 展开状态)
+                          ──▶ 组头渲染器：读自己节点的 data
+展示策略
+  ──▶ 渲染器：按 kind 注入的 hooks，选单个字段
+  ──▶ seat：组合 selector，选出的是自己的结论
+```
+
+The only engine change passes the Location data whose references changed during a flush to the builder through `apply`.
+
+### Responsibilities
+
+| Layer | Owns | Explicitly does not own |
+|---|---|---|
+| `step-groups` Definition | Opening and closing groups, `headStep`, `closeStep`, tool counts and names, running tools; publishes Turn data | View nodes or identification of member nodes |
+| Chat builder | Header-node identity and lifecycle, membership, `turnStarted`, identity comparison and publication of per-key presentation | Reading events or deriving business structure |
+| Presentation policy object | Mapping the enum to capability fields | Node or seat state |
+| Seat | Combining policy fields, role, and store state into hidden state; supplying group open/close actions to the header renderer | Determining group boundaries |
+| Header renderer | Title, chevron, click-to-toggle interaction | The source of group content |
+| assistant-step renderer | Settled reasoning first-line preview; hiding reasoning when closing a group | Group boundaries |
+
+### Header-node identity and lifecycle
+
+A header node's key is `step-group:${turn}:${headStep}`. `headStep` is fixed when a group opens, and later events cannot change its first member. The header exists and is reused from that point onward; its key does not change during streaming. Closing the group only changes `closed` in its data from false to true.
+
+The header anchor is the first member's anchor minus a synthetic offset, placing it immediately before that member. A streaming Assistant is anchored at its first visible chunk, then at its message event after persistence. Its anchor moves once; the header follows in the same structural update without adding another update.
+
+A header is part of the whole-Turn process and hides with its members when the Turn folds. It is not in `TURN_PROCESS_INDEPENDENT_KINDS`.
+
+Header data is the group object published by the fold. Closed group objects never change references, so their header sources never notify. Each event that changes a running group replaces only that group's object and re-renders only its header.
+
+### Fold state machine
+
+The `step-groups` Definition uses the Turn number as its id, starts on `turn/start`, and matches the same event set as `turn-process`. Its State is `{ turn, groups, open }`: `groups` is an array of group objects, and `open` is the active group's index or empty.
+
+| Event | Transition |
+|---|---|
+| `tool/call` | If no group is open, open one at the event's step; increment the count, record distinct tool names, and add callId to the running set |
+| Appended `tool/result` | Remove callId from the running set |
+| `assistant/live-chunk` reasoning delta with visible characters | Open a group at the chunk's step if none is open |
+| `assistant/live-chunk` text delta or text-block end with visible characters | Close an open group at the chunk's step |
+| Appended `assistant/message` | Apply the reasoning rule for visible reasoning and the text rule for a visible reply, in reasoning-then-text order |
+| `turn/end` | Mark an open group as closed by the Turn end |
+| `step/start`, `step/end`, `llm/retry` | No state change; retry rows belong to no group |
+
+Three invariants apply:
+
+- Idempotence: opening an already-open group and closing an already-closed group do nothing. Live chunks and persisted messages describing the same content do not open or close twice; replay with only persisted messages derives the same group list.
+- Stable references: `update` returns the original object when State is unchanged; the `groups` array changes reference only when the group list changes; closed group objects are never replaced.
+- Forward-only folding: do not read neighboring Contexts, nodes, or later history.
+
+Turn-data publication: `buildLocationData` returns a value only for the turn phase and reuses its previous value when the `groups` reference is unchanged, preventing republication. A history window without `turn/start` uses the same fallback as `turn-process`: fold State from the available matches.
+
+Publication timing: batch live chunks at animation frames; publish other changes immediately.
+
+### Membership rules
+
+The builder assigns membership by step, not by seq ranges, because live-chunk seqs and persisted-event seqs use different scales.
+
+| Node | Rule |
+|---|---|
+| `tool-call` at step s | Belongs to the last group with `headStep ≤ s`. If text closes the preceding group in the same step, later tool calls open a new group at that step, so the last group is the applicable one |
+| `assistant-step` at step s where a group has `closeStep === s` | Closer role: the node remains visible; folding the group hides only its reasoning through the existing `reasoningHidden` mechanism |
+| Other `assistant-step` at step s | Member role: belongs to the group with `headStep ≤ s` whose `closeStep` has not been passed |
+| `model-retry`, `turn-error`, `turn-max-tokens`, `turn-tail`, `user`, `steering` | Belong to no group |
+
+Recompute membership only when the group list changes, with cost proportional to that Turn's node count. Streaming chunks that leave the group list unchanged do not publish member presentation.
+
+The header anchors before the earliest member. If a group contains only its closer's reasoning and no members, such as reasoning followed by a reply in one step, anchor the header before the closer so the hidden reasoning still has a control that reveals it.
+
+### Delivering group changes to the builder
+
+The fold publishes Turn data, not view nodes. When Location data changes, the engine's `flush` sets `timelineDirty` and calls `apply` on all active targets, but the builder cannot identify the changed Turn and key. Inferring them from an unrelated node update in the same Turn and flush is not a reliable guarantee.
+
+Add optional `changedLocationData` to `ConversationViewBuilder.apply`: the Location values whose references changed in this flush, each carrying `kind`, `turn`, optional `step`, and `key`. The assembler already compares references in `applyDirtyLocationData`; it collects those results for the builder. Chat reprojects only Turns with `key === 'step-groups'`. When the optional input is absent, the builder falls back to Turns affected by the current upserts.
+
+### Combining hidden state in a seat
+
+Seats stop receiving `compactTranscript` and `historyIncomplete`. A seat reads policy through `usePresentation`, selecting its own result rather than the mode:
+
+```ts
+declare function usePresentation<T>(select: (policy: {
+  stepGrouping: 'collapsed' | 'none'
+  foldCompletedTurns: boolean
+}) => T): T
+declare const group: { readonly headStep: number } | undefined
+
+const grouping = usePresentation(p => group === undefined ? 'none' : p.stepGrouping)
+const foldCompleted = usePresentation(p => p.foldCompletedTurns)
+```
+
+For a seat outside every group, `grouping` is `'none'` in all modes, so it does not re-render. `foldCompletedTurns` likewise stays true in all modes. The selector hook uses `useSyncExternalStoreWithSelector` and re-renders only when the selected value changes.
+
+Three sources combine into `hidden`:
+
+| Source | Condition | Reveal action |
+|---|---|---|
+| Whole-Turn folding | Existing rule: `turnClosed && turnStarted && has reply`, without manual expansion | Open the Turn |
+| Group folding | `grouping === 'collapsed'`, member role, group not manually expanded | Open the group |
+| Group header in Expanded | Header role and `grouping === 'none'` | None |
+
+The closer's reasoning is hidden independently: the seat passes `stepGroup.reasoningHidden` through owner props to the assistant-step renderer.
+
+The chat store keeps group expansion under a key combining `turn` and `headStep`, alongside whole-Turn manual expansion.
+
+### Re-render scope
+
+The following guarantees also define the next round of render-count assertions. Each row names an exact set, not an upper bound.
+
+| External change | May re-render |
+|---|---|
+| A running group receives a reasoning chunk | That assistant seat |
+| A running group receives `tool/call` | That tool seat and the group's header |
+| A reply appears and closes a group | That assistant seat and group header; membership recomputation occurs only when opening or closing groups |
+| A new group opens | Insert the new header into `order` with one structural layout; no other seat refreshes |
+| Switch Compact ↔ Detailed | Only assistant-step renderers with settled reasoning |
+| Switch to or from Expanded | Only member and header seats |
+| Change `performanceUsage` | Only turn-tail |
+| Load an earlier page | New seats and historical seats whose presentation changes |
+| Change locale | All seats, as a control case |
+
+### Presentation policy object
+
+Separate the persisted enum from runtime capabilities. `TranscriptViewMode` contains `compact`, `detailed`, and `expanded`; reading the legacy saved value `normal` maps it to `detailed` without writing it back. Runtime capabilities are the derived `ChatPresentationPolicy`:
+
+| Field | compact | detailed | expanded |
+|---|---|---|---|
+| `foldCompletedTurns` | true | true | true |
+| `stepGrouping` | collapsed | collapsed | none |
+| `settledReasoningPreview` | false | true | true |
+
+The mapping has one owner. Each mode maps to a constant object with a stable reference, so the derived observable needs no subscription bookkeeping: `getSnapshot` performs a lookup and `subscribe` forwards to the mode observable.
+
+Renderers select needed fields instead of comparing enum values. Policy is injected by kind: the assistant-step registration receives it through `inject.hooks.presentation`, just as turn-tail receives `performanceUsage`. Adding a fourth mode changes the table, not the renderers.
+
+### Per-Turn folding
+
+Add `turnStarted` to per-key presentation, derived from whether the Turn's `turn/start` is in the loaded window. Folding eligibility uses it instead of global `!historyIncomplete`. Completing pagination changes no global seat prop; only new nodes and presentation in their Turns change.
+
+### Complexity requirements
+
+| Scenario | Fold | Builder | Publication |
+|---|---|---|---|
+| Content chunk without a group-boundary change | O(1) transition, original object returned | No reprojection | None |
+| Event that changes a group boundary | O(1) | Reproject only the owning Turn, proportional to its node count | Keys whose facts changed in that Turn |
+| Structural changes and pagination | Proportional to matched events | One full pass | Keys whose facts changed |
+| Mode change | None | None | None; seat and renderer selectors determine re-renders |
+
+## Change inventory
+
+| Package | File | Change |
+|---|---|---|
+| ui-conversation | `contract/conversation.ts` | Add `ConversationLocationDataUpdate` and optional `changedLocationData` to `ConversationViewBuilder.apply` |
+| ui-conversation | `conversation/assembler.ts` | Collect changed Location references in `applyDirtyLocationData` and pass them through `apply` |
+| ui-conversation | `index.ts` | Export the new type |
+| ui-chat | `chat-settings.ts` | Three-mode enum; schema accepts legacy `normal` |
+| ui-chat | `transcript-view.ts` | Map `normal` to `detailed` on read |
+| ui-chat | New `presentation-policy.ts` | Policy objects, mapping table, derived observable |
+| ui-chat | `settings/TranscriptViewRow.tsx` | Three options |
+| ui-chat | `locale.ts` | Mode labels and group-header copy |
+| ui-chat | `contract/slots.ts` | `ChatViewInjected.hooks.presentation`, `PresentationInjected`, `ChatNodeOwnerProps.stepGroup`, `StepGroupOwnerProps` |
+| ui-chat | `contract/snapshot.ts` | `ChatTurnProcessPresentation.turnStarted`, `ChatNodeGroupPresentation`; combine `processSource` values per key |
+| ui-chat | `contract/chat-nodes.ts` | `StepGroupChatData` |
+| ui-chat | `contract/store.ts`, `stores.ts` | Manual group-expansion state and actions |
+| ui-chat | `conversation-nodes/common.ts` | Header anchor offset |
+| ui-chat | New `conversation-nodes/step-groups.ts` | Fold Definition and Turn-data declaration merging |
+| ui-chat | New `conversation-nodes/step-group-nodes.ts` | Materialize headers and project membership |
+| ui-chat | `conversation-nodes/turn-process-presentation.ts` | `turnStarted` and combined per-key presentation |
+| ui-chat | `conversation-nodes/chat-snapshot-builder.ts` | Integrate materialization, consume `changedLocationData`, support key deletion in the store |
+| ui-chat | `conversation-nodes/register.ts` | Register the fold Definition |
+| ui-chat | `chat/ChatView.tsx` | Stop passing `compactTranscript` and `historyIncomplete`; pass `usePresentation` |
+| ui-chat | `chat/ChatNodeSeat.tsx` | Combined selector, three hiding sources, `stepGroup` owner props |
+| ui-chat | `chat/AssistantNodeView.tsx`, `chat/AssistantMarkdown.tsx`, `chat/ReasoningRow.tsx` | Inject policy, toggle settled reasoning previews, hide closer reasoning |
+| ui-chat | New `chat/StepGroupNodeView.tsx` | Header renderer |
+| ui-chat | `chat/register-node-renderers.ts` | Register header renderer and inject policy into assistant-step |
+| ui-chat | `apply.ts`, `index.ts` | Create and inject policy observable; export types |
+
+This inventory retains the complete grouping proposal. Independent features have updated READMEs, i18n pairing files, and the slot catalog. The migration record tracks tests and snapshots; those updates do not complete the outstanding grouping work.
+
+## Acceptance criteria
+
+Grouping validation remains unimplemented; the migration record tracks independent presentation-feature evidence.
+
+**Render-count isolation.** Add counters to the existing `chat-view.client.spec` mounting approach: React Profiler `onRender` counts per seat, and test renderers registered in `conversation.chat.node` count by kind. Assert the exact sets in the re-render-scope table for each stimulus.
+
+**Publication counts.** Count notifications from each key's source under the same stimuli and assert the exact set.
+
+**Fold state-machine tests.** Feed event sequences and assert opening, closing, a new group after text then tools in one step, Turn-end closure, idempotence, unchanged closed-group references, and equivalent replay using only persisted messages.
+
+**Membership tests.** Given the group list and Turn nodes, assert each key's role.
+
+**Benchmark coverage.** Add incremental apply with reasoning and tools to `conversation-fold`, and a streaming fixture with tools and reasoning to `long-session-browser`. These provide wall-clock evidence, not a gate.
+
+## Risks
+
+- **Builder-owned node creation.** This is the first proposed node creation by a view builder. A builder may only materialize rows from Turn or Step data; it must not read events or derive business structure. Synthetic keys use `step-group:`, while Context keys begin with digits, preventing collisions. Fall back to approach A if this ownership is rejected in practice.
+- **Header anchor moves once with its first member.** Persisting a streaming Assistant moves its anchor from the first visible chunk to the message event. The header follows in the Assistant's structural update.
+- **Actual mode differences in this phase.** Compact and Detailed currently differ only in settled reasoning first-line previews. Running detail titles and category summaries are outside this phase; the policy table leaves room for them.
+- **Pagination and partial Turns.** The oldest partial Turn neither folds nor groups. Membership uses steps and is independent of pagination.
+- **Header copy.** This phase proposes only processing/completed labels and tool-call counts; category summaries remain product work.
+- **Streaming chunk step.** `assistant/live-chunk` carries `step`, as used by `turn-process`; a chunk without a step does not open a group.
+
+## Retained alternative: parent-derived child Contexts
+
+If builder materialization exposes more ownership problems than expected, add an engine primitive: a Context's `update` may derive a child Context with an explicit kind and id, then forward later matches. Each child owns its node, publication timing, and Location. Parent replay aligns children by id; children no longer derived become hidden under the existing withdrawal rules.
+
+This returns row identity and content to Definitions with one Context per group and no array fragmentation. It requires assembler forwarding and cascaded replay, and introduces a Context creation path outside `match`. Reconsider it if more than two business features exceed the builder's materialization limits, or if membership requires cases that steps cannot express.
diff --git a/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.zh.md b/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.zh.md
new file mode 100644
index 0000000000..1bf9cf9517
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-20-chat-presentation-policy-and-step-groups.zh.md
@@ -0,0 +1,286 @@
+# Agent Note: Chat 展示策略通道与过程分组的基础架构
+
+Status: proposed
+
+[English](2026-09-20-chat-presentation-policy-and-step-groups.md) | 中文
+
+## 问题
+
+Chat 的「对话显示」设置在本提案开始时只有两档：`normal` 不折叠、`compact` 在轮次结束后把过程行折进一个整轮控件。设置值的流向是：`TranscriptViewPolicy.mode` 观察量注入 ChatView，ChatView 用 `useTranscriptView` 读成一个布尔值 `compactTranscript`，再作为 prop 传给 `ChatNodeList`，再传给每一个 `ChatNodeSeat`。另一个全局布尔值 `hasMore` 走同一条路，以 `historyIncomplete` 的名字进每个 seat。两个值一变，全部 seat 重渲染一遍，哪怕只有可折叠的那几个输出真的变了。
+
+产品要把这个设置改成三档：简洁、详细、完全展开；并在简洁和详细两档里把回复之间的连续过程行归成可折叠的组。PR #4565 做过一次完整实现，合并八分钟后因性能回退被整体撤回。合并前后在本机的对照实测：长会话分页耗时 +27%，DOM 节点 +23%，堆内存 +14%，Trajectory 切换 +10%，全部仍在 CI 预算内；仓库现有六个基准没有任何一个覆盖「流式期间 reasoning 或工具 chunk 进入活动分组、分组重投影、seat 重渲染」这条它新增的热路径。
+
+审阅那次实现，问题不在业务需求，在选型：
+
+- 模式被当成列表结构的输入。`ChatNodeList` 订阅整表 `layout`，按 range 生成 wrapper 组件；完全展开模式下 wrapper 消失。模式切换等于整棵列表重挂载，任何一次重新分组都重建 wrapper 的 key。
+- 模式进了 `ChatNodeOwnerProps`。每个 seat 的 owner 对象随模式变，所有业务渲染器跟着重渲染，包括与模式无关的用户消息、工具行、压缩标记。
+- 同一个 Assistant 节点在 seat 里被拆成 reasoning 与 response 两份派生对象，只为了让 wrapper 在 DOM 上包住前者不包住后者。master 的 `AssistantMarkdown` 早有 `reasoningHidden` 与 `revealProcess`，靠隐藏状态就能只藏 reasoning。
+- 基础设施行的 Chat 可见性由消费方过滤函数在四处各判一遍，而节点本身有 `visibility` 字段由 Definition 决定。
+
+再往下一层，是一个信息流上的两难：分组的行要出现在成员之前，从组打开那一刻就该存在；但它要显示的内容，只有看到整轮所有事件的人才知道。事件驱动的 Context 模型里每个 Context 只收自己的事件，能看到整轮的只有 turn 级 Context，而它只能产出一个节点。
+
+本记录给出一套基础架构，让三档模式与分组落地时满足下面的约束，并让后续产品变化只落在少数节点上。
+
+三档设置、展示策略通道与按轮折叠资格已实现；step-group 仍是提案。当前实现、已提交范围和未完成项以[迁移进度表](../feature/2026-09-20-chat-work-details-migration.zh.md)为准，下面的分组状态机与改动清单不表示已经交付。
+
+## 目标与约束
+
+下表是评审阶段已经确认的裁决，本方案不再重新讨论它们。
+
+| 编号 | 裁决 | 含义 |
+|---|---|---|
+| 1 | 分组结构在 Definition 层定义 | 组的开合、成员范围、摘要由一个多重匹配本轮事件的 Definition 折叠出来，不由渲染层扫描节点得到 |
+| 2 | 有限刷 seat | 切模式只重渲染 presentation 真正变化的 seat；流式 chunk 只重渲染所属 seat 和它所在组的组头；用户消息、回复、turn-tail 在这两种变化下零重渲染 |
+| 3 | 一个 Context 一个节点 | 不引入「一个 Context 产出多个节点」，理由是绝大多数 Context 只会有一个元素，数组化让内存更零散 |
+| 4 | 模式不开关 Definition | 注册变化会触发 registry 重建与全量重放，所有 seat 必刷；Definition 必须与模式无关 |
+| 5 | 折叠按轮判定 | 一轮只要自己的 `turn/start` 已加载就可以折叠；被分页切开的最老一轮保持展开，本轮不优化 |
+| 6 | 允许改 ui-conversation | 引擎可以改，但只做让方案正确成立所必需的小改动 |
+| 7 | 初始实现范围 | 初始阶段只写代码与本记录；测试与其他文档在 CI 修复阶段补齐 |
+
+有一条前置澄清：接受「切模式全屏重排版」不等于接受「所有 seat 重渲染」。浏览器重排是几何结果，seat 重渲染是 React 组件函数重跑，后者才是这里要限制的量。
+
+## 可行的路线
+
+围绕「组头这一行的身份从哪来、内容从哪来」，可行的路线有五条。
+
+**路线 A，头成员的 seat 画组头。** 列表不变，builder 算出分组后告诉第一个成员的 seat「你是组头」，该 seat 在自己上方画标题，其余成员 seat 用现有 `hidden` 机制藏起来。零新概念。缺点是 seat 里出现「自身可见但只显示标题」的第三种状态，且标题寄生在一个业务节点的 seat 里。
+
+**路线 α，每步一个 Context 当组头。** 增加一个 id 为 `turn:step` 的 Definition，在构建时读上一步的 `assistant-step` 数据判断自己是否新组开头，是则产出组头节点。组的内容由另一个 turn 级 Definition 发布成 Turn 数据供渲染器读取。
+
+**路线 β，一个 Context 产出多个节点。** turn 级 Definition 一个人产出整轮控件加 N 个组头。
+
+**路线 γ，父 Context 派生子 Context。** turn 级 fold 在开组时生成一个 `step-group` 子 Context 并把后续事件转发给它，子 Context 有自己的单个节点。引擎需要新增转发原语与重放级联。
+
+**路线 δ，Definition 拥有结构，builder 物化行。** turn 级 Definition 折叠出组列表并发布为 Turn 数据；Chat builder 据此物化组头节点并给成员写归属；seat 用组合 selector 决定隐藏；引擎给 `ViewBuilder.apply` 的入参加一份「本次 flush 哪些 Location 数据换了引用」。
+
+## 备选方案与取舍
+
+**每组一个 Context 无法成立。** 引擎要求 `match(event)` 只看单个事件算出 id，「第几组」取决于前面有没有回复，单个事件算不出。这不是实现难度，是契约上的不可能。
+
+**路线 α 与裁决 2 冲突。** 组头身份能算出，但内容要读整轮一份 Turn 数据，任何一组变化全轮组头都重渲染。改成去读 `turn.steps` 里后面几步的数据，又碰上组头节点不会因为后面的步到来而重建，读到的是陈旧引用。
+
+**路线 β 被裁决 3 否决。** 见上表。
+
+**路线 γ 现在不值。** 它在所有权上最纯，但要给 assembler 加转发与重放级联，是几百行的引擎核心改动。本记录把它保留为备选，条件写在末尾。
+
+**路线 A 作为退路保留。** 如果 builder 物化节点在实践中被否决，退到 A；两者的结构来源相同，只差组头这一行的承载。
+
+选择路线 δ。
+
+## 方案
+
+### 数据流
+
+```
+事件流
+  ──▶ step-groups Definition（turn 级 fold，多重匹配本轮事件）
+        ──▶ Turn 数据 step-groups：组列表，每组一个对象
+              ──▶ Chat builder
+                    ├─ 物化组头节点：一组一个 key，data 即组对象
+                    └─ 成员归属：按 step 映射到 key，写进 per-key presentation
+                          ──▶ seat：hidden = f(策略字段, 角色, 展开状态)
+                          ──▶ 组头渲染器：读自己节点的 data
+展示策略
+  ──▶ 渲染器：按 kind 注入的 hooks，选单个字段
+  ──▶ seat：组合 selector，选出的是自己的结论
+```
+
+引擎改动只有一处：assembler 在 flush 时把「哪些 Location 数据换了引用」随 `apply` 入参交给 builder。
+
+### 各层职责
+
+| 层 | 拥有 | 明确不拥有 |
+|---|---|---|
+| `step-groups` Definition | 组的开合、`headStep`、`closeStep`、工具计数与名称、运行中的工具；作为 Turn 数据发布 | 任何视图节点；成员是哪些节点 |
+| Chat builder | 组头节点的身份与生命周期；成员归属；`turnStarted`；per-key presentation 的身份比较发布 | 读事件；自己算业务结构 |
+| 展示策略对象 | 枚举到能力字段的映射 | 任何节点或 seat 状态 |
+| seat | 用策略字段、角色、store 状态合成 hidden；把组的开合能力交给组头渲染器 | 判断组的边界 |
+| 组头渲染器 | 标题、箭头、点击开合 | 组的内容来源 |
+| assistant-step 渲染器 | 是否显示已完成推理的首行预览；作为组的关闭者时隐藏推理部分 | 组的边界 |
+
+### 组头节点的身份与生命周期
+
+组头节点的 key 是 `step-group:${turn}:${headStep}`。`headStep` 在组打开那一刻就确定，之后任何事件都改不了「谁是第一个」，所以组头节点从打开起就存在并被复用，运行中不会换 key。组关闭只是它 data 里的 `closed` 从 false 变 true。
+
+组头节点的锚点是该组头成员节点锚点减去一个合成偏移，位置紧贴在第一个成员之前。头成员的 Assistant 节点在流式期间锚在第一个可见 chunk，落盘后锚在消息事件，锚点会移动一次；组头随之移动一次，这是一次结构性更新，与 Assistant 节点自己的结构性更新同时发生，不额外增加次数。
+
+组头节点属于整轮过程的一部分：整轮折叠时它随成员一起隐藏。它不在 `TURN_PROCESS_INDEPENDENT_KINDS` 里。
+
+组头节点的 data 就是 fold 发布的组对象。已关闭的组对象引用永不改变，因此已关闭组头的 source 永不通知；正在运行的组每来一个改变它的事件换一个对象，只有这一组的组头重渲染。
+
+### fold 状态机
+
+`step-groups` Definition 的 id 是 turn 号，在 `turn/start` 上启动，匹配与 `turn-process` 同一批事件。State 是 `{ turn, groups, open }`，`groups` 是组对象数组，`open` 是当前打开组的下标或空。
+
+| 事件 | 转移 |
+|---|---|
+| `tool/call` | 没有打开的组则以该事件的 step 开新组；计数加一；记录 distinct 工具名；把 callId 加入运行集合 |
+| `tool/result` 追加 | 从运行集合移除 callId |
+| `assistant/live-chunk` 推理 delta 含可见字符 | 没有打开的组则以该 chunk 的 step 开新组 |
+| `assistant/live-chunk` 文本 delta 或文本块结束含可见字符 | 有打开的组则以该 chunk 的 step 关闭它 |
+| `assistant/message` 追加 | 消息含可见推理则按推理规则处理，含可见回复则按文本规则处理；顺序是先推理后文本 |
+| `turn/end` | 有打开的组则标记为被轮次结束关闭 |
+| `step/start`、`step/end`、`llm/retry` | 不改变状态；重试行不属于任何组 |
+
+三条不变量：
+
+- 幂等。开组时已有打开的组则无操作；关组时组已关闭则无操作。live chunk 与落盘消息重复描述同一内容不会开两次或关两次，历史重放只有落盘消息也能得到同样的组列表。
+- 引用稳定。State 没变时 `update` 返回原对象；`groups` 数组只在组列表变化时换引用；已关闭的组对象永不替换。
+- 只向前折叠。不读邻居 Context，不读节点，不向后看。
+
+Turn 数据发布：`buildLocationData` 只在 turn 阶段返回值，`groups` 引用不变时返回上一次发布的值，引擎据此不重新发布。没有 `turn/start` 的历史窗口用与 `turn-process` 相同的兜底：从已有匹配折叠出 State。
+
+发布节奏：live chunk 走动画帧合并，其余立即。
+
+### 成员归属规则
+
+归属由 builder 按 step 判定，不用 seq 区间，因为 live chunk 的 seq 与落盘事件的 seq 不在一个尺度上。
+
+| 节点 | 规则 |
+|---|---|
+| `tool-call`，step 为 s | 属于 `headStep ≤ s` 的最后一组。文本在同一 step 关闭了上一组之后的工具调用，会由 fold 以该 step 开出新组，所以「最后一组」总是正确的那一组 |
+| `assistant-step`，step 为 s，且某组 `closeStep === s` | 角色为关闭者。节点保持可见；组折叠时只隐藏它的推理部分，用现有 `reasoningHidden` 机制 |
+| `assistant-step`，step 为 s，其余情况 | 属于 `headStep ≤ s` 且 `s` 未越过 `closeStep` 的组，角色为成员 |
+| `model-retry`、`turn-error`、`turn-max-tokens`、`turn-tail`、`user`、`steering` | 不属于任何组 |
+
+归属只在组列表变化时重算，成本是该轮节点数。流式 chunk 不改变组列表时，成员的 presentation 不发布。
+
+组头行锚在最早的成员之前。一个组如果只有关闭者的推理而没有任何成员，比如一步里先推理后回复，组头行就锚在关闭者之前，这样被隐藏的推理仍然有一行可以点开。
+
+### 分组变化怎样到达 builder
+
+fold 只发布 Turn 数据，没有视图节点。engine 的 `flush` 在 Location 数据有变化时会把 `timelineDirty` 置真并对所有活跃目标调用 `apply`，但 builder 不知道是哪一轮的哪个 key 变了。依赖「同一轮总有别的节点也在这次 flush 里变了」去推断，是巧合不是契约。
+
+所以给 `ConversationViewBuilder.apply` 的入参增加可选的 `changedLocationData`：本次 flush 里换了引用的 Location 数据清单，每项含 `kind`、`turn`、可选 `step`、`key`。assembler 在 `applyDirtyLocationData` 里本来就逐条比较了前后引用，只是把比较结果收集起来交给 builder。Chat builder 只取 `key === 'step-groups'` 的轮次做重投影。入参可选，不传时 builder 退化为按本次 upsert 涉及的轮次重投影。
+
+### seat 的 hidden 合成
+
+seat 不再接收 `compactTranscript` 与 `historyIncomplete` 两个 prop。它通过 `usePresentation` 读策略，但选出的不是模式，而是自己的结论：
+
+```ts
+declare function usePresentation<T>(select: (policy: {
+  stepGrouping: 'collapsed' | 'none'
+  foldCompletedTurns: boolean
+}) => T): T
+declare const group: { readonly headStep: number } | undefined
+
+const grouping = usePresentation(p => group === undefined ? 'none' : p.stepGrouping)
+const foldCompleted = usePresentation(p => p.foldCompletedTurns)
+```
+
+不在任何组里的 seat，`grouping` 在三档下都是 `'none'`，值没变就不重渲染。`foldCompletedTurns` 在三档下都是 true，同理。selector hook 的底层是 `useSyncExternalStoreWithSelector`，只有选出的值变化才重渲染。
+
+三个隐藏来源合成一个 `hidden`：
+
+| 来源 | 条件 | 揭示动作 |
+|---|---|---|
+| 整轮折叠 | 现有规则，`turnClosed && turnStarted && 有回复` 且未手动展开 | 打开整轮 |
+| 组折叠 | `grouping === 'collapsed'`、角色为成员、组未手动展开 | 打开该组 |
+| 组头在完全展开档 | 角色为组头且 `grouping === 'none'` | 无 |
+
+关闭者节点的推理部分单独隐藏：seat 通过 owner props 里的 `stepGroup.reasoningHidden` 告诉 assistant-step 渲染器。
+
+组的展开状态进 chat store，key 是 `turn` 加 `headStep`，与整轮的手动展开状态并列。
+
+### 刷新范围
+
+下表是这套结构给出的保证，也是下一轮渲染次数测试的断言表。每一行断言的是精确集合，不是上限。
+
+| 外部变化 | 允许重渲染的 |
+|---|---|
+| 运行中的组来一个推理 chunk | 该 assistant seat |
+| 运行中的组来一个 `tool/call` | 该 tool seat，加这一组的组头 |
+| 回复出现，组关闭 | 该 assistant seat，加这一组的组头；成员归属重算只发生在开关组时 |
+| 新组打开 | 新组头进 `order`，一次结构重排；其他 seat 不刷 |
+| 模式在简洁与详细之间切换 | 仅有已完成推理的 assistant-step 渲染器 |
+| 模式切到完全展开或切回 | 仅成员与组头 seat |
+| `performanceUsage` 切换 | 仅 turn-tail |
+| 加载更早一页 | 新增 seat，加 presentation 变了的历史 seat |
+| 语言切换 | 全部，作为对照 |
+
+### 展示策略对象
+
+持久化的枚举与运行时词汇分开。枚举 `TranscriptViewMode` 是 `compact`、`detailed`、`expanded`，存档里的旧值 `normal` 读取时映射为 `detailed`，不回写。运行时词汇是派生的 `ChatPresentationPolicy`：
+
+| 字段 | compact | detailed | expanded |
+|---|---|---|---|
+| `foldCompletedTurns` | true | true | true |
+| `stepGrouping` | collapsed | collapsed | none |
+| `settledReasoningPreview` | false | true | true |
+
+映射只存在于一处。每档对应一个常量对象，同一档永远同一引用，所以派生观察量不需要自己的订阅簿记：`getSnapshot` 是查表，`subscribe` 直接转给模式观察量。
+
+渲染器不比较枚举，只 select 自己需要的字段。策略观察量按 kind 注入：assistant-step 的注册通过 `inject.hooks.presentation` 拿到它，与 turn-tail 注入 `performanceUsage` 是同一写法。以后加第四档只改这张表，渲染器一个不动。
+
+### 按轮折叠
+
+per-key presentation 增加 `turnStarted`，来源是该轮 `turn/start` 是否在加载窗口内。seat 的折叠资格由 `turnStarted` 替代原来的全局 `!historyIncomplete`。分页加载完成时不再有任何全局 prop 变化，只有新增节点与它们所在轮的 presentation 变化。
+
+### 复杂度契约
+
+| 场景 | fold | builder | 发布 |
+|---|---|---|---|
+| 内容型 chunk，不改变组边界 | O(1) 状态转移，返回原对象 | 无重投影 | 零 |
+| 改变组边界的事件 | O(1) | 只重投影所属轮，成本为该轮节点数 | 该轮内事实变化的 key |
+| 结构变化与分页 | 按匹配的事件数 | 全量一次 | 事实变化的 key |
+| 模式切换 | 无 | 无 | 无；重渲染由 seat 与渲染器的 selector 决定 |
+
+## 改动清单
+
+| 包 | 文件 | 改动 |
+|---|---|---|
+| ui-conversation | `contract/conversation.ts` | 新增 `ConversationLocationDataUpdate`；`ConversationViewBuilder.apply` 入参增加可选 `changedLocationData` |
+| ui-conversation | `conversation/assembler.ts` | `applyDirtyLocationData` 收集换了引用的 Location 数据并随 `apply` 传出 |
+| ui-conversation | `index.ts` | 导出新类型 |
+| ui-chat | `chat-settings.ts` | 三档枚举；schema 接受旧值 `normal` |
+| ui-chat | `transcript-view.ts` | 读取时 `normal` 映射为 `detailed` |
+| ui-chat | `presentation-policy.ts` 新增 | 策略对象、映射表、派生观察量 |
+| ui-chat | `settings/TranscriptViewRow.tsx` | 三个选项 |
+| ui-chat | `locale.ts` | 三档文案；组头文案 |
+| ui-chat | `contract/slots.ts` | `ChatViewInjected.hooks.presentation`；`PresentationInjected`；`ChatNodeOwnerProps.stepGroup`；`StepGroupOwnerProps` |
+| ui-chat | `contract/snapshot.ts` | `ChatTurnProcessPresentation.turnStarted`；`ChatNodeGroupPresentation`；`processSource` 的值改为 per-key 组合对象 |
+| ui-chat | `contract/chat-nodes.ts` | `StepGroupChatData` |
+| ui-chat | `contract/store.ts`、`stores.ts` | 组的手动展开状态与动作 |
+| ui-chat | `conversation-nodes/common.ts` | 组头锚点偏移 |
+| ui-chat | `conversation-nodes/step-groups.ts` 新增 | fold Definition 与 Turn 数据声明合并 |
+| ui-chat | `conversation-nodes/step-group-nodes.ts` 新增 | 组头节点物化与成员归属投影 |
+| ui-chat | `conversation-nodes/turn-process-presentation.ts` | `turnStarted`；组合 per-key presentation |
+| ui-chat | `conversation-nodes/chat-snapshot-builder.ts` | 接入物化投影；消费 `changedLocationData`；store 支持删除 key |
+| ui-chat | `conversation-nodes/register.ts` | 注册 fold Definition |
+| ui-chat | `chat/ChatView.tsx` | 删除 `compactTranscript` 与 `historyIncomplete` 的传递；传 `usePresentation` |
+| ui-chat | `chat/ChatNodeSeat.tsx` | 组合 selector；三个隐藏来源；`stepGroup` owner props |
+| ui-chat | `chat/AssistantNodeView.tsx`、`chat/AssistantMarkdown.tsx`、`chat/ReasoningRow.tsx` | 注入策略；已完成推理的预览开关；关闭者的推理隐藏 |
+| ui-chat | `chat/StepGroupNodeView.tsx` 新增 | 组头渲染器 |
+| ui-chat | `chat/register-node-renderers.ts` | 注册组头渲染器；给 assistant-step 注入策略 |
+| ui-chat | `apply.ts`、`index.ts` | 创建策略观察量并注入；导出类型 |
+
+上述清单保留完整分组方案；独立功能已经更新 README、i18n 配对文件及 slot catalog。测试与快照进度见迁移记录，未完成的分组改动不随这些更新自动完成。
+
+## 验收标准
+
+分组相关验收仍待实现；独立展示功能的验证进度见迁移记录。
+
+**渲染次数隔离测试。** 在现有 `chat-view.client.spec` 的挂载方式上加计数：React Profiler 的 `onRender` 按 seat 计数，测试专用的计数渲染器注册进 `conversation.chat.node` 按 kind 计数。刺激与期望按「刷新范围」一节的表逐行断言精确集合。
+
+**发布次数测试。** 同样的刺激下统计每个 key 的 source 通知次数，断言精确集合。
+
+**fold 状态机单测。** 喂事件序列，断言组列表：开组、关组、同 step 先文本后工具开新组、轮次结束关组、幂等性、已关闭组对象引用不变、只有落盘消息的历史重放得到相同组列表。
+
+**成员归属单测。** 给定组列表与该轮节点，断言每个 key 的角色。
+
+**基准补位。** `conversation-fold` 增加带推理与工具的增量 apply 场景；`long-session-browser` 增加带工具与推理的流式 fixture。这是墙钟兜底，不是门禁。
+
+## 风险
+
+- **builder 产出节点的边界。** 这是这套架构里第一次由视图 builder 产出节点。边界写死为：builder 只能从 Turn 或 Step 数据物化行，不能读事件，不能自己算业务结构。合成 key 用 `step-group:` 前缀，Context key 以数字开头，不会冲突。如果实践中被否决，退到路线 A。
+- **组头锚点随头成员移动一次。** 头成员是流式 Assistant 时，落盘让锚点从首个可见 chunk 移到消息事件，组头跟着移动一次。与 Assistant 自己的结构性更新同时发生。
+- **三档在本轮的实际差异。** 简洁与详细目前只差已完成推理的首行预览；运行中的详情标题、类别摘要等产品特性不在本轮。策略表已为它们留了位置。
+- **分页与半截轮。** 被分页切开的最老一轮不折叠、不分组；归属只按 step 计算，不受分页影响。
+- **组头文案。** 本轮只有「正在处理」与「已完成处理」加工具调用次数，类别摘要留给产品层。
+- **流式 chunk 的 step 字段。** `assistant/live-chunk` 事件携带 `step`，与 `turn-process` 的用法相同；若 chunk 缺少 step 则不开组。
+
+## 备选保留：父 Context 派生子 Context
+
+如果 builder 物化节点在使用中暴露出比预期更多的边界问题，替代方案是给引擎加一个原语：Context 在 `update` 中可以派生一个指定 kind 与 id 的子 Context，并把后续匹配转发给它；子 Context 有自己的单个节点、自己的发布节奏与 Location。父 Context 重放时子 Context 按 id 对齐，未再派生的子 Context 按现有撤回规则转为隐藏。
+
+它的收益是行的身份与内容都回到 Definition 层，一组一个 Context，没有数组碎片。代价是 assembler 要新增转发与重放级联，且 `match` 之外多出一条 Context 创建路径。切换条件：builder 物化节点的边界在两个以上业务里被突破，或成员归属的按 step 规则出现无法用 step 表达的用例。
diff --git a/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.i18n.yaml b/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.i18n.yaml
new file mode 100644
index 0000000000..1f41262d74
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both 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-09-20-chat-work-details-migration.md
+2026-09-20-chat-work-details-migration.md: cd5dbe723425d5bed719bbb579305e3f917d0cc5
+2026-09-20-chat-work-details-migration.zh.md: 4055b027fc7e5c710358886361badb88a4e9b13e
diff --git a/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.md b/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.md
new file mode 100644
index 0000000000..cd5dbe7234
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.md
@@ -0,0 +1,144 @@
+# Agent Note: Chat work-details migration progress
+
+Status: proposed
+
+English | [中文](2026-09-20-chat-work-details-migration.zh.md)
+
+## Problem
+
+PR #4565 combines three display modes, process grouping, whole-Turn status, trigger notifications, tool-row visuals, and infrastructure-row hiding. Migrating it as one batch mixes independent features with list restructuring and makes individual performance changes difficult to assess. A feature-based progress table allows independent visuals to be reviewed first and Turn-related behavior to be considered with step-group later, without losing product requirements.
+
+## Proposal
+
+Completed independent features stay in `feat/chat-presentation-channel`. The remaining unfinished code continues in `.artifacts/worktrees/pr-4565-turnstep` under the repository root, based on the current channel and this progress record, with drafts kept unstaged for combined turn/step and grouping review. The `pr-4565` worktree remains the original PR's behavior and implementation reference; existing `feat/chat-step-groups` experiments are outside this transfer.
+
+This record tracks feature scope, current implementation, and acceptance progress. The [presentation policy channel and process-group architecture](../architecture/2026-09-20-chat-presentation-policy-and-step-groups.md) retains the architecture and alternatives. This record neither replaces it nor treats its proposals as implemented. Because it does not fully supersede that decision, retain the architecture note without archival or deletion.
+
+This record maintains an English/Chinese pair. Completion, implementation, staging or commit state, and acceptance are separate dimensions. Incomplete items remain marked incomplete even when drafts exist, and stay in the inventory. Tests and documentation are added during CI repair; browser snapshots and performance acceptance are tracked separately. Written code, staging, commits, and successful builds do not establish complete functional or performance acceptance.
+
+### Status definitions
+
+| Dimension | State | Meaning |
+|---|---|---|
+| Completion | Complete | Migration code has been reviewed feature by feature and committed to this channel; behavior and performance evidence are separate |
+| Completion | Incomplete | Outside the channel's completed migration scope; may have an unstaged draft or no implementation |
+| Implementation | Existing capability | Already present in this channel |
+| Implementation | Code written | Implementation exists in the relevant worktree; does not imply completion, staging, commit, or acceptance |
+| Implementation | Awaiting migration | Included in non-grouping scope but not yet implemented |
+| Implementation | Grouping phase | Requirement retained; depends on grouping structure or interactions and is not connected to this channel yet |
+| Staging or commit | Unstaged | Changes remain in the worktree, including untracked files |
+| Staging or commit | Partially staged | Only some feature changes are staged; the exact scope must be stated |
+| Staging or commit | Staged | All pending code changes for the feature are staged but not committed |
+| Staging or commit | Committed | Feature code is included in current HEAD |
+| Acceptance | Pending | Requires behavior, node identity, update-scope, or browser performance evidence; Git state and compilation cannot substitute |
+
+Verify staging against the feature's diff hunks, not whole files. Inspect the worktree, index, and HEAD when updating status. Staging some fields in a shared file does not stage every feature depending on that file.
+
+### Capabilities already in this channel
+
+| Capability | compact | detailed | expanded | Completion | Implementation | Staging or commit | Acceptance |
+|---|---|---|---|---|---|---|---|
+| Three settings and legacy-value reading | Compact | Detailed; legacy `normal` reads as this mode without write-back | Expanded | Complete | Existing capability | Committed | Pending |
+| Per-Turn folding eligibility | A closed Turn with its start loaded and a final reply can fold process content; cancellation/failure extensions are item 6 | Same | Same | Complete | Existing capability | Committed | Pending |
+| Collapsed settled-reasoning summary | Think title only | First line | First line | Complete | Existing capability | Committed | Pending |
+| Retain summary DOM across mode changes | CSS hides summary and separator | Show existing summary and separator | Same | Complete | Existing capability | Committed | Pending |
+| Local reasoning-preview subscription | `ReasoningRow` selects its own visibility | Same | Same | Complete | Existing capability | Committed | Pending |
+| Stable disclosure-row references | Callbacks, icons, and unchanged summaries retain references; full Markdown mounts only on expansion | Same | Same | Complete | Existing capability | Committed | Pending |
+
+All three modes retain whole-Turn folding. `expanded` means removing secondary process groups, not disabling whole-Turn folding or automatically expanding reasoning and tool-card bodies. Until grouping is connected, Chat presents `detailed` and `expanded` identically.
+
+### Migration inventory without grouping dependencies
+
+“All three modes” means the behavior applies in every mode, not that switching modes changes it. “Without grouping dependencies” means the draft introduces no step-group, not that every item must be accepted before grouping. Numbers follow the feature review inventory; item 0's compilation wiring is complete and committed, so it is not listed as a product feature. Incomplete drafts remain in `pr-4565-turnstep`, outside this channel's completed features. Behavior and performance acceptance remain pending for the features below.
+
+| Number | Feature | compact | detailed | expanded | Completion | Implementation | Staging or commit | Destination and considerations |
+|---|---|---|---|---|---|---|---|---|
+| 1 | Chinese tool titles | All three modes | All three modes | All three modes | Complete | Code written | Committed | Bash/Pwsh: “运行命令”; Grep: “搜索文件内容”; Glob: “查找文件”; Skill: “加载技能”. Only UI dictionaries change; model tool names do not |
+| 2 | Tool-row interaction visuals | All three modes | All three modes | All three modes | Complete | Code written | Committed | Hover darkens titles and summaries in tool, Bash, and command rows; shared `DisclosureRow` and independent Bash rows point the expanded chevron upward |
+| 3 | Bash stopped-state screen-reader text | All three modes | All three modes | All three modes | Complete | Code written | Committed | Complete the stopped-state accessible name without changing execution or cancellation semantics |
+| 4 | Running tool/command text shimmer | All three modes | All three modes | All three modes | Complete | Code written | Both 4A shimmer and 4B accompanying optimizations committed | 4A includes a fixed `TextShimmer` span, CSS activation, tool/command integration, replacement of old sweep styles, and reduced-motion support, excluding step/turn. 4B adds business-row computation caches, stable callbacks, and JSX references |
+| 5 | Streaming reasoning summary | Update after a paragraph's first line completes | Same | Same | Complete | Code written | Committed | `ReasoningRow` retains the original PR's `latestCompletedParagraphFirstLine(text)` and computes from full text. Retain summary DOM, stable props, and right-edge fading; add no Definition parsing state or cross-layer summary fields |
+| 6 | Keep process expanded after cancellation/failure | All three modes | All three modes | All three modes | Incomplete | Draft code written | Unstaged | Draft uses `keepOpen` in Turn process projection; folding eligibility and stopped/failed behavior await Turn/grouping review |
+| 7 | Whole-Turn status and duration control | All three modes | All three modes | All three modes | Incomplete | Draft code written | Unstaged | Draft anchors the control to loaded `turn/start` after opening inputs, isolates timing in `LiveTurnProcessLabel`, and replaces the bottom activity bar; positioning and status await review |
+| 8 | Non-human trigger notifications | All three modes | All three modes | All three modes | Incomplete | Draft code written | Unstaged | Draft identifies waking inputs from next-turn and first-step next-step claims and projects `turn-trigger`; Turn starts, notification ownership, and expanded content await review |
+| 9 (permission/system) | Hide permission-command and system-prompt rows | All three modes | All three modes | All three modes | Complete | Code written | Committed | `isVisibleChatNode` centralizes filtering for the existing Chat list, navigation, and process presentation. Command and request-prompt Definitions do not own these filters; persistence and Trajectory are unchanged |
+| 9 (context) | Hide ordinary Context rows | All three modes | All three modes | All three modes | Incomplete | Draft code written | Unstaged | Paired with item 8's waking notifications to retain source explanations; final filter ownership awaits Turn/grouping review |
+| 10 | Turn action-bar positioning | All three modes | All three modes | All three modes | Incomplete | Draft code written | Unstaged | Draft anchors `turn-tail` after `turn/end`; reply ownership for feedback/copy and the real Turn-end seq for branching await combined review |
+| 11 | Action-bar persistent visibility | All three modes | All three modes | All three modes | Incomplete | Draft code written | Unstaged | Draft projects `footer` per Turn in the Chat builder: persistently visible when the latest Turn ends in a reply, otherwise on hover/focus; tail detection will be considered with grouping |
+
+The current base already enables developer tools by default; do not migrate that again. Retain the protection that waits for Host acceptance of settings instead of applying the original PR's missing-value fallback. Its `Switch` change only affects a comment and is not a migrated feature.
+
+### Subsequent review batches
+
+Review batches are independent of implementation and staging status. Review remaining drafts in `pr-4565-turnstep`, kept unstaged; a draft does not complete a migration. Transfer only this channel's remaining code, without automatically incorporating `feat/chat-step-groups` experiments or installing dependencies and compiling in the destination worktree.
+
+| Batch | Features | Review scope |
+|---|---|---|
+| Independent feature, committed | 4A: text shimmer | `TextShimmer`, row integration, and browser painting cost; performance acceptance pending |
+| Independent optimization, committed | 4B: accompanying memoization and reference stability | `ToolRow`, `BashRow`, and `GenericCommandCard` computation caches, callbacks, and JSX references; not required for shimmer itself; performance acceptance pending |
+| Independent feature, committed | Permission-command and system-prompt hiding from item 9 | Retain the original PR's centralized visibility decision; without step-group, the main list connects it in `orderedVisibleChatNodes`, independent of waking-message classification |
+| Incomplete, transferred to turnstep worktree | 6, 7, 10, 11 | Whole-Turn folding eligibility, status/clock, action-bar position, and tail detection, considered with Turn/group relationships |
+| Incomplete, transferred to turnstep worktree | 8 and ordinary Context hiding from item 9 | Trigger notifications depend on Turn starts and Inbox claims; Context hiding accompanies notifications so waking reasons remain visible |
+
+### Requirements retained for the grouping phase
+
+All items below remain incomplete and retain their full requirements for the turn/step and grouping phase. Neither this channel nor the transferred drafts introduce step-group. Experimental code in `feat/chat-step-groups` does not establish completion of these product behaviors or performance requirements.
+
+| Feature | compact | detailed | expanded | Current state |
+|---|---|---|---|---|
+| Consecutive process groups between replies | Group tools and reasoning, initially collapsed | Same | Show process rows directly without secondary wrappers | Incomplete (grouping phase) |
+| Independent reasoning/reply visibility within one Assistant | Reasoning may join the preceding group; reply stays visible | Same | No secondary group hiding | Incomplete; do not directly copy the original split into two render nodes |
+| Header category summary | Current category while running; aggregate main categories after completion | Same | No header | Incomplete (grouping phase) |
+| Running header details | Hidden | Show command, path, query, etc.; reasoning summary when no tool is running | No header | Incomplete (grouping phase) |
+| Header update cadence | Preserve category title's minimum display duration | Also handle detail updates | Not applicable | Incomplete (grouping phase) |
+| Height-limited scrolling within a group | Limit expanded height, scroll independently, fade edges | Same | Not applicable | Incomplete (grouping phase) |
+| Group and whole-Turn folding interaction | Hide groups when the Turn folds | Same | Whole-Turn folding only | Incomplete; retain node identity and separately decide whether internal expansion resets |
+| Pagination, streaming settlement, and group identity | Stable existing headers and members; handle partial Turns separately | Same | Show the same business nodes directly | Incomplete (grouping phase) |
+
+Grouping details to verify: completed summaries aggregate at most three categories and use “etc.” beyond three; call counts determine category ordering rather than appearing as header numbers. Detailed-mode live details collapse whitespace and are capped at 160 characters. Titles remain for at least 150ms; retain only the latest update without replaying queued updates. Expanded height is at most the smaller of 400px and half the viewport. Scrollable edges use a 24px fade and preserve interaction with outer scrolling. Retry rows are outside secondary groups. These values describe the original PR's reference behavior, not completed grouping experiments.
+
+## Performance constraints
+
+| Scenario | Property to preserve | Required evidence |
+|---|---|---|
+| Switching among modes | Business-node keys do not change; modes do not re-register Definitions; only relevant visibility/presentation fields update | Node identity and update-scope checks |
+| Incremental reasoning/tool content | Update only the owning node without scanning full history; compute reasoning summary from current full text during rendering | Update scope and long-text cost; the current summary algorithm does not reduce `ReasoningRow` render count |
+| Whole-Turn running clock | Only live clock content updates each second, without refreshing members, historical rows, or list | Update scope and timer disposal |
+| Summary visibility | Keep lightweight summaries mounted; do not mount every full Markdown body for mode switching | DOM identity, initial loading, memory observations |
+| Pagination | Update new nodes and nodes with changed facts; completed Turns do not refresh together because of global pagination state | Multi-page interaction and update-scope checks |
+| State transitions | Stable text/icon/callback references when content is unchanged; do not clear internal state through remounting | Interaction state and component lifecycle checks |
+
+Retaining DOM reduces mounting and unmounting cost, not style calculation, layout, or painting, and can increase retained memory. Changing display properties alone is not a guarantee against jank. The aim is lower switching peaks with acceptable initial-load, pagination, and streaming costs.
+
+## Alternatives considered
+
+**Replay the original PR as one batch.** Rejected: grouping, node splitting, whole-Turn status, and independent visuals would mix, obscuring each feature's performance effects and overwriting local subscriptions and node reuse already completed in this channel.
+
+**Unmount and recreate summaries or process nodes on mode changes.** Rejected for summary mode changes. Stable mounts allow repeated switching to change only display state; initial costs for new nodes still require separate validation.
+
+**Keep every Markdown body mounted for smooth switching.** Rejected: lightweight summaries and full bodies differ in memory, DOM, and rendering cost. Bodies remain mounted according to manual expansion.
+
+**Remount renderers when folding a Turn to reset tool cards.** Do not migrate directly. It conflicts with stable nodes and preserved interaction state. If reset behavior remains necessary, define its state owner and trigger explicitly.
+
+## Acceptance criteria
+
+Update implementation, staging, and commit status separately as work progresses. Completion follows feature review and commits; acceptance follows actual validation. Retain incomplete items across branch splits and worktree transfers. Before grouping work starts, check every product requirement and mode mapping above.
+
+| Acceptance item | Current state |
+|---|---|
+| Complete behavior validation of existing channel capabilities | Relevant unit and browser regressions pass; this excludes unmigrated grouping features and does not establish performance acceptance |
+| Non-grouping feature migration | Completed scope is in the inventory; incomplete drafts await review in `pr-4565-turnstep`; functional and performance validation remain incomplete |
+| DOM identity and update scope during mode changes | Unit tests verify summary/expanded-body DOM identity and policy-field subscriptions; browsers verify persistence of all modes and whole-Turn folding; whole-page update scope and performance remain pending |
+| Long-session initial loading, pagination, streaming, and memory | Pending; the original PR's historical measurements do not validate this implementation |
+| Unit, browser, and recorded-snapshot coverage | 785 relevant unit tests pass; read-only replay of 35 browser files yields 178 passing tests and 4 conditional skips; UI expectations are updated and Session JSONL is unchanged |
+| Grouping and the Detailed/Expanded distinction | Incomplete (grouping phase) |
+
+Validation evidence: after rebasing onto master, this channel passed full `pnpm run build`, lint, duplication checks, and all 41 documentation checks. New presentation policy, shimmer, and visibility filtering, plus the settings and Skill rows reported by CI, pass 100% coverage checks over their selected source scope. Test repairs, UI snapshots, and bilingual pairing are committed together as CI fixes. No install, build, or tests ran in `pr-4565-turnstep`; this channel's results do not establish acceptance for that worktree. A real-model GUI demo and performance measurements remain outstanding.
+
+## Risks
+
+- `expanded` and `detailed` currently present identically; the original PR's distinction exists only after grouping is implemented.
+- Whole-Turn duration replaces the existing tool/message-count title, changing product information. Migration must preserve status, accessible names, and Turns with no process content, not merely restyle the control.
+- Hiding ordinary Context before adding trigger notifications removes background waking reasons; connect both items in the inventory's order.
+- The original footer decision depends on grouping indexes. Rework ownership per feature rather than introducing the whole grouping infrastructure for a footer.
+- Group identity, membership, and builder materialization in the experiments still require evaluation; this record does not treat the experiment as final architecture.
diff --git a/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.zh.md b/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.zh.md
new file mode 100644
index 0000000000..4055b027fc
--- /dev/null
+++ b/.agents/notes/proposed/feature/2026-09-20-chat-work-details-migration.zh.md
@@ -0,0 +1,144 @@
+# Agent Note: Chat 工作过程展示迁移进度
+
+Status: proposed
+
+[English](2026-09-20-chat-work-details-migration.md) | 中文
+
+## 问题
+
+PR #4565 同时包含三档展示设置、过程分组、整轮状态、触发通知、工具行视觉和基础设施行隐藏。整批迁移会把独立功能与列表重组混在一起，也难以逐项判断性能变化。需要一份按功能维护的进度表，先评审独立视觉功能，再结合 step-group 统一考虑轮次相关行为，避免遗漏原有产品需求。
+
+## 方案
+
+已完成的独立功能保留在 `feat/chat-presentation-channel`。剩余未完成代码的后续工作区是仓库根目录下的 `.artifacts/worktrees/pr-4565-turnstep`，以当前通道及本进度记录为基线，草稿保持未暂存；后续结合 turn/step 与分组整体评审。`pr-4565` worktree 继续作为原 PR 的行为和实现参考；`feat/chat-step-groups` 的既有分组实验不在本次搬迁范围内。
+
+本记录管理功能范围、当前实现和验收进度。[展示策略通道与过程分组的基础架构](../architecture/2026-09-20-chat-presentation-policy-and-step-groups.zh.md)保留架构路线及备选方案；本记录不替代它，也不把其中的方案视为已经实现。新记录没有完整取代既有架构决策，因此保留原记录，不做归档或删除。
+
+本记录维护中英文配对。完成状态、实现状态、暂存或提交状态、验收状态分别记录。未完成项即使已有代码草稿，也继续标为未完成，不从清单移除。测试和文档随 CI 修复补齐，浏览器快照与性能验收单独记录；代码写好、进入暂存区、提交或构建通过，都不等同于完整功能或性能验收。
+
+### 状态定义
+
+| 维度 | 状态 | 含义 |
+|---|---|---|
+| 完成 | 已完成 | 功能迁移代码已逐项审阅并提交到当前通道；行为与性能证据另行记录 |
+| 完成 | 未完成 | 尚未纳入当前通道的已完成迁移范围；可以已有未暂存草稿，也可以尚未编写 |
+| 实现 | 当前代码已有 | 当前通道的既有基础能力 |
+| 实现 | 代码已写好 | 对应工作区中已有实现；不代表已完成、已暂存、已提交或通过验收 |
+| 实现 | 待迁移 | 已纳入非分组迁移范围，当前尚未实现 |
+| 实现 | 分组阶段 | 产品需求保留，依赖分组结构或分组交互，暂不接入当前通道 |
+| 暂存或提交 | 未暂存 | 该功能的改动仍在工作区，包括尚未跟踪的新文件 |
+| 暂存或提交 | 部分暂存 | 该功能只有部分改动进入暂存区，必须注明具体范围 |
+| 暂存或提交 | 已暂存 | 该功能当前待提交的代码改动均已进入暂存区，尚未提交 |
+| 暂存或提交 | 已提交 | 该功能代码已包含在当前 HEAD 中 |
+| 验收 | 待验收 | 需要行为、节点身份、刷新范围或浏览器性能证据；不能用 Git 状态或编译结果代替 |
+
+暂存状态按产品功能对应的差异片段核对，不按整个文件推断。更新状态时同时查看工作区、暂存区和 HEAD；共享文件只暂存部分字段，不能将依赖该文件的所有功能都标为已暂存。
+
+### 当前通道已有的能力
+
+| 能力 | compact | detailed | expanded | 完成状态 | 实现状态 | 暂存或提交状态 | 验收状态 |
+|---|---|---|---|---|---|---|---|
+| 三档设置与旧值读取 | 简洁 | 详细；旧值 `normal` 读作本档，不回写 | 完全展开 | 已完成 | 当前代码已有 | 已提交 | 待验收 |
+| 按轮判断整轮折叠资格 | 已加载起点且存在最终回复的结束轮次，可收起过程内容；停止和失败的扩展行为见迁移项 6 | 相同 | 相同 | 已完成 | 当前代码已有 | 已提交 | 待验收 |
+| 已完成推理的收起摘要 | 只显示「思考」 | 显示首行 | 显示首行 | 已完成 | 当前代码已有 | 已提交 | 待验收 |
+| 模式切换时保留摘要 DOM | 用 CSS 隐藏摘要及分隔点 | 显示原有摘要及分隔点 | 相同 | 已完成 | 当前代码已有 | 已提交 | 待验收 |
+| 推理预览的局部订阅 | `ReasoningRow` 选择自己的可见性 | 相同 | 相同 | 已完成 | 当前代码已有 | 已提交 | 待验收 |
+| 折叠行引用稳定 | 回调、图标及未变化的摘要保持引用；完整 Markdown 仅在展开时挂载 | 相同 | 相同 | 已完成 | 当前代码已有 | 已提交 | 待验收 |
+
+三档都保留整轮折叠。`expanded` 的产品含义是取消二级过程分组，并非禁止整轮折叠，也不是自动展开每个思考或工具卡的正文。分组尚未接入时，`detailed` 与 `expanded` 的 Chat 展示相同。
+
+### 不依赖分组的迁移清单
+
+下表的“三档共用”表示三档都应用该行为，不表示切换档位时会改变它。“不依赖分组”指实现草稿未引入 step-group，不代表都要先于分组接受。编号沿用逐项评审清单；编号 0 的编译接线修正已完成并提交，不作为产品功能另列。未完成项的草稿留在 `pr-4565-turnstep`，不是当前通道已完成的功能。下列功能的行为与性能均待验收。
+
+| 编号 | 功能 | compact | detailed | expanded | 完成状态 | 实现状态 | 暂存或提交状态 | 迁移落点与注意事项 |
+|---|---|---|---|---|---|---|---|---|
+| 1 | 工具标题中文化 | 三档共用 | 三档共用 | 三档共用 | 已完成 | 代码已写好 | 已提交 | Bash/Pwsh 为「运行命令」、Grep 为「搜索文件内容」、Glob 为「查找文件」、Skill 为「加载技能」；只改 UI 字典，不改模型工具名 |
+| 2 | 工具行交互视觉 | 三档共用 | 三档共用 | 三档共用 | 已完成 | 代码已写好 | 已提交 | 工具行、Bash 行和命令行悬停时标题及摘要加深；共享 `DisclosureRow` 和独立 Bash 行展开箭头朝上 |
+| 3 | Bash 停止状态的读屏提示 | 三档共用 | 三档共用 | 三档共用 | 已完成 | 代码已写好 | 已提交 | 补齐停止状态的可访问名称，不改变执行或取消语义 |
+| 4 | 工具及命令运行时文字扫光 | 三档共用 | 三档共用 | 三档共用 | 已完成 | 代码已写好 | 4A 扫光与 4B 附带优化均已提交 | 4A 包含 `TextShimmer` 固定 span 与 CSS 启停、工具及命令行接入、旧扫光样式替换和减少动态效果支持，不含 step/turn；4B 为业务行额外的计算缓存、稳定回调及 JSX 引用 |
+| 5 | 流式推理摘要 | 段落首行写完后才更新 | 相同 | 相同 | 已完成 | 代码已写好 | 已提交 | `ReasoningRow` 沿用原 PR 的 `latestCompletedParagraphFirstLine(text)`，直接从完整文本计算；摘要 DOM、稳定 props 和右侧渐隐保留，不增加 Definition 解析状态或跨层摘要字段 |
+| 6 | 取消、失败后保持过程展开 | 三档共用 | 三档共用 | 三档共用 | 未完成 | 代码草稿已写好 | 未暂存 | 草稿在 Turn 过程投影中使用 `keepOpen`；轮次与分组阶段再评审折叠资格和停止、失败行为 |
+| 7 | 整轮状态与用时控件 | 三档共用 | 三档共用 | 三档共用 | 未完成 | 代码草稿已写好 | 未暂存 | 草稿将控件锚定到已加载的 `turn/start`、排在开场输入之后，以 `LiveTurnProcessLabel` 单独计时，并替换底部运行条；整体定位与状态待评审 |
+| 8 | 非人工触发通知 | 三档共用 | 三档共用 | 三档共用 | 未完成 | 代码草稿已写好 | 未暂存 | 草稿使用 next-turn 及首步 next-step 领取事实识别唤醒输入，投影 `turn-trigger`；轮次起点、通知归属和展开内容待评审 |
+| 9（permission/系统） | 隐藏 permission 命令与系统提示词行 | 三档共用 | 三档共用 | 三档共用 | 已完成 | 代码已写好 | 已提交 | `isVisibleChatNode` 集中判断，现有 Chat 列表、导航和过程展示复用；命令与请求提示词 Definition 不承载这些过滤规则，持久化数据与 Trajectory 不变 |
+| 9（context） | 隐藏普通上下文行 | 三档共用 | 三档共用 | 三档共用 | 未完成 | 代码草稿已写好 | 未暂存 | 与 8 的唤醒通知配套，保留来源解释；过滤规则的最终归属留到轮次与分组阶段 |
+| 10 | 轮次操作栏位置 | 三档共用 | 三档共用 | 三档共用 | 未完成 | 代码草稿已写好 | 未暂存 | 草稿将 `turn-tail` 锚定到 `turn/end` 之后；反馈、复制的回复归属和分支的真实轮次结束序号待整体评审 |
+| 11 | 操作栏常显条件 | 三档共用 | 三档共用 | 三档共用 | 未完成 | 代码草稿已写好 | 未暂存 | 草稿由 Chat builder 按 Turn 投影 `footer`；最新轮以回复结尾时常显，其余悬停或聚焦显示，尾部判定与分组一起考虑 |
+
+开发者工具默认开启已由当前基线提供，不重复迁移。当前实现保留等待 Host 接受设置后才启用相关能力的保护，不以原 PR 的缺值回退覆盖它。原 PR 的 `Switch` 改动只有注释，不作为功能迁移项。
+
+### 后续评审批次
+
+评审批次独立于实现和暂存状态。未完成草稿的后续评审统一在 `pr-4565-turnstep`，保持未暂存；已有草稿不代表迁移已完成。仅搬迁当前通道的剩余代码，不自动合入 `feat/chat-step-groups` 的实验，也不在目标工作区安装依赖或编译。
+
+| 批次 | 功能 | 评审范围 |
+|---|---|---|
+| 独立功能，已提交 | 4A：文字扫光 | `TextShimmer` 本身、各行的调用方式和浏览器绘制成本；性能待验收 |
+| 独立优化，已提交 | 4B：附带的 memo 与引用稳定化 | `ToolRow`、`BashRow` 和 `GenericCommandCard` 的计算缓存、回调和 JSX 引用；不是扫光功能的必要条件，性能待验收 |
+| 独立功能，已提交 | 9 中的 permission 命令与系统提示词隐藏 | 沿用原 PR 的集中可见性判断；当前无 step-group，主列表改在 `orderedVisibleChatNodes` 接入，不依赖唤醒消息分类 |
+| 未完成，转入 turnstep 工作区 | 6、7、10、11 | 整轮折叠资格、状态与时钟、操作栏位置和尾部判定，统一考虑轮次与分组关系 |
+| 未完成，转入 turnstep 工作区 | 8、9 中的普通 context 隐藏 | 触发通知依赖轮次起点和 Inbox 领取判定；隐藏普通上下文与通知配套，避免先隐藏唤醒原因 |
+
+### 分组阶段保留的需求
+
+这些项目均未完成，继续保留全部需求，后续在 turn/step 与分组阶段处理。当前通道和本次搬迁草稿均未引入 step-group；`feat/chat-step-groups` 的实验代码不代表这些产品行为或性能要求已经完成。
+
+| 功能 | compact | detailed | expanded | 当前状态 |
+|---|---|---|---|---|
+| 回复之间的连续过程分组 | 工具与推理归组，默认收起 | 相同 | 过程行直接展示，不使用二级分组包装 | 未完成（分组阶段） |
+| 同一 Assistant 中推理与回复的分别显隐 | 推理可归入前组，回复外露 | 相同 | 不做二级分组隐藏 | 未完成；不直接复制原版拆成两个渲染节点的实现 |
+| 组头类别摘要 | 运行时显示当前类别，完成后聚合主要类别 | 相同 | 无组头 | 未完成（分组阶段） |
+| 运行中组头详情 | 不显示 | 显示命令、路径、查询等详情，无运行工具时显示推理摘要 | 无组头 | 未完成（分组阶段） |
+| 组头内容更新节奏 | 保留类别标题的最短展示时间 | 同时处理详情更新 | 不适用 | 未完成（分组阶段） |
+| 组内限高滚动 | 展开内容限高、独立滚动、边缘渐隐 | 相同 | 不适用 | 未完成（分组阶段） |
+| 分组与整轮折叠联动 | 整轮收起时隐藏分组 | 相同 | 仅整轮折叠 | 未完成；保留节点身份，内部开合状态是否重置单独确定 |
+| 分页、流式结算与组身份 | 既有组头和成员稳定，半截轮单独处理 | 相同 | 同一批业务节点直接展示 | 未完成（分组阶段） |
+
+分组产品细节的核对项：完成摘要最多聚合前三类，超过三类使用「等」；调用计数用于分类排序，不直接显示为组头数字。详细模式的实时详情合并空白并限制为 160 个字符；标题最短展示时间为 150ms，只保留最新更新，不补播积压项。展开区高度不超过 400px 与半屏中的较小值，可滚动方向显示 24px 渐隐，并保留与外层滚动的衔接。重试行不属于二级过程组。这些数值是原 PR 的行为参考，不代表当前分组实验已经实现。
+
+## 性能约束
+
+| 场景 | 要保留的性质 | 所需证据 |
+|---|---|---|
+| 切换三档模式 | 不改变业务节点 key，不因模式切换重新注册 Definition；仅相关可见性或展示字段更新 | 节点身份和刷新范围检查 |
+| 推理或工具内容增量更新 | 只更新所属节点，不扫描完整历史；推理摘要在渲染时从当前完整文本计算 | 更新范围与长内容计算开销；当前摘要算法不减少 `ReasoningRow` 的渲染次数 |
+| 整轮运行时钟 | 只有运行中的时钟内容按秒更新，不带动整轮成员、历史行和列表 | 更新范围及计时器释放检查 |
+| 摘要显隐 | 轻量摘要常驻；完整 Markdown 正文不为模式切换而全部常驻 | DOM 身份、首次加载和内存观察 |
+| 分页 | 新增节点与事实变化的节点更新，已完成轮次不因全局分页状态一起刷新 | 多页历史交互与刷新范围检查 |
+| 状态切换 | 文字、图标、回调引用在内容未变时稳定；不通过重挂载清空内部状态 | 交互状态与组件生命周期检查 |
+
+保留 DOM 只减少挂载和卸载成本，不消除样式计算、布局与绘制，也会增加常驻内存。不能将“只改显示属性”写成“不会卡顿”的保证。性能目标是降低切换峰值，并保持首次加载、分页和流式更新的成本可接受。
+
+## 备选方案与取舍
+
+**整批重放原 PR。** 不采用。分组、节点拆分、整轮状态和独立视觉功能混在一起，难以把性能变化对应到具体功能，也会覆盖当前通道已完成的局部订阅与节点复用。
+
+**切换模式时卸载、重新创建摘要或过程节点。** 摘要模式切换不采用该方式。稳定挂载让来回切换只改变显示状态；新增节点的初始成本仍须单独检查。
+
+**为了切换平滑，把所有 Markdown 正文常驻。** 不采用。轻量摘要与完整正文的内存、DOM 和渲染成本不同；正文继续按手动展开状态挂载。
+
+**收起整轮时重挂载 renderer，以重置工具卡。** 不直接迁移。该实现与稳定节点及保留交互状态的方向冲突；若后续仍需要重置行为，应明确状态所有者和触发规则。
+
+## 验收标准
+
+每项代码写好、暂存或提交后，分别更新对应状态；完成状态按逐项评审和提交记录更新，验收只按实际验证记录更新。未完成项保留，不因拆分分支或搬迁工作区而删除。分组阶段开始前，逐行复核上面的产品需求和模式对应关系。
+
+| 验收项 | 当前状态 |
+|---|---|
+| 当前通道已有能力的完整行为验证 | 已通过本次相关单元和浏览器回归；不包含未迁移的分组功能，也不代表性能验收 |
+| 非分组功能迁移 | 完成范围见迁移清单；未完成草稿留到 `pr-4565-turnstep` 继续评审，功能与性能验证仍未完成 |
+| 模式切换时的 DOM 身份和刷新范围 | 单元测试已验证摘要、手动展开正文的 DOM 身份和策略字段订阅；浏览器已验证三档持久化及整轮折叠，整页刷新范围与性能仍待验收 |
+| 长会话首次打开、分页、流式输入与内存 | 待验收；原 PR 的历史测量不代表本实现 |
+| 新行为的单元、浏览器与录制快照覆盖 | 相关单元测试 785 项通过；35 个浏览器文件只读回放，178 项通过、4 项按条件跳过；UI 预期输出已更新，Session JSONL 未改动 |
+| 分组功能与两档差异 | 未完成（分组阶段） |
+
+验证记录：当前通道在 rebase master 后通过完整 `pnpm run build`、lint、重复代码检查和完整文档检查（41 项）。新增展示策略与扫光、可见性过滤，以及 CI 报告的设置行和 Skill 行覆盖率已通过对应源码范围的 100% 检查。测试修复、UI 快照和中英配对随 CI 修复一并提交；`pr-4565-turnstep` 未执行安装、构建或测试，当前通道的结果不代表该工作区已验收。真实模型 GUI 演示和性能测量仍待补。
+
+## 风险
+
+- 当前 `expanded` 与 `detailed` 的展示相同；只有分组阶段完成后，两档才具备原 PR 设计的区别。
+- 整轮用时控件替换现有工具和消息计数标题，属于产品信息变化；迁移时不能只换样式而遗漏状态、可访问名称或空过程轮次。
+- 普通上下文隐藏若先于触发通知，会让后台唤醒原因消失；两项需按清单顺序衔接。
+- 原 PR 的页脚判定与分组索引耦合，需要按功能重写归属，不能为页脚单独引入整套分组基础设施。
+- 分组实验中的组身份、成员归属和 builder 物化路线仍需继续评估；本记录不将实验实现列为最终架构。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 32b58e9bc1..0c2077159b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -357,6 +357,9 @@ jobs:
         if: vars.DSH_CI_FAILOVER_LINUX == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]'
         run: pnpm --filter @deepseek-ai/dsh-web-frontend exec playwright install chromium
 
+      - name: Build and execute the Linux Office runtime
+        run: CI=true pnpm run prepare:primary-runtime --target linux-x64 --output "$RUNNER_TEMP/office-runtime" --cache "$RUNNER_TEMP/office-runtime-downloads"
+
       - name: Run compatibility, snapshot, and artifact gates
         run: pnpm run check:ci:consumers
 
diff --git a/.gitignore b/.gitignore
index 7ad33230ad..86e330fc0c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,8 +32,7 @@ mise.toml
 dist-exe/
 /dist/
 apps/desktop/.desktop-build/
-python/sdk-runtime/src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*
-python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/
+python/sdk-runtime/src/deepseek_harness_runtime/runtime/
 python/**/__pycache__/
 python/**/.pytest_cache/
 packages/**/__pycache__/
diff --git a/AGENTS.md b/AGENTS.md
index 7a128b6167..aa83ae8c08 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,8 @@ pnpm run test:docs      # quick documentation checks (no build; doc-quick aggreg
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm dsh --profile headless "task"  # run one task from source (needs DEEPSEEK_API_KEY)
 pnpm run demo:ptc -- "task"  # headless PTC mode run (needs key)
+pnpm run dev:web | dev:desktop  # build, then launch; Web also rebuilds client bundles on edits. start:web | start:desktop skip the build
+make web|dev-web|desktop|dev-desktop|build  # the same commands; ARGS='--no-open' forwards options
 ```
 
 ### Host sandbox failures
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000..4b95df6766
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,31 @@
+# Short names for the Web and Desktop application commands. The package.json
+# scripts they call stay the source of truth; docs/development.md documents both.
+.DEFAULT_GOAL := help
+.PHONY: help build web desktop dev-web dev-desktop
+
+PNPM ?= pnpm
+ARGS ?=
+
+help:
+	@echo "make build        pnpm run build           complete repository build"
+	@echo "make web          pnpm run start:web       serve the built Web artifacts from source"
+	@echo "make desktop      pnpm run start:desktop   launch the built Desktop artifacts"
+	@echo "make dev-web      pnpm run dev:web         build, serve, and rebuild Web on source edits"
+	@echo "make dev-desktop  pnpm run dev:desktop     build, then launch Desktop"
+	@echo "ARGS='--no-open --port 3081' forwards options to the launched application;"
+	@echo "the Web commands accept dsh web flags, the Desktop launcher accepts none."
+
+build:
+	$(PNPM) run build
+
+web:
+	$(PNPM) run start:web $(ARGS)
+
+desktop:
+	$(PNPM) run start:desktop $(ARGS)
+
+dev-web:
+	$(PNPM) run dev:web $(ARGS)
+
+dev-desktop:
+	$(PNPM) run dev:desktop $(ARGS)
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 904c7928d2..ce6f75b18d 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
-README.md: 36adfe913902e75ce0673adc2cb5cb692151a291
-README.zh.md: f6861b4c9490741b5e5f2d825a370766178dd9f6
+README.md: 423bccd7d9352dbc48f1705f37d35642e74f5b41
+README.zh.md: c760f87e4ac3b7dbb7bb55d733e31db5ab379836
diff --git a/README.md b/README.md
index 36adfe9139..423bccd7d9 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Start with the [development guide](docs/development.md) and [architecture documentation](docs/architecture.md).
 
+`pnpm run dev:web` builds, serves, and rebuilds client bundles on source edits in one terminal, and `make help` lists the matching Make targets for Web and Desktop; the guide's application commands section owns the full table.
+
 For agents, follow [AGENTS.md](AGENTS.md).
 
 ## Citation
diff --git a/README.zh.md b/README.zh.md
index f6861b4c94..c760f87e4a 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -75,6 +75,8 @@ pnpm dsh web
 
 请先阅读[开发指南](docs/development.zh.md)与[架构文档](docs/architecture.zh.md)。
 
+`pnpm run dev:web` 会在一个终端里完成构建、启动，并在源码修改时重建 client bundle；`make help` 列出 Web 与 Desktop 对应的 Make target。完整表格见开发指南的「应用命令」一节。
+
 面向 agent：请遵循 [AGENTS.md](AGENTS.md)。
 
 ## 引用
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index ec698dca33..2ad45f06c7 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -5,7 +5,7 @@
 
 DeepSeek Harness is licensed under [MIT](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
 
-This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Desktop bundled Python distributions. It is generated by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
+This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Bundled Python distributions. It is generated by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
 
 The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python SDK closure is recorded separately in [`python/sdk/uv.lock`](python/sdk/uv.lock).
 
@@ -126,6 +126,7 @@ External packages installed for runtime use or distributed inside the prebuilt b
 
 pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification:
 
+- `@earendil-works/pi-ai@0.85.1` — [`patches/@earendil-works__pi-ai@0.85.1.patch`](patches/@earendil-works__pi-ai@0.85.1.patch)
 - `@electron/osx-sign@1.3.3` — [`patches/@electron__osx-sign@1.3.3.patch`](patches/@electron__osx-sign@1.3.3.patch)
 - `@yao-pkg/pkg@6.21.0` — [`patches/@yao-pkg__pkg@6.21.0.patch`](patches/@yao-pkg__pkg@6.21.0.patch)
 - `node-pty@1.2.0-beta.15` — [`patches/node-pty@1.2.0-beta.15.patch`](patches/node-pty@1.2.0-beta.15.patch)
@@ -245,9 +246,9 @@ Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the developm
 | [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only |
 | [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |
 
-## Desktop bundled Python distributions
+## Bundled Python distributions
 
-The [Desktop runtime lock](apps/desktop/scripts/primary-runtime-lock.json) records each distribution version and the wheel download hashes. The table includes every entry in `pythonPackages`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
+The [shared runtime lock](scripts/primary-runtime/lock.json) records each distribution version and the wheel download hashes. The table includes every entry in `pythonPackages`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
 
 | Distribution | Locked version | Project license |
 | --- | --- | --- |
diff --git a/apps/cli/package.json b/apps/cli/package.json
index b3cff4af5d..2521fe120d 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -69,6 +69,8 @@
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-skill-filesystem": "workspace:^",
+    "@deepseek-ai/dsh-skill-office": "workspace:^",
+    "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:^",
     "@deepseek-ai/dsh-terminal": "workspace:^",
     "@deepseek-ai/dsh-terminal-bash": "workspace:^",
     "@deepseek-ai/dsh-time-context": "workspace:^",
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 0cff0e5cdb..cb0eddf183 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: cf0e1400f2dc8cd29cc59cefbdda379df2e0b899
-README.zh.md: a01818f59ccf54f3f826c68505bfb830a9316664
+README.md: 33465e8c96df9cbfbecc038616caf297146ec971
+README.zh.md: d25d27851ca789a3db358157368b97c3669ed79d
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index cf0e1400f2..33465e8c96 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -85,7 +85,7 @@ Git-hosted plugins that ship sources build during install through their `prepare
 
 ## Web profile
 
-`dsh web` uses the profile shorthand. Launcher flags are parsed first; the remaining flags 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 `--no-open` disables the default-browser handoff for this invocation. The client-plugin HMR receiver is always mounted and stays idle until a separate `pnpm run dev:web` watcher rebuilds client bundles.
+`dsh web` uses the profile shorthand. Launcher flags are parsed first; the remaining flags 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 `--no-open` disables the default-browser handoff for this invocation. The client-plugin HMR receiver is always mounted and stays idle until `pnpm run dev:web` rebuilds client bundles; that command builds once, starts this same launcher, and keeps client bundles rebuilt, or with `--no-serve` runs only the watchers beside a `dsh web` started elsewhere.
 
 ```sh
 dsh web
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a01818f59c..d25d27851c 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -87,7 +87,7 @@ dsh --profile tui
 
 ## Web Profile
 
-`dsh web` 使用 profile 简写。启动器先解析自身的 flag，其余 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--no-open` 则只对本次调用关闭默认浏览器交接。客户端插件 HMR（热模块替换）接收器始终挂载，在单独运行的 `pnpm run dev:web` watcher 重建客户端 bundle 之前保持空闲。
+`dsh web` 使用 profile 简写。启动器先解析自身的 flag，其余 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--no-open` 则只对本次调用关闭默认浏览器交接。客户端插件 HMR（热模块替换）接收器始终挂载，在 `pnpm run dev:web` 重建客户端 bundle 之前保持空闲；该命令先构建一次，再启动这同一个启动器并持续重建客户端 bundle，加 `--no-serve` 则只运行 watcher、配合别处启动的 `dsh web`。
 
 ```sh
 dsh web
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 1cd1c1636c..874e216499 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -520,7 +520,6 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       successText: 'ACP BUILT PROFILE OK',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-built-acp-'))
-    writeFileSync(join(home, 'settings.yaml'), 'llm-deepseek:\n  protocol: chat-completions\n')
     const child = execa(process.execPath, [dshBin, '--profile', 'acp'], {
       cwd: home,
       reject: false,
@@ -606,7 +605,6 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       successText: 'published headless profile reached the mock',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-built-headless-'))
-    writeFileSync(join(home, 'settings.yaml'), 'llm-deepseek:\n  protocol: chat-completions\n')
     try {
       const result = await runBuiltBin(['--profile', 'headless', 'answer', 'from', 'the', 'published', 'entry'], {
         DSH_HOME: home,
@@ -618,7 +616,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(result.stdout).toBe('published headless profile reached the mock')
       expect(result.stderr).toBe('dsh: reasoning:\nInspecting the published entry.')
       expect(server.requests.length).toBeGreaterThan(0)
-      expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
+      expect(server.requests.every(request => request.path === '/v1/messages')).toBe(true)
       expect(JSON.stringify(server.requests.map(request => request.body))).toContain('answer from the published entry')
     } finally {
       await server.close()
@@ -743,7 +741,6 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       successText: 'launching endpoint reached the mock',
     })
     const home = mkdtempSync(join(tmpdir(), 'dsh-home-environment-'))
-    writeFileSync(join(home, 'settings.yaml'), 'llm-deepseek:\n  protocol: chat-completions\n')
     const project = mkdtempSync(join(tmpdir(), 'dsh-home-project-'))
     writeFileSync(join(home, '.credentials.yaml'), `version: 1\nrefs:\n  DEEPSEEK_API_KEY: ${apiKey}\n`, { mode: 0o600 })
     createEnvironmentProbeProfile(home, project)
@@ -766,8 +763,8 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(result.stdout).not.toContain(apiKey)
       expect(result.stderr).not.toContain(apiKey)
       expect(server.requests).toHaveLength(1)
-      expect(server.requests[0]?.path).toBe('/chat/completions')
-      expect(server.requests[0]?.headers.authorization).toBe(`Bearer ${apiKey}`)
+      expect(server.requests[0]?.path).toBe('/v1/messages')
+      expect(server.requests[0]?.headers['x-api-key']).toBe(apiKey)
       expect(JSON.stringify(server.requests[0]?.body)).not.toContain(apiKey)
     } finally {
       await server.close()
diff --git a/apps/cli/tests/desktop-host.e2e.ts b/apps/cli/tests/desktop-host.e2e.ts
index dce2ecbce0..cf6305caf7 100644
--- a/apps/cli/tests/desktop-host.e2e.ts
+++ b/apps/cli/tests/desktop-host.e2e.ts
@@ -13,7 +13,7 @@ it.each([false, true])('settles startup after parent IPC disconnect (boot failur
   const modules = join(root, 'node_modules', '@deepseek-ai')
   const hostDirectory = fileURLToPath(new URL('../../desktop-host/', import.meta.url))
   const manifest = JSON.parse(readFileSync(join(hostDirectory, 'package.json'), 'utf8')) as { dependencies: Record<string, string> }
-  const stubbed = new Set(['@deepseek-ai/dsh-app-boot', '@deepseek-ai/dsh', '@deepseek-ai/dsh-home-paths', '@deepseek-ai/dsh-tools'])
+  const stubbed = new Set(['@deepseek-ai/dsh-app-boot', '@deepseek-ai/dsh', '@deepseek-ai/dsh-home-paths'])
   for (const name of Object.keys(manifest.dependencies)) {
     const destination = join(root, 'node_modules', name)
     mkdirSync(dirname(destination), { recursive: true })
@@ -22,7 +22,6 @@ it.each([false, true])('settles startup after parent IPC disconnect (boot failur
   }
   for (const [name, source] of [
     ['dsh-home-paths', `export const resolveDshHome = () => ${JSON.stringify(root)}`],
-    ['dsh-tools', 'export const defineTool = value => value'],
   ] as const) {
     writeFileSync(join(modules, name, 'package.json'), '{"type":"module","exports":"./index.js"}')
     writeFileSync(join(modules, name, 'index.js'), source)
diff --git a/apps/cli/tests/profiles/acp/tests/fixtures/image-offload.cordis.yml b/apps/cli/tests/profiles/acp/tests/fixtures/image-offload.cordis.yml
index e369eb59f3..aec25ed875 100644
--- a/apps/cli/tests/profiles/acp/tests/fixtures/image-offload.cordis.yml
+++ b/apps/cli/tests/profiles/acp/tests/fixtures/image-offload.cordis.yml
@@ -4,7 +4,6 @@
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    protocol: !!js process.env.DSH_SNAPSHOT_PROTOCOL
     apiKeyEnv: DSH_SNAPSHOT_API_KEY
     baseURL: !!js process.env.DSH_SNAPSHOT_BASE_URL
     thinking: disabled
diff --git a/apps/cli/tests/profiles/acp/tests/image-offload.expected.e2e.ts b/apps/cli/tests/profiles/acp/tests/image-offload.expected.e2e.ts
index 16da9a81d7..59195c7669 100644
--- a/apps/cli/tests/profiles/acp/tests/image-offload.expected.e2e.ts
+++ b/apps/cli/tests/profiles/acp/tests/image-offload.expected.e2e.ts
@@ -18,9 +18,9 @@ const IMAGE_OFFLOAD_CONFIG = fileURLToPath(new URL('./fixtures/image-offload.cor
 const SNAPSHOTS_DIR = fileURLToPath(new URL('../../../../../../snapshots/acp/', import.meta.url))
 const READ_IMAGE_WORKSPACE = fileURLToPath(new URL('../../../../../../snapshots/session/read-image/workspace/', import.meta.url))
 
-it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and inline fallback in assembled requests', async (protocol) => {
-  const filesPath = protocol === 'messages' ? '/v1/files' : '/files'
-  const modelPath = protocol === 'messages' ? '/v1/messages' : '/chat/completions'
+it('pins Messages Files offload and inline fallback in assembled requests', async () => {
+  const filesPath = '/v1/files'
+  const modelPath = '/v1/messages'
   const requests: Record<string, unknown>[] = []
   const fileRequests: Array<{ method: string; path: string; bytes: number }> = []
   let rejectFiles = false
@@ -49,21 +49,13 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
             return
           }
           const createdAt = Math.floor(Date.now() / 1_000)
-          response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(protocol === 'messages' ? {
+          response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({
             id: 'file-api-snapshot-1',
             type: 'file',
             size_bytes: file.size,
             created_at: new Date(createdAt * 1_000).toISOString(),
             filename: 'dsh-snapshot.png',
             mime_type: file.type,
-          } : {
-            id: 'file-api-snapshot-1',
-            object: 'file',
-            bytes: file.size,
-            created_at: createdAt,
-            filename: 'dsh-snapshot.png',
-            purpose: 'user_data',
-            expires_at: createdAt + Number(form.get('expires_after[seconds]')),
           }))
           return
         }
@@ -73,35 +65,18 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
         }
         requests.push(JSON.parse(body.toString('utf8')) as Record<string, unknown>)
         response.writeHead(200, { 'content-type': 'text/event-stream' })
-        if (protocol === 'messages') {
-          const toolCall = requests.length === 1
-          const events = [
-            { type: 'message_start', message: { id: 'offload-response', model: 'deepseek-v4-flash-vision-exp', usage: { input_tokens: 3, output_tokens: 0 } } },
-            { type: 'content_block_start', index: 0, content_block: toolCall
-              ? { type: 'tool_use', id: 'native-read-image', name: 'read_image', input: { file_path: 'red.png' } }
-              : { type: 'text', text: 'DONE' } },
-            { type: 'content_block_stop', index: 0 },
-            { type: 'message_delta', delta: { stop_reason: toolCall ? 'tool_use' : 'end_turn' }, usage: { output_tokens: 1 } },
-            { type: 'message_stop' },
-          ]
-          response.end(events.map(event => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`).join(''))
-          return
-        }
-        const events = requests.length === 1
-          ? [
-            'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"native-read-image","type":"function","function":{"name":"read_image","arguments":"{\\"file_path\\":\\"red.png\\"}"}}]},"index":0,"finish_reason":null}]}',
-            'data: {"choices":[{"delta":{},"index":0,"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
-            'data: [DONE]',
-            '',
-          ]
-          : [
-            'data: {"choices":[{"delta":{"role":"assistant","content":""},"index":0,"finish_reason":null}]}',
-            'data: {"choices":[{"delta":{"content":"DONE"},"index":0,"finish_reason":null}]}',
-            'data: {"choices":[{"delta":{},"index":0,"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
-            'data: [DONE]',
-            '',
-          ]
-        response.end(events.join('\n\n'))
+        const toolCall = requests.length === 1
+        const events = [
+          { type: 'message_start', message: { id: 'offload-response', model: 'deepseek-v4-flash-vision-exp', usage: { input_tokens: 3, output_tokens: 0 } } },
+          { type: 'content_block_start', index: 0, content_block: toolCall
+            ? { type: 'tool_use', id: 'native-read-image', name: 'read_image', input: { file_path: 'red.png' } }
+            : { type: 'text', text: 'DONE' } },
+          { type: 'content_block_stop', index: 0 },
+          { type: 'message_delta', delta: { stop_reason: toolCall ? 'tool_use' : 'end_turn' }, usage: { output_tokens: 1 } },
+          { type: 'message_stop' },
+        ]
+        response.end(events.map(event => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`).join(''))
+        return
       })().catch((error: unknown) => {
         response.writeHead(500, { 'content-type': 'text/plain' }).end(String(error))
       })
@@ -137,7 +112,6 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
       fixtureFile: join(SNAPSHOTS_DIR, 'image-offload-request', 'session.jsonl'),
       workspaceDir: READ_IMAGE_WORKSPACE,
       env: {
-        DSH_SNAPSHOT_PROTOCOL: protocol,
         DSH_SNAPSHOT_API_KEY: 'snapshot-key',
         DSH_SNAPSHOT_BASE_URL: `http://127.0.0.1:${address.port}`,
       },
@@ -162,14 +136,9 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
         + ' Copy to a writable path ending in .png before editing.'
     }
     const normalizedAccess = accessText(result.cwd)
-    const imagePrefix = protocol === 'messages' ? '' : '\n'
-    const fileImage = protocol === 'messages'
-      ? { type: 'image', source: { type: 'file', file_id: 'file-api-snapshot-1' } }
-      : { type: 'file', file_id: 'file-api-snapshot-1' }
+    const fileImage = { type: 'image', source: { type: 'file', file_id: 'file-api-snapshot-1' } }
     const offloadedImage = `[image omitted to fit request image limits; ${attachmentId}.${normalizedAccess}]`
     const imageHandle = `Image ${attachmentId}; request preview 1x1px.${normalizedAccess}`
-    const normalizedToolImageHandle = `Image "red.png" (${attachmentId}); request preview 1x1px.${normalizedAccess}`
-      .replaceAll(result.cwd, '{{cwd}}')
     const runtimeContext = 'Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\n'
       + 'Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\n'
       + 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'
@@ -179,80 +148,31 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
       { type: 'text', text: 'Compare the older image ' },
       { type: 'text', text: offloadedImage },
       { type: 'text', text: ' with the newer image ' },
-      { type: 'text', text: `${imagePrefix}${imageHandle}` },
+      { type: 'text', text: imageHandle },
       fileImage,
       { type: 'text', text: ', then use read_image on red.png and reply with DONE.' },
-      ...protocol === 'messages' ? [{ type: 'text', text: runtimeContext }] : [],
+      { type: 'text', text: runtimeContext },
     ])
 
-    if (protocol === 'messages') {
-      const followup = requests[1]?.messages as Array<{ role: string; content: Array<Record<string, unknown>> }>
-      expect(followup).toHaveLength(3)
-      expect(followup[0]?.content.filter(block => block.type === 'image')).toEqual([])
-      expect(followup[0]?.content.filter(block => block.text === offloadedImage)).toHaveLength(2)
-      expect(followup[1]).toEqual({ role: 'assistant', content: [
-        { type: 'tool_use', id: 'native-read-image', name: 'read_image', input: { file_path: 'red.png' } },
-      ] })
-      expect(followup[2]?.role).toBe('user')
-      expect(followup[2]?.content).toHaveLength(1)
-      const toolResult = followup[2]!.content[0]!
-      expect(toolResult.type).toBe('tool_result')
-      expect(toolResult.tool_use_id).toBe('native-read-image')
-      const content = toolResult.content as Array<Record<string, unknown>>
-      expect(content[0]?.type).toBe('text')
-      expect(content[0]?.text).toContain('image/png image, 1x1 px, 69 bytes')
-      expect(content.slice(1)).toEqual([
-        { type: 'text', text: `Image "red.png" (${attachmentId}); request preview 1x1px.${normalizedAccess}` },
-        fileImage,
-      ])
-    } else {
-      const followup = structuredClone((requests[1]?.messages as unknown[]).slice(1)) as Array<{
-        role?: unknown
-        content?: unknown
-      }>
-      const toolMessage = followup.find(message => message.role === 'tool')
-      if (toolMessage === undefined || typeof toolMessage.content !== 'string') {
-        throw new Error('native read_image request has no tool content')
-      }
-      const cwdSpellings = [...new Set([result.cwd, ...result.cwdAliases].flatMap(cwd => (
-        cwd.startsWith('/private/') ? [cwd, cwd.slice('/private'.length)] : [cwd, `/private${cwd}`]
-      )))]
-      let toolContent = toolMessage.content
-      for (const cwd of cwdSpellings) toolContent = toolContent.replaceAll(cwd, '{{cwd}}')
-      toolMessage.content = toolContent
-      expect(followup).toEqual([
-        {
-          role: 'user',
-          content: `Compare the older image ${offloadedImage} with the newer image ${offloadedImage}, then use read_image on red.png and reply with DONE.`,
-        },
-        {
-          role: 'user',
-          content: runtimeContext,
-        },
-        {
-          role: 'assistant',
-          content: '',
-          tool_calls: [{
-            id: 'native-read-image',
-            type: 'function',
-            function: { name: 'read_image', arguments: '{"file_path":"red.png"}' },
-          }],
-        },
-        {
-          role: 'tool',
-          tool_call_id: 'native-read-image',
-          content: '<path>{{cwd}}/red.png</path>\n<type>image</type>\n<content>\nimage/png image, 1x1 px, 69 bytes\n'
-            + `</content>\n${normalizedToolImageHandle}`,
-        },
-        {
-          role: 'user',
-          content: [
-            { type: 'text', text: 'Attached image(s) from tool result:' },
-            { type: 'file', file_id: 'file-api-snapshot-1' },
-          ],
-        },
-      ])
-    }
+    const followup = requests[1]?.messages as Array<{ role: string; content: Array<Record<string, unknown>> }>
+    expect(followup).toHaveLength(3)
+    expect(followup[0]?.content.filter(block => block.type === 'image')).toEqual([])
+    expect(followup[0]?.content.filter(block => block.text === offloadedImage)).toHaveLength(2)
+    expect(followup[1]).toEqual({ role: 'assistant', content: [
+      { type: 'tool_use', id: 'native-read-image', name: 'read_image', input: { file_path: 'red.png' } },
+    ] })
+    expect(followup[2]?.role).toBe('user')
+    expect(followup[2]?.content).toHaveLength(1)
+    const toolResult = followup[2]!.content[0]!
+    expect(toolResult.type).toBe('tool_result')
+    expect(toolResult.tool_use_id).toBe('native-read-image')
+    const content = toolResult.content as Array<Record<string, unknown>>
+    expect(content[0]?.type).toBe('text')
+    expect(content[0]?.text).toContain('image/png image, 1x1 px, 69 bytes')
+    expect(content.slice(1)).toEqual([
+      { type: 'text', text: `Image "red.png" (${attachmentId}); request preview 1x1px.${normalizedAccess}` },
+      fileImage,
+    ])
 
     rejectFiles = true
     const fallback = await runScenario(input, {
@@ -262,7 +182,6 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
       fixtureFile: join(SNAPSHOTS_DIR, 'image-offload-request', 'session.jsonl'),
       workspaceDir: READ_IMAGE_WORKSPACE,
       env: {
-        DSH_SNAPSHOT_PROTOCOL: protocol,
         DSH_SNAPSHOT_API_KEY: 'snapshot-fallback-key',
         DSH_SNAPSHOT_BASE_URL: `http://127.0.0.1:${address.port}`,
       },
@@ -280,12 +199,10 @@ it.each(['chat-completions', 'messages'] as const)('pins %s Files offload and in
       { type: 'text', text: 'Compare the older image ' },
       { type: 'text', text: `[image omitted to fit request image limits; ${attachmentId}.${fallbackAccess}]` },
       { type: 'text', text: ' with the newer image ' },
-      { type: 'text', text: `${imagePrefix}Image ${attachmentId}; request preview 1x1px.${fallbackAccess}` },
-      protocol === 'messages'
-        ? { type: 'image', source: { type: 'base64', media_type: 'image/png', data: image } }
-        : { type: 'image_url', image_url: { url: `data:image/png;base64,${image}` } },
+      { type: 'text', text: `Image ${attachmentId}; request preview 1x1px.${fallbackAccess}` },
+      { type: 'image', source: { type: 'base64', media_type: 'image/png', data: image } },
       { type: 'text', text: ', then use read_image on red.png and reply with DONE.' },
-      ...protocol === 'messages' ? [{ type: 'text', text: runtimeContext }] : [],
+      { type: 'text', text: runtimeContext },
     ])
   } finally {
     await new Promise<void>(resolve => server.close(() => { resolve() }))
diff --git a/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts b/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts
index 4724981169..93e6e27ad4 100644
--- a/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/headless.expected.e2e.ts
@@ -83,7 +83,9 @@ async function expectHeadlessStream(normalized: string, expectedPath: string): P
 }
 
 /** Serve one deterministic DeepSeek-compatible response while retaining its request body. */
-async function deepseekDefaultsServer(options: { waitForTitleRequest?: boolean; protocol?: 'messages' } = {}): Promise<DeepSeekDefaultsServer> {
+async function deepseekDefaultsServer(
+  options: { waitForTitleRequest?: boolean; piAiCompatibility?: true } = {},
+): Promise<DeepSeekDefaultsServer> {
   const requests: JsonObject[] = []
   const paths: string[] = []
   const server = createServer((request: IncomingMessage, response: ServerResponse) => {
@@ -103,7 +105,7 @@ async function deepseekDefaultsServer(options: { waitForTitleRequest?: boolean;
           timer = setTimeout(write, 60)
           return
         }
-        if (options.protocol === 'messages') {
+        if (options.piAiCompatibility !== true) {
           response.end([
             { type: 'message_start', message: { id: 'defaults-response', model: 'deepseek-v4-flash', usage: { input_tokens: 3, output_tokens: 0 } } },
             { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
@@ -582,7 +584,7 @@ describe('headless stream-json snapshots', () => {
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
   it('keeps provider comments alive and sends DeepSeek defaults through the one-shot app', async () => {
-    const server = await deepseekDefaultsServer({ protocol: 'messages' })
+    const server = await deepseekDefaultsServer()
     try {
       const result = await runLoaderSmoke({
         label: 'DeepSeek adapter defaults headless stream-json snapshot',
@@ -638,7 +640,7 @@ describe('headless stream-json snapshots', () => {
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
   it('keeps the compatibility stream open until the title request arrives', async () => {
-    const server = await deepseekDefaultsServer({ waitForTitleRequest: true })
+    const server = await deepseekDefaultsServer({ waitForTitleRequest: true, piAiCompatibility: true })
     try {
       const response = await fetch(server.url, {
         method: 'POST',
@@ -675,7 +677,7 @@ describe('headless stream-json snapshots', () => {
   })
 
   it('sends pi-ai DeepSeek compatibility through the one-shot app', async () => {
-    const server = await deepseekDefaultsServer({ waitForTitleRequest: true })
+    const server = await deepseekDefaultsServer({ waitForTitleRequest: true, piAiCompatibility: true })
     try {
       const result = await runLoaderSmoke({
         label: 'pi-ai DeepSeek compatibility headless stream-json snapshot',
diff --git a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts
index 80601c27c6..9978557402 100644
--- a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts
+++ b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts
@@ -15,6 +15,7 @@ const bundleName = 'profile-resolution-bundle'
 const bridgeName = 'profile-resolution-bridge'
 const leafName = 'profile-resolution-leaf'
 const pluginName = 'profile-resolution-plugin'
+const sourceProbeName = 'source-probe'
 const externalName = 'profile-resolution-external'
 const externalLeafName = 'profile-resolution-external-leaf'
 const marker = 'DSH_PROFILE_RESOLUTION '
@@ -33,6 +34,12 @@ interface ResolutionEvidence {
   sameCjsExternalLeaf: boolean
   externalManaged: boolean
   toolsInstance: boolean
+  pluginToolsInstance: boolean
+  sourceToolsInstance: boolean
+  profileToolsCjs: string | null
+  sourceToolsCjs: string | null
+  sourceLeafCjs: string
+  sourceLeafExplicitCjs: string
   scheduler: boolean
   modules: string[]
 }
@@ -64,6 +71,8 @@ export function testProfileResolution(mode: ExampleMode): void {
       const bridgeDir = layout === 'npm-link' ? join(root, 'dependencies', bridgeName) : installedBridge
       const logicalLeaf = join(bundleDir, 'node_modules', leafName)
       const realLeaf = join(root, 'dependencies', 'node_modules', leafName)
+      const sourcePackageDir = join(root, 'work', 'source-package')
+      const sourceDevLeaf = join(sourcePackageDir, 'node_modules', leafName)
       const exports = { import: './index.mjs', require: './index.cjs' }
       await writePackage(bundleDir, {
         name: bundleName, version: '1.0.0', dependencies: { [bridgeName]: '*' },
@@ -75,7 +84,9 @@ export function testProfileResolution(mode: ExampleMode): void {
         'index.mjs': `export { leaf } from '${leafName}'`,
         'index.cjs': `module.exports = require('${leafName}')`,
       })
-      for (const [dir, version] of [[logicalLeaf, '1.0.0'], [realLeaf, '2.0.0']] as const) {
+      for (const [dir, version] of [
+        [logicalLeaf, '1.0.0'], [realLeaf, '2.0.0'], [sourceDevLeaf, '0.0.0'],
+      ] as const) {
         await writePackage(dir, { name: leafName, version, exports }, {
           'index.mjs': `export const leaf = { version: '${version}', url: import.meta.url }`,
           'index.cjs': `exports.leaf = { version: '${version}', filename: __filename }`,
@@ -91,7 +102,10 @@ export function testProfileResolution(mode: ExampleMode): void {
       }
 
       const sharedModules = join(home, 'profiles', 'node_modules')
-      const pluginDir = join(profileDir, 'node_modules', pluginName)
+      const installedPlugin = join(profileDir, 'node_modules', pluginName)
+      // npm-link keeps the plugin as a linked root outside the profile tree, so its own node_modules hold the
+      // developer's devDependency dsh-tools copy (stale, never read) and the declared dependency's install.
+      const pluginDir = layout === 'npm-link' ? join(root, 'work', pluginName) : installedPlugin
       const sharedExternal = join(sharedModules, externalName)
       const externalDir = layout === 'npm-link' ? join(root, 'external', externalName) : sharedExternal
       const externalLeaf = join(externalDir, 'node_modules', externalLeafName)
@@ -100,8 +114,14 @@ export function testProfileResolution(mode: ExampleMode): void {
       const ancestorLeaf = join(home, 'node_modules', externalLeafName)
       await writePackage(pluginDir, {
         name: pluginName, version: '1.0.0', exports, dependencies: { [externalName]: '*' },
+        peerDependencies: { '@deepseek-ai/dsh-tools': '*' }, devDependencies: { '@deepseek-ai/dsh-tools': '*' },
       }, {
-        'index.mjs': `export { external } from '${externalName}'\nexport function apply() {}`,
+        'index.mjs': [
+          `export { external } from '${externalName}'`,
+          "import Tools from '@deepseek-ai/dsh-tools'",
+          'export { Tools as PluginTools }',
+          'export function apply() {}',
+        ].join('\n'),
         'index.cjs': `module.exports = require('${externalName}')`,
       })
       for (const [dir, version] of [[externalDir, '3.0.0'], [ancestorExternal, '9.0.0']] as const) {
@@ -122,9 +142,33 @@ export function testProfileResolution(mode: ExampleMode): void {
         'index.mjs': "export default class Tools {}\nexport const TOOL_RUNTIME_SCHEDULER = Symbol()\nthrow new Error('STALE_DSH_TOOLS')",
         'index.cjs': "throw new Error('STALE_DSH_TOOLS')",
       })
+      const sourceDir = join(sourcePackageDir, 'src')
+      const toolsCjsExpression = mode === 'lib' ? "require.resolve('@deepseek-ai/dsh-tools')" : 'null'
+      await mkdir(sourceDir, { recursive: true })
+      // The ESM-only source hook does not map CommonJS exports to source, so its CJS probe uses a fixture-owned peer.
+      await writePackage(sourcePackageDir, {
+        name: 'source-package', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh-tools': '*', [leafName]: '*' },
+      }, {
+        'src/query.mjs': [
+          "import { createRequire } from 'node:module'",
+          "import Tools from '@deepseek-ai/dsh-tools'",
+          'export { Tools as SourceTools }',
+          'const require = createRequire(import.meta.url)',
+          `export const sourceToolsCjs = ${toolsCjsExpression}`,
+          `export const sourceLeafCjs = require.resolve('${leafName}')`,
+          `export const sourceLeafExplicitCjs = require.resolve('${leafName}', { paths: [${JSON.stringify(sourceDir)}] })`,
+        ].join('\n'),
+      })
       for (const [target, link] of [
         [staleTools, staleToolsLink],
-        ...layout === 'npm-link' ? [[externalDir, sharedExternal]] as const : [],
+        [sourceDir, join(profileDir, 'node_modules', sourceProbeName)],
+        [staleTools, join(sourcePackageDir, 'node_modules', '@deepseek-ai', 'dsh-tools')],
+        ...layout === 'npm-link' ? [
+          [externalDir, sharedExternal],
+          [pluginDir, installedPlugin],
+          [staleTools, join(pluginDir, 'node_modules', '@deepseek-ai', 'dsh-tools')],
+          [externalDir, join(pluginDir, 'node_modules', externalName)],
+        ] as const : [],
       ] as const) {
         await mkdir(dirname(link), { recursive: true })
         await symlink(target, link, 'junction')
@@ -143,7 +187,8 @@ export function testProfileResolution(mode: ExampleMode): void {
           `import { leaf } from '${leafName}'`,
           `import { leaf as bridgeLeaf } from '${bridgeName}'`,
           `import { external } from '${externalName}'`,
-          `import { external as pluginExternal } from '${pluginName}'`,
+          `import { external as pluginExternal, PluginTools } from '${pluginName}'`,
+          `import { SourceTools, sourceToolsCjs, sourceLeafCjs, sourceLeafExplicitCjs } from '${sourceProbeName}/query.mjs'`,
           `import { leaf as externalLeaf } from ${JSON.stringify(pathToFileURL(join(externalLeaf, 'index.mjs')).href)}`,
           'const require = createRequire(import.meta.url)',
           "export const inject = ['tools', 'agentLoop', 'loader']",
@@ -165,6 +210,10 @@ export function testProfileResolution(mode: ExampleMode): void {
           `      sameCjsExternalLeaf: externalCjs.leaf === require(${JSON.stringify(join(externalLeaf, 'index.cjs'))}).leaf,`,
           `      externalManaged: entries.some(entry => [${JSON.stringify(externalName)}, ${JSON.stringify(externalLeafName)}].includes(entry.name)),`,
           '      toolsInstance: ctx.tools instanceof Tools,',
+          '      pluginToolsInstance: ctx.tools instanceof PluginTools,',
+          '      sourceToolsInstance: ctx.tools instanceof SourceTools,',
+          `      profileToolsCjs: ${toolsCjsExpression},`,
+          '      sourceToolsCjs, sourceLeafCjs, sourceLeafExplicitCjs,',
           "      scheduler: typeof ctx.tools[TOOL_RUNTIME_SCHEDULER]?.prepare === 'function',",
           '      modules: [...ctx.loader.internal.loadCache.keys()]',
           '        .filter(url => /\\/packages\\/core\\/(?:tools|agent-loop)\\//.test(url)),',
@@ -185,8 +234,8 @@ export function testProfileResolution(mode: ExampleMode): void {
         ]),
       })
       const packageDirs = [
-        bundleDir, bridgeDir, logicalLeaf, realLeaf, pluginDir, externalDir, externalLeaf,
-        sharedLeaf, ancestorExternal, ancestorLeaf, staleTools, profileDir,
+        bundleDir, bridgeDir, logicalLeaf, realLeaf, sourceDevLeaf, pluginDir, externalDir, externalLeaf,
+        sharedLeaf, ancestorExternal, ancestorLeaf, staleTools, sourcePackageDir, sourceDir, profileDir,
       ]
       const packageFiles = (await Promise.all(packageDirs.map(async dir =>
         (await readdir(dir, { withFileTypes: true })).filter(entry => entry.isFile()).map(entry => join(dir, entry.name)),
@@ -233,6 +282,15 @@ export function testProfileResolution(mode: ExampleMode): void {
       expect(evidence.sameCjsExternalLeaf).toBe(true)
       expect(evidence.externalManaged).toBe(false)
       expect(evidence.toolsInstance).toBe(true)
+      expect(evidence.pluginToolsInstance).toBe(true)
+      expect(evidence.sourceToolsInstance).toBe(true)
+      expect(evidence.sourceToolsCjs).toBe(evidence.profileToolsCjs)
+      expect(evidence.profileToolsCjs).toBe(mode === 'lib'
+        ? realpathSync.native(join(repoRoot, 'packages/core/tools/lib/index.js'))
+        : null)
+      expect(evidence.sourceLeafCjs).toBe(evidence.cjs.filename)
+      expect(evidence.sourceLeafExplicitCjs).toBe(realpathSync.native(join(sourceDevLeaf, 'index.cjs')))
+      expect(evidence.sourceLeafCjs).not.toBe(evidence.sourceLeafExplicitCjs)
       expect(evidence.scheduler).toBe(true)
       expect(evidence.execArgv).toEqual(mode === 'src' ? launch.args.slice(0, 2) : [])
       for (const name of ['tools', 'agent-loop']) {
@@ -243,6 +301,7 @@ export function testProfileResolution(mode: ExampleMode): void {
       }
       for (const [path, content] of contents) expect(await readFile(path), path).toEqual(content)
       for (const [path, target] of linkTargets) expect(await readlink(path), path).toBe(target)
+      expect(await readdir(sourceDir)).toEqual(['query.mjs'])
     } finally {
       try {
         for (const link of links.reverse()) await unlink(link)
diff --git a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts
index 7aac156cd8..4e0fc43235 100644
--- a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts
@@ -28,6 +28,7 @@ import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
 import * as ToolJobs from '@deepseek-ai/dsh-tool-jobs'
 import CordisHostRunner from '@deepseek-ai/dsh-cordis-host-runner'
 import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
+import * as CordisInspectProviders from '@deepseek-ai/dsh-tool-cordis/host'
 
 /**
  * With-key PTC mode proof: a real model receives only `run_code`, composes two
@@ -280,6 +281,7 @@ describe('PTC mode typed values: keyless real-process contracts', () => {
   it('uses runtime inspection results directly through PTC', async () => {
     ctx = await typedPtcModeHarness()
     await ctx.plugin(CordisHostRunner)
+    await ctx.plugin(CordisInspectProviders)
     await ctx.plugin(ToolCordis)
     const agent = {
       id: SessionId('ptc-cordis'),
diff --git a/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts b/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts
index 7019b87f71..e4a615b8bc 100644
--- a/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts
+++ b/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts
@@ -1,13 +1,14 @@
 import { createServer } from 'node:http'
-import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
 import { zstdDecompress } from 'node:zlib'
 import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 import { execa } from 'execa'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import { workspaceDependencyPaths, type PrimaryRuntimeManifest } from '@deepseek-ai/dsh-tool-workspace-dependencies'
 
 const repoRoot = fileURLToPath(new URL('../../../../../', import.meta.url))
 const launch = resolveExampleLaunch({
@@ -408,3 +409,123 @@ describe('Python SDK dsh profile keyless smoke', () => {
     }
   }, 30_000)
 })
+
+/** Materialize a native-layout payload whose paths the query can validate without executing binaries. */
+async function officeFixture(root: string, pythonOnly: boolean) {
+  const source = join(root, 'resources', 'primary-runtime')
+  const manifest: PrimaryRuntimeManifest = {
+    desktopVersion: '1.0.0', platform: process.platform, arch: process.arch,
+    python: '3.12.14',
+    ...(pythonOnly ? {} : { node: '24.21.0', pnpm: '11.7.0' }),
+    pythonPackages: { 'python-docx': '1.2.0', 'python-pptx': '1.0.2', openpyxl: '3.1.5' },
+  }
+  const paths = workspaceDependencyPaths(source, manifest)
+  for (const file of [paths.python, paths.node, paths.pnpm]) {
+    if (file === undefined) continue
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, 'fixture interpreter')
+  }
+  await mkdir(paths.pythonPackages, { recursive: true })
+  if (paths.nodePackages !== undefined) await mkdir(paths.nodePackages, { recursive: true })
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(manifest))
+  await cp(join(repoRoot, 'packages/skill/skill-office/assets'), join(root, 'resources', 'office-skills'), { recursive: true })
+  return { source, paths }
+}
+
+it.each(['unset', 'empty', 'bundled', 'full', 'python-only', 'missing-assets', 'wrong-type'] as const)('composes Office resources through the SDK profile (%s)', async (mode) => {
+  const root = await mkdtemp(join(tmpdir(), 'sdk-office-'))
+  onTestFinished(() => rm(root, { recursive: true, force: true }))
+  const enabled = mode !== 'unset' && mode !== 'empty'
+  const { source, paths } = await officeFixture(root, mode === 'python-only')
+  if (mode === 'missing-assets') await rm(join(root, 'resources', 'office-skills'), { recursive: true })
+  if (mode === 'wrong-type') {
+    await rm(paths.python)
+    await mkdir(paths.python)
+  }
+  const requests: Record<string, unknown>[] = []
+  const server = createServer((request, response) => {
+    let body = ''
+    request.setEncoding('utf8').on('data', (chunk: string) => { body += chunk })
+    request.on('end', () => {
+      requests.push(JSON.parse(body) as Record<string, unknown>)
+      const query = requests.length === 1 && enabled
+      response.writeHead(200, { 'content-type': 'text/event-stream' })
+      response.end(messagesResponse(query
+        ? { type: 'tool_use', id: 'workspace-dependencies', name: 'load_workspace_dependencies', input: {} }
+        : { type: 'text', text: 'done' }, query ? 'tool_use' : 'end_turn'))
+    })
+  })
+  onTestFinished(() => new Promise<void>((resolve) => { server.close(() => { resolve() }) }))
+  await new Promise<void>((resolve) => { server.listen(0, '127.0.0.1', resolve) })
+  const address = server.address()
+  if (address === null || typeof address === 'string') throw new Error('model fixture did not bind')
+  const home = join(root, 'home')
+  const officeLaunch = resolveExampleLaunch({
+    srcBin: fileURLToPath(new URL('../../../src/bin.ts', import.meta.url)), mode: 'lib',
+    configArgs: ['--profile', 'sdk'],
+    env: { DSH_HOME: home, DSH_PRIMARY_RUNTIME: mode === 'unset' || mode === 'bundled' ? undefined : mode === 'empty' ? '' : source + '/',
+      DSH_BUNDLED_PRIMARY_RUNTIME: mode === 'unset' ? undefined : mode === 'bundled' || mode === 'empty' ? source : join(root, 'unused-default'),
+      DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1',
+      DEEPSEEK_API_KEY: 'local-fixture', DEEPSEEK_BASE_URL: `http://127.0.0.1:${address.port}` },
+  })
+  const child = execa(officeLaunch.command, officeLaunch.args, { cwd: repoRoot, env: officeLaunch.env, timeout: 60_000, reject: false })
+  onTestFinished(async () => { child.kill('SIGKILL'); await child })
+  let buffer = '', stderr = ''
+  const lines: string[] = []
+  child.stdout.on('data', (chunk: Buffer) => {
+    buffer += chunk.toString()
+    const parts = buffer.split('\n')
+    buffer = parts.pop() ?? ''
+    lines.push(...parts)
+  })
+  child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString() })
+  const send = (id: number, method: string, params?: object) => {
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
+    return waitForLine(lines, value => value.id === id, () => stderr)
+  }
+  expect(await send(1, 'initialize', { cwd: root, provider: 'deepseek-official', model: 'deepseek-v4-pro' })).toHaveProperty('result')
+  await send(2, 'session/prompt', { sessionId: 'office', contentBlocks: [{ type: 'text', text: 'Query workspace dependencies.' }] })
+  await waitForLine(lines, (value) => {
+    const params = value.params as { sessionId?: string; event?: { type?: string } } | undefined
+    return value.method === 'session.event' && params?.sessionId === 'office' && params.event?.type === 'turn/end'
+  }, () => stderr)
+  const names = (requests[0]!.tools as { name: string }[]).map(value => value.name)
+  expect(names.includes('load_workspace_dependencies')).toBe(enabled)
+  for (const name of ['office-docx', 'office-pptx', 'office-xlsx']) {
+    expect(JSON.stringify(requests[0]!.messages).includes(name)).toBe(enabled && mode !== 'missing-assets')
+  }
+  if (mode === 'wrong-type') {
+    expect(requests).toHaveLength(2)
+    const messages = requests[1]!.messages as { content: { type: string; tool_use_id?: string; content?: unknown }[] }[]
+    const result = messages.flatMap(message => message.content).find(block => block.tool_use_id === 'workspace-dependencies')
+    expect(JSON.parse(JSON.stringify(result).replaceAll(JSON.stringify(paths.python).slice(1, -1), '<python>'))).toMatchInlineSnapshot(`
+      {
+        "content": [
+          {
+            "text": "Error: primary runtime: expected file at <python>",
+            "type": "text",
+          },
+        ],
+        "is_error": true,
+        "tool_use_id": "workspace-dependencies",
+        "type": "tool_result",
+      }
+    `)
+  } else if (enabled) {
+    expect(requests).toHaveLength(2)
+    const content: unknown = expect.arrayContaining([
+      expect.objectContaining({ type: 'tool_result', tool_use_id: 'workspace-dependencies',
+        content: [{ type: 'text', text: JSON.stringify(paths, undefined, 2) }] }),
+    ])
+    expect(requests[1]!.messages).toEqual(expect.arrayContaining([
+      expect.objectContaining({ role: 'user', content }),
+    ]))
+  }
+  if (mode === 'missing-assets') expect(stderr).toContain('check_office.py')
+  await send(3, 'shutdown')
+  const exit = await child
+  expect(exit.timedOut).toBe(false)
+  expect(exit.signal).toBeUndefined()
+  expect(exit.exitCode, stderr).toBe(0)
+  await expect(readFile(join(home, 'dsh-runtimes', 'dsh-primary-runtime', 'runtime.json'))).rejects.toMatchObject({ code: 'ENOENT' })
+})
diff --git a/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts b/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts
index 0e58af42f3..ecf19a7253 100644
--- a/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts
+++ b/apps/cli/tests/profiles/web/tests/web-default-isolation.expected.e2e.ts
@@ -8,7 +8,7 @@ import { withDefaultWeb, webGet } from './default-web-process.ts'
 
 const experimentalName = '@deepseek-ai/dsh-experimental-client-ui-agent-team'
 
-it('boots the default Web profile without experimental Host modules, mounted plugins, or Client entries', async (test) => {
+it('boots default Web without experimental modules or an active built-in Browser', async (test) => {
   await withDefaultWeb(test, async ({ url, request }) => {
     const auth = await webGet(url, test.signal)
     const cookie = auth.headers['set-cookie']?.[0]?.split(';', 1)[0]
@@ -29,6 +29,11 @@ it('boots the default Web profile without experimental Host modules, mounted plu
     expect(roster.plugins.length).toBeGreaterThan(roster.entries.length)
     expect(roster.modules.some(url => modulePackage(url) === '@deepseek-ai/dsh')).toBe(true)
     expect(roster.client.entries.length).toBeGreaterThan(0)
+    const browserName = '@deepseek-ai/dsh-client-ui-sidebar-browser'
+    const browserEntry = roster.entries.find(entry => entry.name === browserName)
+    expect(browserEntry).toBeDefined()
+    expect(browserEntry!.state).toBeUndefined()
+    expect(delivered.entries.some(entry => entry.id === browserName)).toBe(false)
     expect(experimentalRuntimeReferences(roster)).toEqual([])
 
     const contaminated = await request('mount-experimental')
diff --git a/apps/cli/tests/resolved-profile-boot.spec.ts b/apps/cli/tests/resolved-profile-boot.spec.ts
index ff7609c83b..0df34251c6 100644
--- a/apps/cli/tests/resolved-profile-boot.spec.ts
+++ b/apps/cli/tests/resolved-profile-boot.spec.ts
@@ -125,7 +125,7 @@ describe('runProfile with an application-owned profile', () => {
       name: 'desktop', dir: home, patchPath: profilePatch,
       patches: [{ id: 'target', config: { profile: true, priority: 'profile' } }],
       layers: [{
-        packageName: 'test-bundle', packageDir: home, patchPath: join(home, 'bundle.yml'),
+        packageName: 'test-bundle', packageDir: home, patchPaths: [join(home, 'bundle.yml')],
         patches: [{ insert: [
           { id: 'target', name: 'target', config: { bundle: true, priority: 'bundle' } },
           { id: 'session-telemetry-otel', name: 'telemetry' },
diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts
index 692cad3ebd..0434078f16 100644
--- a/apps/cli/tests/web-agent-presets.e2e.ts
+++ b/apps/cli/tests/web-agent-presets.e2e.ts
@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { mkdir, mkdtemp, readFile, stat, symlink, writeFile } from 'node:fs/promises'
+import { cp, mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
@@ -369,6 +369,23 @@ describe('the shipped Web composition', () => {
       expect(tools).not.toContain('str_replace_editor')
       expect(ctx.commands.find(handle.agent, 'goal')).toBeDefined()
 
+      // The persona is `standard`'s, pinned verbatim so the two composition
+      // files cannot drift apart: tool descriptions and the skill catalog
+      // carry every creation-mode instruction.
+      const standard = await ctx.agents.create({
+        sessionId: SessionId('preset-cordis-standard-persona'),
+        setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+      })
+      try {
+        const persona = async (agent: Agent) => (await ctx.systemPrompt.assemble({ scope: agent })).sections
+          .filter(section => section.name.startsWith('deployment:persona-'))
+        const cordisPersona = await persona(handle.agent)
+        expect(cordisPersona.map(section => section.name)).toEqual(['deployment:persona-prefix', 'deployment:persona-suffix'])
+        expect(cordisPersona).toEqual(await persona(standard.agent))
+      } finally {
+        await standard.dispose()
+      }
+
       // The preset's own authoring skill registers into ITS layer of the host
       // registry: the cordis agent's view carries it, the global view does not.
       const scoped = (await ctx.skills.list({ scope: handle.agent })).map(skill => skill.name)
@@ -651,6 +668,80 @@ describe('product Bundle and user-preset intersection', () => {
   }, 120_000)
 })
 
+describe('a user preset copied from a shipped one', () => {
+  /** The JSON text a `cordis_inspect_*` result renders. */
+  function resultText(result: { content: ReadonlyArray<{ type: string; text?: string }> }): string {
+    return result.content.filter(part => part.type === 'text').map(part => part.text ?? '').join('')
+  }
+
+  it('mounts beside the shipped `cordis` preset and reads the shared Host inspect providers', async () => {
+    // The Host inspect providers are one process-global set registered by the
+    // host composition (`@deepseek-ai/dsh-tool-cordis/host`); each preset's
+    // `tool-cordis` row only registers the tools. Before that split the copy
+    // failed to mount: its row re-registered provider "Service".
+    const root = await mkdtemp(join(tmpdir(), 'dsh-copied-preset-'))
+    const userRoot = join(root, 'presets')
+    await cp(join(SHIPPED_PRESET_ROOT, 'cordis'), join(userRoot, 'cordis-copy'), { recursive: true })
+    const settingsFile = join(root, 'settings.yaml')
+    await writeFile(settingsFile, '{}\n')
+    const copyCtx = await bootWeb(settingsFile, [{
+      id: 'agent-presets',
+      config: { default: 'standard', roots: [{ path: userRoot, trust: 'user' }], includeUserRoot: false },
+    }])
+    try {
+      const shipped = await copyCtx.agents.create({
+        sessionId: SessionId(`preset-cordis-shipped-${randomUUID()}`),
+        setup: agentCtx => copyCtx.agentPresets.mount(agentCtx, 'cordis').then(() => undefined),
+      })
+      const copied = await copyCtx.agents.create({
+        sessionId: SessionId(`preset-cordis-copy-${randomUUID()}`),
+        setup: agentCtx => copyCtx.agentPresets.mount(agentCtx, 'cordis-copy').then(() => undefined),
+      })
+      try {
+        for (const handle of [shipped, copied]) {
+          expect(toolNames(copyCtx, handle.agent)).toEqual(expect.arrayContaining([
+            'cordis_inspect_list', 'cordis_inspect_query', 'plugin_manager',
+          ]))
+        }
+        const signal = new AbortController().signal
+        const listed = await copyCtx.tools.execute({
+          callId: ToolCallId('copied-preset-inspect-list'),
+          name: 'cordis_inspect_list',
+          arguments: {},
+          signal,
+          agent: copied.agent,
+        })
+        expect(listed.isError).toBe(false)
+        const providers = (JSON.parse(resultText(listed)) as { providers: Array<{ id: string; platform: string }> }).providers
+        expect(providers.filter(provider => provider.platform === 'host').map(provider => provider.id))
+          .toEqual(['Service', 'Event', 'Builtin', 'Tool'])
+
+        // The `Tool` provider is the one built over the host context: it
+        // answers with the shared registry's view of the REQUESTING agent,
+        // so the copy sees its own preset's tools, not the host's empty set.
+        const queried = await copyCtx.tools.execute({
+          callId: ToolCallId('copied-preset-inspect-tools'),
+          name: 'cordis_inspect_query',
+          arguments: { platform: 'host', provider: 'Tool', method: 'listTools' },
+          signal,
+          agent: copied.agent,
+        })
+        expect(queried.isError).toBe(false)
+        const tools = (JSON.parse(resultText(queried)) as { data: { tools: Array<{ name: string }> } }).data.tools
+        expect(tools.map(tool => tool.name)).toEqual(expect.arrayContaining([
+          'bash', 'cordis_inspect_list', 'cordis_inspect_query', 'plugin_manager',
+        ]))
+      } finally {
+        await copied.dispose()
+        await shipped.dispose()
+      }
+    } finally {
+      await copyCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+    }
+  }, 120_000)
+})
+
 describe('a switch survives the session', () => {
   it('records the choice so the log states what the agent runs', async () => {
     const handle = await ctx.agents.create({
diff --git a/apps/desktop-host/package.json b/apps/desktop-host/package.json
index 092e3c2813..5014681e9a 100644
--- a/apps/desktop-host/package.json
+++ b/apps/desktop-host/package.json
@@ -18,7 +18,7 @@
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-home-paths": "workspace:^",
     "@deepseek-ai/dsh-jobs": "workspace:^",
-    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:^",
     "@deepseek-ai/dsh-skill-office": "workspace:^"
   }
 }
diff --git a/apps/desktop-host/src/office.ts b/apps/desktop-host/src/office.ts
index 9645435e8c..8420aa0feb 100644
--- a/apps/desktop-host/src/office.ts
+++ b/apps/desktop-host/src/office.ts
@@ -3,7 +3,7 @@
 import { dirname, join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import * as officeSkills from '@deepseek-ai/dsh-skill-office'
-import * as workspaceDependencies from './workspace-dependencies.ts'
+import * as workspaceDependencies from '@deepseek-ai/dsh-tool-workspace-dependencies'
 
 /** Loader identity for the application-owned Office composition. */
 export const name = 'desktop-office'
diff --git a/apps/desktop-host/src/primary-runtime.ts b/apps/desktop-host/src/primary-runtime.ts
deleted file mode 100644
index 130e75d9cc..0000000000
--- a/apps/desktop-host/src/primary-runtime.ts
+++ /dev/null
@@ -1,134 +0,0 @@
-/** Offline installation and absolute paths for Desktop's bundled script dependencies. */
-
-import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, stat } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-
-/** Versions recorded by the Desktop build, independent of user-installed packages. */
-export interface PrimaryRuntimeManifest {
-  readonly desktopVersion: string
-  readonly platform: string
-  readonly arch: string
-  /** Locked payload identity; absent only in installations made before payload hashing. */
-  readonly payloadDigest?: string
-  /** Installed wheel distribution versions; absent in older release manifests. */
-  readonly pythonPackages?: Readonly<Record<string, string>>
-  readonly components: {
-    readonly python: string
-    readonly node: string
-    readonly pnpm: string
-    readonly numpy: string
-    readonly pandas: string
-  }
-}
-
-/** Absolute entry points and bundled versions; pnpm runs through the returned Node executable. */
-export interface WorkspaceDependencies {
-  readonly python: string
-  readonly node: string
-  readonly pnpm: string
-  readonly pythonPackages: string
-  readonly nodePackages: string
-  /** Locked distribution versions; excludes packages users add to the installed environment. */
-  readonly pythonDistributions: Readonly<Record<string, string>>
-}
-
-/**
- * Read build metadata, rejecting duplicate normalized names and conflicting component/distribution versions.
- * @param root - Installed or bundled primary runtime directory.
- * @returns Validated component versions and target identifiers.
- */
-export async function readPrimaryRuntime(root: string): Promise<PrimaryRuntimeManifest> {
-  const value: unknown = JSON.parse(await readFile(join(root, 'runtime.json'), 'utf8'))
-  if (typeof value !== 'object' || value === null) throw new Error('primary runtime: invalid metadata')
-  const record = value as Record<string, unknown>
-  const components = record.components
-  const packages = record.pythonPackages
-  if (typeof record.desktopVersion !== 'string' || record.desktopVersion.length === 0
-    || !['win32', 'darwin'].includes(String(record.platform)) || !['x64', 'arm64'].includes(String(record.arch))
-    || typeof components !== 'object' || components === null
-    || !['python', 'node', 'pnpm', 'numpy', 'pandas'].every(key => /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/u.test(String((components as Record<string, unknown>)[key])))
-    || (record.payloadDigest !== undefined && (typeof record.payloadDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(record.payloadDigest)))
-    || (packages !== undefined && (typeof packages !== 'object' || packages === null || Array.isArray(packages)
-      || !Object.entries(packages).every(([name, version]) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name)
-        && typeof version === 'string' && /^\d[\w.!+-]*$/u.test(version))))) {
-    throw new Error('primary runtime: invalid metadata')
-  }
-  const manifest = value as PrimaryRuntimeManifest
-  const entries = Object.entries(manifest.pythonPackages ?? {})
-  const distributions = new Map(entries.map(([name, version]) => [name.toLowerCase().replace(/[-_.]+/gu, '-'), version]))
-  if (distributions.size !== entries.length) throw new Error('primary runtime: invalid metadata')
-  for (const name of ['numpy', 'pandas'] as const) {
-    const version = distributions.get(name)
-    if (version !== undefined && version !== manifest.components[name]) {
-      throw new Error(`primary runtime: conflicting ${name} distribution version`)
-    }
-  }
-  return manifest
-}
-
-/**
- * Resolve platform-specific interpreter and library locations without changing the environment.
- * @param root - Absolute installation directory.
- * @param manifest - Validated runtime metadata.
- * @returns Absolute paths for explicit script execution and recorded bundled Python versions.
- */
-export function workspaceDependencyPaths(root: string, manifest: PrimaryRuntimeManifest): WorkspaceDependencies {
-  const dependencies = join(root, 'dependencies')
-  const windows = manifest.platform === 'win32'
-  return {
-    python: join(dependencies, 'python', ...(windows ? ['python.exe'] : ['bin', 'python3'])),
-    node: join(dependencies, 'node', 'bin', windows ? 'node.exe' : 'node'),
-    pnpm: join(dependencies, 'pnpm', 'bin', 'pnpm.mjs'),
-    pythonPackages: join(dependencies, 'python', ...(windows ? ['Lib'] : ['lib', `python${manifest.components.python.split('.').slice(0, 2).join('.')}`]), 'site-packages'),
-    nodePackages: join(dependencies, 'node', 'node_modules'),
-    pythonDistributions: manifest.pythonPackages ?? {},
-  }
-}
-
-async function exists(path: string): Promise<boolean> {
-  try {
-    if ((await lstat(path)).isSymbolicLink()) throw new Error(`primary runtime: installation path is a filesystem link: ${path}`)
-    return true
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
-    throw error
-  }
-}
-
-/**
- * Install the application-owned payload locally, retaining a complete previous tree on copy failure.
- * @param source - Payload carried by the current Desktop installation.
- * @param root - Fixed primary runtime directory under the Harness home.
- * @returns Paths into the installed payload; no PATH or package-manager configuration is changed.
- */
-export async function installPrimaryRuntime(source: string, root: string): Promise<WorkspaceDependencies> {
-  const manifest = await readPrimaryRuntime(source)
-  if (manifest.platform !== process.platform || manifest.arch !== process.arch) throw new Error('primary runtime: incompatible platform or architecture')
-  await mkdir(dirname(root), { recursive: true })
-  const previous = `${root}.previous`
-  await exists(previous)
-  await exists(root)
-  if (!await exists(root) && await exists(previous)) await rename(previous, root)
-  if (await exists(join(root, 'runtime.json')) && JSON.stringify(await readPrimaryRuntime(root)) === JSON.stringify(manifest)) {
-    const paths = workspaceDependencyPaths(root, manifest)
-    for (const path of [paths.python, paths.node, paths.pnpm, paths.pythonPackages, paths.nodePackages]) await stat(path)
-    return paths
-  }
-  const staging = await mkdtemp(join(dirname(root), '.primary-runtime-'))
-  try {
-    await cp(source, staging, { recursive: true, dereference: true })
-    const paths = workspaceDependencyPaths(staging, manifest)
-    for (const path of [paths.python, paths.node, paths.pnpm, paths.pythonPackages, paths.nodePackages]) await stat(path)
-    await rm(previous, { recursive: true, force: true })
-    const replacing = await exists(root)
-    if (replacing) await rename(root, previous)
-    try { await rename(staging, root) } catch (error) {
-      if (replacing) await rename(previous, root)
-      throw error
-    }
-    await rm(previous, { recursive: true, force: true })
-  } finally {
-    await rm(staging, { recursive: true, force: true })
-  }
-  return workspaceDependencyPaths(root, manifest)
-}
diff --git a/apps/desktop-host/src/update-tasks.ts b/apps/desktop-host/src/update-tasks.ts
index 106869532f..2b2bbf4a33 100644
--- a/apps/desktop-host/src/update-tasks.ts
+++ b/apps/desktop-host/src/update-tasks.ts
@@ -45,7 +45,7 @@ export function installDesktopUpdateTaskControl(ctx: Context): (action: 'inspect
     const liveAgents = agents.list()
     return liveAgents.some(agent => agent.status === 'running'
       || agent.inbox.nextTurn.length > 0 || agent.inbox.nextStep.length > 0)
-      || [undefined, ...liveAgents].some(agent => jobs.list(agent)
+      || [undefined, ...liveAgents].some(agent => jobs.list(agent?.id)
         .some(job => job.status === 'running' || job.status === 'stopping'))
   }
 }
diff --git a/apps/desktop-host/src/workspace-dependencies.ts b/apps/desktop-host/src/workspace-dependencies.ts
deleted file mode 100644
index 7444495263..0000000000
--- a/apps/desktop-host/src/workspace-dependencies.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-/** Desktop tool exposing bundled interpreters without modifying command resolution. */
-
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import { installPrimaryRuntime, type WorkspaceDependencies } from './primary-runtime.ts'
-
-export const name = 'desktop-workspace-dependencies'
-export const inject = ['tools']
-
-/** Application-selected payload and installation directories. */
-export interface Config {
-  readonly source: string
-  readonly root: string
-}
-
-/**
- * Register the read-only path query, preparing bundled files on its first invocation.
- * @param ctx - Desktop tool registry owner.
- * @param config - Application payload and fixed installation paths.
- */
-export function apply(ctx: Context, config: Config): void {
-  let installation: Promise<WorkspaceDependencies> | undefined
-  ctx.effect(() => async () => {
-    // Tool execution reports installation failures; disposal only waits for filesystem work to settle.
-    await installation?.catch(() => undefined)
-  })
-  ctx.tools.register(defineTool({
-    name: 'load_workspace_dependencies',
-    description: 'Get absolute paths to bundled Python, Node.js, pnpm, and library directories, plus bundled Python distribution versions. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. Run pnpm with the returned Node executable and pnpm script path. This does not change PATH or package-manager settings.',
-    parameters: {},
-    output: {
-      schema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          python: { type: 'string', required: true },
-          node: { type: 'string', required: true },
-          pnpm: { type: 'string', required: true },
-          pythonPackages: { type: 'string', required: true },
-          nodePackages: { type: 'string', required: true },
-          pythonDistributions: { type: 'object', additionalProperties: true, required: true, description: 'Bundled distribution names and versions recorded in runtime.json; excludes user-installed additions.' },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, undefined, 2) }],
-    },
-    execute: () => {
-      installation ??= installPrimaryRuntime(config.source, config.root).catch((error: unknown) => {
-        installation = undefined
-        throw error
-      })
-      return installation
-    },
-    presentCall: () => ({ card: 'generic', title: 'Load workspace dependencies', kind: 'read' }),
-  }))
-}
diff --git a/apps/desktop-host/tests/primary-runtime.spec.ts b/apps/desktop-host/tests/primary-runtime.spec.ts
deleted file mode 100644
index cd1cff25c9..0000000000
--- a/apps/desktop-host/tests/primary-runtime.spec.ts
+++ /dev/null
@@ -1,193 +0,0 @@
-import { mkdir, mkdtemp, readFile, rename, rm, symlink, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { afterEach, expect, it } from 'vitest'
-import { Context } from '@deepseek-ai/cordis'
-import Loader from '@deepseek-ai/cordis-plugin-loader'
-import Include from '@deepseek-ai/cordis-plugin-include'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRuntime from '@deepseek-ai/dsh-tools'
-import { ToolCallId } from '@deepseek-ai/dsh-llm'
-import { installPrimaryRuntime, readPrimaryRuntime, workspaceDependencyPaths, type PrimaryRuntimeManifest } from '../src/primary-runtime.ts'
-import * as workspaceDependencies from '../src/workspace-dependencies.ts'
-
-const roots: string[] = []
-afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))) })
-
-async function fixture() {
-  const directory = await mkdtemp(join(tmpdir(), 'dsh-primary-runtime-'))
-  roots.push(directory)
-  const source = join(directory, 'resources')
-  const root = join(directory, 'home', 'dsh-runtimes', 'dsh-primary-runtime')
-  const manifest: PrimaryRuntimeManifest = {
-    desktopVersion: '1.0.0', platform: process.platform === 'win32' ? 'win32' : 'darwin', arch: process.arch,
-    components: { python: '3.12.14', node: '24.21.0', pnpm: '11.7.0', numpy: '2.3.5', pandas: '3.0.1' },
-    pythonPackages: { 'python-docx': '1.2.0', 'python-pptx': '1.0.2', openpyxl: '3.1.5' },
-  }
-  const paths = workspaceDependencyPaths(source, manifest)
-  for (const path of [paths.python, paths.node, paths.pnpm]) {
-    await mkdir(dirname(path), { recursive: true })
-    await writeFile(path, 'interpreter')
-  }
-  await mkdir(paths.pythonPackages, { recursive: true })
-  await mkdir(paths.nodePackages, { recursive: true })
-  await writeFile(join(source, 'runtime.json'), JSON.stringify(manifest))
-  return { source, root, manifest, directory }
-}
-
-it.each(['win32', 'darwin'])('returns %s interpreter and package paths', (platform) => {
-  const manifest: PrimaryRuntimeManifest = { desktopVersion: '1', platform, arch: 'x64', components: { python: '3.12.14', node: '24.21.0', pnpm: '11.7.0', numpy: '2.3.5', pandas: '3.0.1' } }
-  const paths = workspaceDependencyPaths('/runtime', manifest)
-  expect(paths.pythonDistributions).toEqual({})
-  expect(paths.python).toBe(join('/runtime', 'dependencies', 'python', ...(platform === 'win32' ? ['python.exe'] : ['bin', 'python3'])))
-  expect(paths.pythonPackages).toBe(join('/runtime', 'dependencies', 'python', ...(platform === 'win32' ? ['Lib'] : ['lib', 'python3.12']), 'site-packages'))
-})
-
-it.skipIf(process.platform === 'linux')('installs offline, reuses the same release, and leaves environment and user packages unchanged', async () => {
-  const { source, root, manifest } = await fixture()
-  const environment = { ...process.env }
-  const installed = await installPrimaryRuntime(source, root)
-  await writeFile(join(installed.pythonPackages, 'user-package.py'), 'user content')
-  expect(await installPrimaryRuntime(source, root)).toEqual(installed)
-  expect(installed.pythonDistributions).toEqual(manifest.pythonPackages)
-  expect(await readFile(join(installed.pythonPackages, 'user-package.py'), 'utf8')).toBe('user content')
-  expect(process.env).toEqual(environment)
-})
-
-it.skipIf(process.platform === 'linux')('replaces release components and recovers an interrupted directory swap', async () => {
-  const { source, root, manifest } = await fixture()
-  await installPrimaryRuntime(source, root)
-  await rename(root, `${root}.previous`)
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, desktopVersion: '2.0.0' }))
-  await installPrimaryRuntime(source, root)
-  expect((await readPrimaryRuntime(root)).desktopVersion).toBe('2.0.0')
-})
-
-it.skipIf(process.platform === 'linux')('replaces dependencies when the locked payload changes without a Desktop version change', async () => {
-  const { source, root, manifest } = await fixture()
-  const first = { ...manifest, payloadDigest: 'a'.repeat(64), pythonPackages: { 'python-docx': '1.1.2' } }
-  await writeFile(join(source, 'runtime.json'), JSON.stringify(first))
-  const installed = await installPrimaryRuntime(source, root)
-  await writeFile(join(installed.pythonPackages, 'old-package.py'), 'old dependency')
-  const next = { ...first, payloadDigest: 'b'.repeat(64), pythonPackages: { 'python-docx': '1.2.0' } }
-  await writeFile(join(source, 'runtime.json'), JSON.stringify(next))
-  await writeFile(join(workspaceDependencyPaths(source, next).pythonPackages, 'new-package.py'), 'new dependency')
-  await installPrimaryRuntime(source, root)
-  expect(await readPrimaryRuntime(root)).toEqual(next)
-  expect(await readFile(join(installed.pythonPackages, 'new-package.py'), 'utf8')).toBe('new dependency')
-  await expect(readFile(join(installed.pythonPackages, 'old-package.py'))).rejects.toMatchObject({ code: 'ENOENT' })
-})
-
-it.skipIf(process.platform === 'linux')('upgrades a release manifest without a payload digest', async () => {
-  const { source, root, manifest } = await fixture()
-  await installPrimaryRuntime(source, root)
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, payloadDigest: 'a'.repeat(64), pythonPackages: { 'python-docx': '1.2.0' } }))
-  await installPrimaryRuntime(source, root)
-  expect((await readPrimaryRuntime(root)).payloadDigest).toBe('a'.repeat(64))
-})
-
-it.skipIf(process.platform === 'linux')('replaces changed payload bytes when only the digest changes', async () => {
-  const { source, root, manifest } = await fixture()
-  const first = { ...manifest, payloadDigest: 'a'.repeat(64), pythonPackages: { 'python-docx': '1.2.0' } }
-  const sourceFile = join(workspaceDependencyPaths(source, first).pythonPackages, 'library.py')
-  await writeFile(join(source, 'runtime.json'), JSON.stringify(first))
-  await writeFile(sourceFile, 'first wheel bytes')
-  const installed = await installPrimaryRuntime(source, root)
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...first, payloadDigest: 'b'.repeat(64) }))
-  await writeFile(sourceFile, 'repacked wheel bytes')
-  await installPrimaryRuntime(source, root)
-  expect(await readFile(join(installed.pythonPackages, 'library.py'), 'utf8')).toBe('repacked wheel bytes')
-  expect((await readPrimaryRuntime(root)).pythonPackages).toEqual(first.pythonPackages)
-})
-
-it.skipIf(process.platform === 'linux')('keeps the installed release when the replacement payload is incomplete', async () => {
-  const { source, root, manifest } = await fixture()
-  await installPrimaryRuntime(source, root)
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, desktopVersion: '2.0.0' }))
-  await rm(workspaceDependencyPaths(source, manifest).python)
-  await expect(installPrimaryRuntime(source, root)).rejects.toThrow()
-  expect((await readPrimaryRuntime(root)).desktopVersion).toBe('1.0.0')
-})
-
-it.skipIf(process.platform === 'linux')('refuses linked installation directories without modifying their targets', async () => {
-  const { source, root, directory } = await fixture()
-  const outside = join(directory, 'outside')
-  await mkdir(outside)
-  await writeFile(join(outside, 'keep'), 'untouched')
-  await mkdir(dirname(root), { recursive: true })
-  await symlink(outside, root, process.platform === 'win32' ? 'junction' : 'dir')
-  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('filesystem link')
-  expect(await readFile(join(outside, 'keep'), 'utf8')).toBe('untouched')
-})
-
-it('rejects malformed metadata and incompatible targets', async () => {
-  const { source, root, manifest } = await fixture()
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, arch: process.arch === 'x64' ? 'arm64' : 'x64' }))
-  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('incompatible')
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, components: { ...manifest.components, python: '../escape' } }))
-  await expect(readPrimaryRuntime(source)).rejects.toThrow('invalid metadata')
-})
-
-it.each([['numpy', 'numpy'], ['pandas', 'pandas'], ['Numpy', 'numpy'], ['PANDAS', 'pandas']] as const)('rejects conflicting %s component and distribution versions', async (distribution, name) => {
-  const { source, manifest } = await fixture()
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, pythonPackages: { [distribution]: '0.0.1' } }))
-  await expect(readPrimaryRuntime(source)).rejects.toThrow(`conflicting ${name} distribution version`)
-  const consistent = { ...manifest, pythonPackages: { [distribution]: manifest.components[name] } }
-  await writeFile(join(source, 'runtime.json'), JSON.stringify(consistent))
-  expect(await readPrimaryRuntime(source)).toEqual(consistent)
-})
-
-it.each([
-  { payloadDigest: 'invalid' },
-  { pythonPackages: ['python-docx'] },
-  { pythonPackages: { 'python-docx': '../escape' } },
-  { pythonPackages: { '../escape': '1.2.0' } },
-  { pythonPackages: { numpy: '2.3.5', Numpy: '2.3.5' } },
-  { pythonPackages: { Pillow: '12.3.0', pillow: '12.3.0' } },
-  { pythonPackages: { typing_extensions: '4.16.0', 'typing.extensions': '4.16.0' } },
-])('rejects invalid locked payload metadata: %j', async (invalid) => {
-  const { source, manifest } = await fixture()
-  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, ...invalid }))
-  await expect(readPrimaryRuntime(source)).rejects.toThrow('invalid metadata')
-})
-
-it.skipIf(process.platform === 'linux')('loads the real tool through Cordis, exposes installed paths, and unregisters on disposal', async () => {
-  const { source, root, manifest, directory } = await fixture()
-  const ctx = new Context()
-  try {
-    ctx.baseUrl = pathToFileURL(directory).href + '/'
-    await ctx.plugin(Loader)
-    ctx.loader.builtins.include = Include
-    const modules = new Map<string, unknown>([
-      ['agents', AgentRegistry], ['systemPrompt', SystemPrompt], ['tools', ToolRuntime], ['dependencies', workspaceDependencies],
-    ])
-    ctx.loader.internal = {
-      version: 'v2',
-      async import(specifier: string) {
-        if (!modules.has(specifier)) throw new Error(`unexpected plugin ${specifier}`)
-        return modules.get(specifier)
-      },
-    } as unknown as NonNullable<typeof ctx.loader.internal>
-    const config = join(directory, 'cordis.yml')
-    await writeFile(config, `- name: agents\n- name: systemPrompt\n- name: tools\n- name: dependencies\n  config:\n    source: ${JSON.stringify(source)}\n    root: ${JSON.stringify(root)}\n`)
-    await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(config).href } })
-    await ctx.loader.await()
-    for (const entry of ctx.loader.entries()) await entry.fiber?.await()
-    const environment = { ...process.env }
-    const request = { signal: new AbortController().signal, name: 'load_workspace_dependencies', arguments: {} }
-    const results = await Promise.all(['first', 'second'].map(id => ctx.tools.execute({ ...request, callId: ToolCallId(id) })))
-    for (const result of results) {
-      expect(result.isError).toBe(false)
-      expect(result.content).toEqual([{ type: 'text', text: JSON.stringify(workspaceDependencyPaths(root, manifest), undefined, 2) }])
-    }
-    expect(process.env).toEqual(environment)
-    const entry = [...ctx.loader.entries()].find(entry => entry.options.name === 'dependencies')
-    expect(entry).toBeDefined()
-    await entry?.fiber?.dispose()
-    expect(ctx.tools.schemas().some(tool => tool.name === 'load_workspace_dependencies')).toBe(false)
-  } finally {
-    await ctx.fiber.dispose()
-  }
-})
diff --git a/apps/desktop-host/tsconfig.json b/apps/desktop-host/tsconfig.json
index 89780f7b94..81277cb3ff 100644
--- a/apps/desktop-host/tsconfig.json
+++ b/apps/desktop-host/tsconfig.json
@@ -13,7 +13,7 @@
     { "path": "../../packages/jobs/jobs" },
     { "path": "../../packages/skill/skill-office" },
     { "path": "../../packages/util/home-paths" },
-    { "path": "../../packages/core/tools" },
+    { "path": "../../packages/skill/tool-workspace-dependencies" },
     {
       "path": "../cli"
     },
diff --git a/apps/desktop/.env.macos.example b/apps/desktop/.env.macos.example
index ef0f625950..960e1195c5 100644
--- a/apps/desktop/.env.macos.example
+++ b/apps/desktop/.env.macos.example
@@ -3,6 +3,9 @@
 DSH_DESKTOP_APP_ID=com.deepseek.harness
 DSH_DESKTOP_AUTO_UPDATE_ENV=test
 DOWNLOAD_TEST_ORIGIN=
+# Required for test releases: 32 lowercase hexadecimal characters from a secure random generator.
+# Generate once per release batch; retain it for retries and versions testing upgrades within that batch.
+DOWNLOAD_TEST_RELEASE_ID=
 
 # Workspace tarball workers; omit to use 4. Must be a positive integer.
 DSH_DESKTOP_MACOS_PACK_CONCURRENCY=4
diff --git a/apps/desktop/.env.windows.example b/apps/desktop/.env.windows.example
index 9b38d46df9..1212622b98 100644
--- a/apps/desktop/.env.windows.example
+++ b/apps/desktop/.env.windows.example
@@ -3,6 +3,9 @@
 DSH_DESKTOP_APP_ID=com.deepseek.harness
 DSH_DESKTOP_AUTO_UPDATE_ENV=test
 DOWNLOAD_TEST_ORIGIN=
+# Required for test releases: 32 lowercase hexadecimal characters from a secure random generator.
+# Generate once per release batch; retain it for retries and versions testing upgrades within that batch.
+DOWNLOAD_TEST_RELEASE_ID=
 
 # The selected mandatory-update origin is required, including unsigned and preparation builds.
 DSH_DESKTOP_MANDATORY_UPDATE_TEST_ORIGIN=
@@ -20,6 +23,9 @@ DSH_DESKTOP_WINDOWS_TOKEN_PIN=
 # Optional absolute, private local directory; defaults to %USERPROFILE%\.dsh-desktop-signing\signature-cache\v1.
 # DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_DIR=C:\Users\build\.dsh-desktop-signing\signature-cache\v1
 
+# Cache-hit restore and verification workers (1-8). Hardware signing remains serial.
+DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY=4
+
 # Optional upload configuration; packaging does not require these credentials.
 # DOWNLOAD_TEST_COS_BUCKET=
 # DOWNLOAD_TEST_COS_SECRET_ID=
diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index 455501862e..81f1df65f7 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent 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/desktop/README.md
-README.md: 6c9a6a8784732e6fa1369df5632391b789786b22
-README.zh.md: a0f2184d911eeab46902670cf992b6847e2bca31
+README.md: 43cde4f41f2e82bf2d3ccce0a7e93d81234010c5
+README.zh.md: 9e300996cd7ed0428c7199e9f9bd43b6f9077e0a
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 6c9a6a8784..43cde4f41f 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -4,12 +4,14 @@ English | [中文](README.zh.md)
 
 The desktop application is an Electron shell around the complete dsh Web application. An Electron RunAsNode child starts the shared profile runner, and Electron immediately loads the packaged Web entry at `dsh-app://app/`. Its shared loading page waits for Host boot injections, then starts the client without navigating to another document. Electron forwards application HTTP requests to the authenticated Web Host; WebSocket streams connect to that Host with credentials attached only for the owned application window. Node IPC carries boot injections, readiness, and shutdown. Desktop defaults to port `19387`, separate from Web’s `3080`; a `webserver.config.port` patch can override it.
 
-The first application-menu command, **About DeepSeek Harness**, opens Electron's native About panel with the application icon, product name, and installed release version. The menu follows the Desktop shell locale. macOS reads the icon from its application bundle, so an unpackaged development launch displays Electron's icon; Windows receives the packaged PNG.
+The first application-menu command, **About DeepSeek Harness**, opens Electron's native About panel with the application icon, product name, and installed release version. The menu follows the Desktop shell locale. On macOS, Hide, Hide Others, Show All, and Quit use localized labels; Hide and Quit include the DeepSeek Harness product name. These commands retain their native actions and shortcuts. macOS reads the icon from its application bundle, so an unpackaged development launch displays Electron's icon; Windows receives the packaged PNG.
 
 Desktop’s local native directory flow opens an Electron folder dialog attached to the application window, restoring, showing, and focusing that window first. Concurrent requests share one dialog; cancellation returns no path and failures remain retryable. Ordinary Web uses the Host chooser. Browse mode lists Host directories. On Linux without zenity or kdialog, automatic selection uses browse instead of the Electron dialog.
 
 Creator and the Web Plugin Manager use Desktop’s bundled pnpm under Electron Node mode without requiring pnpm on PATH. The private Node launcher environment applies only to package operations.
 
+Desktop microphone access is restricted to audio requests from the primary `dsh-app://app` frame. macOS uses system microphone authorization and a packaged usage description.
+
 ## Key technical decisions
 
 The original artwork lives in `resources/icon.png` and `resources/icon.svg`; platform adaptations retain the whale and gradients in `resources/icon-windows.*` and `resources/icon-macos.*`. Export each platform SVG as a transparent 1024×1024 PNG. Electron-builder generates the multi-size ICO for the Windows application, installer, and uninstaller ([Windows icon requirements](https://learn.microsoft.com/en-us/windows/apps/design/iconography/app-icon-construction)). The installation pages use matching artwork in both themes; the uninstaller's welcome and finish pages share `installer/assets/uninstaller-sidebar.png`, converted to a 164×314 BMP during preparation.
@@ -24,11 +26,11 @@ Desktop carries independent Python, Node.js and pnpm distributions. Python inclu
 
 Desktop registers `office-docx`, `office-pptx`, and `office-xlsx` by default. The skills use the bundled Python libraries for creation and focused edits, then reopen the files and run a shared structural checker before delivery. PowerPoint creation and editing use python-pptx. Skill resources are copied to `runtime/office-skills` outside ASAR so Python can read the checker. An available `render_document` tool can add visual inspection; its absence does not prevent authoring or delivery. See the [Office skill package](../../packages/skill/skill-office/README.md) for checks and limitations.
 
-The payload follows the Desktop release. `runtime.json` records the Desktop version, target, component and Python distribution versions, and a digest of the selected target’s locked payload inputs and assembly format. Distribution names use PEP 503 normalization; duplicate normalized names and conflicting numpy/pandas component and distribution versions reject the manifest. Matching installations are reused; a dependency or archive change replaces the directory after a complete staged copy even when the Desktop version stays unchanged. Older manifests without a digest are replaced on their next installation. User-added Python packages remain only while the payload identity matches. A failed directory replacement retains the previous installation; Windows may refuse replacement while an interpreter is still running.
+The payload follows the Desktop release. `runtime.json` records the Desktop version, target, top-level interpreter/package-manager versions and the Python distribution map, and a digest of the selected target’s locked payload inputs and assembly format. Distribution names use PEP 503 normalization; duplicate normalized names reject the manifest. Legacy `components` manifests remain readable through normalization, with their existing library-version consistency checks. Matching installations are reused; a dependency or archive change replaces the directory after a complete staged copy even when the Desktop version stays unchanged. Older manifests without a digest are replaced on their next installation. User-added Python packages remain only while the payload identity matches. A failed directory replacement retains the previous installation; Windows may refuse replacement while an interpreter is still running.
 
 The private Desktop `runtime/bin` directory is added only to package-installation processes, not the Host PATH inherited by PTC and agent shells. This tool does not change PATH, environment variables or user package-manager configuration. pnpm retains its own defaults and user settings for global packages, executable entries and its store, including native errors when the environment does not support global installation. There is no separate dependency updater. [The primary-runtime decision](../../.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md) records these choices.
 
-Node prepares the bundled interpreters and Python libraries without a system Python or pip. [The download lock](scripts/primary-runtime-lock.json) pins interpreter archives, Python distribution versions and target-specific wheel URLs and hashes; pnpm follows the Desktop build dependency lock. Wheel filenames and distribution versions must agree for every target. Preserve key order within the selected target, wheel records and distribution map, plus wheel-entry order; these affect payload identity, while top-level lock key order does not. Library wheels unpack into site-packages, retaining auxiliary files under each wheel's `.data/scripts` directory without generating command wrappers. Other installation schemes are rejected. Native-target checks verify the locked wheel set and versions, permit the interpreter's bundled pip, and check the Python version, Office document read/write operations and dependency completeness without writing bytecode after staging cleanup and again after macOS signing. The standalone Node executable receives the JIT entitlement required by V8. Cross-target execution and signed installation require the target release host. Both `dev:desktop` and `start:desktop` prepare `.desktop-build/targets/<target>/runtime/primary-runtime` before launching Electron; first use may download locked dependencies. An unfinished preparation cannot report a successful launcher exit.
+Node prepares the bundled interpreters and Python libraries without a system Python or pip. [The download lock](../../scripts/primary-runtime/lock.json) pins interpreter archives, Python distribution versions and target-specific wheel URLs and hashes; the shared builder resolves pnpm from the root development dependency pin. The root package-manager version and the Desktop pin are checked for agreement. Wheel filenames and distribution versions must agree for every target. Preserve key order within the selected target, wheel records and distribution map, plus wheel-entry order; these affect payload identity, while top-level lock key order does not. Library wheels unpack into site-packages, retaining auxiliary files under each wheel's `.data/scripts` directory without generating command wrappers. Other installation schemes are rejected. Native-target checks verify the locked wheel set and versions, permit the interpreter's bundled pip, and check the Python version, Office document read/write operations and dependency completeness without writing bytecode after staging cleanup and again after macOS signing. The standalone Node executable receives the JIT entitlement required by V8. Cross-target execution and signed installation require the target release host. Both `dev:desktop` and `start:desktop` prepare `.desktop-build/targets/<target>/runtime/primary-runtime` before launching Electron; first use may download locked dependencies. An unfinished preparation cannot report a successful launcher exit.
 
 | Decision | Why | Direct consequence |
 |---|---|---|
@@ -46,13 +48,15 @@ The [thin-wrapper decision](../../.agents/notes/implemented/architecture/2026-09
 
 Electron owns `$DSH_HOME/profiles/desktop`. Its `dependencies` contains packages installed by pnpm; `dsh.profile.bundles` contains the built-in bundles followed by enabled plugins. The signed application supplies dsh, the private Desktop Host, and their production packages from `resources/app.asar/dsh`. Packaged applications select runtime profile resolution without creating package links; development profiles use filesystem links. Both host and plugins execute in the same Electron Node-mode process; Desktop does not enable `--preserve-symlinks`. The CLI cannot boot or mutate this profile.
 
-The application preload exposes boot readiness, fatal startup reporting, and native directory selection. Product documents use the shared authenticated HTTP APIs and receive the Desktop marker, update presentation, and an action that opens native confirmation; they cannot choose artifacts or authorize installation. Plugin management uses the Web application's authenticated HTTP APIs. Electron serves update-dialog documents and assets locally at `dsh-app://shell/`, independently of Host readiness. Electron exposes no plugin-management IPC or separate management document. No renderer receives filesystem access, raw Electron IPC, a shell, or arbitrary pnpm arguments.
+The application preload exposes boot readiness, fatal startup reporting, native directory selection, the `__DSH_HOST_PATHS__` bridge for composer path references, and the lease-scoped Browser bridge only to `dsh-app://app` documents. Product documents use the shared authenticated HTTP APIs and receive the Desktop marker, update presentation, and an action that opens native confirmation; they cannot choose artifacts or authorize installation. Plugin management uses the Web application's authenticated HTTP APIs. Electron serves update-dialog documents and assets locally at `dsh-app://shell/`, independently of Host readiness. Electron exposes no plugin-management IPC or separate management document. No renderer receives filesystem access, raw Electron IPC, a shell, or arbitrary pnpm arguments.
+
+Only the main application window enables `<webview>`. Guest attachment must match a main-issued lease and partition; guests keep sandbox, context isolation and Web security without Node integration or guest preload. Browser IPC listeners are created only for the application document. [Sidebar Browser](../../packages/client/ui-sidebar-browser/README.md) describes storage grouping and guest limitations; Host authentication remains required independently of URL filtering.
 
 The `dsh-app://shell/` origin serves packaged update documents, scripts, and styles without contacting the Host. Static requests retain GET/HEAD, path-containment, and MIME handling; each update document keeps its isolated preload and owned-window IPC checks.
 
 The product UI retains Web actions, including "Open In..." through the shared authenticated HTTP routes. Desktop uses Web's automatic directory-picker selection and initializes new profiles with the shared Web template's bundles.
 
-Electron chooses typed English or Chinese shell copy from its application locale and falls back to English. On Windows, the main document's language updates desktop menus, recovery and update prompts. The repository Client UI i18n gate checks desktop sources.
+Electron chooses typed English or Chinese shell copy from its application locale and falls back to English. The macOS application bundle declares English and Simplified Chinese in `CFBundleLocalizations`, allowing macOS to match the initial application language to the user’s preferred languages. Saved Client UI language preferences still take precedence for the main interface. On Windows, the main document's language updates desktop menus, recovery and update prompts. The repository Client UI i18n gate checks desktop sources.
 
 Windows uses a 40-DIP caption with native window controls and colors synchronized from the application palette. Localized Application and Edit entries beside the sidebar toggle open native popup menus. They mount only after the application frame publishes its shell overlay seat, and remain absent during startup loading. Application provides Check for Updates and Exit; Edit provides undo, redo, cut, copy, paste, delete, and select all by sending the corresponding keys to the focused editor. Plugin management uses the main application's Plugins page. No separate native menu row appears on Alt. Other platforms retain their native menus. Editable fields retain keyboard commands and a context menu without shortcut labels; Chromium supplies command availability, and selected read-only text offers Copy.
 
@@ -93,7 +97,7 @@ After an explicit build, `start:desktop` reconstructs the disposable project and
 pnpm run start:desktop
 ```
 
-Workspace development runs the current CLI and private Desktop Host packages under Electron RunAsNode. Plugin management and recovery use `$DSH_HOME/profiles/desktop`, separate from the disposable workspace runtime. The Host uses runtime module resolution in both development and packaged builds without creating official-package fallback links; developer-installed packages, including links, retain native priority. Use an unpacked application to exercise Electron RunAsNode, bundled pnpm, bundled dsh resources, plugin installation and repair paths.
+The Web counterparts are `pnpm run dev:web` and `pnpm run start:web`, documented in the [development guide](../../docs/development.md). Workspace development runs the current CLI and private Desktop Host packages under Electron RunAsNode. Plugin management and recovery use `$DSH_HOME/profiles/desktop`, separate from the disposable workspace runtime. The Host uses runtime module resolution in both development and packaged builds without creating official-package fallback links; developer-installed packages, including links, retain native priority. Use an unpacked application to exercise Electron RunAsNode, bundled pnpm, bundled dsh resources, plugin installation and repair paths.
 
 ## Package
 
@@ -158,13 +162,15 @@ pwsh -NoProfile -File apps/desktop/scripts/smoke-windows.ps1 -Makensis $Makensis
 
 The Windows installer extracts the new version beside the installation directory, stops the old application, and replaces directories through same-volume renames. Same-path upgrades preserve the old directory until promotion succeeds; extraction failure leaves it intact, and promotion failure attempts to restore it. The installer removes the old backup before launch. Forced termination or power loss can leave `.new-*` or `.old-*` directories; installation-location and scope migrations retain electron-builder's old-uninstaller flow.
 
+<a id="upload-updates"></a>
+
 ### Upload updates
 
 Test and production uploads through `upload:*` retain a fresh `.desktop-build/upload-records/<environment>-<target>-*` directory after release preflight. `plan.json` records destination, version, every file's size/SHA-512, and published YAML bytes; flushed `events.jsonl` records PUT intent and available response status/request ID; `result.json` records completion or the last failed stage. A missing final result means interruption or unavailable storage, not success. No credential values, authorization headers, or raw SDK errors are recorded. Audit-write failures stop later PUTs. Every object is one streamed Tencent COS PUT with an explicit length and Content-MD5; the COS SDK repeats a request only when its body is not a stream, and this uploader does not retry either. Retain partial records and inspect remote state before another operation: a timeout or failed receipt write does not prove that the object was not stored. These records are local, not tamper-proof or automatically backed up; archive each release's records with its build evidence in controlled storage. Public CDN readback remains separate release qualification, explicitly marked `not-performed` in the upload result.
 
 Windows operators can keep a CLIXML object with DPAPI-encrypted `SecretId` and `SecretKey` SecureString fields outside the repository. The [credential launcher](scripts/upload-with-credentials.ps1) requires an explicit `-CredentialFile` and `-Environment production` or `test`; without `-Upload`, it only verifies decryption and injection into a local Node child, with no network request. It requires Node on `PATH` and the Windows user and machine that encrypted the file. Plaintext, empty, and whitespace-only fields fail. The parent environment is unchanged; the child receives only the selected COS pair after unrelated secrets and Node preload options are removed. Raw child stderr is suppressed and credential values in stdout are redacted. This check does not prove COS authorization. An explicit upload additionally requires `-Upload -Target <target> -Bucket <bucket>` and the normal completed-release prerequisites below; actual cloud upload remains release-operator qualification. This launcher supports permanent keys, not STS credentials. An explicit upload requires the selected deployment and bucket to match the target dotenv and completed package record before network writes; it uses the DPAPI credential pair even if the dotenv contains other COS keys.
 
-`DSH_DESKTOP_AUTO_UPDATE_ENV` selects `test` or `production` for both the URL embedded during packaging and the later COS upload; an absent value selects `test`. Test packaging requires its HTTPS origin in `DOWNLOAD_TEST_ORIGIN`; production uses `https://download.deepseek.com`. Upload requires the selected bucket in `DOWNLOAD_TEST_COS_BUCKET` or `DOWNLOAD_PROD_COS_BUCKET`. Feed directories are `dsh-desk/feeds/<target>/`; versioned packages and blockmaps live in `dsh-desk/bin/<target>/`. Targets are `mac-arm64`, `mac-x64`, and `win-x64`.
+`DSH_DESKTOP_AUTO_UPDATE_ENV` selects `test` or `production` for both the URL embedded during packaging and the later COS upload; an absent value selects `test`. Test packaging requires its HTTPS origin in `DOWNLOAD_TEST_ORIGIN`; production uses `https://download.deepseek.com`. Upload requires the selected bucket in `DOWNLOAD_TEST_COS_BUCKET` or `DOWNLOAD_PROD_COS_BUCKET`. Production feeds use `dsh-desk/feeds/<target>/` and binaries use `dsh-desk/bin/<target>/`. Test releases require `DOWNLOAD_TEST_RELEASE_ID`: 32 lowercase hexadecimal characters inserted as `dsh-desk/<release-id>/feeds/<target>/` and `dsh-desk/<release-id>/bin/<target>/`. YAML references, stable-channel aliases, and blockmaps stay inside that release directory. Targets are `mac-arm64`, `mac-x64`, and `win-x64`.
 
 The update destination and upload credentials follow the selected deployment:
 
@@ -173,6 +179,14 @@ The update destination and upload credentials follow the selected deployment:
 | `test` or unset | `DOWNLOAD_TEST_ORIGIN` | `DOWNLOAD_TEST_COS_BUCKET` | `DOWNLOAD_TEST_COS_SECRET_ID`, `DOWNLOAD_TEST_COS_SECRET_KEY` |
 | `production` | `https://download.deepseek.com` | `DOWNLOAD_PROD_COS_BUCKET` | `DOWNLOAD_PROD_COS_SECRET_ID`, `DOWNLOAD_PROD_COS_SECRET_KEY` |
 
+Generate a fresh ID for each test release batch with the command below and copy its output into `DOWNLOAD_TEST_RELEASE_ID` in `.env.macos` or `.env.windows`. These Git-ignored platform files own the value; shell variables do not override it, and dotenv values are not shell-expanded. Keep the ID through packaging, upload, and retries; upload rejects a completion record with a different update URL. To test an upgrade between versions, reuse the installed client’s ID for the later version. Production does not use this field.
+
+```sh
+node --input-type=module -e "import { randomBytes } from 'node:crypto'; console.log(randomBytes(16).toString('hex'))"
+```
+
+Distribute each test batch through its complete download links. Installed test clients retain their batch feed and do not discover a new ID automatically. Format validation cannot establish randomness; use the generator output. Random paths reduce guessing, not access by link holders; withdrawing a batch requires deleting its COS objects and purging its CDN directory.
+
 Configure the update origin and selected COS bucket, SecretId, and SecretKey in the target dotenv file, then package and upload the same target:
 
 ```sh
@@ -232,7 +246,9 @@ Runtime signing shares complete signed files across the current Windows account'
 
 Preflight, primary-runtime signing, application-runtime signing and artifact creation each hold the account's signing-stage lock until their supervised child processes settle. Other builds wait before entering those stages; compilation and preparation do not hold the lock. Runtime signing workers own their locks, so terminating only the outer packaging process does not unlock a surviving cache user. Migration and maintenance acquire the same lock; older or external signing commands do not participate and must be scheduled separately. Stage waiting is outside the preflight deadline. Closing the stage handle releases ordinary contention without removing the separate hardware-attempt interlock; a retained hardware failure still requires operator recovery.
 
-Each runtime stage writes `SIGNATURE_CACHE_SUMMARY` to stdout and its packaging journal, including the actual directory, policy identity, hit/miss counts, newly published and retained entries, signing requests, avoided signing requests and validation failures. Timings distinguish signing, trust verification of restored and newly signed files, and restoration; restoration includes its trust check and staging cleanup. These counters exclude preflight, final artifact signing and the outer runtime signature checks. Stage lock events record waiting separately.
+Cache-hit copying, hashing and per-file trust checks run with `DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY` workers from `.env.windows` (default `4`, integer `1`–`8`). All restores and their post-verification finish before cache misses enter serial hardware signing. A restore or verification failure stops new dispatch and drains active work before releasing the stage lock; hardware signing, runtime smoke checks and final integrity validation remain required.
+
+Each runtime stage writes `SIGNATURE_CACHE_SUMMARY` to stdout and its packaging journal, including the actual directory, policy identity, hit/miss counts, newly published and retained entries, signing requests, avoided signing requests and validation failures. Timings distinguish signing, trust verification of restored and newly signed files, and restoration; restoration includes its trust check and staging cleanup. These counters exclude preflight, final artifact signing and the outer runtime signature checks. Stage lock events record waiting separately. Concurrent timings sum per-file work rather than stage wall time.
 
 Use `pnpm --dir apps/desktop run cache:windows-signatures --usage` to inspect structurally complete-entry bytes and counts, or `--from <absolute-old-cache>` to import an explicitly selected cache owned by the same account. Migration leaves the source unchanged, skips staging names, rejects corrupt entries and retains valid existing entries even when their timestamp bytes differ. `--clear` explicitly removes complete entries under the stage lock; no automatic capacity eviction runs. `--directory <absolute-cache>` selects a maintenance destination without loading release credentials. Incomplete staging entries remain untouched and are counted separately; inspect them only after all builds have stopped. These commands never clear hardware failure evidence. Default storage is outside AppData so MSIX launcher virtualization does not split the account's cache; redirected overrides fail explicitly.
 
@@ -320,7 +336,7 @@ With `feishu-test`, an HTTP 401 JSON response containing `error.code: "UNAUTHENT
 
 Login and policy requests share an in-memory Session, separate from product windows and the updater; restarting requires a new login. Closing cancels login, and navigation failure provides localized retry guidance. Returning to the service triggers a fresh policy query; a redirect, cookie, or HTTP 422 is not a valid policy decision. Cancellation, expiry, and invalid responses retain any known mandatory block. Fixed login outcomes appear in process diagnostics and the optional update journal; cookies, OAuth parameters, and remote error text are not recorded by the login controller. Live Harness gateway/API integration and macOS login qualification remain unverified.
 
-A flattened `40005` opens a shell-owned modal and refuses subsequent plugin mutations without stopping existing Host tasks. Server title and detail are optional plain text and fall back to client copy; an absent or unapproved download URL hides the external-page actions without clearing the block. On macOS the mandatory overlay fades in and out in place, keeps its backdrop during update-state changes, and redirects parent-window focus and keyboard input to the overlay. On Windows the mandatory window has a native title bar and can be moved, resized, and maximized. Closing it exits the application after cleanup without clearing the update requirement; Esc does not dismiss it. Once installation is approved, installer-owned quit releases the modal before Electron closes windows. Download, file verification including preparation, task inspection, and installation confirmation share this same modal. Only the second user approval permits task teardown and installation; deferral retains the block and package. Restart feedback mentions task stopping only when affected tasks exist. Policy is not persisted across application restarts, and policy responses never revoke or replace an updater artifact.
+A flattened `40005` opens a shell-owned modal and refuses subsequent plugin mutations without stopping existing Host tasks. Server title and detail are optional plain text and fall back to client copy; an absent or unapproved download URL hides the external-page actions without clearing the block. On macOS the mandatory overlay fades in and out in place, keeps its backdrop during update-state changes, and redirects parent-window focus and keyboard input to the overlay. On Windows the isolated application preload mounts a shell-origin frame inside the main window, covering the content below the 40 DIP caption with a backdrop and dialog. It blocks background page input without creating another native window; moving and maximizing affect only the main window. Caption menus retain mouse and keyboard operation; Web controls in the caption remain reachable. The shared DOM is a presentation constraint, not a security boundary: product scripts can hide the overlay but cannot clear main-process policy or authorize installation through it. Update actions and state use a private MessageChannel between the isolated preload and shell frame. The parent remains enabled for native move, resize, minimize, maximize, and close controls. Closing the application performs cleanup without clearing the update requirement; Esc does not dismiss the overlay. Once installation is approved, installer-owned quit releases the modal before Electron closes windows. Download, file verification including preparation, task inspection, and installation confirmation share this same modal. Only the second user approval permits task teardown and installation; deferral retains the block and package. Restart feedback mentions task stopping only when affected tasks exist. Policy is not persisted across application restarts, and policy responses never revoke or replace an updater artifact.
 
 Failures retain blocking, localized retry guidance, and folded diagnostics inside the modal. The allowed download-page action appears in recovery states, not beside normal download or installation. Requesting the browser immediately exposes a copy alternative even while the OS request is pending; a resolved request does not prove the page opened. Copy failure reveals the complete, read-only address for manual copying. Browser and clipboard outcomes do not overwrite updater errors. Only a fresh valid no-force response clears the block; the top-menu check remains available while blocked.
 
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index a0f2184d91..9e300996cd 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -4,12 +4,14 @@
 
 桌面应用是完整 dsh Web 应用外的一层 Electron 壳。Electron RunAsNode 子进程启动共享 profile runner，Electron 立即从 `dsh-app://app/` 加载打包内的 Web 入口。共享加载页等待 Host 启动注入，然后在同一文档中启动客户端。Electron 将应用 HTTP 请求转发给已认证的 Web Host；WebSocket 流连接到该 Host，仅为归属的应用窗口附加凭据。Node IPC 承载启动注入、就绪与关闭。Desktop 默认使用端口 `19387`，与 Web 的 `3080` 分开；可通过 `webserver.config.port` patch 覆盖。
 
-应用菜单第一项“**关于 DeepSeek Harness**”打开 Electron 原生关于面板，展示应用图标、产品名称和当前安装的发布版本。菜单文案跟随桌面壳的语言。macOS 从应用包读取图标，因此未打包的开发启动会显示 Electron 图标；Windows 使用随包分发的 PNG。
+应用菜单第一项“**关于 DeepSeek Harness**”打开 Electron 原生关于面板，展示应用图标、产品名称和当前安装的发布版本。菜单文案跟随桌面壳的语言。macOS 的隐藏、隐藏其他、显示全部和退出条目使用本地化文案，隐藏和退出条目包含 DeepSeek Harness 产品名称。这些条目保留原生动作和快捷键。macOS 从应用包读取图标，因此未打包的开发启动会显示 Electron 图标；Windows 使用随包分发的 PNG。
 
 Desktop 的本地原生目录流程打开绑定应用窗口的 Electron 文件夹对话框，并先恢复、显示和聚焦该窗口。并发请求共用一个对话框；取消不返回路径，失败后可以重试。普通 Web 使用 Host 选择器。浏览模式列出 Host 目录。Linux 缺少 zenity 或 kdialog 时，自动选择使用浏览模式，不使用 Electron 对话框。
 
 Creator 和 Web Plugin Manager 在 Electron Node 模式下使用 Desktop 内置 pnpm，无需 PATH 中存在 pnpm。私有 Node 启动器环境仅应用于包操作。
 
+桌面麦克风访问仅允许主 `dsh-app://app` 页面发起的音频请求。macOS 使用系统麦克风授权与随包用途说明。
+
 ## 关键技术决策
 
 设计师原稿位于 `resources/icon.png` 和 `resources/icon.svg`；平台适配保留鲸鱼与渐变，分别位于 `resources/icon-windows.*` 和 `resources/icon-macos.*`。将各平台 SVG 导出为透明的 1024×1024 PNG。electron-builder 为 Windows 应用、安装程序和卸载程序生成多尺寸 ICO（[Windows 图标要求](https://learn.microsoft.com/en-us/windows/apps/design/iconography/app-icon-construction)）。安装页面在两种主题下使用匹配的图案；卸载程序的欢迎和完成页共用 `installer/assets/uninstaller-sidebar.png`，准备阶段将其转换为 164×314 BMP。
@@ -24,11 +26,11 @@ Desktop 携带独立的 Python、Node.js 和 pnpm 分发包。Python 包含 nump
 
 Desktop 默认注册 `office-docx`、`office-pptx` 和 `office-xlsx`。这些技能使用内置 Python 库创建文件和进行定点编辑，随后重新打开文件，并在交付前运行共享结构检查器。PowerPoint 的创建和编辑使用 python-pptx。技能资源复制到 ASAR 外的 `runtime/office-skills`，让 Python 可以读取检查器。可用的 `render_document` 工具可以补充视觉检查；缺少该工具不妨碍创作或交付。检查范围与限制见 [Office 技能包](../../packages/skill/skill-office/README.zh.md)。
 
-该产物随 Desktop 版本发布。`runtime.json` 记录 Desktop 版本、目标平台、组件与 Python 分发包版本，以及所选目标的锁定产物输入与组装格式的摘要。分发包名称按 PEP 503 归一化；名称归一化后重复，或 numpy/pandas 的组件版本与分发包版本冲突时，清单会被拒绝。匹配的安装会被复用；依赖或压缩包变化后，即使 Desktop 版本不变，也会在完整暂存副本完成后替换目录。不含摘要的旧清单会在下次安装时被替换。用户自行添加的 Python 包仅在产物身份一致时保留。目录替换失败时保留之前的安装；解释器仍在运行时，Windows 可能拒绝替换。
+该产物随 Desktop 版本发布。`runtime.json` 记录 Desktop 版本、目标平台、顶层解释器和包管理器版本及 Python 分发包版本表，以及所选目标的锁定产物输入与组装格式的摘要。分发包名称按 PEP 503 归一化；名称归一化后重复时，清单会被拒绝。旧 `components` 清单通过归一化继续可读，并保留其原有库版本一致性校验。匹配的安装会被复用；依赖或压缩包变化后，即使 Desktop 版本不变，也会在完整暂存副本完成后替换目录。不含摘要的旧清单会在下次安装时被替换。用户自行添加的 Python 包仅在产物身份一致时保留。目录替换失败时保留之前的安装；解释器仍在运行时，Windows 可能拒绝替换。
 
 Desktop 私有的 `runtime/bin` 目录仅添加到包安装进程，不进入 PTC 和 agent shell 从 Host 继承的 PATH。该工具不修改 PATH、环境变量或用户包管理器配置。pnpm 的全局包、命令入口和 store 保留自身默认值及用户设置，包括环境不支持全局安装时的原生错误。不提供独立依赖更新器。[第一方 Runtime 决策](../../.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md)记录这些选择。
 
-Node 准备内置解释器和 Python 库，无需系统 Python 或 pip。[下载锁](scripts/primary-runtime-lock.json)固定解释器压缩包、Python 分发包版本及目标平台 wheel 的 URL 和哈希；pnpm 使用 Desktop 构建依赖锁。每个目标的 wheel 文件名必须与分发包版本一致。所选目标、wheel 记录及分发包映射内部的键顺序，以及 wheel 条目顺序都会影响产物身份，编辑时须保留；锁文件顶层键的顺序不影响该身份。库 wheel 解压到 site-packages，各 wheel 的 `.data/scripts` 目录保留辅助文件，不生成命令行包装器。其他安装方案会被拒绝。本机目标检查在清理暂存目录后以及 macOS 签名后验证锁定 wheel 的集合与版本，允许解释器自带的 pip，并检查 Python 版本、Office 文档读写和依赖完整性，不写入字节码。独立 Node 可执行文件获得 V8 所需的 JIT 权限。跨目标执行和签名安装需要对应的发布主机。`dev:desktop` 和 `start:desktop` 都会在启动 Electron 前准备 `.desktop-build/targets/<target>/runtime/primary-runtime`；首次准备可能需要下载锁定的依赖。准备未完成时，启动命令不能报告成功退出。
+Node 准备内置解释器和 Python 库，无需系统 Python 或 pip。[下载锁](../../scripts/primary-runtime/lock.json)固定解释器压缩包、Python 分发包版本及目标平台 wheel 的 URL 和哈希；共享构建器从根开发依赖中解析 pnpm 固定版本。测试检查根 package-manager 版本和 Desktop 固定版本保持一致。每个目标的 wheel 文件名必须与分发包版本一致。所选目标、wheel 记录及分发包映射内部的键顺序，以及 wheel 条目顺序都会影响产物身份，编辑时须保留；锁文件顶层键的顺序不影响该身份。库 wheel 解压到 site-packages，各 wheel 的 `.data/scripts` 目录保留辅助文件，不生成命令行包装器。其他安装方案会被拒绝。本机目标检查在清理暂存目录后以及 macOS 签名后验证锁定 wheel 的集合与版本，允许解释器自带的 pip，并检查 Python 版本、Office 文档读写和依赖完整性，不写入字节码。独立 Node 可执行文件获得 V8 所需的 JIT 权限。跨目标执行和签名安装需要对应的发布主机。`dev:desktop` 和 `start:desktop` 都会在启动 Electron 前准备 `.desktop-build/targets/<target>/runtime/primary-runtime`；首次准备可能需要下载锁定的依赖。准备未完成时，启动命令不能报告成功退出。
 
 | 决策 | 原因 | 直接结果 |
 |---|---|---|
@@ -46,15 +48,17 @@ Node 准备内置解释器和 Python 库，无需系统 Python 或 pip。[下载
 
 Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm 安装的包；`dsh.profile.bundles` 包含内置 bundle，后接已启用插件。签名应用从 `resources/app.asar/dsh` 提供 dsh、私有 Desktop Host 及其生产依赖。打包应用选择 runtime profile 解析，不创建包链接；开发 profile 使用文件系统链接。宿主与插件在同一个 Electron Node 模式进程中执行；Desktop 不启用 `--preserve-symlinks`。CLI 不能启动或修改此 profile。
 
-应用 preload 暴露启动就绪、致命启动失败上报和原生目录选择。产品页面还获得 Desktop 标记、更新展示数据和打开原生确认的操作，不能选择安装产物或授权安装。插件管理使用 Web 应用经过认证的 HTTP API；Electron 在 `dsh-app://shell/` 本地提供更新弹窗文档和资源，不依赖 Host 就绪。Electron 不提供插件管理 IPC 或独立管理页面。
+应用 preload 只向 `dsh-app://app` 文档暴露启动就绪、致命启动失败上报、原生目录选择、用于 composer 路径引用的 `__DSH_HOST_PATHS__` 桥接和租约范围内的 Browser 桥接。产品页面还获得 Desktop 标记、更新展示数据和打开原生确认的操作，不能选择安装产物或授权安装。插件管理使用 Web 应用经过认证的 HTTP API；Electron 在 `dsh-app://shell/` 本地提供更新弹窗文档和资源，不依赖 Host 就绪。Electron 不提供插件管理 IPC 或独立管理页面。
+
+只有主应用窗口启用 `<webview>`。guest 挂载必须匹配主进程签发的租约和分区；guest 保持 sandbox、context isolation 和 Web security，不启用 Node integration 或 guest preload。Browser IPC 监听只为应用文档创建。[Sidebar Browser](../../packages/client/ui-sidebar-browser/README.zh.md) 说明存储分组和 guest 限制；Host 鉴权仍独立于 URL 过滤而必需。
 
 `dsh-app://shell/` 无需联系 Host 即可提供打包的更新文档、脚本和样式。静态请求保留 GET/HEAD、路径范围和 MIME 处理；每个更新文档继续使用隔离 preload 和所属窗口的 IPC 校验。
 
 产品 UI 保留 Web 操作，包括通过共享认证 HTTP 路由执行的“打开方式…”。Desktop 使用 Web 的自动目录选择机制，并以共享 Web 模板的 bundle 列表初始化新 profile。
 
-Electron 根据应用语言选择类型化的英文或中文 shell 文案，并回退到英文。在 Windows 上，主文档的语言会更新桌面菜单、恢复与更新提示。仓库 Client UI i18n 检查覆盖桌面端源码。
+Electron 根据应用语言选择类型化的英文或中文 shell 文案，并回退到英文。macOS 应用包通过 `CFBundleLocalizations` 声明支持英语和简体中文，让 macOS 根据用户的首选语言匹配初始应用语言。主界面仍优先使用已保存的 Client UI 语言偏好。在 Windows 上，主文档的语言会更新桌面菜单、恢复与更新提示。仓库 Client UI i18n 检查覆盖桌面端源码。
 
-Windows 使用 40 DIP 顶栏，保留原生窗口按钮，颜色随应用调色板同步。侧栏开关旁的本地化“应用”和“编辑”入口打开原生弹出菜单。仅当应用框架发布 shell overlay 席位后才挂载菜单，启动加载期间不显示。“应用”提供检查更新和退出；“编辑”向当前编辑器发送对应按键，提供撤销、重做、剪切、复制、粘贴、删除和全选。插件管理使用主应用的“插件”页面。按 Alt 不会出现额外的原生菜单行。其他平台保留原生菜单。可编辑区域保留快捷键和不带快捷键标注的右键菜单；命令可用状态由 Chromium 提供，选中的只读文本提供“复制”命令。
+Windows 使用 40 DIP 顶栏，保留原生窗口按钮，颜色随应用调色板同步。侧栏开关旁的本地化“应用”和“编辑”入口打开原生弹出菜单。仅当应用框架发布 shell overlay 席位后才挂载菜单，启动加载期间不显示。“应用”提供检查更新和退出；“编辑”向当前编辑器发送对应按键，提供撤销、重做、剪切、复制、粘贴、删除和全选。插件管理使用主应用的“插件”页面。按 Alt 不会出现额外的原生菜单行。其他平台保留原生菜单。可编辑区域保留快捷键和不带快捷键标注的右键菜单；命令可用状态由 Chromium 提供，选中的只读文本提供“复制”命令。 顶栏菜单保留鼠标和键盘操作，顶栏中的 Web 控件仍可触达。共享 DOM 只约束展示，不构成安全边界：产品脚本可以隐藏蒙层，但不能借此清除主进程策略或授权安装。更新操作与状态通过隔离预加载和壳 frame 之间的私有 MessageChannel 传递。
 
 macOS 上自定义应用菜单还会声明标准的 File、Window 和应用菜单，因为替换 Electron 的默认菜单会丢掉 Close Window（⌘W）、Minimize（⌘M）和 Hide（⌘H）。Linux 保留应用菜单和 Edit 菜单。
 
@@ -93,7 +97,7 @@ pnpm run dev:desktop
 pnpm run start:desktop
 ```
 
-Workspace 开发使用 Electron RunAsNode 运行当前 CLI 与私有 Desktop Host 包，插件管理和恢复使用 `$DSH_HOME/profiles/desktop`，与一次性工作区运行时分离。Host 在开发与打包构建中都使用 runtime 模块解析，不创建官方包的 fallback 链接；开发者安装的包（包括链接）保留原生优先级。需要验证 Electron RunAsNode、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。
+Web 侧的对应命令是 `pnpm run dev:web` 与 `pnpm run start:web`，见[开发指南](../../docs/development.zh.md)。Workspace 开发使用 Electron RunAsNode 运行当前 CLI 与私有 Desktop Host 包，插件管理和恢复使用 `$DSH_HOME/profiles/desktop`，与一次性工作区运行时分离。Host 在开发与打包构建中都使用 runtime 模块解析，不创建官方包的 fallback 链接；开发者安装的包（包括链接）保留原生优先级。需要验证 Electron RunAsNode、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。
 
 ## 打包
 
@@ -158,13 +162,15 @@ pwsh -NoProfile -File apps/desktop/scripts/smoke-windows.ps1 -Makensis $Makensis
 
 Windows 安装器先将新版本解压到安装目录旁边，再退出旧应用并通过同卷目录改名完成替换。同路径升级在替换成功前保留旧目录；解压失败时旧版不变，替换失败时尝试恢复旧目录。安装器在启动前清理旧版备份。强制结束安装器或断电可能留下 `.new-*` 或 `.old-*` 目录；不同安装位置或安装范围迁移仍使用 electron-builder 的旧卸载器流程。
 
+<a id="upload-updates"></a>
+
 ### 上传更新
 
 test 与 production 的 `upload:*` 上传在发布前置检查通过后，分别保留新的 `.desktop-build/upload-records/<environment>-<target>-*` 目录。`plan.json` 记录目标、版本、每个文件的大小/SHA-512 和发布的 YAML 字节；刷盘的 `events.jsonl` 记录 PUT 意图及可用的响应状态/请求 ID；`result.json` 记录完成结果或最后失败阶段。缺少最终结果表示中断或存储不可用，不表示成功。不记录凭据值、认证头或原始 SDK 错误。审计写入失败即停止后续 PUT。每个对象都以一次流式腾讯 COS PUT 上传，并携带显式长度与 Content-MD5；COS SDK 仅在请求体不是流时才会重发请求，上传器自身也不重试。保留部分记录，检查远端状态后再执行下一次操作：超时或回执写入失败不能证明对象未存储。这些记录仅在本地，不防篡改，也不会自动备份；每次发布应将它们与构建证据一同归档到受控存储。公网 CDN 回读仍是单独的发布验收，上传结果明确标记为 `not-performed`。
 
 Windows 操作人员可以在仓库外保存 CLIXML 对象，其中 `SecretId` 和 `SecretKey` 是经 DPAPI 加密的 SecureString 字段。[凭据启动器](scripts/upload-with-credentials.ps1)要求显式提供 `-CredentialFile` 和 `-Environment production` 或 `test`；不指定 `-Upload` 时，只验证解密以及向本地 Node 子进程注入凭据，不发起网络请求。它要求 `PATH` 中有 Node，并使用加密该文件时的 Windows 用户和机器。明文、空字段及纯空白字段都会失败。父进程环境保持不变；子进程先清除无关密钥与 Node 预加载选项，再仅接收所选 COS 凭据对。原始子进程 stderr 不会显示，stdout 中的凭据值会被遮盖。此检查不能证明 COS 授权有效。显式上传还要求 `-Upload -Target <target> -Bucket <bucket>` 及下述常规发布完成前提；真实云端上传仍需发布操作人员验收。此启动器支持长期密钥，不支持 STS 凭据。显式上传要求所选部署环境和 bucket 与目标 dotenv 文件及已完成的打包记录一致，才会发起网络写入；即使 dotenv 文件含有其他 COS 密钥，也使用 DPAPI 凭据对。
 
-`DSH_DESKTOP_AUTO_UPDATE_ENV` 同时选择打包写入的 URL 与后续 COS 上传环境，可取 `test` 或 `production`；缺省为 `test`。测试打包通过 `DOWNLOAD_TEST_ORIGIN` 提供 HTTPS origin；生产使用 `https://download.deepseek.com`。上传通过 `DOWNLOAD_TEST_COS_BUCKET` 或 `DOWNLOAD_PROD_COS_BUCKET` 提供所选 bucket。清单目录为 `dsh-desk/feeds/<target>/`；带版本的安装包和 blockmap 位于 `dsh-desk/bin/<target>/`。目标为 `mac-arm64`、`mac-x64` 和 `win-x64`。
+`DSH_DESKTOP_AUTO_UPDATE_ENV` 同时选择打包写入的 URL 与后续 COS 上传环境，可取 `test` 或 `production`；缺省为 `test`。测试打包通过 `DOWNLOAD_TEST_ORIGIN` 提供 HTTPS origin；生产使用 `https://download.deepseek.com`。上传通过 `DOWNLOAD_TEST_COS_BUCKET` 或 `DOWNLOAD_PROD_COS_BUCKET` 提供所选 bucket。生产清单位于 `dsh-desk/feeds/<target>/`，安装包位于 `dsh-desk/bin/<target>/`。测试发布必须配置 `DOWNLOAD_TEST_RELEASE_ID`：32 位小写十六进制字符，分别插入路径 `dsh-desk/<release-id>/feeds/<target>/` 和 `dsh-desk/<release-id>/bin/<target>/`。YAML 引用、稳定通道别名和 blockmap 都位于该发布目录内。目标为 `mac-arm64`、`mac-x64` 和 `win-x64`。
 
 更新目标与上传凭据都与所选环境对应：
 
@@ -173,6 +179,14 @@ Windows 操作人员可以在仓库外保存 CLIXML 对象，其中 `SecretId` 
 | `test` 或未设置 | `DOWNLOAD_TEST_ORIGIN` | `DOWNLOAD_TEST_COS_BUCKET` | `DOWNLOAD_TEST_COS_SECRET_ID`、`DOWNLOAD_TEST_COS_SECRET_KEY` |
 | `production` | `https://download.deepseek.com` | `DOWNLOAD_PROD_COS_BUCKET` | `DOWNLOAD_PROD_COS_SECRET_ID`、`DOWNLOAD_PROD_COS_SECRET_KEY` |
 
+每个测试发布批次用下方命令生成新 ID，将输出填入 `.env.macos` 或 `.env.windows` 的 `DOWNLOAD_TEST_RELEASE_ID`。这两个被 Git 忽略的平台文件管理该值，shell 变量不能覆盖它，dotenv 值也不会进行 shell 展开。打包、上传和重试必须沿用同一个 ID；上传会拒绝更新 URL 不一致的完成记录。需要验证跨版本升级时，后续版本沿用已安装客户端的 ID。生产环境不使用该字段。
+
+```sh
+node --input-type=module -e "import { randomBytes } from 'node:crypto'; console.log(randomBytes(16).toString('hex'))"
+```
+
+通过完整下载链接分发每个测试批次。已安装的测试客户端保留当前批次的清单地址，不会自动发现新 ID。格式校验无法判断随机性，请使用生成器的输出。随机路径降低被猜中的概率，不限制持有链接者访问；撤下批次需要删除其 COS 对象并清除对应 CDN 目录缓存。
+
 在目标 `.env` 中配置更新地址与所选 COS bucket、SecretId、SecretKey，再打包并上传同一个目标：
 
 ```sh
@@ -232,7 +246,9 @@ Windows 打包使用 Visual C++ Build Tools 和 Windows SDK 编译 x86 Win32/GDI
 
 预检、主要运行时签名、应用运行时签名和产物生成分别持有账户级签名阶段锁，直到受监督的子进程结束。其他构建进入这些阶段前等待；编译和准备步骤不持锁。运行时签名进程自行持锁，因此仅终止外层打包进程不会释放仍在访问缓存的阶段锁。迁移及维护获取同一把锁；旧版或外部签名命令不参与排队，应另行避免并发。阶段等待不计入预检期限。关闭阶段句柄会释放普通竞争锁，不删除独立的硬件尝试互锁；遗留硬件失败仍需操作人员恢复。
 
-每个运行时阶段向标准输出及打包日志写入 `SIGNATURE_CACHE_SUMMARY`，包含实际目录、策略标识、命中及未命中数、新发布及保留项数、签名请求数、省去的签名请求数和验证失败数。计时区分签名、恢复文件和新签名文件的信任验证及恢复；恢复耗时包含其信任检查和暂存清理。这些统计不包含预检、最终产物签名及外层运行时验签。阶段锁事件单独记录等待时间。
+缓存命中的复制、摘要和逐文件信任检查使用 `.env.windows` 中的 `DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY` 个工作任务（默认 `4`，整数 `1`–`8`）。所有恢复及后置验签完成后，未命中项才进入串行硬件签名。恢复或验签失败会停止派发新任务，并在释放阶段锁前等待在途工作结束；硬件签名、运行时 smoke 检查和最终完整性校验仍须执行。
+
+每个运行时阶段向标准输出及打包日志写入 `SIGNATURE_CACHE_SUMMARY`，包含实际目录、策略标识、命中及未命中数、新发布及保留项数、签名请求数、省去的签名请求数和验证失败数。计时区分签名、恢复文件和新签名文件的信任验证及恢复；恢复耗时包含其信任检查和暂存清理。这些统计不包含预检、最终产物签名及外层运行时验签。阶段锁事件单独记录等待时间。 并发计时累加逐文件工作耗时，不代表阶段墙钟时间。
 
 使用 `pnpm --dir apps/desktop run cache:windows-signatures --usage` 查看结构完整的缓存项字节数和数量，或用 `--from <absolute-old-cache>` 导入显式指定、属于同账户的旧缓存。迁移不修改源目录，跳过暂存名称，拒绝损坏项，并保留已有有效项，即使它们的时间戳字节不同。`--clear` 在阶段锁保护下显式删除完整缓存项；不执行自动容量淘汰。`--directory <absolute-cache>` 指定维护目标目录，无需加载发布凭据。不完整暂存项保持原状并单独计数；仅在所有构建停止后检查它们。这些命令绝不清除硬件失败证据。默认存储位于 AppData 之外，避免 MSIX 启动器虚拟化将账户缓存拆开；被重定向的覆盖目录会明确失败。
 
@@ -320,7 +336,7 @@ macOS 打包在组装 App 时、代码签名前写入 `Contents/Resources/app-up
 
 登录和策略请求共用内存 Session，与产品窗口及 updater 隔离；应用重启后需要重新登录。关闭窗口取消登录，导航失败提供本地化重试提示。返回服务后重新查询策略；重定向、Cookie 或 HTTP 422 都不是有效策略决定。取消、登录过期及无效响应均保留已知强更阻塞。固定登录结果写入进程诊断及可选更新日志；登录控制器不记录 Cookie、OAuth 参数或远程错误原文。真实 Harness 网关/API 联调及 macOS 登录验收仍未完成。
 
-扁平化的 `40005` 打开壳拥有的模态窗口，并拒绝后续插件修改，不停止现有 Host 任务。服务端标题与详情是可选纯文本，缺失时使用客户端兜底文案；缺少下载地址或地址未获批准时隐藏外部页面操作，不解除阻塞。macOS 强更蒙层原位渐入渐出，在更新状态切换时保留蒙层，并将父窗口焦点和键盘输入重定向到蒙层。Windows 强更窗口使用原生标题栏，可拖动、调整大小和最大化。关闭窗口会在完成清理后退出应用，不会解除更新要求；Esc 不会关闭窗口。批准安装后，安装器接管的退出流程会在 Electron 关闭窗口前释放模态窗口。下载、含准备步骤的文件校验、任务检查和安装确认共用同一弹窗。只有第二次用户批准才允许任务收尾和安装；稍后更新保留阻塞与安装包。仅存在受影响任务时，重启文案才提示正在停止任务。策略不跨应用重启持久化，策略响应也不作废或替换 updater 产物。
+扁平化的 `40005` 打开壳拥有的模态窗口，并拒绝后续插件修改，不停止现有 Host 任务。服务端标题与详情是可选纯文本，缺失时使用客户端兜底文案；缺少下载地址或地址未获批准时隐藏外部页面操作，不解除阻塞。macOS 强更蒙层原位渐入渐出，在更新状态切换时保留蒙层，并将父窗口焦点和键盘输入重定向到蒙层。Windows 由隔离的应用 preload 在主窗口内挂载 shell 来源的 frame，以蒙层和弹窗覆盖 40 DIP 顶栏下方的内容区域。它阻止背景页面输入，不创建额外的原生窗口；移动和最大化只作用于主窗口。父窗口保持启用，原生移动、缩放、最小化、最大化和关闭控件仍可操作。退出应用会完成清理，不会解除更新要求；Esc 不会关闭覆盖层。批准安装后，安装器接管的退出流程会在 Electron 关闭窗口前释放模态窗口。下载、含准备步骤的文件校验、任务检查和安装确认共用同一弹窗。只有第二次用户批准才允许任务收尾和安装；稍后更新保留阻塞与安装包。仅存在受影响任务时，重启文案才提示正在停止任务。策略不跨应用重启持久化，策略响应也不作废或替换 updater 产物。
 
 失败时在同一弹窗内保留阻塞、本地化重试提示和折叠诊断。白名单下载页面操作只在恢复状态出现，不与正常下载或安装并列。请求打开浏览器后立即提供复制替代入口，即使系统请求尚未返回；请求成功不证明网页已打开。复制失败时展示完整、只读的地址供手动复制。浏览器与剪贴板结果不覆盖 updater 错误。只有新的有效无需强更响应才解除阻塞；阻塞期间仍可使用顶部菜单检查。
 
diff --git a/apps/desktop/electron-builder.config.d.mts b/apps/desktop/electron-builder.config.d.mts
index f7cfd63f42..632250119b 100644
--- a/apps/desktop/electron-builder.config.d.mts
+++ b/apps/desktop/electron-builder.config.d.mts
@@ -21,6 +21,7 @@ export interface DesktopElectronBuilderConfig {
     { readonly from: string, readonly to: 'icon.png' },
   ]
   readonly mac: {
+    readonly extendInfo: { readonly NSMicrophoneUsageDescription: string }
     readonly identity: string | undefined
     readonly forceCodeSigning: boolean
     readonly notarize: boolean
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index bd93859ecd..e9850c256e 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -41,6 +41,8 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings-general": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar-browser": "workspace:^",
     "@deepseek-ai/dsh-home-paths": "workspace:^",
     "@deepseek-ai/node-addon-system": "workspace:^",
     "@electron/get": "^5.1.0",
@@ -53,11 +55,9 @@
     "electron": "^44.0.0",
     "electron-builder": "^26.15.3",
     "extract-zip": "^2.0.1",
-    "fflate": "^0.8.2",
     "js-yaml": "^4.2.0",
     "koffi": "^3.1.0",
     "pnpm": "11.7.0",
-    "tar": "^7.5.0",
     "typescript": "^6.0.3"
   }
 }
diff --git a/apps/desktop/renderer/mandatory-update-frame.js b/apps/desktop/renderer/mandatory-update-frame.js
new file mode 100644
index 0000000000..098059e237
--- /dev/null
+++ b/apps/desktop/renderer/mandatory-update-frame.js
@@ -0,0 +1,42 @@
+/** The embedded shell page delegates actions only to its owning application preload. */
+if (window.parent !== window && window.dshMandatoryUpdate === undefined) {
+  let state
+  let port
+  let sequence = 0
+  const listeners = new Set()
+  const requests = new Map()
+  const initial = Promise.withResolvers()
+  const receive = event => {
+    const message = event.data
+    if (message?.type === 'dsh-mandatory-state' && message.state) {
+      state = message.state
+      initial.resolve(state)
+      for (const listener of listeners) listener(state)
+    }
+    if (message?.type === 'dsh-mandatory-result') {
+      const request = requests.get(message.id)
+      if (!request) return
+      requests.delete(message.id)
+      if (message.ok) request.resolve()
+      else request.reject(new Error('Update action failed'))
+    }
+  }
+  window.addEventListener('message', event => {
+    if (!event.isTrusted || event.source !== window.parent || event.origin !== 'dsh-app://app'
+      || event.data?.type !== 'dsh-mandatory-connect' || event.ports.length !== 1 || port) return
+    port = event.ports[0]
+    port.onmessage = receive
+  })
+  window.addEventListener('pagehide', () => { port?.close() }, { once: true })
+  window.dshMandatoryUpdate = {
+    status: () => state ? Promise.resolve(state) : initial.promise,
+    subscribe: listener => { listeners.add(listener); return () => listeners.delete(listener) },
+    action: (action, version, revision) => {
+      const id = ++sequence
+      const request = Promise.withResolvers()
+      requests.set(id, request)
+      port.postMessage({ type: 'dsh-mandatory-action', id, action, version, revision })
+      return request.promise
+    },
+  }
+}
diff --git a/apps/desktop/renderer/mandatory-update.html b/apps/desktop/renderer/mandatory-update.html
index 673c5d0953..f009ab8a37 100644
--- a/apps/desktop/renderer/mandatory-update.html
+++ b/apps/desktop/renderer/mandatory-update.html
@@ -32,6 +32,7 @@
         <label id="manual-copy" hidden><span id="address-label"></span><textarea id="address" readonly rows="3" spellcheck="false"></textarea></label>
       </div>
     </main>
+    <script src="mandatory-update-frame.js"></script>
     <script src="mandatory-update.js"></script>
   </body>
 </html>
diff --git a/apps/desktop/scripts/desktop-auto-update-environment.d.mts b/apps/desktop/scripts/desktop-auto-update-environment.d.mts
index b1661646e5..00ebf8c5c0 100644
--- a/apps/desktop/scripts/desktop-auto-update-environment.d.mts
+++ b/apps/desktop/scripts/desktop-auto-update-environment.d.mts
@@ -7,13 +7,14 @@ export type DesktopAutoUpdateEnvironment = 'test' | 'production'
 /** Directory name of one supported Desktop release target. */
 export type DesktopAutoUpdateTarget = 'mac-arm64' | 'mac-x64' | 'win-x64'
 
-/** Public updater URL for one release target. */
+/** Public updater URL and object prefixes for one release target. */
 export interface DesktopAutoUpdateConfig {
   readonly environment: DesktopAutoUpdateEnvironment
   readonly target: DesktopAutoUpdateTarget
   readonly origin: string
   readonly publicUrl: string
   readonly keyPrefix: string
+  readonly binaryKeyPrefix: string
 }
 
 /** Public updater URL and private COS destination for one upload target. */
@@ -62,12 +63,12 @@ export function desktopUpdateMetadataFilename(
 ): string
 
 /**
- * Resolve the public updater URL for one release target.
+ * Resolve the public updater URL and object prefixes for one release target.
  * @param env - Packaging or upload environment.
  * @param platform - Target Node.js platform.
  * @param arch - Target Node.js architecture.
  * @returns Resolved updater configuration.
- * @throws When the test deployment lacks a valid HTTPS origin.
+ * @throws When the test deployment lacks a valid HTTPS origin or a 32-character lowercase hexadecimal release ID.
  */
 export function resolveDesktopAutoUpdateConfig(
   env: NodeJS.ProcessEnv,
@@ -81,7 +82,7 @@ export function resolveDesktopAutoUpdateConfig(
  * @param platform - Target Node.js platform.
  * @param arch - Target Node.js architecture.
  * @returns Resolved upload configuration.
- * @throws When the selected deployment lacks a required origin or bucket, or the test origin is not HTTPS.
+ * @throws When the selected deployment lacks a bucket or valid updater configuration.
  */
 export function resolveDesktopUploadConfig(
   env: NodeJS.ProcessEnv,
diff --git a/apps/desktop/scripts/desktop-auto-update-environment.mjs b/apps/desktop/scripts/desktop-auto-update-environment.mjs
index eebd20156a..464d079b4d 100644
--- a/apps/desktop/scripts/desktop-auto-update-environment.mjs
+++ b/apps/desktop/scripts/desktop-auto-update-environment.mjs
@@ -120,12 +120,12 @@ function httpsOrigin(value, name) {
 }
 
 /**
- * Resolve the public updater URL for one release target.
+ * Resolve the public updater URL and object prefixes for one release target.
  * @param {NodeJS.ProcessEnv} env - Packaging or upload environment.
  * @param {NodeJS.Platform} platform - Target Node.js platform.
  * @param {string} arch - Target Node.js architecture.
- * @returns {{ environment: 'test' | 'production', target: 'mac-arm64' | 'mac-x64' | 'win-x64', origin: string, publicUrl: string, keyPrefix: string }} Resolved updater configuration.
- * @throws {Error} When the test deployment lacks a valid HTTPS origin.
+ * @returns {{ environment: 'test' | 'production', target: 'mac-arm64' | 'mac-x64' | 'win-x64', origin: string, publicUrl: string, keyPrefix: string, binaryKeyPrefix: string }} Resolved updater configuration.
+ * @throws {Error} When the test deployment lacks a valid HTTPS origin or a 32-character lowercase hexadecimal release ID.
  */
 export function resolveDesktopAutoUpdateConfig(env, platform, arch) {
   const environment = resolveDesktopAutoUpdateEnvironment(env)
@@ -137,12 +137,21 @@ export function resolveDesktopAutoUpdateConfig(env, platform, arch) {
     if (originEnvName === undefined) throw new Error('desktop auto-update: selected deployment has no origin')
     origin = httpsOrigin(requiredEnvironmentValue(env, originEnvName), originEnvName)
   }
-  const keyPrefix = `dsh-desk/feeds/${target}`
+  let releasePrefix = 'dsh-desk'
+  if (environment === 'test') {
+    const releaseId = requiredEnvironmentValue(env, 'DOWNLOAD_TEST_RELEASE_ID')
+    if (!/^[a-f0-9]{32}$/u.test(releaseId)) {
+      throw new Error('desktop auto-update: DOWNLOAD_TEST_RELEASE_ID must contain 32 lowercase hexadecimal characters')
+    }
+    releasePrefix += `/${releaseId}`
+  }
+  const keyPrefix = `${releasePrefix}/feeds/${target}`
   return {
     environment,
     target,
     origin,
     keyPrefix,
+    binaryKeyPrefix: `${releasePrefix}/bin/${target}`,
     publicUrl: `${origin}/${keyPrefix}/`,
   }
 }
@@ -152,8 +161,8 @@ export function resolveDesktopAutoUpdateConfig(env, platform, arch) {
  * @param {NodeJS.ProcessEnv} env - Upload environment.
  * @param {NodeJS.Platform} platform - Target Node.js platform.
  * @param {string} arch - Target Node.js architecture.
- * @returns {{ environment: 'test' | 'production', target: 'mac-arm64' | 'mac-x64' | 'win-x64', origin: string, publicUrl: string, keyPrefix: string, bucket: string, secretIdEnvName: string, secretKeyEnvName: string }} Resolved upload configuration.
- * @throws {Error} When the selected deployment lacks a required origin or bucket, or the test origin is not HTTPS.
+ * @returns {{ environment: 'test' | 'production', target: 'mac-arm64' | 'mac-x64' | 'win-x64', origin: string, publicUrl: string, keyPrefix: string, binaryKeyPrefix: string, bucket: string, secretIdEnvName: string, secretKeyEnvName: string }} Resolved upload configuration.
+ * @throws {Error} When the selected deployment lacks a bucket or valid updater configuration.
  */
 export function resolveDesktopUploadConfig(env, platform, arch) {
   const update = resolveDesktopAutoUpdateConfig(env, platform, arch)
diff --git a/apps/desktop/scripts/desktop-package-environment.mjs b/apps/desktop/scripts/desktop-package-environment.mjs
index c8a794e3c7..71dd9a6655 100644
--- a/apps/desktop/scripts/desktop-package-environment.mjs
+++ b/apps/desktop/scripts/desktop-package-environment.mjs
@@ -10,10 +10,11 @@ import { createWindowsTokenSigner } from './windows-sign.mjs'
 import { resolveDesktopPolicyEnvironment } from './desktop-policy-environment.mjs'
 import { resolveMacOSPackageSettings } from './macos-package-settings.mjs'
 import { resolveWindowsSignatureCacheDirectory } from './windows-signature-cache-directory.mjs'
+import { resolveWindowsPackageSettings } from './windows-package-settings.mjs'
 
 const APP_ROOT = fileURLToPath(new URL('..', import.meta.url))
-const SHARED_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|MANDATORY_UPDATE_(?:CONFIG|(?:TEST|PROD)_ORIGIN))|DOWNLOAD_(?:TEST|PROD)_(?:ORIGIN|COS_BUCKET|COS_SECRET_ID|COS_SECRET_KEY))$/u
-const WINDOWS_SETTING = /^DSH_DESKTOP_WINDOWS_(?:CER_FILE|SIGNTOOL|KEY_CONTAINER|TOKEN_PIN|SIGNATURE_CACHE_DIR)$/u
+const SHARED_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|MANDATORY_UPDATE_(?:CONFIG|(?:TEST|PROD)_ORIGIN))|DOWNLOAD_TEST_RELEASE_ID|DOWNLOAD_(?:TEST|PROD)_(?:ORIGIN|COS_BUCKET|COS_SECRET_ID|COS_SECRET_KEY))$/u
+const WINDOWS_SETTING = /^DSH_DESKTOP_WINDOWS_(?:CER_FILE|SIGNTOOL|KEY_CONTAINER|TOKEN_PIN|SIGNATURE_CACHE_DIR|SIGNATURE_CACHE_CONCURRENCY)$/u
 const MACOS_SETTING = /^(?:DSH_DESKTOP_MACOS_(?:SIGNING_IDENTITY|TEAM_ID|PACK_CONCURRENCY|DOWNLOAD_PROXY|NOTARIZATION_PROXY)|APPLE_(?:API_KEY|API_KEY_ID|API_ISSUER|ID|APP_SPECIFIC_PASSWORD|TEAM_ID|KEYCHAIN|KEYCHAIN_PROFILE)|CSC_(?:LINK|KEY_PASSWORD))$/u
 const AMBIENT_RELEASE_SETTING = /^(?:DSH_DESKTOP_(?:APP_ID|AUTO_UPDATE_ENV|MANDATORY_UPDATE_.*|WINDOWS_.*|MACOS_.*)|APPLE_.*|(?:WIN_)?CSC_.*|DOWNLOAD_(?:TEST|PROD)_.*)$/iu
 const FILE_SETTINGS = ['DSH_DESKTOP_WINDOWS_CER_FILE', 'DSH_DESKTOP_WINDOWS_SIGNTOOL', 'APPLE_API_KEY', 'APPLE_KEYCHAIN', 'CSC_LINK']
@@ -79,6 +80,7 @@ export function validateDesktopPackageEnvironment(environment, target, options =
   resolveDesktopAppId(environment)
   resolveDesktopPolicyEnvironment(environment)
   if (target.platform === 'darwin') resolveMacOSPackageSettings(environment)
+  else resolveWindowsPackageSettings(environment)
   if (options.unsigned) return
   if (!options.prepareOnly) resolveDesktopAutoUpdateConfig(environment, target.platform, target.arch)
   if (target.platform === 'win32') {
diff --git a/apps/desktop/scripts/desktop-upload-plan.ts b/apps/desktop/scripts/desktop-upload-plan.ts
index 0ec76dba3a..32f891dcc8 100644
--- a/apps/desktop/scripts/desktop-upload-plan.ts
+++ b/apps/desktop/scripts/desktop-upload-plan.ts
@@ -222,7 +222,7 @@ export async function createDesktopUploadPlan(
   const updaterInfo = updateFileInfo(metadata.files[0], `${metadataFilename}.files[0]`, `${base}.${updaterExtension}`)
   const updaterPath = await verifyChecksummedArtifact(artifactsRoot, updaterInfo)
   const artifacts: DesktopUploadArtifact[] = []
-  const binaryPrefix = `dsh-desk/bin/${targetName}`
+  const binaryPrefix = update.binaryKeyPrefix
 
   if (target.platform === 'darwin') {
     const dmgPath = await requireArtifact(artifactsRoot, `${base}.dmg`)
diff --git a/apps/desktop/scripts/electron-builder-config.mjs b/apps/desktop/scripts/electron-builder-config.mjs
index cf2f76768f..3f469c3be2 100644
--- a/apps/desktop/scripts/electron-builder-config.mjs
+++ b/apps/desktop/scripts/electron-builder-config.mjs
@@ -126,9 +126,12 @@ export function createElectronBuilderConfig(
     mac: {
       icon: fileURLToPath(new URL('../resources/icon-macos.png', import.meta.url)),
       category: 'public.app-category.developer-tools',
+      // macOS matches the application locale against this bundle, not Electron Framework resources.
+      extendInfo: { CFBundleLocalizations: ['en', 'zh_CN'] },
       identity: macOSSigning?.signingIdentity,
       forceCodeSigning: true,
       hardenedRuntime: true,
+      extendInfo: { NSMicrophoneUsageDescription: 'DeepSeek Harness uses your microphone to transcribe speech into message drafts.' },
       // ASAR-unpacked native runtime files are pre-signed; PAK resources are sealed by their enclosing bundle.
       signIgnore: ['/Contents/Resources/app\\.asar\\.unpacked/dsh(?:/|$)', '/Contents/Resources/runtime/primary-runtime(?:/|$)', '\\.pak$'],
       notarize: true,
diff --git a/apps/desktop/scripts/package-target.ts b/apps/desktop/scripts/package-target.ts
index 651bd64cce..688d3d9671 100644
--- a/apps/desktop/scripts/package-target.ts
+++ b/apps/desktop/scripts/package-target.ts
@@ -30,6 +30,7 @@ const WINDOWS_SIGNING_ENV_NAMES = [
   'DSH_DESKTOP_WINDOWS_SIGNTOOL',
   'DSH_DESKTOP_WINDOWS_TOKEN_PIN',
   'DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_DIR',
+  'DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY',
 ] as const
 const DESKTOP_UPLOAD_CREDENTIAL_ENV_NAMES = new Set([
   'DOWNLOAD_TEST_COS_SECRET_ID',
diff --git a/apps/desktop/scripts/prepare-primary-runtime.ts b/apps/desktop/scripts/prepare-primary-runtime.ts
index 9163db1234..44484baefc 100644
--- a/apps/desktop/scripts/prepare-primary-runtime.ts
+++ b/apps/desktop/scripts/prepare-primary-runtime.ts
@@ -1,171 +1,35 @@
-/** Prepare pinned, relocatable script interpreters without installing into the build host. */
+/** Desktop resource locations and signing-aware verification for the shared runtime builder. */
 
-import { execFileSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { cp } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import { tmpdir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
-import extractZip from 'extract-zip'
-import { x as extractTar } from 'tar'
-import { workspaceDependencyPaths, type PrimaryRuntimeManifest } from '../../desktop-host/src/primary-runtime.ts'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { preparePrimaryRuntime as preparePayload, smokePrimaryRuntime as smokePayload } from '../../../scripts/primary-runtime/prepare.ts'
+import { parsePrimaryRuntime, workspaceDependencyPaths } from '../../../packages/skill/tool-workspace-dependencies/src/index.ts'
 import { resolveDesktopBuildTarget, resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs'
 import { scrubWindowsSigningEnvironment } from './windows-sign.mjs'
-import lock from './primary-runtime-lock.json' with { type: 'json' }
 
 /**
- * Download or reuse an archive only when its bytes match the release lock.
- * @param url - Locked archive URL.
- * @param sha256 - Expected SHA-256 digest.
- * @param cache - Download cache directory.
- * @returns Verified local archive path.
- */
-export async function downloadPrimaryRuntimeAsset(url: string, sha256: string, cache: string): Promise<string> {
-  const destination = join(cache, sha256)
-  let bytes: Buffer
-  try { bytes = readFileSync(destination) } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-    const response = await fetch(url)
-    if (!response.ok) throw new Error(`primary runtime download: ${String(response.status)} ${url}`)
-    bytes = Buffer.from(await response.arrayBuffer())
-  }
-  if (createHash('sha256').update(bytes).digest('hex') !== sha256) throw new Error(`primary runtime download: checksum mismatch for ${url}`)
-  writeFileSync(destination, bytes)
-  return destination
-}
-
-async function pythonArchive(target: keyof typeof lock.targets, cache: string): Promise<string> {
-  const artifact = lock.targets[target]
-  const filename = `cpython-${lock.pythonVersion}+${lock.pythonRelease}-${artifact.pythonTarget}-install_only_stripped.tar.gz`
-  return downloadPrimaryRuntimeAsset(`https://github.com/astral-sh/python-build-standalone/releases/download/${lock.pythonRelease}/${encodeURIComponent(filename)}`, artifact.pythonSha256, cache)
-}
-
-/**
- * Identify the inputs that assemble one target's payload, excluding unrelated target locks.
- * @param target - Desktop target whose archives are installed.
- * @param runtimeLock - Locked interpreter and wheel inputs.
- * @param pnpmVersion - Package-manager version copied into the payload.
- * @returns SHA-256 payload identity for installation reuse.
- */
-export function primaryRuntimePayloadDigest(target: keyof typeof lock.targets, runtimeLock: typeof lock, pnpmVersion: string): string {
-  const { pythonVersion, pythonRelease, nodeVersion, wheels, pythonPackages } = runtimeLock
-  // Identity preserves key order within the selected target, wheel records and distribution map, plus wheel-entry order.
-  // Bump format when extraction or assembly changes payload bytes without changing locked inputs.
-  return createHash('sha256').update(JSON.stringify({
-    format: 2, target, pythonVersion, pythonRelease, nodeVersion,
-    artifact: runtimeLock.targets[target], wheels, pythonPackages, pnpm: pnpmVersion,
-  })).digest('hex')
-}
-
-/**
- * Unpack a locked library wheel, retaining auxiliary scripts in its distribution data directory.
- * @param archive - Hash-verified wheel archive.
- * @param destination - Absolute site-packages directory.
- * @returns Resolves after extraction without command wrappers; rejects other wheel installation schemes.
- */
-export async function unpackPrimaryRuntimeWheel(archive: string, destination: string): Promise<void> {
-  await extractZip(archive, {
-    dir: destination,
-    onEntry: (entry) => {
-      const [directory, scheme] = entry.fileName.split('/')
-      if (directory?.endsWith('.data') && scheme !== '' && scheme !== 'scripts') {
-        throw new Error(`primary runtime: wheel requires unsupported installation paths: ${entry.fileName}`)
-      }
-    },
-  })
-}
-
-/**
- * Copy the skill package's complete asset tree to ordinary filesystem resources.
- * @param source - The package's assets directory.
- * @param destination - Desktop runtime resource directory outside ASAR.
- * @returns Resolves after replacing the external assets with the complete package tree.
- */
-export async function prepareOfficeSkillAssets(source: string, destination: string): Promise<void> {
-  rmSync(destination, { recursive: true, force: true })
-  await cp(source, destination, { recursive: true, dereference: true })
-}
-
-/**
- * Materialize the selected Desktop target's primary runtime in its build resources.
+ * Prepare Desktop resources for its selected packaging target.
  * @param options - Signed Windows packaging defers execution until its supervised signing stage.
- * @returns Resolves after materialization and, unless deferred, native-target execution checks.
+ * @returns Resolves after preparation and, unless deferred, native-target execution checks.
  */
 export async function preparePrimaryRuntime(options: { deferSmoke?: boolean } = {}): Promise<void> {
-  const target = resolveDesktopBuildTarget()
   const paths = resolveDesktopTargetBuildPaths()
-  const artifact = lock.targets[target]
-  mkdirSync(paths.runtime, { recursive: true })
-  mkdirSync(paths.downloads, { recursive: true })
-  const staging = mkdtempSync(join(tmpdir(), 'dsh-primary-'))
-  try {
-    const output = join(staging, 'payload')
-    const dependencies = join(output, 'dependencies')
-    mkdirSync(dependencies, { recursive: true })
-    const nodeFilename = `node-v${lock.nodeVersion}-${artifact.nodeArchive}`
-    const nodeArchive = await downloadPrimaryRuntimeAsset(`https://nodejs.org/dist/v${lock.nodeVersion}/${nodeFilename}`, artifact.nodeSha256, paths.downloads)
-    const unpackedNode = join(staging, 'node')
-    mkdirSync(unpackedNode)
-    if (target === 'win-x64') await extractZip(nodeArchive, { dir: unpackedNode })
-    else await extractTar({ file: nodeArchive, cwd: unpackedNode })
-    const nodeSource = join(unpackedNode, nodeFilename.replace(/\.(?:zip|tar\.gz)$/u, ''))
-    mkdirSync(join(dependencies, 'node', 'bin'), { recursive: true })
-    mkdirSync(join(dependencies, 'node', 'node_modules'))
-    writeFileSync(join(dependencies, 'node', 'node_modules', 'README.txt'), 'Reserved for bundled Node packages. pnpm uses its default installation directories.\n')
-    cpSync(join(nodeSource, ...(target === 'win-x64' ? ['node.exe'] : ['bin', 'node'])),
-      join(dependencies, 'node', 'bin', target === 'win-x64' ? 'node.exe' : 'node'))
-    cpSync(join(nodeSource, 'LICENSE'), join(dependencies, 'node', 'LICENSE'))
-    await extractTar({ file: await pythonArchive(target, paths.downloads), cwd: dependencies })
-    const require = createRequire(import.meta.url)
-    const pnpmManifest = require.resolve('pnpm')
-    const pnpm = JSON.parse(readFileSync(pnpmManifest, 'utf8')) as { version: string }
-    await cp(dirname(pnpmManifest), join(dependencies, 'pnpm'), { recursive: true, dereference: true })
-    const desktop = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8')) as { version: string }
-    const manifest: PrimaryRuntimeManifest = {
-      desktopVersion: desktop.version,
-      platform: target === 'win-x64' ? 'win32' : 'darwin',
-      arch: target === 'mac-arm64' ? 'arm64' : 'x64',
-      payloadDigest: primaryRuntimePayloadDigest(target, lock, pnpm.version),
-      pythonPackages: lock.pythonPackages,
-      components: {
-        python: lock.pythonVersion, node: lock.nodeVersion, pnpm: pnpm.version,
-        numpy: lock.pythonPackages.numpy, pandas: lock.pythonPackages.pandas,
-      },
-    }
-    const entries = workspaceDependencyPaths(output, manifest)
-    for (const wheel of [...artifact.wheels, ...lock.wheels]) {
-      await unpackPrimaryRuntimeWheel(await downloadPrimaryRuntimeAsset(wheel.url, wheel.sha256, paths.downloads), entries.pythonPackages)
-    }
-    writeFileSync(join(output, 'runtime.json'), `${JSON.stringify(manifest, undefined, 2)}\n`)
-    const destination = join(paths.runtime, 'primary-runtime')
-    rmSync(destination, { recursive: true, force: true })
-    await cp(output, destination, { recursive: true, dereference: true })
-  } finally {
-    rmSync(staging, { recursive: true, force: true })
-  }
-  const hostRequire = createRequire(resolve(import.meta.dirname, '..', '..', 'desktop-host', 'package.json'))
-  await prepareOfficeSkillAssets(join(dirname(hostRequire.resolve('@deepseek-ai/dsh-skill-office/package.json')), 'assets'),
-    join(paths.runtime, 'office-skills'))
+  const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }
+  await preparePayload({ target: resolveDesktopBuildTarget(), output: paths.runtime, cache: paths.downloads, version })
   if (!options.deferSmoke) smokePrimaryRuntime(join(paths.runtime, 'primary-runtime'))
 }
 
 /**
- * Execute the native payload's interpreters, package manager and Python libraries.
+ * Verify Desktop's complete payload after preparation or platform signing.
  * @param root - Final payload directory, including any platform signatures.
  */
 export function smokePrimaryRuntime(root: string): void {
-  const manifest = JSON.parse(readFileSync(join(root, 'runtime.json'), 'utf8')) as PrimaryRuntimeManifest
+  const manifest = parsePrimaryRuntime(JSON.parse(readFileSync(join(root, 'runtime.json'), 'utf8')))
   if (manifest.platform !== process.platform || manifest.arch !== process.arch) return
-  if (manifest.pythonPackages === undefined) throw new Error('primary runtime: missing Python distribution versions; prepare the payload before running its smoke checks.')
+  if (Object.keys(manifest.pythonPackages).length === 0) throw new Error('primary runtime: missing Python distribution versions; prepare the payload before running its smoke checks.')
   const entries = workspaceDependencyPaths(root, manifest)
-  const options = { stdio: 'inherit', timeout: 120_000, env: scrubWindowsSigningEnvironment(process.env) } as const
-  execFileSync(entries.python, ['-I', '-c', 'import decimal, xml.parsers.expat, lzma, uuid, numpy, pandas; assert numpy.arange(4).sum() == 6; assert pandas.DataFrame({"n": [1, 2]}).n.sum() == 3'], options)
-  execFileSync(entries.python, ['-I', '-B', join(import.meta.dirname, 'smoke-primary-runtime.py'), JSON.stringify(manifest.pythonPackages),
-    manifest.components.python, join(dirname(root), 'office-skills', 'scripts', 'check_office.py')], options)
-  execFileSync(entries.python, ['-I', '-B', '-m', 'pip', 'check'], options)
-  execFileSync(entries.node, ['-e', `if (process.versions.node !== ${JSON.stringify(manifest.components.node)}) process.exit(1)`], options)
-  execFileSync(entries.node, [entries.pnpm, '--version'], options)
+  if (entries.node === undefined || entries.pnpm === undefined) throw new Error('primary runtime: the Desktop payload must declare node and pnpm components.')
+  smokePayload(root, scrubWindowsSigningEnvironment(process.env))
 }
 
 if (import.meta.main) await preparePrimaryRuntime()
diff --git a/apps/desktop/scripts/sign-primary-runtime.ts b/apps/desktop/scripts/sign-primary-runtime.ts
index d48711b4a0..d9a9b36c25 100644
--- a/apps/desktop/scripts/sign-primary-runtime.ts
+++ b/apps/desktop/scripts/sign-primary-runtime.ts
@@ -5,6 +5,7 @@ import { join, resolve } from 'node:path'
 import { createWindowsTokenSigner } from './windows-sign.mjs'
 import { inspectWindowsRuntimeSignature, signWindowsCode, type WindowsCodeSigningOptions } from './windows-runtime-signature.mjs'
 import { createCachedSigner, signatureCacheIdentity } from './windows-signature-cache.mjs'
+import { resolveWindowsPackageSettings } from './windows-package-settings.mjs'
 import { prepareWindowsSignatureCacheDirectory, resolveWindowsSignatureCacheDirectory } from './windows-signature-cache-directory.mjs'
 import { withWindowsSigningStage } from './windows-signing-stage.mjs'
 import { failPackagingRun, recordPackagingEvent } from './packaging-run.mjs'
@@ -46,6 +47,7 @@ export async function signWindowsDesktopRuntime(root: string, version: string,
 
 async function main(): Promise<void> {
   if (process.platform !== 'win32' || resolveDesktopBuildTarget() !== 'win-x64') throw new Error('primary runtime signing requires Windows x64')
+  const { signatureCacheConcurrency } = resolveWindowsPackageSettings(process.env)
   const runDirectory = process.env.DSH_DESKTOP_PACKAGING_RUN_DIR
   if (!runDirectory) throw new Error('primary runtime signing requires a supervised packaging run')
   await readFile(join(runDirectory, 'run.json'))
@@ -67,7 +69,8 @@ async function main(): Promise<void> {
       await prepareWindowsSignatureCacheDirectory(cacheRoot)
       const cachedSign = createCachedSigner({ root: cacheRoot, identity, thumbprint,
         sign, inspect: inspectWindowsRuntimeSignature, record })
-      const options = { thumbprint, sign: cachedSign, record }
+      const options = { thumbprint, sign: cachedSign, record,
+        cache: { restore: cachedSign.restore, concurrency: signatureCacheConcurrency } }
       record({ type: 'signature-cache-open', root: cachedSign.summary().root, identity })
       try {
         if (process.argv.includes('--dsh')) {
diff --git a/apps/desktop/scripts/test-workspace-updates.ts b/apps/desktop/scripts/test-workspace-updates.ts
index b768de5544..245007a7ab 100644
--- a/apps/desktop/scripts/test-workspace-updates.ts
+++ b/apps/desktop/scripts/test-workspace-updates.ts
@@ -43,6 +43,11 @@ try {
   for (const owner of [application, project]) {
     await symlink(join(repo, 'node_modules/.pnpm/node_modules'), join(owner, 'node_modules'), process.platform === 'win32' ? 'junction' : 'dir')
   }
+  const target = `${process.platform === 'darwin' ? 'mac' : 'win'}-${process.arch}`
+  const targetRoot = join(application, '.desktop-build/targets', target)
+  await mkdir(targetRoot, { recursive: true })
+  await symlink(join(repo, 'apps/desktop/.desktop-build/targets', target, 'runtime'), join(targetRoot, 'runtime'),
+    process.platform === 'win32' ? 'junction' : 'dir')
   await writeFile(join(profile, 'cordis.patch.yml'), JSON.stringify([
     { id: 'webserver', config: { host: '127.0.0.1', port: 0 } },
     { id: 'llm-deepseek', disabled: true }, { id: 'session-title-llm', disabled: true },
diff --git a/apps/desktop/scripts/windows-package-settings.d.mts b/apps/desktop/scripts/windows-package-settings.d.mts
new file mode 100644
index 0000000000..a7627e3b7d
--- /dev/null
+++ b/apps/desktop/scripts/windows-package-settings.d.mts
@@ -0,0 +1,6 @@
+/**
+ * Validate the file-owned Windows cache worker limit before packaging starts.
+ * @param environment Windows packaging settings loaded from .env.windows.
+ * @returns Worker limit from one to eight, defaulting to four when omitted; invalid values throw.
+ */
+export function resolveWindowsPackageSettings(environment: NodeJS.ProcessEnv): { signatureCacheConcurrency: number }
diff --git a/apps/desktop/scripts/windows-package-settings.mjs b/apps/desktop/scripts/windows-package-settings.mjs
new file mode 100644
index 0000000000..847849af97
--- /dev/null
+++ b/apps/desktop/scripts/windows-package-settings.mjs
@@ -0,0 +1,14 @@
+/** Resolve file-owned Windows signature-cache concurrency before packaging starts. */
+
+/**
+ * Validate the cache worker limit without accessing signing hardware.
+ * @param {NodeJS.ProcessEnv} environment File-owned Windows packaging settings.
+ * @returns {{signatureCacheConcurrency: number}} Worker limit, defaulting to four when omitted.
+ */
+export function resolveWindowsPackageSettings(environment) {
+  const value = environment.DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY ?? '4'
+  if (!/^[1-8]$/u.test(value)) {
+    throw new Error('desktop package: DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY must be an integer from 1 to 8')
+  }
+  return { signatureCacheConcurrency: Number(value) }
+}
diff --git a/apps/desktop/scripts/windows-runtime-signature.d.mts b/apps/desktop/scripts/windows-runtime-signature.d.mts
index 9c6e207a17..f47e306885 100644
--- a/apps/desktop/scripts/windows-runtime-signature.d.mts
+++ b/apps/desktop/scripts/windows-runtime-signature.d.mts
@@ -31,6 +31,11 @@ export interface WindowsCodeSigningOptions {
   sign: ReturnType<typeof import('./windows-sign.mjs').createWindowsTokenSigner>
   inspect?: typeof inspectWindowsRuntimeSignature
   record: (event: object) => void
+  /** Hardware-free restores on distinct targets; concurrency is a resolved positive integer. All restores and their verification drain before serial signing starts. */
+  cache?: {
+    restore: import('./windows-signature-cache.mjs').WindowsCachedSigner['restore']
+    concurrency: number
+  }
 }
 
 /**
@@ -44,7 +49,7 @@ export function windowsRuntimeCode(root: string): Promise<string[]>
  * Preserve valid signatures and sign unsigned PE files with a supervised signer.
  * @param root Materialized directory to sign.
  * @param options Signer, certificate identity and audit sink.
- * @returns Resolves after verified sequential signing; rejects without retries.
+ * @returns Resolves after verified parallel cache restores and sequential signing; stops dispatch and drains active restores on failure, without retries.
  */
 export function signWindowsCode(root: string, options: WindowsCodeSigningOptions): Promise<void>
 
diff --git a/apps/desktop/scripts/windows-runtime-signature.mjs b/apps/desktop/scripts/windows-runtime-signature.mjs
index ee70330fd7..8780f182ca 100644
--- a/apps/desktop/scripts/windows-runtime-signature.mjs
+++ b/apps/desktop/scripts/windows-runtime-signature.mjs
@@ -101,7 +101,7 @@ async function inspectWindowsCode(files, inspect) {
  * Preserve valid signatures and sign unsigned PE files with a supervised signer.
  * @param {string} root - Owned final runtime directory.
  * @param {import('./windows-runtime-signature.mjs').WindowsCodeSigningOptions} options - Supervised signer, certificate identity, audit sink.
- * @returns {Promise<void>} Resolves only after sequential signatures and verification; no retries.
+ * @returns {Promise<void>} Resolves after bounded cache restores and sequential hardware signing, each with verification; failures drain active restores before rejecting.
  */
 export async function signWindowsCode(root, options) {
   const inspect = options.inspect ?? inspectWindowsRuntimeSignature
@@ -116,14 +116,36 @@ export async function signWindowsCode(root, options) {
     else if (signature.status !== 'Valid') throw new Error(`Windows code: refusing ${signature.status} signature: ${path}`)
   }
   options.record({ type: 'windows-code-signing-plan', files: files.length, unsigned: unsigned.length })
-  for (const path of unsigned) {
-    await options.sign({ path, hash: 'sha256', isNest: false })
+  async function verifySigned(path) {
     const signature = await inspect(path)
     if (signature.status !== 'Valid' || !signature.timestamped || signature.thumbprint?.toUpperCase() !== options.thumbprint.toUpperCase()) {
       throw new Error(`Windows code: signing verification failed: ${path}`)
     }
     options.record({ type: 'windows-code-signature-verified', path, ...signature })
   }
+  const restored = new Set()
+  if (options.cache) {
+    let next = 0
+    let failure
+    const worker = async () => {
+      while (failure === undefined && next < unsigned.length) {
+        const path = unsigned[next++]
+        try {
+          if (await options.cache.restore({ path, hash: 'sha256', isNest: false })) {
+            await verifySigned(path)
+            restored.add(path)
+          }
+        } catch (error) { failure ??= { error } }
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(options.cache.concurrency, unsigned.length) }, worker))
+    if (failure !== undefined) throw failure.error
+  }
+  for (const path of unsigned) {
+    if (restored.has(path)) continue
+    await options.sign({ path, hash: 'sha256', isNest: false })
+    await verifySigned(path)
+  }
 }
 
 /**
diff --git a/apps/desktop/scripts/windows-signature-cache.d.mts b/apps/desktop/scripts/windows-signature-cache.d.mts
index e68abdf345..dcc2301371 100644
--- a/apps/desktop/scripts/windows-signature-cache.d.mts
+++ b/apps/desktop/scripts/windows-signature-cache.d.mts
@@ -18,7 +18,7 @@ export interface WindowsSignatureCacheOptions {
  */
 export function signatureCacheIdentity(files: readonly string[]): Promise<string>
 
-/** Counters include failed attempts; verification covers both restored and newly signed files, while restore time includes its verification and staging cleanup. */
+/** Counters include failed attempts; times sum per-file work. Verification covers restored and newly signed files; restore time includes its verification and staging cleanup. */
 export interface WindowsSignatureCacheSummary {
   root: string
   identity: string
@@ -34,8 +34,14 @@ export interface WindowsSignatureCacheSummary {
   signingMs: number
 }
 
-/** Serial cache callback with a snapshot of this instance's completed and failed operations. */
+/** Serial signing callback with a separate hardware-free restore operation and shared counters. */
 export type WindowsCachedSigner = ReturnType<typeof createWindowsTokenSigner> & {
+  /**
+   * Restore a hit without accessing hardware; distinct targets may run concurrently under the stage lock.
+   * @param configuration Unsigned target owned exclusively by the caller.
+   * @returns True after verified replacement, false for an absent entry without counting a signing miss; corrupt entries reject. The caller drains all restores before signing or reporting failure.
+   */
+  restore(configuration: Parameters<ReturnType<typeof createWindowsTokenSigner>>[0]): Promise<boolean>
   /** @returns Current counters and elapsed times; does not wait for queued operations. */
   summary(): WindowsSignatureCacheSummary
 }
@@ -43,7 +49,7 @@ export type WindowsCachedSigner = ReturnType<typeof createWindowsTokenSigner> &
 /**
  * Reuse complete signed files only after input, integrity, identity and timestamp checks.
  * @param options Cache policy, supervised signer, public-key verifier and audit sink.
- * @returns Serial signer that stops its queue on any failure and never repairs invalid cache entries.
+ * @returns Serial fail-stop signer with hardware-free restores; invalid cache entries are never repaired.
  */
 export function createCachedSigner(options: WindowsSignatureCacheOptions): WindowsCachedSigner
 
diff --git a/apps/desktop/scripts/windows-signature-cache.mjs b/apps/desktop/scripts/windows-signature-cache.mjs
index 1df9cd955f..39f75da374 100644
--- a/apps/desktop/scripts/windows-signature-cache.mjs
+++ b/apps/desktop/scripts/windows-signature-cache.mjs
@@ -125,7 +125,7 @@ export async function maintainSignatureCache(root, clear = false) {
 /**
  * Wrap a supervised signer with immutable entries keyed by unsigned bytes and signing policy.
  * @param {import('./windows-signature-cache.mjs').WindowsSignatureCacheOptions} options Cache policy and existing supervised operations.
- * @returns {import('./windows-signature-cache.mjs').WindowsCachedSigner} Serial, fail-stop callback with counters; cache hits still verify trust and timestamp.
+ * @returns {import('./windows-signature-cache.mjs').WindowsCachedSigner} Serial, fail-stop signer plus hardware-free restores; cache hits still verify trust and timestamp.
  */
 export function createCachedSigner(options) {
   let pending = Promise.resolve()
@@ -142,7 +142,7 @@ export function createCachedSigner(options) {
     if (record.inputDigest !== inputDigest || record.identity !== options.identity) throw new Error('signature cache: invalid input record')
     return record
   }
-  async function sign(configuration) {
+  async function sign(configuration, restoreOnly = false) {
     if (configuration.hash !== 'sha256' || configuration.isNest) throw new Error('signature cache: only unsigned SHA-256 runtime files are supported')
     const inputDigest = digest(await regularFile(configuration.path))
     const key = digest(JSON.stringify({ version: 1, inputDigest, identity: options.identity }))
@@ -173,8 +173,9 @@ export function createCachedSigner(options) {
       } finally { statistics.restoreMs += performance.now() - start }
       statistics.hits++
       options.record({ type: 'signature-cache-hit', key, path: configuration.path })
-      return
+      return true
     }
+    if (restoreOnly) return false
     statistics.misses++
     options.record({ type: 'signature-cache-miss', key, path: configuration.path })
     const start = performance.now()
@@ -210,9 +211,10 @@ export function createCachedSigner(options) {
     } finally { await rm(staging, { recursive: true, force: true }) }
   }
   const signer = configuration => {
-    pending = pending.then(() => sign(configuration))
+    pending = pending.then(async () => { await sign(configuration) })
     return pending
   }
+  signer.restore = configuration => sign(configuration, true)
   signer.summary = () => ({ root: options.root, identity: options.identity, ...statistics, avoidedSigningCalls: statistics.hits })
   return signer
 }
diff --git a/apps/desktop/src/browser-guests.ts b/apps/desktop/src/browser-guests.ts
new file mode 100644
index 0000000000..027b7cee5b
--- /dev/null
+++ b/apps/desktop/src/browser-guests.ts
@@ -0,0 +1,166 @@
+/** Main-process ownership and fixed isolation policy for Sidebar webview guests. */
+import { randomUUID } from 'node:crypto'
+import { app, session, type BrowserWindow, type Session, type WebContents } from 'electron'
+import type { DesktopBrowserLeaseId, DesktopBrowserOpenRequest, DesktopBrowserReservation } from '@deepseek-ai/dsh-client-ui-sidebar-browser/types'
+import { DESKTOP_IPC } from './ipc.ts'
+
+interface GuestLease {
+  readonly owner: WebContents
+  readonly partition: string
+  attached: boolean
+  guest?: WebContents
+}
+
+/** Owns workspace storage partitions independently from individual tab guests. */
+export class DesktopBrowserGuests {
+  private readonly partitions = new Map<string, string>()
+  private readonly leases = new Map<DesktopBrowserLeaseId, GuestLease>()
+
+  /** @param hostUrl - current authenticated DSH Host, which guests cannot request. */
+  constructor(private readonly hostUrl: () => string | undefined) {}
+
+  /**
+   * Reserve one guest in a workspace's process-lifetime partition.
+   * @param owner - authenticated primary application WebContents.
+   * @param workspace - workspace identity received over IPC.
+   * @returns opaque lease and the partition approved for it.
+   */
+  acquire(owner: WebContents, workspace: unknown): DesktopBrowserReservation {
+    if (typeof workspace !== 'string' || workspace.length === 0 || workspace.length > 4096) {
+      throw new Error('desktop browser: a workspace storage identity is required')
+    }
+    let partition = this.partitions.get(workspace)
+    if (partition === undefined) {
+      partition = `dsh-sidebar-browser-${randomUUID()}`
+      this.configureSession(session.fromPartition(partition))
+      this.partitions.set(workspace, partition)
+    }
+    const lease = randomUUID() as DesktopBrowserLeaseId
+    this.leases.set(lease, { owner, partition, attached: false })
+    return { lease, partition }
+  }
+
+  /**
+   * Release only a lease issued to this application window; workspace storage survives.
+   * @param owner - authenticated IPC sender.
+   * @param id - lease received over IPC.
+   */
+  async release(owner: WebContents, id: unknown): Promise<void> {
+    if (typeof id !== 'string') throw new Error('desktop browser: invalid guest lease')
+    const key = id as DesktopBrowserLeaseId
+    const lease = this.leases.get(key)
+    if (lease === undefined) return
+    if (lease.owner !== owner) throw new Error('desktop browser: guest belongs to another window')
+    this.leases.delete(key)
+    const guest = lease.guest
+    if (guest !== undefined && !guest.isDestroyed()) {
+      const destroyed = new Promise<void>((resolve) => { guest.once('destroyed', resolve) })
+      guest.close({ waitForBeforeUnload: false })
+      await destroyed
+    }
+  }
+
+  /**
+   * Install attachment checks before the application document can create a webview.
+   * @param window - primary application window.
+   */
+  bind(window: BrowserWindow): void {
+    const owner = window.webContents
+    owner.on('will-attach-webview', (event, preferences, params) => {
+      const id = typeof params.src === 'string' && params.src.startsWith('about:blank#')
+        ? params.src.slice('about:blank#'.length) : ''
+      const lease = this.leases.get(id as DesktopBrowserLeaseId)
+      if (lease === undefined || lease.owner !== owner || lease.attached || params.partition !== lease.partition) {
+        event.preventDefault()
+        return
+      }
+      lease.attached = true
+      // Keep Electron's allowpopups dispatch flag; the guest handler still denies native windows.
+      for (const key of Object.keys(preferences)) {
+        if (key !== 'disablePopups') Reflect.deleteProperty(preferences, key)
+      }
+      Object.assign(preferences, {
+        partition: lease.partition,
+        nodeIntegration: false, nodeIntegrationInWorker: false, nodeIntegrationInSubFrames: false,
+        contextIsolation: true, sandbox: true, webSecurity: true, allowRunningInsecureContent: false,
+        webviewTag: false, plugins: false, navigateOnDragDrop: false, disableDialogs: true,
+        devTools: !app.isPackaged,
+      })
+      params.httpreferrer = ''
+    })
+    owner.on('did-attach-webview', (_event, guest) => {
+      let attachedLease: DesktopBrowserLeaseId | undefined
+      // The first document is an inert about:blank carrying the approved lease.
+      // Bind on the main-process event before the renderer can navigate the ready guest.
+      guest.once('dom-ready', () => {
+        const url = guest.getURL()
+        const id = (url.startsWith('about:blank#') ? url.slice('about:blank#'.length) : '') as DesktopBrowserLeaseId
+        const lease = this.leases.get(id)
+        if (lease === undefined || lease.owner !== owner || lease.guest !== undefined) {
+          guest.close({ waitForBeforeUnload: false })
+          return
+        }
+        lease.guest = guest
+        attachedLease = id
+        guest.once('destroyed', () => { this.leases.delete(id) })
+      })
+      guest.setWindowOpenHandler(({ url, postBody }) => {
+        const lease = attachedLease === undefined ? undefined : this.leases.get(attachedLease)
+        if (attachedLease !== undefined && lease?.guest === guest && lease.owner === owner && !owner.isDestroyed()
+          && postBody === undefined && this.allowedNavigation(url)) {
+          const request: DesktopBrowserOpenRequest = { lease: attachedLease, url: new URL(url).href }
+          owner.send(DESKTOP_IPC.browserOpenRequested, request)
+        }
+        return { action: 'deny' }
+      })
+      guest.on('will-frame-navigate', (event) => {
+        if (event.isMainFrame && !this.allowedNavigation(event.url)) event.preventDefault()
+      })
+      guest.on('will-redirect', (event, url, _inPlace, mainFrame) => {
+        if (mainFrame && !this.allowedNavigation(url)) event.preventDefault()
+      })
+      guest.on('will-attach-webview', (event) => { event.preventDefault() })
+      guest.on('login', (event, _details, _authInfo, callback) => { event.preventDefault(); callback() })
+    })
+    const releaseAll = (): void => {
+      for (const [id, lease] of this.leases) {
+        if (lease.owner === owner) void this.release(owner, id).catch((error: unknown) => { console.error(error) })
+      }
+    }
+    owner.on('did-start-navigation', (_event, _url, inPlace, mainFrame) => {
+      if (mainFrame && !inPlace) releaseAll()
+    })
+    owner.on('render-process-gone', releaseAll)
+    owner.once('destroyed', releaseAll)
+  }
+
+  private configureSession(browserSession: Session): void {
+    browserSession.setPermissionRequestHandler((_contents, _permission, callback) => { callback(false) })
+    browserSession.setPermissionCheckHandler(() => false)
+    browserSession.setDevicePermissionHandler(() => false)
+    browserSession.setDisplayMediaRequestHandler((_request, callback) => { callback({}) })
+    browserSession.on('will-download', (event) => { event.preventDefault() })
+    browserSession.webRequest.onBeforeRequest((details, callback) => {
+      const url = new URL(details.url)
+      const network = ['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)
+      callback({ cancel: network
+        ? url.username !== '' || url.password !== '' || this.isApplicationHost(url)
+        : !['about:', 'data:', 'blob:'].includes(url.protocol) })
+    })
+  }
+
+  private allowedNavigation(value: string): boolean {
+    if (!URL.canParse(value)) return false
+    const url = new URL(value)
+    return ['http:', 'https:'].includes(url.protocol) && url.username === '' && url.password === ''
+      && !this.isApplicationHost(url)
+  }
+
+  private isApplicationHost(url: URL): boolean {
+    const value = this.hostUrl()
+    if (value === undefined) return false
+    const host = new URL(value)
+    return url.port === host.port
+      && (url.hostname === host.hostname || ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+  }
+}
diff --git a/apps/desktop/src/ipc.ts b/apps/desktop/src/ipc.ts
index f5f1f6e82e..ea77749109 100644
--- a/apps/desktop/src/ipc.ts
+++ b/apps/desktop/src/ipc.ts
@@ -1,11 +1,15 @@
 /** Typed preload operations exposed only by the Electron shell. */
 
 import type { IpcMainInvokeEvent } from 'electron'
+import type { DesktopBrowserBridge } from '@deepseek-ai/dsh-client-ui-sidebar-browser/types'
 
 /** IPC channel names kept private to the desktop application bundle. */
 export const DESKTOP_IPC = {
   boot: 'dsh-desktop:boot',
   bootFailed: 'dsh-desktop:boot-failed',
+  browserAcquire: 'dsh-desktop:browser-acquire',
+  browserRelease: 'dsh-desktop:browser-release',
+  browserOpenRequested: 'dsh-desktop:browser-open-requested',
   directoryPick: 'dsh-desktop:directory-pick',
   updatesStatus: 'dsh-desktop:updates-status',
   updatesOpen: 'dsh-desktop:updates-open',
@@ -54,6 +58,7 @@ export interface DesktopUpdatePresentation {
 /** Product documents cannot supply update versions, package URLs, or installation authorization. */
 export interface DshDesktopProductApi {
   readonly protocolVersion: 1
+  readonly browser: DesktopBrowserBridge
   readonly updates: {
     status(): Promise<DesktopUpdatePresentation>
     open(): Promise<void>
diff --git a/apps/desktop/src/locale.ts b/apps/desktop/src/locale.ts
index 03e6f29a57..09dedf44e5 100644
--- a/apps/desktop/src/locale.ts
+++ b/apps/desktop/src/locale.ts
@@ -3,6 +3,10 @@
 export const en = {
   application: 'Application',
   aboutMenu: 'About DeepSeek Harness',
+  hideApplication: 'Hide DeepSeek Harness',
+  hideOtherApplications: 'Hide Others',
+  showAllApplications: 'Show All',
+  quitApplication: 'Quit DeepSeek Harness',
   edit: 'Edit',
   menuBar: 'Application menu',
   delete: 'Delete',
@@ -94,6 +98,10 @@ export type DesktopMessages = { readonly [Key in keyof typeof en]: string }
 export const zh = {
   application: '应用',
   aboutMenu: '关于 DeepSeek Harness',
+  hideApplication: '隐藏 DeepSeek Harness',
+  hideOtherApplications: '隐藏其他',
+  showAllApplications: '显示全部',
+  quitApplication: '退出 DeepSeek Harness',
   edit: '编辑',
   menuBar: '应用菜单',
   delete: '删除',
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index e5aa563c6e..15d7453dcb 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -22,6 +22,7 @@ import { resolveDesktopPaths } from './paths.ts'
 import { DesktopProjectManager } from './project-manager.ts'
 import { DesktopHostProcess, DesktopHostUncleanExitError } from './host-process.ts'
 import { installDesktopDirectoryPicker } from './directory-picker.ts'
+import { installMicrophonePermissions } from './microphone-permissions.ts'
 import { DesktopBackendController } from './backend-controller.ts'
 import { DESKTOP_IPC, SCHEME, assertDesktopSender, type DesktopUpdateState } from './ipc.ts'
 import { formatDesktopMessage, resolveDesktopLocale } from './locale.ts'
@@ -39,6 +40,7 @@ import { DesktopMandatoryUpdateWindow } from './mandatory-update-window.ts'
 import { DesktopPolicyTestAuth } from './policy-test-auth.ts'
 import { DesktopUpdateDialog, type UpdateDialogOptions } from './update-dialog.ts'
 import { readDesktopRuntime } from './runtime-tree.ts'
+import { DesktopBrowserGuests } from './browser-guests.ts'
 
 let focusPrimaryWindow = (): void => {}
 let stopForRecovery = async (): Promise<void> => {}
@@ -108,6 +110,17 @@ function developmentHostInspectPort(enabled: boolean): number | undefined {
   return port
 }
 
+/**
+ * Opaque chrome fallback matching the built-in sidebar palette (the resolved
+ * `--dsw-static-neutral-bluish-900` / `-50` tokens). An approximation for
+ * custom themes: Windows swaps in the renderer's measured palette over the
+ * windowsAppearance IPC, and macOS shows it only while minimized or hidden.
+ * @returns the sidebar fill hex for the active system color scheme.
+ */
+function chromeFallbackFill(): string {
+  return nativeTheme.shouldUseDarkColors ? '#1b1b1c' : '#f9fafb'
+}
+
 function createWindow(preload: string, show = false, primary = false): BrowserWindow {
   const window = new BrowserWindow({
     width: 1280,
@@ -117,7 +130,7 @@ function createWindow(preload: string, show = false, primary = false): BrowserWi
     show,
     ...(process.platform === 'win32' && primary ? {
       titleBarStyle: 'hidden' as const,
-      titleBarOverlay: { height: WINDOWS_TITLEBAR_HEIGHT, color: nativeTheme.shouldUseDarkColors ? '#1b1b1c' : '#f9fafb',
+      titleBarOverlay: { height: WINDOWS_TITLEBAR_HEIGHT, color: chromeFallbackFill(),
         symbolColor: nativeTheme.shouldUseDarkColors ? '#f9fafb' : '#0f1115' },
     } : {}),
     // hiddenInset places traffic lights inside the sidebar; sidebar vibrancy
@@ -137,6 +150,7 @@ function createWindow(preload: string, show = false, primary = false): BrowserWi
       contextIsolation: true,
       sandbox: true,
       webSecurity: true,
+      webviewTag: primary,
     },
   })
   window.webContents.setWindowOpenHandler(({ url }) => {
@@ -154,6 +168,26 @@ function createWindow(preload: string, show = false, primary = false): BrowserWi
     // Reloads and navigations re-register the preload listener; resend the
     // current state so a fullscreen reload does not fall back to windowed CSS.
     window.webContents.on('did-finish-load', sendFullscreen)
+    // Deminiaturize reattaches the NSVisualEffectView material late
+    // (electron/electron#25368), so a transparent window shows the desktop
+    // through the sidebar until then. Paint an opaque base while minimized or
+    // hidden so the deminiaturize animation and the reattachment gap show a
+    // solid fill; restoring flips back, and the null -> 'sidebar' transition
+    // forces the material to reattach.
+    const applyBackdrop = (): void => {
+      if (window.isDestroyed()) return
+      if (window.isMinimized() || !window.isVisible()) {
+        window.setVibrancy(null)
+        window.setBackgroundColor(chromeFallbackFill())
+      } else {
+        window.setVibrancy('sidebar')
+        window.setBackgroundColor('#00000000')
+      }
+    }
+    window.on('minimize', applyBackdrop)
+    window.on('hide', applyBackdrop)
+    window.on('restore', applyBackdrop)
+    window.on('show', applyBackdrop)
   }
   window.webContents.on('context-menu', (_event, { isEditable, selectionText, editFlags }) => {
     const items: MenuItemConstructorOptions[] = []
@@ -234,6 +268,7 @@ async function main(): Promise<void> {
   const applicationUrl = `${SCHEME}://app/`
   let hostUrl: string | undefined
   let hostCookie: string | undefined
+  const browserGuests = new DesktopBrowserGuests(() => hostUrl)
   let injections: readonly unknown[] = []
   const assertProductSender = (event: IpcMainInvokeEvent): void => {
     assertDesktopSender(event, ['app'])
@@ -410,7 +445,7 @@ async function main(): Promise<void> {
   protocol.handle(SCHEME, (request) => {
     const url = new URL(request.url)
     // Serves shell URLs declared in update-dialog.ts and mandatory-update-window.ts plus their renderer assets.
-    // Removing this route leaves those modal windows empty while their parent remains blocked.
+    // Removing this route leaves those shell windows and embedded documents empty while their parent remains blocked.
     if (url.hostname === 'shell') return serveWebDocument(request, join(app.getAppPath(), 'renderer'))
     if (url.hostname === 'app') {
       if (url.pathname === '/' || url.pathname === '/index.html' || url.pathname.startsWith('/assets/')
@@ -426,6 +461,7 @@ async function main(): Promise<void> {
   })
 
   installDesktopDirectoryPicker(() => mainWindow)
+  installMicrophonePermissions(session.defaultSession, () => mainWindow?.webContents)
 
   ipcMain.handle(DESKTOP_IPC.boot, async (event) => {
     assertDesktopSender(event, ['app'])
@@ -443,6 +479,15 @@ async function main(): Promise<void> {
     reportFatal(new Error(message))
   })
 
+  ipcMain.handle(DESKTOP_IPC.browserAcquire, (event, workspace: unknown) => {
+    assertProductSender(event)
+    return browserGuests.acquire(event.sender, workspace)
+  })
+  ipcMain.handle(DESKTOP_IPC.browserRelease, (event, lease: unknown) => {
+    assertProductSender(event)
+    return browserGuests.release(event.sender, lease)
+  })
+
   session.defaultSession.webRequest.onBeforeSendHeaders({ urls: ['ws://127.0.0.1/*'] }, (details, callback) => {
     if (hostUrl === undefined || hostCookie === undefined || details.webContentsId !== mainWindow?.webContents.id) {
       callback({})
@@ -608,12 +653,15 @@ async function main(): Promise<void> {
   })
   // A custom application menu replaces Electron's default menu, so macOS needs
   // its standard menus and application hide commands declared explicitly.
+  // Keep app.name stable: Electron derives its default userData directory from it.
   const darwin = process.platform === 'darwin'
   const platformMenus: MenuItemConstructorOptions[] = darwin
     ? [{ role: 'fileMenu' }, { role: 'editMenu' }, { role: 'windowMenu' }]
     : [{ role: 'editMenu' }]
   const hideCommands: MenuItemConstructorOptions[] = darwin
-    ? [{ role: 'hide' }, { role: 'hideOthers' }, { role: 'unhide' }, { type: 'separator' }]
+    ? [{ role: 'hide', label: currentDesktopLocale().messages.hideApplication },
+      { role: 'hideOthers', label: currentDesktopLocale().messages.hideOtherApplications },
+      { role: 'unhide', label: currentDesktopLocale().messages.showAllApplications }, { type: 'separator' }]
     : []
   const applicationItems = (): MenuItemConstructorOptions[] => [
     { label: currentDesktopLocale().messages.aboutMenu, role: 'about' },
@@ -621,7 +669,8 @@ async function main(): Promise<void> {
     { label: currentDesktopLocale().messages.checkUpdatesMenu, click: () => { void openUpdatePrompt(true) } },
     { type: 'separator' },
     ...hideCommands,
-    { role: 'quit', ...(process.platform === 'win32' ? { label: currentDesktopLocale().messages.exitApplication } : {}) },
+    { role: 'quit', ...(darwin ? { label: currentDesktopLocale().messages.quitApplication }
+      : process.platform === 'win32' ? { label: currentDesktopLocale().messages.exitApplication } : {}) },
   ]
   Menu.setApplicationMenu(process.platform === 'win32' ? null : Menu.buildFromTemplate([{
     label: darwin ? app.name : currentDesktopLocale().messages.application,
@@ -680,6 +729,7 @@ async function main(): Promise<void> {
   const createMainWindow = (): BrowserWindow => {
     const window = createWindow(appPreload, true, true)
     mainWindow = window
+    browserGuests.bind(window)
     window.on('focus', automaticCheck)
     window.on('closed', () => { if (mainWindow === window) mainWindow = undefined })
     window.webContents.on('did-fail-load', (_event, code, description, url, isMainFrame) => {
diff --git a/apps/desktop/src/mandatory-update-window.ts b/apps/desktop/src/mandatory-update-window.ts
index 17438ab15e..cfca36679b 100644
--- a/apps/desktop/src/mandatory-update-window.ts
+++ b/apps/desktop/src/mandatory-update-window.ts
@@ -2,10 +2,10 @@
 
 import { app, BrowserWindow, clipboard, ipcMain, shell, type IpcMainInvokeEvent } from 'electron'
 import type { DesktopLocale } from './locale.ts'
-import type { DesktopUpdateState } from './ipc.ts'
+import { assertDesktopSender, type DesktopUpdateState } from './ipc.ts'
 import { desktopPolicyPage, type DesktopPolicyState } from './mandatory-update-policy.ts'
 import { MANDATORY_IPC } from './mandatory-update-ipc.ts'
-import { createMandatoryUpdateWindow } from './update-overlay.ts'
+import { createUpdateOverlay } from './update-overlay.ts'
 import { DesktopUpdateAttention } from './update-attention.ts'
 
 /** A renderer action never carries a URL or authorizes a different version. */
@@ -46,8 +46,12 @@ export interface MandatoryUpdateWindowOptions {
 // main.ts's protocol.handle shell route serves this document and its renderer assets; the modal requires that route.
 const page = 'dsh-app://shell/mandatory-update.html'
 
-/** A modal child blocks the product window without cancelling work in the Host. */
+/** Shell-owned update presentation; Windows embeds it in the main document without a child window. */
 export class DesktopMandatoryUpdateWindow {
+  private readonly embedded = process.platform === 'win32'
+  private embeddedParent: BrowserWindow | undefined
+  private embeddedBlocking = false
+  private readonly publishEmbedded = (): void => { this.embeddedBlocking = false; this.sync() }
   private window: BrowserWindow | undefined
   private closing: ReturnType<typeof setTimeout> | undefined
   private disposed = false
@@ -65,6 +69,8 @@ export class DesktopMandatoryUpdateWindow {
   /** @param options - Main-process actions and immutable deployment/navigation settings. */
   constructor(private readonly options: MandatoryUpdateWindowOptions) {
     this.attention = new DesktopUpdateAttention(options.locale)
+    this.embeddedParent = this.embedded ? options.parent() : undefined
+    this.embeddedParent?.webContents.on('did-finish-load', this.publishEmbedded)
     ipcMain.handle(MANDATORY_IPC.status, (event) => { this.assertSender(event); return this.view() })
     ipcMain.handle(MANDATORY_IPC.action, (event, action: unknown, version: unknown, confirmationRevision: unknown) => {
       this.assertSender(event)
@@ -103,7 +109,7 @@ export class DesktopMandatoryUpdateWindow {
   }
 
   /** Active modal used as the owner of shell installation-confirmation dialogs. */
-  get confirmationWindow(): BrowserWindow | undefined { return this.window }
+  get confirmationWindow(): BrowserWindow | undefined { return this.embedded ? this.options.parent() : this.window }
 
   /**
    * @param version - Updater-owned target, already downloaded and verified.
@@ -119,8 +125,9 @@ export class DesktopMandatoryUpdateWindow {
       this.confirmation = { version, active, revision: ++this.confirmationRevision, resolve }
       this.sync()
       const parent = this.options.parent()
-      if (parent !== undefined && this.window !== undefined) {
-        this.attention.ready(version, parent, this.window, () => {
+      const owner = this.confirmationWindow
+      if (parent !== undefined && owner !== undefined) {
+        this.attention.ready(version, parent, owner, () => {
           if (!this.disposed && this.options.policy().blocking && this.confirmation !== undefined) this.focus()
         })
       } else this.finishConfirmation(false)
@@ -137,6 +144,18 @@ export class DesktopMandatoryUpdateWindow {
   /** Publish current status, create the block immediately, or close it only after policy clearance. */
   sync(): void {
     if (this.disposed) return
+    if (this.embedded) {
+      const parent = this.options.parent()
+      if (parent !== this.embeddedParent) {
+        if (this.embeddedParent !== undefined && !this.embeddedParent.isDestroyed()) {
+          this.embeddedParent.webContents.off('did-finish-load', this.publishEmbedded)
+        }
+        this.embeddedBlocking = false
+        this.embeddedParent = parent
+        if (parent !== undefined && !parent.isDestroyed()) parent.webContents.on('did-finish-load', this.publishEmbedded)
+      }
+      if (parent === undefined || parent.isDestroyed()) return
+    }
     if (!this.options.policy().blocking) {
       this.finishConfirmation(false)
       this.attention.reset()
@@ -153,16 +172,25 @@ export class DesktopMandatoryUpdateWindow {
         }, 150)
       }
       this.error = undefined
+      if (this.embedded && this.embeddedBlocking) {
+        this.embeddedBlocking = false
+        this.embeddedParent?.webContents.send(MANDATORY_IPC.state, this.view())
+      }
       return
     }
     clearTimeout(this.closing)
     this.closing = undefined
     if (this.navigationUrl !== this.options.policy().page) this.clearNavigation()
     if (this.options.update().phase === 'error') this.restart = undefined
+    if (this.embedded) {
+      this.embeddedBlocking = true
+      this.embeddedParent?.webContents.send(MANDATORY_IPC.state, this.view())
+      return
+    }
     if (this.window === undefined) {
       const parent = this.options.parent()
       if (parent === undefined) return
-      const window = createMandatoryUpdateWindow(parent, this.options.preload, this.options.locale.messages.mandatoryTitle)
+      const window = createUpdateOverlay(parent, this.options.preload, this.options.locale.messages.mandatoryTitle, false)
       this.window = window
       window.setMenu(null)
       window.on('close', (event) => { if (!this.disposed && this.options.policy().blocking) { event.preventDefault(); app.quit() } })
@@ -187,13 +215,15 @@ export class DesktopMandatoryUpdateWindow {
   focus(): void {
     this.sync()
     const parent = this.options.parent()
+    if (parent?.isDestroyed()) return
     if (parent?.isMinimized()) parent.restore()
     parent?.show()
+    if (this.embedded) parent?.focus()
     this.window?.show()
     this.window?.focus()
   }
 
-  /** Detach IPC and release the modal during application shutdown. */
+  /** Detach IPC and release the modal during shutdown, including after the main window closes. */
   dispose(): void {
     this.disposed = true
     clearTimeout(this.closing)
@@ -203,6 +233,10 @@ export class DesktopMandatoryUpdateWindow {
     this.clearNavigation()
     ipcMain.removeHandler(MANDATORY_IPC.status)
     ipcMain.removeHandler(MANDATORY_IPC.action)
+    if (this.embeddedParent !== undefined && !this.embeddedParent.isDestroyed()) {
+      this.embeddedParent.webContents.off('did-finish-load', this.publishEmbedded)
+      this.embeddedParent.webContents.send(MANDATORY_IPC.state, { ...this.view(), policy: { blocking: false, checking: false } })
+    }
     this.window?.destroy()
     this.window = undefined
   }
@@ -258,6 +292,15 @@ export class DesktopMandatoryUpdateWindow {
   }
 
   private assertSender(event: IpcMainInvokeEvent): void {
+    if (this.embedded) {
+      const parent = this.options.parent()
+      if (parent === undefined || parent.isDestroyed() || event.sender !== parent.webContents
+        || event.senderFrame !== parent.webContents.mainFrame) {
+        throw new Error('desktop policy: rejected unowned renderer')
+      }
+      assertDesktopSender(event, ['app'])
+      return
+    }
     if (event.sender !== this.window?.webContents || event.senderFrame !== this.window.webContents.mainFrame
       || event.senderFrame.url !== page) throw new Error('desktop policy: rejected unowned renderer')
   }
diff --git a/apps/desktop/src/microphone-permissions.ts b/apps/desktop/src/microphone-permissions.ts
new file mode 100644
index 0000000000..4d41a8e390
--- /dev/null
+++ b/apps/desktop/src/microphone-permissions.ts
@@ -0,0 +1,31 @@
+/** Microphone access belongs to the primary application frame and the operating system. */
+import { systemPreferences, type Session, type WebContents } from 'electron'
+
+function applicationFrame(url: string): boolean {
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'dsh-app:' && parsed.hostname === 'app'
+  } catch (_error) { return false /* Invalid frame URLs cannot request microphone access. */ }
+}
+
+/**
+ * Handle microphone requests from the owned application window; other permissions retain Electron's defaults.
+ * @param session - application's browser session.
+ * @param primary - current primary window contents, absent while no window is open.
+ */
+export function installMicrophonePermissions(session: Pick<Session, 'setPermissionCheckHandler' | 'setPermissionRequestHandler'>, primary: () => WebContents | undefined): void {
+  session.setPermissionCheckHandler((contents, permission, origin, details) => {
+    if (permission !== 'media') return true
+    return contents != null && contents === primary() && details.isMainFrame
+      && applicationFrame(origin) && details.mediaType === 'audio'
+      && (process.platform !== 'darwin' || systemPreferences.getMediaAccessStatus('microphone') === 'granted')
+  })
+  session.setPermissionRequestHandler((contents, permission, callback, details) => {
+    if (permission !== 'media') { callback(true); return }
+    const allowed = contents === primary() && details.isMainFrame && applicationFrame(details.requestingUrl)
+      && 'mediaTypes' in details && details.mediaTypes.length === 1 && details.mediaTypes[0] === 'audio'
+    if (!allowed) { callback(false); return }
+    if (process.platform !== 'darwin') { callback(true); return }
+    void systemPreferences.askForMediaAccess('microphone').then(callback, () => { callback(false) })
+  })
+}
diff --git a/apps/desktop/src/preload-app.ts b/apps/desktop/src/preload-app.ts
index 10ea92326f..8133c72a7c 100644
--- a/apps/desktop/src/preload-app.ts
+++ b/apps/desktop/src/preload-app.ts
@@ -1,29 +1,41 @@
-/** Origin-scoped boot, native directory selection, and update presentation with native confirmation actions. */
+/** Origin-scoped boot, native directory selection, host paths of picked files, and update presentation with native confirmation actions. */
 
-import { contextBridge, ipcRenderer } from 'electron'
+import { contextBridge, ipcRenderer, webUtils } from 'electron'
 import { DESKTOP_IPC, SCHEME, type DshDesktopProductApi, type DesktopUpdatePresentation } from './ipc.ts'
 import { markDocumentPlatform, syncWindowFullscreen } from './preload-platform.ts'
 import { syncNativeTheme } from './preload-theme.ts'
 import { syncWindowsAppearance } from './preload-windows.ts'
+import { installMandatoryUpdateOverlay } from './preload-mandatory-overlay.ts'
+import { createDesktopBrowserBridge } from './preload-browser.ts'
 
-const product: DshDesktopProductApi = {
-  protocolVersion: 1,
-  updates: {
-    status: () => ipcRenderer.invoke(DESKTOP_IPC.updatesStatus) as Promise<DesktopUpdatePresentation>,
-    open: () => ipcRenderer.invoke(DESKTOP_IPC.updatesOpen) as Promise<void>,
-    subscribe(listener) {
-      const handle = (_event: Electron.IpcRendererEvent, state: DesktopUpdatePresentation): void => { listener(state) }
-      ipcRenderer.on(DESKTOP_IPC.updatesPresentation, handle)
-      return () => { ipcRenderer.off(DESKTOP_IPC.updatesPresentation, handle) }
+function createProductApi(): DshDesktopProductApi {
+  return {
+    protocolVersion: 1,
+    browser: createDesktopBrowserBridge(),
+    updates: {
+      status: () => ipcRenderer.invoke(DESKTOP_IPC.updatesStatus) as Promise<DesktopUpdatePresentation>,
+      open: () => ipcRenderer.invoke(DESKTOP_IPC.updatesOpen) as Promise<void>,
+      subscribe(listener) {
+        const handle = (_event: Electron.IpcRendererEvent, state: DesktopUpdatePresentation): void => { listener(state) }
+        ipcRenderer.on(DESKTOP_IPC.updatesPresentation, handle)
+        return () => { ipcRenderer.off(DESKTOP_IPC.updatesPresentation, handle) }
+      },
     },
-  },
+  }
 }
 
 if (location.protocol === `${SCHEME}:` && location.hostname === 'app') {
   syncWindowsAppearance()
+  if (process.platform === 'win32') installMandatoryUpdateOverlay()
   contextBridge.exposeInMainWorld('__DSH_DIRECTORY_PICKER__', {
     pick: () => ipcRenderer.invoke(DESKTOP_IPC.directoryPick) as Promise<string | null>,
   })
+  // The composer cites dropped, picked, and pasted files and folders that
+  // have a real path as `@path` references instead of uploading them; a
+  // File without one (pasted bytes) answers '' and uploads as before.
+  contextBridge.exposeInMainWorld('__DSH_HOST_PATHS__', {
+    pathFor: (file: File) => webUtils.getPathForFile(file),
+  })
   contextBridge.exposeInMainWorld('dshDesktopBoot', {
     ready: () => ipcRenderer.invoke(DESKTOP_IPC.boot) as Promise<unknown>,
     failed: (message: string) => ipcRenderer.invoke(DESKTOP_IPC.bootFailed, message) as Promise<void>,
@@ -34,4 +46,4 @@ markDocumentPlatform()
 syncWindowFullscreen()
 syncNativeTheme()
 // Main-process IPC also verifies the owning window and top frame.
-contextBridge.exposeInMainWorld('dshDesktop', location.protocol === `${SCHEME}:` && location.hostname === 'app' ? product : { protocolVersion: 1 })
+contextBridge.exposeInMainWorld('dshDesktop', location.protocol === `${SCHEME}:` && location.hostname === 'app' ? createProductApi() : { protocolVersion: 1 })
diff --git a/apps/desktop/src/preload-browser.ts b/apps/desktop/src/preload-browser.ts
new file mode 100644
index 0000000000..fadf2f1ce1
--- /dev/null
+++ b/apps/desktop/src/preload-browser.ts
@@ -0,0 +1,32 @@
+/** Lease-scoped browser operations and one main-process event subscription per window. */
+import { ipcRenderer } from 'electron'
+import type { DesktopBrowserBridge, DesktopBrowserLeaseId } from '@deepseek-ai/dsh-client-ui-sidebar-browser/types'
+import { DESKTOP_IPC } from './ipc.ts'
+
+/** @returns browser operations that expose neither IPC nor Electron objects. */
+export function createDesktopBrowserBridge(): DesktopBrowserBridge {
+  const listeners = new Map<DesktopBrowserLeaseId, Set<(url: string) => void>>()
+  ipcRenderer.on(DESKTOP_IPC.browserOpenRequested, (_event, request: unknown) => {
+    if (typeof request !== 'object' || request === null || !('lease' in request) || !('url' in request)
+      || typeof request.lease !== 'string' || typeof request.url !== 'string') return
+    const callbacks = listeners.get(request.lease as DesktopBrowserLeaseId)
+    if (callbacks === undefined) return
+    for (const callback of [...callbacks]) {
+      try { callback(request.url) }
+      catch (error) { console.error('Desktop browser link handler failed', error) }
+    }
+  })
+  return {
+    acquire: workspace => ipcRenderer.invoke(DESKTOP_IPC.browserAcquire, workspace) as ReturnType<DesktopBrowserBridge['acquire']>,
+    release: lease => ipcRenderer.invoke(DESKTOP_IPC.browserRelease, lease) as Promise<void>,
+    onOpenRequested(lease, listener) {
+      let callbacks = listeners.get(lease)
+      if (callbacks === undefined) { callbacks = new Set(); listeners.set(lease, callbacks) }
+      callbacks.add(listener)
+      return () => {
+        callbacks.delete(listener)
+        if (callbacks.size === 0 && listeners.get(lease) === callbacks) listeners.delete(lease)
+      }
+    },
+  }
+}
diff --git a/apps/desktop/src/preload-mandatory-overlay.ts b/apps/desktop/src/preload-mandatory-overlay.ts
new file mode 100644
index 0000000000..6c4076e091
--- /dev/null
+++ b/apps/desktop/src/preload-mandatory-overlay.ts
@@ -0,0 +1,85 @@
+/** Mounts the shell-owned Windows update document inside the main window's content area. */
+import { ipcRenderer } from 'electron'
+import { MANDATORY_IPC } from './mandatory-update-ipc.ts'
+import type { MandatoryUpdateView } from './mandatory-update-window.ts'
+import { WINDOWS_TITLEBAR_HEIGHT } from './windows-layout.ts'
+
+/** Keep update actions on a private channel to the shell frame; the shared product DOM is not a tamper-proof display. */
+export function installMandatoryUpdateOverlay(): void {
+  let disposed = false
+  let state: MandatoryUpdateView | undefined
+  let host: HTMLDivElement | undefined
+  let frame: HTMLIFrameElement | undefined
+  let port: MessagePort | undefined
+  let closing: ReturnType<typeof setTimeout> | undefined
+  const publish = (): void => { port?.postMessage({ type: 'dsh-mandatory-state', state }) }
+  const remove = (): void => { port?.close(); port = undefined; host?.remove(); host = undefined; frame = undefined }
+  const render = (): void => {
+    if (state === undefined || document.readyState === 'loading') return
+    if (!state.policy.blocking) {
+      if (frame === undefined || closing !== undefined) return
+      publish()
+      closing = setTimeout(remove, 150)
+      return
+    }
+    clearTimeout(closing)
+    closing = undefined
+    if (frame === undefined) {
+      host = document.createElement('div')
+      host.style.cssText = `position:fixed;top:${WINDOWS_TITLEBAR_HEIGHT}px;left:0;right:0;bottom:0;z-index:2147483647;backdrop-filter:blur(2px)`
+      const shadow = host.attachShadow({ mode: 'closed' })
+      frame = document.createElement('iframe')
+      frame.title = state.locale.messages.mandatoryTitle
+      frame.style.cssText = 'display:block;width:100%;height:100%;border:0;background:transparent'
+      frame.src = 'dsh-app://shell/mandatory-update.html'
+      shadow.append(frame)
+      document.documentElement.append(host)
+      frame.addEventListener('load', () => {
+        port?.close()
+        const channel = new MessageChannel()
+        port = channel.port1
+        port.onmessage = message
+        frame?.contentWindow?.postMessage({ type: 'dsh-mandatory-connect' }, 'dsh-app://shell', [channel.port2])
+        publish()
+        frame?.focus()
+      })
+    }
+    publish()
+  }
+  const receive = (_event: Electron.IpcRendererEvent, next: MandatoryUpdateView): void => { state = next; render() }
+  const message = (event: MessageEvent<unknown>): void => {
+    const value = event.data
+    if (typeof value !== 'object' || value === null || !('type' in value)) return
+    if (value.type !== 'dsh-mandatory-action' || !('id' in value) || !Number.isSafeInteger(value.id)
+      || !('action' in value) || !('version' in value) || !('revision' in value)) return
+    const target = port
+    if (target === undefined) return
+    void ipcRenderer.invoke(MANDATORY_IPC.action, value.action, value.version, value.revision).then(
+      () => { target.postMessage({ type: 'dsh-mandatory-result', id: value.id, ok: true }) },
+      () => { target.postMessage({ type: 'dsh-mandatory-result', id: value.id, ok: false }) },
+    )
+  }
+  const blockBackgroundKey = (event: KeyboardEvent): void => {
+    if (frame === undefined || state?.policy.blocking !== true
+      || event.composedPath().some(target => target instanceof HTMLElement && target.hasAttribute('data-windows-menu'))) return
+    event.preventDefault()
+    event.stopImmediatePropagation()
+    frame.focus()
+  }
+  ipcRenderer.on(MANDATORY_IPC.state, receive)
+  void ipcRenderer.invoke(MANDATORY_IPC.status).then((initial: MandatoryUpdateView) => {
+    if (!disposed && state === undefined) { state = initial; render() }
+  }, () => {
+    // Development may omit policy configuration; a later main-frame load still resynchronizes configured policy.
+  })
+  window.addEventListener('keydown', blockBackgroundKey, true)
+  window.addEventListener('DOMContentLoaded', render, { once: true })
+  window.addEventListener('pagehide', () => {
+    disposed = true
+    clearTimeout(closing)
+    remove()
+    ipcRenderer.off(MANDATORY_IPC.state, receive)
+    window.removeEventListener('keydown', blockBackgroundKey, true)
+    window.removeEventListener('DOMContentLoaded', render)
+  }, { once: true })
+}
diff --git a/apps/desktop/src/update-overlay.ts b/apps/desktop/src/update-overlay.ts
index 2ff0b8c0d4..a6e341ecb9 100644
--- a/apps/desktop/src/update-overlay.ts
+++ b/apps/desktop/src/update-overlay.ts
@@ -47,19 +47,3 @@ export function createUpdateOverlay(parent: BrowserWindow, preload: string, titl
   window.webContents.setWindowOpenHandler(() => ({ action: 'deny' }))
   return window
 }
-
-/** A native Windows modal retains its own title bar while the product window remains blocked. */
-export function createMandatoryUpdateWindow(parent: BrowserWindow, preload: string, title: string,
-  platform: NodeJS.Platform = process.platform): BrowserWindow {
-  if (platform !== 'win32') return createUpdateOverlay(parent, preload, title, false)
-  const window = new BrowserWindow({
-    parent, modal: true, show: false, title,
-    width: 640, height: 560, minWidth: 480, minHeight: 360,
-    movable: true, resizable: true, maximizable: true,
-    backgroundColor: '#f5f5f5',
-    webPreferences: { preload, contextIsolation: true, sandbox: true, nodeIntegration: false, webSecurity: true },
-  })
-  window.once('ready-to-show', () => { if (!window.isDestroyed()) window.show() })
-  window.webContents.setWindowOpenHandler(() => ({ action: 'deny' }))
-  return window
-}
diff --git a/apps/desktop/tests/README.i18n.yaml b/apps/desktop/tests/README.i18n.yaml
index 791271a555..6dd6065d3b 100644
--- a/apps/desktop/tests/README.i18n.yaml
+++ b/apps/desktop/tests/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent 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/desktop/tests/README.md
-README.md: 6171b058adad8e34a3275c013bd875e00f586afc
-README.zh.md: fa18cd947e1315248b5449eaf9bc426bba3d18fc
+README.md: a2684a2bced4326bdc316ff56d80003061d0136d
+README.zh.md: fba5b65aa41aa14b9971f80676c8f0fef4d7be9e
diff --git a/apps/desktop/tests/README.md b/apps/desktop/tests/README.md
index 6171b058ad..a2684a2bce 100644
--- a/apps/desktop/tests/README.md
+++ b/apps/desktop/tests/README.md
@@ -33,7 +33,7 @@ The local command builds Desktop and executes Electron 44 with the actual HTTP u
 | Ordinary updater | Same/older-version rejection, user-authorized full download, SHA-512 rejection, interrupted transfer, stalled-feed/download deadlines, explicit retry, coalesced requests, same-address feed replacement, readiness, and separate install handoff pass |
 | Mandatory policy | Flattened `40005`, exact release headers, guest requests, no-force validation, failure retention, interval/backoff, timeout, and disposal regressions pass |
 | Ordinary scheduling | Fake-clock regressions with the real coordinator verify bounded jitter/backoff, manual joins, success reset, no automatic download retry, wall-clock independence, and disposal. Main-entry tests verify focus/resume throttling, immediate explicit checks, and quit cleanup |
-| Actual mandatory window | Text-only server content, native Windows move/resize/maximize and restore, Escape blocking, direct download, same-modal task confirmation, deferral, recovery-only page actions, navigation/copy feedback, and fresh policy clearance pass; a focused test verifies close-to-exit without clearing policy |
+| Actual mandatory window | Text-only server content, an embedded Windows shell frame with no additional native window and an enabled main window, Escape blocking, direct download, same-modal task confirmation, deferral, recovery-only page actions, navigation/copy feedback, and fresh policy clearance pass; a focused test verifies close-to-exit without clearing policy |
 | Actual ordinary dialog | Isolated preload, 380px card, 24px corners, black primary button, parent blur, Escape cancellation retaining readiness, and task-warning approval with recorded installation handoff pass |
 | Unlocked Windows interaction | OS-level clicks and screenshots of the actual mandatory renderer confirm Escape blocking, user-started download, readiness, red policy-error feedback, and modal clearance with the parent enabled again. A fixture-provided native task-warning dialog returns to readiness on deferral; task activity is simulated, not a full Host workload |
 | Main entry | A known block refuses plugin mutations and recovery without stopping the Host; fresh success closes the block; packaged policy ignores environment overrides; installer failure after a clean stop restores the Host before another confirmation and retains mandatory blocking |
@@ -47,7 +47,7 @@ Chromium headless shell revision 1228 is installed in the ignored `.desktop-buil
 
 The [built Host scenario](fixtures/host-update-qualification.mjs) uses the actual profile Loader, standard agent preset, task services, and Node background processes. It verifies queued turns/steps, a running model request, pending questions/approvals, global and agent jobs in running/stopping states, admission locking without cancellation, restored admission, and rejected inspection after Host disposal. Only model responses and human answers are substituted. Two independent invocations pass concurrently with private profiles and session data; all owned agents, jobs, and Hosts finish before a success report is written.
 
-The [Electron workspace runner](../scripts/test-workspace-updates.ts) executes a private copy of the compiled main entry with the real preload, workspace, and separate Host process. It acknowledges the first-run notice and drives renderer buttons through Electron input events. Ten scenarios pass, covering menu feedback, download failure and retry, separate installation confirmation, real confirmation-time task creation, deferral, mandatory blocking, and actual Host teardown timeout. Both ordinary and mandatory failures restore a replacement Host and require fresh installation confirmation; recovery does not clear mandatory policy. Delivery uses a local server and installation is intercepted; these are not signed installed-app results.
+The [Electron workspace runner](../scripts/test-workspace-updates.ts) executes a private copy of the compiled main entry with the real preload, workspace, and separate Host process. It acknowledges the first-run notice and drives renderer buttons through Electron input events and Chromium debugger input for the embedded Windows frame. The private application reuses the prepared target runtime resources. Ten scenarios pass, covering menu feedback, download failure and retry, separate installation confirmation, real confirmation-time task creation, deferral, mandatory blocking, and actual Host teardown timeout. Both ordinary and mandatory failures restore a replacement Host and require fresh installation confirmation; recovery does not clear mandatory policy. Delivery uses a local server and installation is intercepted; these are not signed installed-app results.
 
 The [Windows signature runner](../scripts/test-windows-update-signature.mjs) uses the installed electron-builder metadata generator and `NsisUpdater` verifier with the public release certificate and real executable inputs. Matching publisher attributes pass; the same valid signature with a different expected publisher and an unsigned executable are rejected. A missing-publisher negative control confirms that verification is skipped. Unit regressions cover DN escaping, incomplete identities, and explicit or host-default Windows targets; removing the publisher configuration fails both metadata cases. This check does not download, install, or sign an artifact.
 
diff --git a/apps/desktop/tests/README.zh.md b/apps/desktop/tests/README.zh.md
index fa18cd947e..fba5b65aa4 100644
--- a/apps/desktop/tests/README.zh.md
+++ b/apps/desktop/tests/README.zh.md
@@ -33,7 +33,7 @@ Host、客户端与 Desktop 产物构建完成后，在 Windows 仓库根目录
 | 常规 updater | 同版本／旧版本拒绝、用户授权完整下载、SHA-512 拒绝、传输中断、清单／下载停滞截止时间、显式重试、请求合并、同地址清单替换、就绪状态和独立安装交接通过 |
 | 强更策略 | 扁平化 `40005`、完整发布头、游客请求、无需强更验证、失败保留、间隔／退避、超时和 dispose（资源释放）回归通过 |
 | 常规调度 | 真实协调器配合模拟时钟的回归验证有上限的抖动／退避、手动复用、成功重置、不自动重试下载、不受系统时钟调整影响，以及 dispose。主入口测试验证聚焦／恢复节流、显式检查立即执行和退出清理 |
-| 真实强更窗口 | 服务端纯文本内容、Windows 原生窗口移动／缩放／最大化及还原、Esc 阻塞、直接下载、同弹窗任务确认、稍后更新、仅恢复态页面操作、导航／复制反馈和新策略解除通过；定向测试验证关闭时退出且不清除策略 |
+| 真实强更窗口 | 服务端纯文本内容、Windows 内嵌 shell frame、不创建额外原生窗口且主窗口保持启用、Esc 阻塞、直接下载、同弹窗任务确认、稍后更新、仅恢复态页面操作、导航／复制反馈和新策略解除通过；定向测试验证关闭时退出且不清除策略 |
 | 真实常规弹窗 | 隔离预加载、380px 卡片、24px 圆角、黑色主按钮、父窗口模糊、Esc 取消后保留就绪，以及任务警告批准后的安装交接记录均通过 |
 | 解锁后的 Windows 交互 | 对真实强更页面执行系统级点击并截图，确认 Esc 阻塞、用户发起下载、就绪、红色策略错误提示，以及弹窗解除后父窗口恢复可用。fixture 提供的原生任务警告弹窗在选择稍后更新后回到就绪态；任务活动为模拟，不是完整 Host 工作负载 |
 | 主入口 | 已知阻塞拒绝插件修改和恢复，但不停止 Host；新成功响应关闭阻塞；打包策略忽略环境覆盖；正常停止后的安装器失败在下次确认前恢复 Host，并保留强更阻塞 |
@@ -47,7 +47,7 @@ Chromium headless shell revision 1228 已安装在忽略目录 `.desktop-build/p
 
 [构建后 Host 场景](fixtures/host-update-qualification.mjs) 使用真实 profile Loader、standard agent 预设、任务服务和 Node 后台进程。它验证排队的轮次／步骤、运行中的模型请求、等待答复的提问／审批、运行／停止中的全局和 agent job、不会取消任务的准入锁定、准入恢复，以及 Host 释放后的检查拒绝。仅模型响应和人工答复使用替身。两个独立调用使用私有 profile 和会话数据并发通过；全部自有 agent、job 和 Host 完成后才写入成功报告。
 
-[Electron 工作区运行器](../scripts/test-workspace-updates.ts) 在私有目录中执行编译后的主入口，使用真实预加载、工作区和独立 Host 进程。它确认首次启动声明，并通过 Electron 输入事件操作页面按钮。十个场景通过，覆盖菜单反馈、下载失败与重试、独立安装确认、确认期间真实任务创建、推迟安装、强更阻塞和真实 Host 停止超时。普通与强更失败均恢复替代 Host，并要求重新确认安装；恢复不会清除强更策略。分发使用本地服务器，安装被拦截；这些不是签名已安装应用的验证结果。
+[Electron 工作区运行器](../scripts/test-workspace-updates.ts) 在私有目录中执行编译后的主入口，使用真实预加载、工作区和独立 Host 进程。它确认首次启动声明，并通过 Electron 输入事件及嵌入式 Windows frame 的 Chromium 调试器输入操作页面按钮。私有应用复用已准备的目标运行时资源。十个场景通过，覆盖菜单反馈、下载失败与重试、独立安装确认、确认期间真实任务创建、推迟安装、强更阻塞和真实 Host 停止超时。普通与强更失败均恢复替代 Host，并要求重新确认安装；恢复不会清除强更策略。分发使用本地服务器，安装被拦截；这些不是签名已安装应用的验证结果。
 
 [Windows 验签运行器](../scripts/test-windows-update-signature.mjs) 使用已安装的 electron-builder 元数据生成器和 `NsisUpdater` 验签器，输入为公开发布证书和真实可执行文件。发布者属性匹配时通过；同一有效签名在预期发布者不同时被拒绝，未签名可执行文件也被拒绝。缺少发布者的负对照确认验签被跳过。单元回归覆盖 DN 转义、不完整身份，以及显式或宿主默认 Windows 目标；移除发布者配置会使两条元数据用例失败。此检查不下载、安装或签名产物。
 
diff --git a/apps/desktop/tests/desktop-auto-update-environment.spec.ts b/apps/desktop/tests/desktop-auto-update-environment.spec.ts
index 747657042b..c33a9384df 100644
--- a/apps/desktop/tests/desktop-auto-update-environment.spec.ts
+++ b/apps/desktop/tests/desktop-auto-update-environment.spec.ts
@@ -8,20 +8,48 @@ import {
   resolveDesktopUploadConfig,
 } from '../scripts/desktop-auto-update-environment.mjs'
 
+const RELEASE_ID = '0123456789abcdef0123456789abcdef'
+
 describe('desktop auto-update environment', () => {
+  it.each([undefined, 'test'])('requires a release ID for deployment %s', (deployment) => {
+    const environment = { DSH_DESKTOP_AUTO_UPDATE_ENV: deployment, DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com',
+      DOWNLOAD_TEST_COS_BUCKET: 'test-bucket' }
+    expect(() => resolveDesktopAutoUpdateConfig(environment, 'win32', 'x64')).toThrow(/DOWNLOAD_TEST_RELEASE_ID/u)
+    expect(() => resolveDesktopUploadConfig(environment, 'win32', 'x64')).toThrow(/DOWNLOAD_TEST_RELEASE_ID/u)
+  })
+
+  it.each(['', ' ', 'release-1', 'a'.repeat(31), 'a'.repeat(33), 'A'.repeat(32), 'g'.repeat(32),
+    '../feeds', '01234567-89ab-cdef-0123-456789abcdef', `${RELEASE_ID}/bin`])('rejects invalid test release ID %j', (id) => {
+    const environment = { DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DOWNLOAD_TEST_RELEASE_ID: id }
+    expect(() => resolveDesktopAutoUpdateConfig(environment, 'darwin', 'arm64')).toThrow(/DOWNLOAD_TEST_RELEASE_ID/u)
+  })
+
+  it.each([['darwin', 'arm64', 'mac-arm64'], ['darwin', 'x64', 'mac-x64'], ['win32', 'x64', 'win-x64']] as const)
+  ('uses one test release directory for %s %s feeds and binaries', (platform, arch, target) => {
+    expect(resolveDesktopAutoUpdateConfig({ DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com',
+      DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID }, platform, arch)).toMatchObject({
+      publicUrl: `https://updates.example.com/dsh-desk/${RELEASE_ID}/feeds/${target}/`,
+      keyPrefix: `dsh-desk/${RELEASE_ID}/feeds/${target}`,
+      binaryKeyPrefix: `dsh-desk/${RELEASE_ID}/bin/${target}`,
+    })
+  })
+
   it('defaults packages and uploads to the test deployment', () => {
     expect(resolveDesktopAutoUpdateEnvironment({})).toBe('test')
     expect(resolveDesktopAutoUpdateConfig({
       DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com/',
+      DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID,
     }, 'darwin', 'arm64')).toEqual({
       environment: 'test',
       target: 'mac-arm64',
       origin: 'https://desktop-updates.example.com',
-      publicUrl: 'https://desktop-updates.example.com/dsh-desk/feeds/mac-arm64/',
-      keyPrefix: 'dsh-desk/feeds/mac-arm64',
+      publicUrl: `https://desktop-updates.example.com/dsh-desk/${RELEASE_ID}/feeds/mac-arm64/`,
+      keyPrefix: `dsh-desk/${RELEASE_ID}/feeds/mac-arm64`,
+      binaryKeyPrefix: `dsh-desk/${RELEASE_ID}/bin/mac-arm64`,
     })
     expect(resolveDesktopUploadConfig({
       DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com/',
+      DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID,
       DOWNLOAD_TEST_COS_BUCKET: 'test-download-bucket',
     }, 'darwin', 'arm64')).toMatchObject({
       bucket: 'test-download-bucket',
@@ -30,13 +58,15 @@ describe('desktop auto-update environment', () => {
     })
   })
 
-  it('selects the production URL for packages and bucket for uploads', () => {
+  it.each([undefined, RELEASE_ID, 'unused-test-value'])('keeps production paths independent of test release ID %s', (id) => {
     expect(resolveDesktopAutoUpdateConfig({
       DSH_DESKTOP_AUTO_UPDATE_ENV: 'production',
+      DOWNLOAD_TEST_RELEASE_ID: id,
     }, 'win32', 'x64')).toMatchObject({
       environment: 'production',
       target: 'win-x64',
       publicUrl: 'https://download.deepseek.com/dsh-desk/feeds/win-x64/',
+      binaryKeyPrefix: 'dsh-desk/bin/win-x64',
     })
     expect(resolveDesktopUploadConfig({
       DSH_DESKTOP_AUTO_UPDATE_ENV: 'production',
@@ -53,9 +83,11 @@ describe('desktop auto-update environment', () => {
       .toThrow(/DOWNLOAD_TEST_ORIGIN/u)
     expect(resolveDesktopAutoUpdateConfig({
       DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com',
+      DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID,
     }, 'darwin', 'arm64').publicUrl).toContain('/mac-arm64/')
     expect(() => resolveDesktopUploadConfig({
       DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com',
+      DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID,
     }, 'darwin', 'arm64')).toThrow(/DOWNLOAD_TEST_COS_BUCKET/u)
     expect(() => resolveDesktopUploadConfig({
       DSH_DESKTOP_AUTO_UPDATE_ENV: 'production',
diff --git a/apps/desktop/tests/desktop-package-environment.spec.ts b/apps/desktop/tests/desktop-package-environment.spec.ts
index 7153f135a3..8533d2a600 100644
--- a/apps/desktop/tests/desktop-package-environment.spec.ts
+++ b/apps/desktop/tests/desktop-package-environment.spec.ts
@@ -3,12 +3,14 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { loadDesktopPackageEnvironment, validateDesktopPackageEnvironment } from '../scripts/desktop-package-environment.mjs'
+import { resolveWindowsPackageSettings } from '../scripts/windows-package-settings.mjs'
 
 const WINDOWS = { platform: 'win32', arch: 'x64' } as const
 const MACOS = { platform: 'darwin', arch: 'arm64' } as const
 const POLICY = { DSH_DESKTOP_MANDATORY_UPDATE_TEST_ORIGIN: 'https://policy.example.com',
   DSH_DESKTOP_MANDATORY_UPDATE_CONFIG: JSON.stringify({ allowedAuthOrigins: ['https://login.example.com'] }) }
-const RELEASE = { ...POLICY, DSH_DESKTOP_APP_ID: 'com.example.desktop', DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com' }
+const RELEASE = { ...POLICY, DSH_DESKTOP_APP_ID: 'com.example.desktop', DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com',
+  DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef' }
 const MAC_IDENTITY = { DSH_DESKTOP_MACOS_SIGNING_IDENTITY: 'Example Company (TEAMID1234)', DSH_DESKTOP_MACOS_TEAM_ID: 'TEAMID1234' }
 
 async function withDirectory(action: (directory: string) => Promise<void>): Promise<void> {
@@ -21,6 +23,30 @@ async function withDirectory(action: (directory: string) => Promise<void>): Prom
 }
 
 describe('Desktop local packaging configuration', () => {
+  it('takes cache concurrency from the Windows file and defaults to four without ambient overrides', async () => {
+    await withDirectory(async (directory) => {
+      const parent = { DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: '8' }
+      await writeFile(join(directory, '.env.windows'), '')
+      expect(resolveWindowsPackageSettings(loadDesktopPackageEnvironment('win32', parent, directory)).signatureCacheConcurrency).toBe(4)
+      await writeFile(join(directory, '.env.windows'), 'DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY=2\n')
+      expect(resolveWindowsPackageSettings(loadDesktopPackageEnvironment('win32', parent, directory)).signatureCacheConcurrency).toBe(2)
+    })
+  })
+
+  it.each(['1', '2', '4', '8'])('accepts cache concurrency %s', (value) => {
+    const settings = resolveWindowsPackageSettings({ DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: value })
+    expect(settings.signatureCacheConcurrency).toBe(Number(value))
+  })
+
+  it.each(['', '0', '-1', '9', '1.5', 'Infinity', '01'])('rejects invalid cache concurrency %s', (value) => {
+    expect(() => resolveWindowsPackageSettings({ DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: value })).toThrow('integer from 1 to 8')
+    for (const options of [{ unsigned: true }, { prepareOnly: true }]) {
+      expect(() => {
+        validateDesktopPackageEnvironment({ ...RELEASE, DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: value }, WINDOWS, options)
+      }).toThrow('integer from 1 to 8')
+    }
+  })
+
   it('selects the platform file, preserves literal secrets, and excludes stale ambient release settings', async () => {
     await withDirectory(async (directory) => {
       await writeFile(join(directory, '.env.windows'), '\uFEFFDSH_DESKTOP_APP_ID=com.example.windows\r\nDSH_DESKTOP_WINDOWS_TOKEN_PIN=" #!$%&literal "\r\nDSH_DESKTOP_WINDOWS_CER_FILE="keys/public certificate.cer"\r\n')
@@ -33,6 +59,7 @@ describe('Desktop local packaging configuration', () => {
         dsh_desktop_mandatory_update_prod_origin: 'https://stale.example.com',
         DSH_DESKTOP_WINDOWS_TOKEN_PIN: 'stale-pin', APPLE_ID: 'stale-apple-id',
         CSC_LINK: 'stale-certificate', DOWNLOAD_TEST_ORIGIN: 'https://stale.example.com',
+        DOWNLOAD_TEST_RELEASE_ID: 'a'.repeat(32), download_test_release_id: 'b'.repeat(32),
         dsh_desktop_windows_key_container: 'case-insensitive-stale-container',
       }
       expect(loadDesktopPackageEnvironment('win32', parent, directory)).toEqual({
@@ -49,6 +76,23 @@ describe('Desktop local packaging configuration', () => {
     })
   })
 
+  it.each(['win32', 'darwin'] as const)('owns the %s release ID in its platform file', async (platform) => {
+    await withDirectory(async (directory) => {
+      const settings = Object.entries(RELEASE).map(([name, value]) => `${name}='${value}'`).join('\n') + '\n'
+      const file = join(directory, platform === 'win32' ? '.env.windows' : '.env.macos')
+      const parent = { DOWNLOAD_TEST_RELEASE_ID: 'a'.repeat(32) }
+      await writeFile(file, settings)
+      expect(loadDesktopPackageEnvironment(platform, parent, directory).DOWNLOAD_TEST_RELEASE_ID).toBe(RELEASE.DOWNLOAD_TEST_RELEASE_ID)
+      await writeFile(file, settings.replace(`DOWNLOAD_TEST_RELEASE_ID='${RELEASE.DOWNLOAD_TEST_RELEASE_ID}'\n`, ''))
+      const missing = loadDesktopPackageEnvironment(platform, parent, directory)
+      expect(missing.DOWNLOAD_TEST_RELEASE_ID).toBeUndefined()
+      expect(() => {
+        validateDesktopPackageEnvironment(missing, platform === 'win32' ? WINDOWS : MACOS)
+      }).toThrow(/DOWNLOAD_TEST_RELEASE_ID/u)
+      expect(parent.DOWNLOAD_TEST_RELEASE_ID).toBe('a'.repeat(32))
+    })
+  })
+
   it('loads mandatory update origins and options only from the platform file without changing its parent', async () => {
     await withDirectory(async (directory) => {
       const windowsPolicy = JSON.stringify({ intervalMs: 5000, allowedPageOrigins: ['https://download.example.invalid'] })
diff --git a/apps/desktop/tests/desktop-upload-plan.spec.ts b/apps/desktop/tests/desktop-upload-plan.spec.ts
index d65a44a923..bf4d68843c 100644
--- a/apps/desktop/tests/desktop-upload-plan.spec.ts
+++ b/apps/desktop/tests/desktop-upload-plan.spec.ts
@@ -12,6 +12,7 @@ import type { DesktopPackageTargetName } from '../scripts/package-target.ts'
 const temporaryDirectories: string[] = []
 const TEST_ORIGIN = 'https://desktop-updates.example.com'
 const TEST_BUCKET = 'test-download-bucket'
+const RELEASE_ID = '0123456789abcdef0123456789abcdef'
 const PRODUCTION_BUCKET = 'production-download-bucket'
 const require = createRequire(import.meta.url)
 const { createBlockmap } = require('app-builder-lib/out/targets/differentialUpdateInfoBuilder.js') as {
@@ -54,7 +55,7 @@ async function fixture(
     target,
     version,
     environment,
-    publicUrl: `${origin}/dsh-desk/feeds/${target}/`,
+    publicUrl: `${origin}/dsh-desk/${environment === 'test' ? `${RELEASE_ID}/` : ''}feeds/${target}/`,
   })}\n`)
 
   if (os === 'mac') {
@@ -64,6 +65,7 @@ async function fixture(
     await writeFile(join(artifactsRoot, `${base}.dmg`), 'notarized DMG fixture')
     await writeFile(join(artifactsRoot, desktopUpdateMetadataFilename(version, 'darwin')), `${JSON.stringify({
       version,
+      path: `${base}.zip`,
       files: [{ url: `${base}.zip`, size: Buffer.byteLength(zip), sha512: digest(zip) }],
     })}\n`)
   }
@@ -75,6 +77,7 @@ async function fixture(
     expect(Object.hasOwn(info, 'blockMapSize')).toBe(false)
     await writeFile(join(artifactsRoot, desktopUpdateMetadataFilename(version, 'win32')), `${JSON.stringify({
       version,
+      path: `${base}.exe`,
       files: [{
         url: `${base}.exe`,
         ...info,
@@ -89,6 +92,7 @@ async function fixture(
       ? {
         DSH_DESKTOP_AUTO_UPDATE_ENV: 'test',
         DOWNLOAD_TEST_ORIGIN: TEST_ORIGIN,
+        DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID,
         DOWNLOAD_TEST_COS_BUCKET: TEST_BUCKET,
       }
       : {
@@ -132,7 +136,7 @@ describe('desktop upload plan', () => {
     expect(plan).toMatchObject({
       environment: 'test',
       version: '1.2.3',
-      publicUrl: 'https://desktop-updates.example.com/dsh-desk/feeds/mac-arm64/',
+      publicUrl: `https://desktop-updates.example.com/dsh-desk/${RELEASE_ID}/feeds/mac-arm64/`,
       bucket: TEST_BUCKET,
     })
     expect(plan.artifacts.map(artifact => artifact.filename)).toEqual([
@@ -147,6 +151,34 @@ describe('desktop upload plan', () => {
     })
   })
 
+  it.each(['mac-arm64', 'mac-x64', 'win-x64'] as const)('publishes every %s object and YAML reference inside the test release directory', async (target) => {
+    const paths = await fixture(target)
+    const plan = await createDesktopUploadPlan(target, paths)
+    const prefix = `dsh-desk/${RELEASE_ID}`
+    const payload = plan.artifacts.find(artifact => artifact.filename.endsWith(target === 'win-x64' ? '.exe' : '.zip'))!
+    for (const artifact of plan.artifacts) {
+      expect(artifact.key).toBe(`${prefix}/${artifact.channelMetadata ? 'feeds' : 'bin'}/${target}/${artifact.filename}`)
+      if (artifact.channelMetadata) {
+        expect(load(artifact.contents!)).toMatchObject({
+          path: `${TEST_ORIGIN}/${payload.key}`,
+          files: [{ url: `${TEST_ORIGIN}/${payload.key}` }],
+        })
+      }
+    }
+    await expect(JSON.stringify(plan.artifacts.map(({ key, contents }) => ({ key, contents })), null, 2) + '\n')
+      .toMatchFileSnapshot(`./expected/test-release-upload-${target}.json`)
+  })
+
+  it('rejects a changed or missing release ID before uploading a completed package', async () => {
+    const paths = await fixture('mac-arm64')
+    await expect(createDesktopUploadPlan('mac-arm64', {
+      ...paths, environment: { ...paths.environment, DOWNLOAD_TEST_RELEASE_ID: 'a'.repeat(32) },
+    })).rejects.toThrow(/completion record/u)
+    await expect(createDesktopUploadPlan('mac-arm64', {
+      ...paths, environment: { ...paths.environment, DOWNLOAD_TEST_RELEASE_ID: undefined },
+    })).rejects.toThrow(/DOWNLOAD_TEST_RELEASE_ID/u)
+  })
+
   it('uploads the prerelease channel metadata emitted by electron-builder', async () => {
     const paths = await fixture('mac-arm64', '1.2.3-alpha.4')
     const plan = await createDesktopUploadPlan('mac-arm64', paths)
@@ -193,6 +225,7 @@ describe('desktop upload plan', () => {
       environment: {
         DSH_DESKTOP_AUTO_UPDATE_ENV: 'test',
         DOWNLOAD_TEST_ORIGIN: TEST_ORIGIN,
+        DOWNLOAD_TEST_RELEASE_ID: RELEASE_ID,
         DOWNLOAD_TEST_COS_BUCKET: TEST_BUCKET,
       },
     })).rejects.toThrow(/completion record.*test/u)
diff --git a/apps/desktop/tests/expected/application-menu-en-US.json b/apps/desktop/tests/expected/application-menu-en-US.json
new file mode 100644
index 0000000000..af72c9b264
--- /dev/null
+++ b/apps/desktop/tests/expected/application-menu-en-US.json
@@ -0,0 +1,18 @@
+[
+  {
+    "role": "hide",
+    "label": "Hide DeepSeek Harness"
+  },
+  {
+    "role": "hideOthers",
+    "label": "Hide Others"
+  },
+  {
+    "role": "unhide",
+    "label": "Show All"
+  },
+  {
+    "role": "quit",
+    "label": "Quit DeepSeek Harness"
+  }
+]
diff --git a/apps/desktop/tests/expected/application-menu-zh-CN.json b/apps/desktop/tests/expected/application-menu-zh-CN.json
new file mode 100644
index 0000000000..991b9d7639
--- /dev/null
+++ b/apps/desktop/tests/expected/application-menu-zh-CN.json
@@ -0,0 +1,18 @@
+[
+  {
+    "role": "hide",
+    "label": "隐藏 DeepSeek Harness"
+  },
+  {
+    "role": "hideOthers",
+    "label": "隐藏其他"
+  },
+  {
+    "role": "unhide",
+    "label": "显示全部"
+  },
+  {
+    "role": "quit",
+    "label": "退出 DeepSeek Harness"
+  }
+]
diff --git a/apps/desktop/tests/expected/test-release-upload-mac-arm64.json b/apps/desktop/tests/expected/test-release-upload-mac-arm64.json
new file mode 100644
index 0000000000..515f0234f9
--- /dev/null
+++ b/apps/desktop/tests/expected/test-release-upload-mac-arm64.json
@@ -0,0 +1,19 @@
+[
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.dmg"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.zip"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.zip.blockmap"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-arm64/nightly-mac.yml",
+    "contents": "version: 1.2.3\npath: >-\n  https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.zip\nfiles:\n  - url: >-\n      https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.zip\n    size: 24\n    sha512: >-\n      IgtiHRPFjickTxiSTW6k0ltyBNOF/gpMGj/xflzVV2iRIzUSFPY6BG45u9fR4GmAJSVtN+FMh3NZx7mddUfJLw==\n"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-arm64/latest-mac.yml",
+    "contents": "version: 1.2.3\npath: >-\n  https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.zip\nfiles:\n  - url: >-\n      https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-arm64/deepseek-harness-1.2.3-mac-arm64.zip\n    size: 24\n    sha512: >-\n      IgtiHRPFjickTxiSTW6k0ltyBNOF/gpMGj/xflzVV2iRIzUSFPY6BG45u9fR4GmAJSVtN+FMh3NZx7mddUfJLw==\n"
+  }
+]
diff --git a/apps/desktop/tests/expected/test-release-upload-mac-x64.json b/apps/desktop/tests/expected/test-release-upload-mac-x64.json
new file mode 100644
index 0000000000..5039a3aede
--- /dev/null
+++ b/apps/desktop/tests/expected/test-release-upload-mac-x64.json
@@ -0,0 +1,19 @@
+[
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.dmg"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.zip"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.zip.blockmap"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-x64/nightly-mac.yml",
+    "contents": "version: 1.2.3\npath: >-\n  https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.zip\nfiles:\n  - url: >-\n      https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.zip\n    size: 24\n    sha512: >-\n      IgtiHRPFjickTxiSTW6k0ltyBNOF/gpMGj/xflzVV2iRIzUSFPY6BG45u9fR4GmAJSVtN+FMh3NZx7mddUfJLw==\n"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-x64/latest-mac.yml",
+    "contents": "version: 1.2.3\npath: >-\n  https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.zip\nfiles:\n  - url: >-\n      https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/mac-x64/deepseek-harness-1.2.3-mac-x64.zip\n    size: 24\n    sha512: >-\n      IgtiHRPFjickTxiSTW6k0ltyBNOF/gpMGj/xflzVV2iRIzUSFPY6BG45u9fR4GmAJSVtN+FMh3NZx7mddUfJLw==\n"
+  }
+]
diff --git a/apps/desktop/tests/expected/test-release-upload-win-x64.json b/apps/desktop/tests/expected/test-release-upload-win-x64.json
new file mode 100644
index 0000000000..cb60e0ce29
--- /dev/null
+++ b/apps/desktop/tests/expected/test-release-upload-win-x64.json
@@ -0,0 +1,16 @@
+[
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/win-x64/deepseek-harness-1.2.3-win-x64.exe"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/bin/win-x64/deepseek-harness-1.2.3-win-x64.exe.blockmap"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/feeds/win-x64/nightly.yml",
+    "contents": "version: 1.2.3\npath: >-\n  https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/win-x64/deepseek-harness-1.2.3-win-x64.exe\nfiles:\n  - url: >-\n      https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/win-x64/deepseek-harness-1.2.3-win-x64.exe\n    size: 30\n    sha512: >-\n      eVumVOW1yvT3fAgGKUnliEzSfhmn8jUfzpNaUPufU1yekWrwJe8wRPC+JOrHH2Hmc/eLynwxjX1yIiER8tVOTA==\n"
+  },
+  {
+    "key": "dsh-desk/0123456789abcdef0123456789abcdef/feeds/win-x64/latest.yml",
+    "contents": "version: 1.2.3\npath: >-\n  https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/win-x64/deepseek-harness-1.2.3-win-x64.exe\nfiles:\n  - url: >-\n      https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/bin/win-x64/deepseek-harness-1.2.3-win-x64.exe\n    size: 30\n    sha512: >-\n      eVumVOW1yvT3fAgGKUnliEzSfhmn8jUfzpNaUPufU1yekWrwJe8wRPC+JOrHH2Hmc/eLynwxjX1yIiER8tVOTA==\n"
+  }
+]
diff --git a/apps/desktop/tests/fixtures/local-updater.mjs b/apps/desktop/tests/fixtures/local-updater.mjs
index 060000fc35..a88c08b881 100644
--- a/apps/desktop/tests/fixtures/local-updater.mjs
+++ b/apps/desktop/tests/fixtures/local-updater.mjs
@@ -1,5 +1,8 @@
 /** Actual Electron HTTP/download qualification; installer execution is forbidden. */
+import { mandatoryFrame } from './mandatory-frame.mjs'
+import { setTimeout as delay } from 'node:timers/promises'
 import assert from 'node:assert/strict'
+import { once } from 'node:events'
 import fs from 'node:fs'
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { join, sep } from 'node:path'
@@ -225,13 +228,14 @@ async function main() {
     })
     await scenario('mandatory-real-window-policy-download-retry-and-clear', async () => {
       protocol.handle('dsh-app', async request => {
+        if (new URL(request.url).hostname === 'app') return new Response('<!doctype html><title>Updater qualification</title>', { headers: { 'content-type': 'text/html' } })
         const path = new URL(request.url).pathname.slice(1)
-        assert.ok(['mandatory-update.html', 'mandatory-update.js', 'mandatory-update.css', 'update-dialog.css'].includes(path))
+        assert.ok(['mandatory-update-frame.js', 'mandatory-update.html', 'mandatory-update.js', 'mandatory-update.css', 'update-dialog.css'].includes(path))
         const mime = path.endsWith('.js') ? 'text/javascript' : path.endsWith('.css') ? 'text/css' : 'text/html'
         return new Response(await readFile(new URL(`../../renderer/${path}`, import.meta.url)), { headers: { 'content-type': mime } })
       })
-      const parent = new BrowserWindow({ show: true, width: 900, height: 650 })
-      await parent.loadURL('data:text/html;charset=utf-8,<title>Local updater qualification</title>')
+      const parent = new BrowserWindow({ show: true, width: 900, height: 650, webPreferences: { preload: fileURLToPath(new URL('../../lib/preload-app.cjs', import.meta.url)), sandbox: true, contextIsolation: true } })
+      await parent.loadURL('dsh-app://app/')
       const f = await fixture('hold-download')
       const config = resolveDesktopPolicyConfig({ origin: server.url, allowedPageOrigins: ['https://downloads.example.com'],
         intervalMs: 600_000, timeoutMs: 1000 }, true)
@@ -262,51 +266,46 @@ async function main() {
         server.policy('force')
         await policy.check('launch')
         const window = modal.confirmationWindow
-        assert.ok(window?.isModal())
+        assert.ok(window)
+        const contents = process.platform === 'win32' ? await mandatoryFrame(parent) : window.webContents
+        assert.equal(window.isModal(), false)
+        assert.equal(parent.isEnabled(), true)
         window.webContents.on('console-message', event => { console.log('mandatory renderer:', event.message) })
         window.webContents.on('preload-error', (_event, _path, error) => { console.error('mandatory preload:', error) })
         async function until(expression) {
-          try { return await window.webContents.executeJavaScript(`new Promise((resolve, reject) => {
+          try { return await contents.executeJavaScript(`new Promise((resolve, reject) => {
             const observer = new MutationObserver(check);
             const deadline = setTimeout(() => { observer.disconnect(); reject(new Error('Modal DOM condition timed out')); }, 10000);
             function check() { if (${expression}) { observer.disconnect(); clearTimeout(deadline); resolve(true); } }
             observer.observe(document, { subtree: true, childList: true, attributes: true, characterData: true }); check();
           })`) } catch (error) {
-            console.error('Modal condition:', expression, await window.webContents.executeJavaScript('({ url: location.href, text: document.body?.innerText, bridge: typeof window.dshMandatoryUpdate })'))
+            console.error('Modal condition:', expression, await contents.executeJavaScript('({ url: location.href, text: document.body?.innerText, bridge: typeof window.dshMandatoryUpdate })'))
             throw error
           }
         }
         await until("document.getElementById('title')?.textContent === '需要更新'")
-        assert.equal(await window.webContents.executeJavaScript("document.querySelector('#title b') === null"), true)
+        assert.equal(await contents.executeJavaScript("document.querySelector('#title b') === null"), true)
         if (process.platform === 'win32') {
-          assert.equal(window.isMovable(), true)
-          assert.equal(window.isResizable(), true)
-          assert.equal(window.isMaximizable(), true)
-          const bounds = window.getBounds()
-          window.setPosition(bounds.x + 20, bounds.y + 20)
-          assert.notDeepEqual(window.getBounds(), bounds)
-          window.maximize()
-          assert.equal(window.isMaximized(), true)
-          window.unmaximize()
-          assert.equal(window.isMaximized(), false)
+          assert.equal(window, parent)
+          assert.equal(parent.getChildWindows().length, 0)
         }
-        assert.equal(await window.webContents.executeJavaScript("document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', cancelable: true }))"), false)
+        assert.equal(await contents.executeJavaScript("document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', cancelable: true }))"), false)
         assert.equal(window.isDestroyed(), false)
         assert.equal(f.installations.length, 0)
-        await window.webContents.executeJavaScript("document.getElementById('page').click()")
+        await contents.executeJavaScript("document.getElementById('page').click()")
         await until("document.getElementById('browser-message').textContent.includes('无法打开浏览器')")
         assert.deepEqual(opened, ['https://downloads.example.com/desktop'])
-        await window.webContents.executeJavaScript("document.getElementById('copy').click()")
+        await contents.executeJavaScript("document.getElementById('copy').click()")
         await copyComplete.promise
         await until("document.getElementById('copy').textContent === '已复制链接'")
         assert.deepEqual(copied, opened)
         await f.coordinator.check()
         modal.sync()
         await until("!document.getElementById('update').hidden")
-        await window.webContents.executeJavaScript("document.getElementById('update').click()")
+        await contents.executeJavaScript("document.getElementById('update').click()")
         await server.arrived()
         assert.equal(f.coordinator.state.phase, 'downloading')
-        assert.equal(await window.webContents.executeJavaScript("document.getElementById('page').hidden"), true)
+        assert.equal(await contents.executeJavaScript("document.getElementById('page').hidden"), true)
         server.release()
         await until("document.getElementById('update').textContent === '停止任务并更新' && !document.getElementById('update').disabled")
         assert.equal(f.installations.length, 0)
@@ -314,14 +313,14 @@ async function main() {
         server.policy('stall')
         await policy.check('manual', true)
         assert.equal(window.isDestroyed(), false)
-        assert.equal(await window.webContents.executeJavaScript("document.getElementById('error').hidden"), true)
-        const snapshot = await window.webContents.executeJavaScript(`({
+        assert.equal(await contents.executeJavaScript("document.getElementById('error').hidden"), true)
+        const snapshot = await contents.executeJavaScript(`({
           title: document.getElementById('title').textContent, detail: document.getElementById('detail').textContent,
           status: document.getElementById('status').textContent, version: document.getElementById('version').textContent,
           buttons: [...document.querySelectorAll('button')].filter(button => button.getClientRects().length > 0).map(button => button.textContent),
         })`)
         assert.deepEqual(snapshot, JSON.parse(await readFile(new URL('../expected/mandatory-update-zh.json', import.meta.url), 'utf8')))
-        await window.webContents.executeJavaScript("document.getElementById('later').click()")
+        await contents.executeJavaScript("document.getElementById('later').click()")
         await until("document.getElementById('update').textContent === '继续安装更新' && !document.getElementById('update').disabled")
         assert.equal(f.installations.length, 0)
         let capture
@@ -333,19 +332,19 @@ async function main() {
         }
         const restartRequested = Promise.withResolvers()
         f.restart(async () => { restartRequested.resolve(); return false })
-        await window.webContents.executeJavaScript("document.getElementById('update').click()")
+        await contents.executeJavaScript("document.getElementById('update').click()")
         await restartRequested.promise
         await until("!document.getElementById('update').disabled")
         assert.equal(f.installations.length, 0)
         assert.equal(policy.state.blocking, true)
         f.restart(async () => { throw new DesktopUpdatePreparationError('stop-failed', resolveDesktopLocale('zh-CN').messages.updateStopFailed,
           'exit 0; shutdown acknowledged false') })
-        await window.webContents.executeJavaScript("document.getElementById('update').click()")
+        await contents.executeJavaScript("document.getElementById('update').click()")
         await until("!document.getElementById('technical-details').hidden && !document.getElementById('update').disabled")
-        assert.equal(await window.webContents.executeJavaScript("document.getElementById('technical-details').open"), false)
+        assert.equal(await contents.executeJavaScript("document.getElementById('technical-details').open"), false)
         for (const expanded of [false, true]) {
           if (expanded) {
-            assert.equal(await window.webContents.executeJavaScript("document.getElementById('technical-details-label').click(); document.getElementById('technical-details').open"), true)
+            assert.equal(await contents.executeJavaScript("document.getElementById('technical-details-label').click(); document.getElementById('technical-details').open"), true)
           }
           const name = expanded ? 'mandatory-error-expanded.png' : 'mandatory-error-collapsed.png'
           await writeFile(join(root, name), (await window.webContents.capturePage()).toPNG())
@@ -354,14 +353,20 @@ async function main() {
         assert.equal(policy.state.blocking, true)
         assert.equal(f.installations.length, 0)
         server.policy('clear')
+        const closed = process.platform === 'win32' ? undefined : once(window, 'closed')
         await policy.check('manual', true)
-        assert.equal(window.isDestroyed(), true)
+        if (closed) { await closed; assert.equal(window.isDestroyed(), true) }
+        else {
+          const deadline = Date.now() + 10000
+          while (!contents.detached && Date.now() < deadline) await delay(20)
+          assert.equal(contents.detached, true)
+        }
         assert.equal(parent.isDestroyed(), false)
       } finally {
         server.release()
+        parent.destroy()
         modal.dispose()
         await policy.dispose()
-        parent.destroy()
         shell.openExternal = originalOpen
         clipboard.writeText = originalCopy
         clipboard.readText = originalRead
diff --git a/apps/desktop/tests/fixtures/mandatory-frame.mjs b/apps/desktop/tests/fixtures/mandatory-frame.mjs
new file mode 100644
index 0000000000..797d3373f7
--- /dev/null
+++ b/apps/desktop/tests/fixtures/mandatory-frame.mjs
@@ -0,0 +1,35 @@
+import { WINDOWS_TITLEBAR_HEIGHT } from '../../lib/types/windows-layout.js'
+import { setTimeout as delay } from 'node:timers/promises'
+
+export async function mandatoryFrame(parent) {
+  const deadline = Date.now() + 10000
+  while (Date.now() < deadline) {
+    const frame = parent.webContents.mainFrame.frames.find(frame => frame.url === 'dsh-app://shell/mandatory-update.html')
+    if (frame && await frame.executeJavaScript("document.readyState === 'complete'")) return frame
+    await delay(20)
+  }
+  throw new Error('Mandatory update frame did not load')
+}
+
+export async function mandatoryFrameDriver(parent) {
+  const frame = await mandatoryFrame(parent)
+  if (!parent.webContents.debugger.isAttached()) parent.webContents.debugger.attach('1.3')
+  const contents = new Proxy(parent.webContents, { get(target, key) {
+    if (key === 'executeJavaScript') return frame.executeJavaScript.bind(frame)
+    if (key === 'sendInputEvent') return event => {
+      if (typeof event.y !== 'number') return target.sendInputEvent(event)
+      return target.debugger.sendCommand('Input.dispatchMouseEvent', {
+        type: event.type === 'mouseDown' ? 'mousePressed' : event.type === 'mouseUp' ? 'mouseReleased' : 'mouseMoved',
+        x: event.x, y: event.y + WINDOWS_TITLEBAR_HEIGHT, button: event.button ?? 'none', clickCount: event.clickCount ?? 0,
+      })
+    }
+    const value = Reflect.get(target, key)
+    return typeof value === 'function' ? value.bind(target) : value
+  } })
+  return new Proxy(parent, { get(target, key) {
+    if (key === 'webContents') return contents
+    if (key === 'isDestroyed') return () => frame.detached
+    const value = Reflect.get(target, key)
+    return typeof value === 'function' ? value.bind(target) : value
+  } })
+}
diff --git a/apps/desktop/tests/fixtures/workspace-updates.mjs b/apps/desktop/tests/fixtures/workspace-updates.mjs
index f6302750d9..51e930cb2f 100644
--- a/apps/desktop/tests/fixtures/workspace-updates.mjs
+++ b/apps/desktop/tests/fixtures/workspace-updates.mjs
@@ -1,4 +1,6 @@
+import { WINDOWS_TITLEBAR_HEIGHT } from '../../lib/types/windows-layout.js'
 /** Real Electron main entry, preload, shared Web Host, and local updater; no installer executes. */
+import { mandatoryFrameDriver } from './mandatory-frame.mjs'
 import assert from 'node:assert/strict'
 import { registerHooks } from 'node:module'
 import { appendFile, readFile, writeFile } from 'node:fs/promises'
@@ -95,6 +97,9 @@ async function documentReady(window, expression) {
   })`))
 }
 async function windowAt(url) {
+  if (process.platform === 'win32' && url === 'dsh-app://shell/mandatory-update.html') {
+    return mandatoryFrameDriver(await windowAt('dsh-app://app/'))
+  }
   const existing = BrowserWindow.getAllWindows().find(window => window.webContents.getURL() === url)
   if (existing) return existing
   return new Promise((resolve, reject) => {
@@ -146,13 +151,15 @@ async function press(window, expression) {
     if (!target.contains(document.elementFromPoint(point.x, point.y))) throw new Error('Click target is obscured');
     return point;
   })()`))
-  window.webContents.sendInputEvent({ type: 'mouseMove', ...point })
-  window.webContents.sendInputEvent({ type: 'mouseDown', button: 'left', clickCount: 1, ...point })
-  window.webContents.sendInputEvent({ type: 'mouseUp', button: 'left', clickCount: 1, ...point })
+  await window.webContents.sendInputEvent({ type: 'mouseMove', ...point })
+  await window.webContents.sendInputEvent({ type: 'mouseDown', button: 'left', clickCount: 1, ...point })
+  await window.webContents.sendInputEvent({ type: 'mouseUp', button: 'left', clickCount: 1, ...point })
 }
 async function clickText(window, label) {
+  const title = await window.webContents.executeJavaScript("document.getElementById('title').textContent")
   await press(window, `[...document.querySelectorAll('button')].find(button => button.textContent.trim() === ${JSON.stringify(label)})`)
-  await waitFor(() => window.isDestroyed(), `dialog response: ${label}`)
+  await waitFor(async () => window.isDestroyed()
+    || await window.webContents.executeJavaScript("document.getElementById('title').textContent") !== title, `dialog response: ${label}`)
 }
 async function dialogWith(message) {
   let found
@@ -173,9 +180,9 @@ async function qualify() {
   try {
     await import(entry)
     console.log('workspace qualification: compiled main module loaded')
-    const applicationUrl = await fixture.ready.promise
+    await fixture.ready.promise
     console.log('workspace qualification: Host process ready')
-    mainWindow = await windowAt(new URL('/', applicationUrl).href)
+    mainWindow = await windowAt('dsh-app://app/')
     await documentReady(mainWindow, `document.querySelector('[class*="frame"]') && window.dshDesktop?.updates`)
     assert.equal(mainWindow.isVisible(), true, 'Workspace qualification requires a visible application window')
     console.log('workspace qualification: workspace document ready')
@@ -187,7 +194,15 @@ async function qualify() {
     console.log('workspace qualification: startup API requests settled')
     const messages = resolveDesktopLocale(app.getLocale()).messages
     await screenshot(mainWindow, 'workspace.png')
-    const menu = Menu.getApplicationMenu().items[0].submenu.items
+    let menu
+    if (process.platform === 'win32') {
+      const popup = Menu.prototype.popup
+      try {
+        Menu.prototype.popup = function (options) { menu = this.items; options.callback?.() }
+        await mainWindow.webContents.executeJavaScript("document.querySelector('[data-windows-menu]').shadowRoot.querySelector('button').click()")
+        await waitFor(() => menu !== undefined, 'Windows application menu')
+      } finally { Menu.prototype.popup = popup }
+    } else menu = Menu.getApplicationMenu().items[0].submenu.items
     const checkMenu = menu.find(item => item.label === messages.checkUpdatesMenu)
     assert.ok(checkMenu)
     if (interactive) {
@@ -203,9 +218,8 @@ async function qualify() {
     const checking = await dialogWith(messages.updateChecking)
     await screenshot(checking, 'checking.png')
     server.release()
-    await waitFor(() => checking.isDestroyed(), 'checking dialog to close')
-    console.log('workspace qualification: checking dialog closed')
     const current = await dialogWith(messages.updateCurrent.replace('{version}', app.getVersion()))
+    assert.equal(current, checking)
     await clickText(current, messages.updateAcknowledge)
     assert.equal(server.requests.filter(path => path === '/payload.exe').length, 0)
     cases.push('native-menu-checking-and-current-without-download')
@@ -272,16 +286,21 @@ async function qualify() {
     await documentReady(mandatory, `document.getElementById('title')?.textContent === '需要更新'`)
     console.log('workspace qualification: mandatory title rendered')
     assert.equal(await mandatory.webContents.executeJavaScript(`document.getElementById('title').children.length`), 0)
-    assert.equal(mandatory.isMovable(), true)
-    assert.equal(mandatory.isResizable(), true)
-    assert.equal(mandatory.isMaximizable(), true)
-    const originalBounds = mandatory.getBounds()
-    mandatory.setPosition(originalBounds.x + 20, originalBounds.y + 20)
-    assert.notDeepEqual(mandatory.getBounds(), originalBounds)
-    mandatory.maximize()
-    await waitFor(() => mandatory.isMaximized(), 'mandatory maximize')
-    mandatory.unmaximize()
-    await waitFor(() => !mandatory.isMaximized(), 'mandatory restore')
+    assert.equal(mandatory.isModal(), false)
+    await waitFor(() => mainWindow.isEnabled(), 'ordinary modal releases the main window')
+    assert.equal(mainWindow.isEnabled(), true)
+    if (process.platform === 'win32') assert.equal(mainWindow.getChildWindows().length, 0)
+    const originalBounds = mainWindow.getBounds()
+    mainWindow.setPosition(originalBounds.x + 20, originalBounds.y + 20)
+    mainWindow.maximize()
+    await waitFor(() => mainWindow.isMaximized(), 'blocked parent maximize')
+    mainWindow.unmaximize()
+    await waitFor(() => !mainWindow.isMaximized(), 'blocked parent restore')
+    if (process.platform === 'win32') {
+      const viewport = await mandatory.webContents.executeJavaScript('({ width: innerWidth, height: innerHeight })')
+      const bounds = mainWindow.getContentBounds()
+      assert.deepEqual(viewport, { width: bounds.width, height: bounds.height - WINDOWS_TITLEBAR_HEIGHT })
+    }
     mandatory.webContents.sendInputEvent({ type: 'keyDown', keyCode: 'Escape' })
     mandatory.webContents.sendInputEvent({ type: 'keyUp', keyCode: 'Escape' })
     assert.equal((await control('status')).queued, 1)
@@ -329,7 +348,8 @@ async function qualify() {
 
     server.policy('force')
     checkMenu.click()
-    const forcedRecovery = await windowAt('dsh-app://shell/mandatory-update.html')
+    let forcedRecovery = await windowAt('dsh-app://shell/mandatory-update.html')
+    await waitFor(() => mainWindow.isEnabled(), 'ordinary modal releases the main window for recovery')
     await press(forcedRecovery, `document.getElementById('update')`)
     await documentReady(forcedRecovery, `document.getElementById('update')?.textContent === ${JSON.stringify(messages.installAndRestart)}`)
     assert.equal(BrowserWindow.getAllWindows().some(window => window.webContents.getURL() === 'dsh-app://shell/update-dialog.html'), false)
@@ -340,7 +360,11 @@ async function qualify() {
     await documentReady(forcedRecovery, `document.getElementById('error')?.textContent === ${JSON.stringify(messages.updateStopFailed)}`)
     await screenshot(forcedRecovery, 'mandatory-stop-failure.png')
     await waitFor(() => fixture.host !== forcedHost && fixture.readyHosts.has(fixture.host), 'mandatory replacement Host readiness')
-    assert.equal(mainWindow.isEnabled(), false)
+    if (process.platform === 'win32') {
+      await waitFor(() => forcedRecovery.isDestroyed(), 'recovery reload replaces the embedded document')
+      forcedRecovery = await mandatoryFrameDriver(mainWindow)
+    }
+    assert.equal(mainWindow.isEnabled(), true)
     assert.equal(fixture.installations.length, 0)
     await control('queue')
     await press(forcedRecovery, `document.getElementById('update')`)
@@ -349,7 +373,7 @@ async function qualify() {
     await press(forcedRecovery, `document.getElementById('later')`)
     await waitFor(() => fixture.coordinator.state.phase === 'ready', 'mandatory deferred retry readiness')
     assert.equal(forcedRecovery.isDestroyed(), false)
-    assert.equal(mainWindow.isEnabled(), false)
+    assert.equal(mainWindow.isEnabled(), true)
     assert.equal(fixture.installations.length, 0)
     server.policy('clear')
     checkMenu.click()
diff --git a/apps/desktop/tests/host-update-tasks.spec.ts b/apps/desktop/tests/host-update-tasks.spec.ts
index 086aaa9a26..7e1ccc4663 100644
--- a/apps/desktop/tests/host-update-tasks.spec.ts
+++ b/apps/desktop/tests/host-update-tasks.spec.ts
@@ -1,16 +1,41 @@
 import { Context } from '@deepseek-ai/cordis'
+import { JobId, JobRegistry } from '@deepseek-ai/dsh-jobs'
+import type { JobStatus, JobView } from '@deepseek-ai/dsh-jobs'
+import { SessionId } from '@deepseek-ai/dsh-session/types'
 import { Readable } from 'node:stream'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { installDesktopUpdateTaskControl } from '../../desktop-host/src/update-tasks.ts'
 
-type AgentState = { status: 'idle' | 'running'; inbox: { nextTurn: object[]; nextStep: object[] } }
-type JobState = { status: 'running' | 'stopping' | 'finished' }
+type AgentState = { id: SessionId; status: 'idle' | 'running'; inbox: { nextTurn: object[]; nextStep: object[] } }
 
 let ctx: Context
 let inspect: ReturnType<typeof installDesktopUpdateTaskControl>
 const agents: AgentState[] = []
-const jobs = new Map<AgentState | undefined, JobState[]>()
+const jobs = new Map<SessionId | undefined, JobStatus[]>()
+
+/** A registry whose only served member is the per-owner roster the inspector reads. */
+class RosterOnlyJobRegistry extends JobRegistry {
+  readonly events = { subscribe: () => () => {} }
+  start(): never { throw new Error('unsupported') }
+  list(caller?: SessionId): JobView[] {
+    return (jobs.get(caller) ?? []).map((status, index) => ({
+      id: JobId(`bash-${index + 1}`),
+      kind: 'bash',
+      label: 'sleep 60',
+      ...caller === undefined ? {} : { owner: caller },
+      status,
+      startedAt: 0,
+      output: { total: 0, earliest: 0 },
+    }))
+  }
+  get(): never { throw new Error('unsupported') }
+  read(): never { throw new Error('unsupported') }
+  readAt(): never { throw new Error('unsupported') }
+  kill(): never { throw new Error('unsupported') }
+  wait(): never { throw new Error('unsupported') }
+  attachController(): () => void { return () => {} }
+}
 
 beforeEach(() => {
   agents.length = 0
@@ -18,13 +43,13 @@ beforeEach(() => {
   ctx = new Context()
   // Narrow service doubles exercise the inspector against a real Cordis event lifecycle.
   ctx.provide('agents', { list: () => agents } as unknown as Context['agents'])
-  ctx.provide('jobs', { list: (agent?: AgentState) => jobs.get(agent) ?? [] } as unknown as Context['jobs'])
+  new RosterOnlyJobRegistry(ctx)
   inspect = installDesktopUpdateTaskControl(ctx)
 })
 
 afterEach(async () => { await ctx.fiber.dispose() })
 
-function idleAgent(): AgentState { return { status: 'idle', inbox: { nextTurn: [], nextStep: [] } } }
+function idleAgent(): AgentState { return { id: SessionId('update-task-owner'), status: 'idle', inbox: { nextTurn: [], nextStep: [] } } }
 
 function request(next: () => Promise<void>) {
   const incoming = Readable.from([]) as IncomingMessage
@@ -48,10 +73,10 @@ describe('Desktop Host update task protection', () => {
   it.each(['running', 'stopping'] as const)('counts global and agent-owned %s jobs', async (status) => {
     const agent = idleAgent()
     agents.push(agent)
-    for (const owner of [undefined, agent]) {
-      jobs.set(owner, [{ status }])
+    for (const owner of [undefined, agent.id]) {
+      jobs.set(owner, [status])
       expect(await inspect('inspect')).toBe(true)
-      jobs.set(owner, [{ status: 'finished' }])
+      jobs.set(owner, ['completed'])
       expect(await inspect('inspect')).toBe(false)
     }
   })
diff --git a/apps/desktop/tests/installed-update-builder.spec.ts b/apps/desktop/tests/installed-update-builder.spec.ts
index 55ad22fd5d..089b04deef 100644
--- a/apps/desktop/tests/installed-update-builder.spec.ts
+++ b/apps/desktop/tests/installed-update-builder.spec.ts
@@ -18,7 +18,7 @@ vi.mock('../scripts/windows-sign.mjs', () => ({
 }))
 
 const versions = ['0.1.6-nightly.20260914.1', '0.1.6-nightly.20260914.2'] as const
-const environment = { DSH_DESKTOP_AUTO_UPDATE_ENV: 'test', DOWNLOAD_TEST_ORIGIN: 'https://download-test.deepseek.com',
+const environment = { DSH_DESKTOP_AUTO_UPDATE_ENV: 'test', DOWNLOAD_TEST_ORIGIN: 'https://download-test.deepseek.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
   DSH_DESKTOP_MANDATORY_UPDATE_TEST_ORIGIN: 'https://policy.example.com',
   DSH_DESKTOP_MANDATORY_UPDATE_CONFIG: JSON.stringify({ allowedAuthOrigins: ['https://login.example.com'] }),
   DOWNLOAD_TEST_COS_BUCKET: 'bj-toc-download-test-1320056602' }
diff --git a/apps/desktop/tests/installed-update/README.i18n.yaml b/apps/desktop/tests/installed-update/README.i18n.yaml
index 8ea70c5cbc..036b9a3a62 100644
--- a/apps/desktop/tests/installed-update/README.i18n.yaml
+++ b/apps/desktop/tests/installed-update/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent 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/desktop/tests/installed-update/README.md
-README.md: 139a80246d6539898cc870129fe55ad726b2673d
-README.zh.md: 2b140cceb37ac104c1984c35322da0814ac365b7
+README.md: b847960862931a8c7ef769908d046cfb0f893d41
+README.zh.md: ac2bed4e2a0304f0362c36504128ff17fc5ba693
diff --git a/apps/desktop/tests/installed-update/README.md b/apps/desktop/tests/installed-update/README.md
index 139a80246d..b847960862 100644
--- a/apps/desktop/tests/installed-update/README.md
+++ b/apps/desktop/tests/installed-update/README.md
@@ -44,7 +44,7 @@ Package both files from the generated `bootstrap` directory beside `lib/`, and s
 
 The `application` command copies built main/preload modules, renderer files, and the prepared bootstrap into `application/files`, with SHA-256 values in `application/result.json`. It does not copy the app's root `.env.windows` or freeze `node_modules` and build tools. The [qualification builder configuration](../../scripts/installed-update-builder.ts) verifies this inventory and the selected private runtime, selects the shared frozen files and isolated package metadata, and preserves ordinary installer and signing hooks. Its tests substitute the signer and pass the pinned builder's configuration validator; they do not produce an installer. A separately authorized supervised build must still record dependency/tool inputs and verify final package contents and signatures.
 
-The [packaging entry](../../scripts/package-installed-update.ts) defaults to checks. A retained signing interlock rejects before credentials are loaded; it never clears that interlock. With no interlock, checks load `.env.windows`, validate prepared inputs, and launch no child. Run this from the repository root with one exact version:
+The [packaging entry](../../scripts/package-installed-update.ts) defaults to checks. A retained signing interlock rejects before credentials are loaded; it never clears that interlock. With no interlock, checks load `.env.windows`, validate prepared inputs, and launch no child. The shared builder requires a valid `DOWNLOAD_TEST_RELEASE_ID` from the [test release settings](../../README.md#upload-updates); qualification still publishes through the manifest’s separate `qualification/<id>` paths. Run this from the repository root with one exact version:
 
 ```powershell
 node --import tsx apps/desktop/scripts/package-installed-update.ts "<run.json>" 0.1.6-alpha.1.20260916.1 --check
diff --git a/apps/desktop/tests/installed-update/README.zh.md b/apps/desktop/tests/installed-update/README.zh.md
index 2b140cceb3..ac2bed4e2a 100644
--- a/apps/desktop/tests/installed-update/README.zh.md
+++ b/apps/desktop/tests/installed-update/README.zh.md
@@ -44,7 +44,7 @@ node --import tsx apps/desktop/scripts/prepare-installed-update.ts application "
 
 `application` 命令将已构建的主程序/预加载模块、界面文件和准备好的启动入口复制到 `application/files`，并在 `application/result.json` 中记录 SHA-256。它不复制应用根目录的 `.env.windows`，也不冻结 `node_modules` 与构建工具。[验收打包配置](../../scripts/installed-update-builder.ts)校验该清单与选定的独立运行时，选用共享冻结文件和隔离包元数据，并保留常规安装器与签名钩子。其测试替换签名器，并通过固定版本构建器的配置校验；测试不生成安装器。另行授权的受监督构建仍须记录依赖/工具输入，并验证最终包内容及签名。
 
-[打包入口](../../scripts/package-installed-update.ts)默认只检查。保留的签名保护锁会在读取凭据前使其拒绝；入口绝不清除此锁。没有保护锁时，检查会加载 `.env.windows`、校验准备输入，不启动子进程。在仓库根目录使用一个准确版本执行：
+[打包入口](../../scripts/package-installed-update.ts)默认只检查。保留的签名保护锁会在读取凭据前使其拒绝；入口绝不清除此锁。没有保护锁时，检查会加载 `.env.windows`、校验准备输入，不启动子进程。共享构建器要求[测试发布配置](../../README.zh.md#upload-updates)中有效的 `DOWNLOAD_TEST_RELEASE_ID`；资格验收仍使用清单中独立的 `qualification/<id>` 路径发布。在仓库根目录使用一个准确版本执行：
 
 ```powershell
 node --import tsx apps/desktop/scripts/package-installed-update.ts "<run.json>" 0.1.6-alpha.1.20260916.1 --check
diff --git a/apps/desktop/tests/installer-packaging.spec.ts b/apps/desktop/tests/installer-packaging.spec.ts
index 1dcfcb24fd..75d6b02d7e 100644
--- a/apps/desktop/tests/installer-packaging.spec.ts
+++ b/apps/desktop/tests/installer-packaging.spec.ts
@@ -31,7 +31,7 @@ describe('installer preparation preserves application dependencies', () => {
       DSH_DESKTOP_MACOS_SIGNING_IDENTITY: 'Example Company (TEAMID1234)',
       DSH_DESKTOP_MACOS_TEAM_ID: 'TEAMID1234',
       APPLE_KEYCHAIN_PROFILE: 'installer-test',
-      DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com',
+      DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
     }
     for (const [name, value] of Object.entries(env)) vi.stubEnv(name, value)
     try {
diff --git a/apps/desktop/tests/macos-signature.spec.ts b/apps/desktop/tests/macos-signature.spec.ts
index 2bd63adbaa..6cd8faeccc 100644
--- a/apps/desktop/tests/macos-signature.spec.ts
+++ b/apps/desktop/tests/macos-signature.spec.ts
@@ -22,7 +22,7 @@ const RELEASE_ENVIRONMENT = {
   APPLE_API_KEY: '/private/credentials/AuthKey_TEST123456.p8',
   APPLE_API_KEY_ID: 'TEST123456',
   APPLE_API_ISSUER: '11111111-2222-3333-4444-555555555555',
-  DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com',
+  DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
 }
 
 function portablePath(value: string): string {
@@ -42,6 +42,7 @@ describe('desktop macOS release signature', () => {
     const { createElectronBuilderConfig } = await import('../electron-builder.config.mjs')
     const config = createElectronBuilderConfig(RELEASE_ENVIRONMENT, 'darwin', 'arm64')
     expect(portablePath(config.directories.output)).toContain('/.desktop-build/targets/mac-arm64/artifacts')
+    expect(config.mac.extendInfo.NSMicrophoneUsageDescription).toContain('microphone')
     expect(config.extraResources).toHaveLength(2)
     expect(config.extraResources[0]?.to).toBe('runtime')
     expect(portablePath(config.extraResources[0]?.from ?? '')).toContain('/.desktop-build/targets/mac-arm64/runtime')
@@ -71,7 +72,7 @@ describe('desktop macOS release signature', () => {
       },
       publish: [{
         provider: 'generic',
-        url: 'https://desktop-updates.example.com/dsh-desk/feeds/mac-arm64/',
+        url: 'https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-arm64/',
         channel: 'nightly',
       }],
     })
diff --git a/apps/desktop/tests/main-startup.spec.ts b/apps/desktop/tests/main-startup.spec.ts
index 171e3855f1..329cf5a9b8 100644
--- a/apps/desktop/tests/main-startup.spec.ts
+++ b/apps/desktop/tests/main-startup.spec.ts
@@ -62,7 +62,9 @@ const harness = await vi.hoisted(async () => {
       getZoomFactor: () => 1,
       focus: vi.fn(),
       sendInputEvent: vi.fn(),
-      send: vi.fn(),
+      send: vi.fn((channel: string, state: { policy?: { blocking: boolean } }) => {
+        if (channel === 'dsh-desktop:mandatory-state' && state.policy?.blocking) policyBlocked.resolve()
+      }),
     })
     readonly show = vi.fn()
     readonly hide = vi.fn()
@@ -70,13 +72,18 @@ const harness = await vi.hoisted(async () => {
     readonly restore = vi.fn()
     readonly setSize = vi.fn()
     readonly setTitleBarOverlay = vi.fn()
+    readonly setVibrancy = vi.fn()
+    readonly setBackgroundColor = vi.fn()
     constructor(readonly options: { show: boolean; modal?: boolean }) {
-      super(); if (windowFailure !== undefined) throw windowFailure; windows.push(this); if (options.modal) policyBlocked.resolve()
+      super(); if (windowFailure !== undefined) throw windowFailure; windows.push(this)
     }
     isDestroyed() { return this.destroyed }
     fullscreen = false
     isFullScreen() { return this.fullscreen }
-    isMinimized() { return false }
+    minimized = false
+    isMinimized() { return this.minimized }
+    visible = true
+    isVisible() { return this.visible }
     isFocused() { return true }
     async loadURL(url: string) {
       this.urls.push(url)
@@ -134,9 +141,10 @@ const harness = await vi.hoisted(async () => {
       }
     }),
   })
+  const nativeTheme = { themeSource: 'system', shouldUseDarkColors: false }
   return {
     failWindow(error: Error) { windowFailure = error },
-    windows, hosts, handlers, app, FakeWindow, FakeHost, powerMonitor,
+    windows, hosts, handlers, app, FakeWindow, FakeHost, powerMonitor, nativeTheme,
     menu, popup, socketHeaders: vi.fn(), updateCheck, updateDownload, updateInstall,
     ipcOn: vi.fn<(channel: string, listener: (event: { sender: unknown; senderFrame: unknown }, ...args: unknown[]) => void) => void>(),
     get updateState() { return updateState },
@@ -177,6 +185,7 @@ const harness = await vi.hoisted(async () => {
       updateCheck.mockReset().mockImplementation(async () => updateState)
       updateDownload.mockReset().mockImplementation(async () => updateState)
       updateInstall.mockReset().mockImplementation(async () => updateState)
+      nativeTheme.themeSource = 'system'; nativeTheme.shouldUseDarkColors = false
       preparing = deferred(); prepared = deferred(); hostStarted = deferred()
       navigated = deferred(); dialogShown = deferred(); quitCompleted = deferred()
       policyBlocked = deferred()
@@ -199,7 +208,7 @@ vi.mock('electron', () => ({
   BrowserWindow: harness.FakeWindow,
   dialog: harness.dialog,
   shell: { openExternal: harness.openExternal },
-  nativeTheme: { themeSource: 'system' },
+  nativeTheme: harness.nativeTheme,
   ipcMain: {
     on: harness.ipcOn,
     handle: (channel: string, handler: InvokeHandler) => {
@@ -209,7 +218,9 @@ vi.mock('electron', () => ({
     removeHandler: (channel: string) => { harness.handlers.delete(channel) },
   },
   Menu: { setApplicationMenu: harness.menu.setApplicationMenu, buildFromTemplate: harness.menu },
-  session: { defaultSession: { webRequest: { onBeforeSendHeaders: harness.socketHeaders } } },
+  session: { defaultSession: {
+    setPermissionCheckHandler: vi.fn(), setPermissionRequestHandler: vi.fn(), webRequest: { onBeforeSendHeaders: harness.socketHeaders },
+  } },
   protocol: { registerSchemesAsPrivileged: vi.fn(), handle: harness.protocolHandle },
   powerMonitor: harness.powerMonitor,
 }))
@@ -468,7 +479,7 @@ describe('desktop main startup', () => {
     expect(testAuth.login).not.toHaveBeenCalled()
   })
 
-  it('retains the same blocking window and running Host after expired test login is cancelled', async () => {
+  it('retains the embedded block and running Host after expired test login is cancelled', async () => {
     harness.embeddedPolicy = { origin: 'https://policy.example.com', authentication: 'feishu-test', allowedAuthOrigins: ['https://login.example.com'],
       allowedPageOrigins: ['https://downloads.example.com'], intervalMs: 1000, jitter: 0 }
     const request = vi.fn<typeof fetch>().mockImplementation(async () =>
@@ -479,7 +490,7 @@ describe('desktop main startup', () => {
     const host = await readyForUpdate()
     await harness.policyBlocked.promise
     await vi.advanceTimersByTimeAsync(1000)
-    const modal = harness.windows.find(window => window.options.modal)!
+    const modal = harness.windows[0]!
     const owned = { sender: modal.webContents, senderFrame: modal.webContents.mainFrame }
     harness.dialog.showMessageBox.mockResolvedValue({ response: 0 })
     testAuth.login.mockResolvedValueOnce('cancelled')
@@ -587,6 +598,48 @@ describe('desktop main startup', () => {
     expect(window.webContents.send.mock.calls.filter(([channel]) => channel === DESKTOP_IPC.windowFullscreen)).toHaveLength(0)
   })
 
+  it('covers the macOS vibrancy reattach gap with an opaque base while minimized or hidden', async () => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+    await import('../src/main.ts')
+    await harness.preparing.promise
+    const window = harness.windows[0]!
+    // Minimizing drops the vibrancy material and paints the theme's opaque fill.
+    window.minimized = true
+    window.emit('minimize')
+    expect(window.setVibrancy).toHaveBeenLastCalledWith(null)
+    expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#f9fafb')
+    // Restoring re-requests the material and returns to the transparent base.
+    window.minimized = false
+    window.emit('restore')
+    expect(window.setVibrancy).toHaveBeenLastCalledWith('sidebar')
+    expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#00000000')
+    // Hiding under the dark palette picks the dark opaque fill.
+    harness.nativeTheme.shouldUseDarkColors = true
+    window.visible = false
+    window.emit('hide')
+    expect(window.setVibrancy).toHaveBeenLastCalledWith(null)
+    expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#1b1b1c')
+    window.visible = true
+    window.emit('show')
+    expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#00000000')
+    // A destroyed window ends the backdrop updates.
+    const applied = window.setVibrancy.mock.calls.length
+    window.destroyed = true
+    window.emit('minimize')
+    expect(window.setVibrancy.mock.calls).toHaveLength(applied)
+  })
+
+  it.each(['win32', 'linux'] as const)('registers no backdrop swap on %s', async (platform) => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue(platform)
+    await import('../src/main.ts')
+    await harness.preparing.promise
+    const window = harness.windows[0]!
+    window.minimized = true
+    window.emit('minimize')
+    expect(window.setVibrancy).not.toHaveBeenCalled()
+    expect(window.setBackgroundColor).not.toHaveBeenCalled()
+  })
+
   it('follows the Windows primary document language and palette without trusting other frames', async () => {
     vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
     await import('../src/main.ts')
@@ -672,6 +725,22 @@ describe('desktop main startup', () => {
     expect(harness.menu.setApplicationMenu).toHaveBeenCalledOnce()
   })
 
+  it.each(['en-US', 'zh-CN'])('localizes macOS visibility and quit commands without changing the application name (%s)', async (locale) => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+    vi.spyOn(harness.app, 'getLocale').mockReturnValue(locale)
+    const originalName = harness.app.name
+    harness.app.name = '@deepseek-ai/dsh-desktop'
+    try {
+      await import('../src/main.ts')
+      await harness.preparing.promise
+      const commands = applicationMenuItems().filter(item =>
+        item.role === 'hide' || item.role === 'hideOthers' || item.role === 'unhide' || item.role === 'quit')
+      await expect(JSON.stringify(commands, null, 2) + '\n')
+        .toMatchFileSnapshot(`./expected/application-menu-${locale}.json`)
+      expect(harness.app.name).toBe('@deepseek-ai/dsh-desktop')
+    } finally { harness.app.name = originalName }
+  })
+
   it('attaches Host socket credentials only to the owned application origin and window', async () => {
     await import('../src/main.ts')
     await harness.preparing.promise
@@ -851,14 +920,15 @@ describe('desktop main startup', () => {
     vi.stubGlobal('fetch', request)
     const host = await readyForUpdate()
     await harness.policyBlocked.promise
-    const modal = harness.windows.find(window => window.options.modal)!
+    const modal = harness.windows[0]!
     expect(modal).toBeDefined()
+    expect(harness.windows).toHaveLength(1)
     const status = harness.handlers.get(MANDATORY_IPC.status)!
     const action = harness.handlers.get(MANDATORY_IPC.action)!
     const owned = { sender: modal.webContents, senderFrame: modal.webContents.mainFrame }
     expect(status(owned)).toMatchObject({ policy: { blocking: true } })
     const unowned = [
-      { ...owned, sender: harness.windows[0]!.webContents },
+      { ...owned, sender: {} },
       { ...owned, senderFrame: { url: 'dsh-app://app/index.html' } },
       { ...owned, senderFrame: { url: 'https://untrusted.example.com/' } },
     ]
@@ -883,7 +953,8 @@ describe('desktop main startup', () => {
     await vi.advanceTimersByTimeAsync(20_000)
     expect(modal.isDestroyed()).toBe(false)
     await vi.advanceTimersByTimeAsync(150)
-    expect(modal.isDestroyed()).toBe(true)
+    expect(modal.isDestroyed()).toBe(false)
+    expect(modal.webContents.send.mock.calls.at(-1)).toMatchObject([MANDATORY_IPC.state, { policy: { blocking: false } }])
     expect(host.stop).not.toHaveBeenCalled()
     expect(request.mock.calls[0]![1]!.headers).toMatchObject({ 'x-client-bundle-id': 'com.deepseek.dsh', 'x-client-version': '1.0.0' })
   })
@@ -1099,7 +1170,7 @@ describe('desktop main startup', () => {
   })
 
   async function answerMandatory(action: 'install' | 'later') {
-    const modal = harness.windows.find(window => window.options.modal && !window.isDestroyed())!
+    const modal = harness.windows[0]!
     const event = { sender: modal.webContents, senderFrame: modal.webContents.mainFrame }
     await vi.waitFor(() => {
       expect(harness.handlers.get(MANDATORY_IPC.status)!(event)).toHaveProperty('confirmation')
@@ -1108,14 +1179,14 @@ describe('desktop main startup', () => {
     await harness.handlers.get(MANDATORY_IPC.action)!(event, action, view.confirmation.version, view.confirmation.revision)
   }
 
-  it('releases the mandatory modal when the confirmed installer quits Electron', async () => {
+  it('closes the main window when the confirmed installer quits Electron', async () => {
     harness.embeddedPolicy = { origin: 'https://policy.example.com', allowedPageOrigins: ['https://downloads.example.com'] }
     vi.stubGlobal('fetch', vi.fn(async () => Response.json({ code: 40005, data: {
       show_content: { title: 'Update required', detail: 'Please update' }, desktop_app_link: 'https://downloads.example.com/',
     } })))
     const host = await readyForUpdate()
     await harness.policyBlocked.promise
-    const modal = harness.windows.find(window => window.options.modal)!
+    const modal = harness.windows[0]!
     const preparing = harness.prepareUpdate()
     await answerMandatory('install')
     await host.stopping.promise
@@ -1159,7 +1230,10 @@ describe('desktop main startup', () => {
     await expect(retry).resolves.toBe(false)
     expect(replacement.updateTasks.mock.calls).toEqual([['inspect']])
     expect(replacement.stop).not.toHaveBeenCalled()
-    if (mandatory) expect(harness.windows.find(window => window.options.modal)?.isDestroyed()).toBe(false)
+    if (mandatory) {
+      expect(harness.windows).toHaveLength(1)
+      expect(harness.windows[0]!.isDestroyed()).toBe(false)
+    }
   })
 
   it.each([false, true])('restores a confirmed non-graceful exit without approving installation, mandatory: %s', async (mandatory) => {
@@ -1193,7 +1267,10 @@ describe('desktop main startup', () => {
     await expect(retry).resolves.toBe(false)
     expect(replacement.updateTasks.mock.calls).toEqual([['inspect']])
     expect(replacement.stop).not.toHaveBeenCalled()
-    if (mandatory) expect(harness.windows.find(window => window.options.modal)?.isDestroyed()).toBe(false)
+    if (mandatory) {
+      expect(harness.windows).toHaveLength(1)
+      expect(harness.windows[0]!.isDestroyed()).toBe(false)
+    }
   })
 
   it('does not replace a Host whose failed stop has not confirmed process exit', async () => {
diff --git a/apps/desktop/tests/mandatory-update-window.spec.ts b/apps/desktop/tests/mandatory-update-window.spec.ts
index 84f9195122..a1c218852a 100644
--- a/apps/desktop/tests/mandatory-update-window.spec.ts
+++ b/apps/desktop/tests/mandatory-update-window.spec.ts
@@ -13,7 +13,7 @@ vi.mock('electron', () => ({ ipcMain: {
   handle: (channel: string, handler: (...args: unknown[]) => unknown) => native.handlers.set(channel, handler),
   removeHandler: (channel: string) => native.handlers.delete(channel),
 }, app: { quit: native.quit }, shell: { openExternal: native.open }, clipboard: { writeText: native.write, readText: native.read } }))
-vi.mock('../src/update-overlay.ts', () => ({ createMandatoryUpdateWindow: () => window }))
+vi.mock('../src/update-overlay.ts', () => ({ createUpdateOverlay: vi.fn(() => window) }))
 
 let window: ReturnType<typeof fakeWindow>
 let ui: DesktopMandatoryUpdateWindow | undefined
@@ -21,12 +21,14 @@ function fakeWindow() {
   const contents = Object.assign(new EventEmitter(), { mainFrame: { url: 'dsh-app://shell/mandatory-update.html' },
     send: vi.fn(), setWindowOpenHandler: vi.fn() })
   return Object.assign(new EventEmitter(), { webContents: contents, setMenu: vi.fn(), setTitle: vi.fn(),
-    loadURL: vi.fn(async () => {}), destroy: vi.fn(), isDestroyed: () => false,
+    loadURL: vi.fn(async () => {}), destroy: vi.fn(), isDestroyed: (): boolean => false,
     isFocused: () => true, isMinimized: () => false, focus: vi.fn(), show: vi.fn(), restore: vi.fn() })
 }
-afterEach(() => { ui?.dispose(); vi.clearAllMocks(); native.handlers.clear(); vi.useRealTimers() })
-function setup() {
+afterEach(() => { ui?.dispose(); vi.restoreAllMocks(); vi.clearAllMocks(); native.handlers.clear(); vi.useRealTimers() })
+function setup(platform: NodeJS.Platform = 'darwin') {
+  vi.spyOn(process, 'platform', 'get').mockReturnValue(platform)
   window = fakeWindow()
+  if (platform === 'win32') window.webContents.mainFrame.url = 'dsh-app://app/'
   let policy: DesktopPolicyState = { blocking: true, checking: false, page: 'https://downloads.example.com/desktop' }
   let update: DesktopUpdateState = { phase: 'ready', version: '1.0.1-nightly.1' }
   const install = vi.fn(async () => update)
@@ -42,6 +44,16 @@ function setup() {
     update(next: DesktopUpdateState) { update = next; ui!.sync() } }
 }
 
+it('releases IPC after the Windows main window has already been destroyed', () => {
+  setup('win32')
+  vi.spyOn(window, 'isDestroyed').mockReturnValue(true)
+  Object.defineProperty(window, 'webContents', { get() { throw new Error('Object has been destroyed') } })
+  expect(() => { ui!.sync(); ui!.focus() }).not.toThrow()
+  expect(() => { ui!.dispose() }).not.toThrow()
+  expect(native.handlers.size).toBe(0)
+  expect(() => { ui!.dispose() }).not.toThrow()
+})
+
 it('waits for a version-bound second click in the same modal and rejects obsolete or hidden responses', async () => {
   const f = setup()
   const pending = ui!.confirm('1.0.1-nightly.1', false)
@@ -152,3 +164,38 @@ it('fades on clearance, reuses a reblocked window, and cancels teardown on dispo
   ui!.dispose()
   expect(vi.getTimerCount()).toBe(0)
 })
+
+it('publishes Windows overlays into the main document without creating or destroying a window', () => {
+  const f = setup('win32')
+  expect(window.loadURL).not.toHaveBeenCalled()
+  expect(ui!.confirmationWindow).toBe(window)
+  expect(window.webContents.send).toHaveBeenLastCalledWith(MANDATORY_IPC.state, f.view())
+  window.webContents.emit('did-finish-load')
+  expect(window.webContents.send).toHaveBeenCalledTimes(2)
+  const event = { sender: window.webContents, senderFrame: { ...window.webContents.mainFrame } }
+  expect(() => native.handlers.get(MANDATORY_IPC.status)!(event)).toThrow(/unowned/)
+  f.policy({ blocking: false, checking: false })
+  expect(window.destroy).not.toHaveBeenCalled()
+  ui!.dispose()
+  expect(window.destroy).not.toHaveBeenCalled()
+  expect(window.webContents.listenerCount('did-finish-load')).toBe(0)
+})
+
+it('rebinds policy updates and reloads to a replacement Windows main window', () => {
+  setup('win32')
+  const previous = window
+  window = fakeWindow()
+  window.webContents.mainFrame.url = 'dsh-app://app/?recovery=1#home'
+  ui!.sync()
+  expect(previous.webContents.listenerCount('did-finish-load')).toBe(0)
+  expect(window.webContents.send.mock.calls.at(-1)).toMatchObject([MANDATORY_IPC.state, { policy: { blocking: true } }])
+  window.webContents.send.mockClear()
+  window.webContents.emit('did-finish-load')
+  expect(window.webContents.send).toHaveBeenCalledOnce()
+  expect(() => native.handlers.get(MANDATORY_IPC.status)!({
+    sender: previous.webContents, senderFrame: previous.webContents.mainFrame,
+  })).toThrow(/unowned/)
+  expect(() => native.handlers.get(MANDATORY_IPC.status)!({
+    sender: window.webContents, senderFrame: window.webContents.mainFrame,
+  })).not.toThrow()
+})
diff --git a/apps/desktop/tests/microphone-permissions.spec.ts b/apps/desktop/tests/microphone-permissions.spec.ts
new file mode 100644
index 0000000000..200a980f20
--- /dev/null
+++ b/apps/desktop/tests/microphone-permissions.spec.ts
@@ -0,0 +1,69 @@
+/** Desktop media permissions exclude external pages, subframes and camera requests. */
+import type { Session, WebContents } from 'electron'
+import { afterEach, expect, it, vi } from 'vitest'
+import { installMicrophonePermissions } from '../src/microphone-permissions.ts'
+
+const access = vi.hoisted(() => ({ getMediaAccessStatus: vi.fn(() => 'granted'), askForMediaAccess: vi.fn(async () => true) }))
+vi.mock('electron', () => ({ systemPreferences: access }))
+afterEach(() => { vi.unstubAllGlobals(); vi.resetAllMocks() })
+function fixture(platform: NodeJS.Platform = 'darwin') {
+  vi.stubGlobal('process', { ...process, platform })
+  const setPermissionCheckHandler = vi.fn<Session['setPermissionCheckHandler']>()
+  const setPermissionRequestHandler = vi.fn<Session['setPermissionRequestHandler']>()
+  const primary = {} as WebContents
+  installMicrophonePermissions({ setPermissionCheckHandler, setPermissionRequestHandler }, () => primary)
+  return { primary, check: setPermissionCheckHandler.mock.calls[0]![0]!, request: setPermissionRequestHandler.mock.calls[0]![0]! }
+}
+it('allows only audio checks from the owned primary application frame', () => {
+  const f = fixture(), details = { isMainFrame: true, mediaType: 'audio' as const }
+  expect(f.check(f.primary, 'media', 'dsh-app://app', details)).toBe(true)
+  expect(f.check(null, 'media', 'dsh-app://app', details)).toBe(false)
+  expect(f.check({} as WebContents, 'media', 'dsh-app://app', details)).toBe(false)
+  expect(f.check(f.primary, 'media', 'https://example.com', details)).toBe(false)
+  expect(f.check(f.primary, 'media', 'invalid', details)).toBe(false)
+  expect(f.check(f.primary, 'media', 'dsh-app://app', { ...details, isMainFrame: false })).toBe(false)
+  expect(f.check(f.primary, 'media', 'dsh-app://app', { ...details, mediaType: 'video' })).toBe(false)
+  expect(f.check(f.primary, 'clipboard-sanitized-write', 'dsh-app://app', details)).toBe(true)
+})
+it.each(['not-determined', 'granted', 'denied', 'restricted', 'unknown'] as const)(
+  'reports existing macOS microphone authorization for %s', (status) => {
+    const f = fixture()
+    access.getMediaAccessStatus.mockReturnValueOnce(status)
+    expect(f.check(f.primary, 'media', 'dsh-app://app', { isMainFrame: true, mediaType: 'audio' })).toBe(status === 'granted')
+    expect(access.getMediaAccessStatus).toHaveBeenCalledExactlyOnceWith('microphone')
+    expect(access.askForMediaAccess).not.toHaveBeenCalled()
+  },
+)
+it.each([true, false])('waits for the first macOS authorization decision: %s', async (allowed) => {
+  const f = fixture(), decision = Promise.withResolvers<boolean>(), done = vi.fn()
+  access.getMediaAccessStatus.mockReturnValue('not-determined')
+  access.askForMediaAccess.mockReturnValueOnce(decision.promise)
+  try {
+    f.request(f.primary, 'media', done, { isMainFrame: true, requestingUrl: 'dsh-app://app/', mediaTypes: ['audio'] })
+    expect(access.askForMediaAccess).toHaveBeenCalledExactlyOnceWith('microphone')
+    expect(done).not.toHaveBeenCalled()
+  } finally { decision.resolve(allowed); await decision.promise }
+  expect(done).toHaveBeenCalledExactlyOnceWith(allowed)
+})
+it('requests macOS microphone access and reports operating-system rejection', async () => {
+  const f = fixture(), done = vi.fn(), details = { isMainFrame: true, requestingUrl: 'dsh-app://app/', mediaTypes: ['audio'] }
+  f.request(f.primary, 'media', done, details)
+  await vi.waitFor(() => { expect(done).toHaveBeenLastCalledWith(true) })
+  expect(access.askForMediaAccess).toHaveBeenCalledWith('microphone')
+  access.askForMediaAccess.mockRejectedValueOnce(new Error('permission denied'))
+  f.request(f.primary, 'media', done, details)
+  await vi.waitFor(() => { expect(done).toHaveBeenLastCalledWith(false) })
+  for (const denied of [{ ...details, mediaTypes: ['audio', 'video'] }, { ...details, mediaTypes: [] },
+    { ...details, isMainFrame: false }, { isMainFrame: true, requestingUrl: 'dsh-app://app/' }]) {
+    f.request(f.primary, 'media', done, denied); expect(done).toHaveBeenLastCalledWith(false)
+  }
+  f.request(f.primary, 'clipboard-sanitized-write', done, details)
+  expect(done).toHaveBeenLastCalledWith(true)
+})
+it.each(['win32', 'linux'] as const)('leaves system authorization to Chromium on %s', (platform) => {
+  const f = fixture(platform), done = vi.fn()
+  expect(f.check(f.primary, 'media', 'dsh-app://app', { isMainFrame: true, mediaType: 'audio' })).toBe(true)
+  f.request(f.primary, 'media', done, { isMainFrame: true, requestingUrl: 'dsh-app://app/', mediaTypes: ['audio'] })
+  expect(done).toHaveBeenCalledWith(true)
+  expect(access.askForMediaAccess).not.toHaveBeenCalled()
+})
diff --git a/apps/desktop/tests/package-macos.spec.ts b/apps/desktop/tests/package-macos.spec.ts
index 3b780b8b06..e8fb5dcf34 100644
--- a/apps/desktop/tests/package-macos.spec.ts
+++ b/apps/desktop/tests/package-macos.spec.ts
@@ -17,7 +17,7 @@ const environment = {
   DSH_DESKTOP_MACOS_SIGNING_IDENTITY: 'Example Company (TEAMID1234)',
   DSH_DESKTOP_MACOS_TEAM_ID: 'TEAMID1234',
   APPLE_KEYCHAIN_PROFILE: 'fixture-profile',
-  DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com',
+  DOWNLOAD_TEST_ORIGIN: 'https://desktop-updates.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
 }
 
 function barrier() {
@@ -33,7 +33,7 @@ async function fixture(arch: 'arm64' | 'x64' = 'arm64') {
   await mkdir(join(appPath, 'Contents', 'Resources'), { recursive: true })
   await writeFile(join(appPath, 'payload'), 'signed content')
   await writeMacOSAppUpdateConfig(join(appPath, 'Contents', 'Resources'), {
-    publicUrl: `https://desktop-updates.example.com/dsh-desk/feeds/mac-${arch}/`,
+    publicUrl: `https://desktop-updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-${arch}/`,
   }, 'deepseek-harness-updater')
   const version = '1.2.3-alpha.1'
   const base = `deepseek-harness-${version}-mac-${arch}`
@@ -107,7 +107,7 @@ describe('parallel macOS artifacts', () => {
         .toEqual({ payload: 'signed content', appTicket: false })
       expect(await readFile(join(f.appPath, 'ticket'), 'utf8')).toBe('accepted')
       expect(await readFile(join(f.appPath, 'Contents', 'Resources', 'app-update.yml'), 'utf8'))
-        .toContain(`/dsh-desk/feeds/mac-${arch}/`)
+        .toContain(`/dsh-desk/0123456789abcdef0123456789abcdef/feeds/mac-${arch}/`)
       expect((await readdir(f.root)).sort()).toEqual(['artifacts'])
       expect(f.apple.verifySignature).toHaveBeenCalledTimes(4)
       expect(f.apple.verifyNotarization).toHaveBeenCalledTimes(1)
diff --git a/apps/desktop/tests/package-target-stages.spec.ts b/apps/desktop/tests/package-target-stages.spec.ts
index 5b8880ce6a..176c9c86b5 100644
--- a/apps/desktop/tests/package-target-stages.spec.ts
+++ b/apps/desktop/tests/package-target-stages.spec.ts
@@ -29,7 +29,8 @@ vi.mock('node:fs', async importOriginal => ({
 afterEach(() => { vi.unstubAllEnvs(); vi.clearAllMocks() })
 
 const environment = { DSH_DESKTOP_APP_ID: 'com.example.test', DSH_DESKTOP_AUTO_UPDATE_ENV: 'test',
-  DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DSH_DESKTOP_WINDOWS_TOKEN_PIN: 'fixture-pin' }
+  DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
+  DSH_DESKTOP_WINDOWS_TOKEN_PIN: 'fixture-pin', DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY: '2' }
 
 function supervisor(failure?: string) {
   vi.stubEnv('npm_execpath', 'fixture-pnpm.cjs')
@@ -56,9 +57,15 @@ it('requires one signing preflight before building, then records only the comple
   for (const call of run.run.mock.calls) {
     if (call[0].startsWith('run prepare:') || call[0].includes('smoke-packaged-runtime')) {
       expect(call[3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_TOKEN_PIN')
+      expect(call[3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY')
+    }
+    if (call[0].startsWith('run sign:primary-runtime')) {
+      expect(call[3].env).toHaveProperty('DSH_DESKTOP_WINDOWS_SIGNATURE_CACHE_CONCURRENCY', '2')
     }
   }
   expect(writeFileSync).toHaveBeenCalledOnce()
+  const record = JSON.parse(vi.mocked(writeFileSync).mock.calls[0]![1] as string) as { publicUrl: string }
+  expect(record.publicUrl).toBe('https://updates.example.com/dsh-desk/0123456789abcdef0123456789abcdef/feeds/win-x64/')
 })
 
 it('initializes shared storage only after acquiring the preflight stage lock', async () => {
diff --git a/apps/desktop/tests/preload-app.spec.ts b/apps/desktop/tests/preload-app.spec.ts
index b095aae2c0..cdce12e6b4 100644
--- a/apps/desktop/tests/preload-app.spec.ts
+++ b/apps/desktop/tests/preload-app.spec.ts
@@ -1,17 +1,20 @@
 import { afterEach, expect, it, vi } from 'vitest'
+import { installMandatoryUpdateOverlay } from '../src/preload-mandatory-overlay.ts'
 import { syncWindowsAppearance } from '../src/preload-windows.ts'
 import { DESKTOP_IPC, type DshDesktopProductApi } from '../src/ipc.ts'
 
 const electron = vi.hoisted(() => ({
   contextBridge: { exposeInMainWorld: vi.fn() },
   ipcRenderer: { invoke: vi.fn(), on: vi.fn(), off: vi.fn(), send: vi.fn() },
+  webUtils: { getPathForFile: vi.fn() },
 }))
 vi.mock('electron', () => electron)
 vi.mock('../src/preload-platform.ts', () => ({ markDocumentPlatform: vi.fn(), syncWindowFullscreen: vi.fn() }))
 vi.mock('../src/preload-theme.ts', () => ({ syncNativeTheme: vi.fn() }))
 vi.mock('../src/preload-windows.ts', () => ({ syncWindowsAppearance: vi.fn() }))
+vi.mock('../src/preload-mandatory-overlay.ts', () => ({ installMandatoryUpdateOverlay: vi.fn() }))
 
-afterEach(() => { vi.unstubAllGlobals(); vi.clearAllMocks(); vi.resetModules() })
+afterEach(() => { vi.unstubAllGlobals(); vi.restoreAllMocks(); vi.clearAllMocks(); vi.resetModules() })
 
 it('limits product documents to update status and a native confirmation action', async () => {
   vi.stubGlobal('location', new URL('dsh-app://app/index.html'))
@@ -25,7 +28,8 @@ it('limits product documents to update status and a native confirmation action',
   expect(api.updates).not.toHaveProperty('install')
   const listener = vi.fn()
   const dispose = api.updates.subscribe(listener)
-  const handler = electron.ipcRenderer.on.mock.calls[0]?.[1] as (event: unknown, state: unknown) => void
+  const handler = electron.ipcRenderer.on.mock.calls.find(([channel]) => channel === DESKTOP_IPC.updatesPresentation)?.[1] as
+    (event: unknown, state: unknown) => void
   handler({}, { visible: false })
   expect(listener).toHaveBeenCalledWith({ visible: false })
   dispose()
@@ -36,6 +40,7 @@ it.each(['dsh-app://shell/plugin-manager.html', 'dsh-app://other/index.html', 'h
   vi.stubGlobal('location', new URL(url))
   await import('../src/preload-app.ts')
   expect(electron.contextBridge.exposeInMainWorld).toHaveBeenCalledWith('dshDesktop', { protocolVersion: 1 })
+  expect(electron.ipcRenderer.on.mock.calls.some(([channel]) => channel === DESKTOP_IPC.browserOpenRequested)).toBe(false)
 })
 
 it('exposes asynchronous boot only to the local application document', async () => {
@@ -69,6 +74,23 @@ it('exposes a directory picker only to the local application document', async ()
   }
 })
 
+it('reports host paths of picked files only to the local application document', async () => {
+  vi.stubGlobal('location', new URL('dsh-app://app/'))
+  await import('../src/preload-app.ts')
+  const api = electron.contextBridge.exposeInMainWorld.mock.calls.find(([name]) => name === '__DSH_HOST_PATHS__')?.[1] as { pathFor(file: File): string }
+  const picked = new File(['x'], 'notes.md')
+  electron.webUtils.getPathForFile.mockReturnValue('/Users/me/notes.md')
+  expect(api.pathFor(picked)).toBe('/Users/me/notes.md')
+  expect(electron.webUtils.getPathForFile).toHaveBeenCalledExactlyOnceWith(picked)
+  for (const url of ['dsh-app://shell/startup.html', 'https://example.com/']) {
+    vi.resetModules()
+    electron.contextBridge.exposeInMainWorld.mockClear()
+    vi.stubGlobal('location', new URL(url))
+    await import('../src/preload-app.ts')
+    expect(electron.contextBridge.exposeInMainWorld.mock.calls.some(([name]) => name === '__DSH_HOST_PATHS__')).toBe(false)
+  }
+})
+
 it.each(['dsh-app://app/', 'dsh-app://shell/plugin-manager.html', 'https://example.com/'])(
   'installs Windows appearance only for the application document (%s)', async (url) => {
     vi.stubGlobal('location', new URL(url))
@@ -76,3 +98,14 @@ it.each(['dsh-app://app/', 'dsh-app://shell/plugin-manager.html', 'https://examp
     expect(syncWindowsAppearance).toHaveBeenCalledTimes(url === 'dsh-app://app/' ? 1 : 0)
   },
 )
+
+it.each(['win32', 'darwin'] as const)('installs the embedded mandatory UI only in the Windows app document (%s)', async (platform) => {
+  vi.spyOn(process, 'platform', 'get').mockReturnValue(platform)
+  for (const url of ['dsh-app://app/', 'dsh-app://shell/mandatory-update.html', 'https://example.com/']) {
+    vi.resetModules()
+    vi.mocked(installMandatoryUpdateOverlay).mockClear()
+    vi.stubGlobal('location', new URL(url))
+    await import('../src/preload-app.ts')
+    expect(installMandatoryUpdateOverlay).toHaveBeenCalledTimes(platform === 'win32' && url === 'dsh-app://app/' ? 1 : 0)
+  }
+})
diff --git a/apps/desktop/tests/preload-mandatory-overlay.spec.ts b/apps/desktop/tests/preload-mandatory-overlay.spec.ts
new file mode 100644
index 0000000000..8416e89fac
--- /dev/null
+++ b/apps/desktop/tests/preload-mandatory-overlay.spec.ts
@@ -0,0 +1,104 @@
+import { MessageChannel } from 'node:worker_threads'
+import { JSDOM } from 'jsdom'
+import { afterEach, expect, it, vi } from 'vitest'
+import { installMandatoryUpdateOverlay } from '../src/preload-mandatory-overlay.ts'
+import { MANDATORY_IPC } from '../src/mandatory-update-ipc.ts'
+import { resolveDesktopLocale } from '../src/locale.ts'
+import type { MandatoryUpdateView } from '../src/mandatory-update-window.ts'
+
+const ipc = vi.hoisted(() => ({ on: vi.fn(), off: vi.fn(), invoke: vi.fn(async () => {}) }))
+vi.mock('electron', () => ({ ipcRenderer: ipc }))
+let dom: JSDOM
+let channel: MessageChannel
+afterEach(() => {
+  dom.window.dispatchEvent(new dom.window.Event('pagehide'))
+  dom.window.close()
+  channel?.port1.close()
+  channel?.port2.close()
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  vi.clearAllMocks()
+  vi.useRealTimers()
+})
+
+function setup() {
+  dom = new JSDOM('<html><body><button>Product action</button><div data-windows-menu></div></body></html>', { url: 'dsh-app://app/' })
+  vi.stubGlobal('window', dom.window)
+  vi.stubGlobal('document', dom.window.document)
+  vi.stubGlobal('HTMLElement', dom.window.HTMLElement)
+  vi.stubGlobal('MessageChannel', function createChannel() { channel = new MessageChannel(); return channel })
+  vi.spyOn(dom.window.document, 'readyState', 'get').mockReturnValue('complete')
+  const shadow = vi.spyOn(dom.window.HTMLElement.prototype, 'attachShadow')
+  installMandatoryUpdateOverlay()
+  const publish = ipc.on.mock.calls.find(([name]) => name === MANDATORY_IPC.state)![1] as
+    (event: unknown, state: MandatoryUpdateView) => void
+  const view: MandatoryUpdateView = { locale: resolveDesktopLocale('zh-CN'), policy: { blocking: true, checking: false },
+    update: { phase: 'available', version: '2.0.0' }, deferred: false }
+  publish({}, view)
+  ipc.invoke.mockClear()
+  const root = shadow.mock.results[0]!.value as ShadowRoot
+  const frame = root.querySelector('iframe')!
+  // JSDOM has no browsing context for a shadow-root iframe; transport uses real paired Node ports.
+  const post = vi.spyOn(dom.window, 'postMessage').mockImplementation(() => {})
+  Object.defineProperty(frame, 'contentWindow', { value: dom.window })
+  const focus = vi.spyOn(frame, 'focus').mockImplementation(() => {})
+  frame.dispatchEvent(new dom.window.Event('load'))
+  expect(post).toHaveBeenCalledWith({ type: 'dsh-mandatory-connect' }, 'dsh-app://shell', [channel.port2])
+  return { publish, view, root, frame, focus, host: root.host as HTMLElement }
+}
+
+it('uses an in-page frame below the caption and reuses it on updates', () => {
+  const f = setup()
+  expect(f.host.style.top).toBe('40px')
+  expect(f.host.style.bottom).toBe('0px')
+  expect(f.frame.src).toBe('dsh-app://shell/mandatory-update.html')
+  expect(dom.window.document.body.style.filter).toBe('')
+  f.publish({}, { ...f.view, update: { phase: 'downloading', version: '2.0.0', percent: 30 } })
+  expect(f.root.querySelector('iframe')).toBe(f.frame)
+})
+
+it('rejects forged window events and accepts actions only through the transferred private port', async () => {
+  const f = setup()
+  const data = { type: 'dsh-mandatory-action', id: 1, action: 'download', version: '2.0.0', revision: undefined }
+  dom.window.dispatchEvent(new dom.window.MessageEvent('message', { source: f.frame.contentWindow, origin: 'dsh-app://shell', data }))
+  expect(ipc.invoke).not.toHaveBeenCalled()
+  const result = new Promise<unknown>(resolve => channel.port2.on('message', (message: unknown) => {
+    if (typeof message === 'object' && message !== null && 'type' in message && message.type === 'dsh-mandatory-result') resolve(message)
+  }))
+  channel.port2.postMessage(data)
+  await expect(result).resolves.toEqual({ type: 'dsh-mandatory-result', id: 1, ok: true })
+  expect(ipc.invoke).toHaveBeenCalledExactlyOnceWith(MANDATORY_IPC.action, 'download', '2.0.0', undefined)
+})
+
+it('keeps caption menu keyboard events available while blocking background shortcuts', () => {
+  const f = setup()
+  const host = dom.window.document.querySelector('[data-windows-menu]')!
+  const shadow = host.attachShadow({ mode: 'open' })
+  const button = dom.window.document.createElement('button')
+  shadow.append(button)
+  const received = vi.fn()
+  button.addEventListener('keydown', received)
+  for (const key of ['Enter', 'ArrowDown', 'ArrowRight']) {
+    const event = new dom.window.KeyboardEvent('keydown', { key, bubbles: true, composed: true, cancelable: true })
+    button.dispatchEvent(event)
+    expect(event.defaultPrevented).toBe(false)
+  }
+  expect(received).toHaveBeenCalledTimes(3)
+  const background = new dom.window.KeyboardEvent('keydown', { key: 'n', bubbles: true, cancelable: true })
+  dom.window.document.body.dispatchEvent(background)
+  expect(background.defaultPrevented).toBe(true)
+  expect(f.focus).toHaveBeenCalled()
+})
+
+it('clears once without postponing removal on progress ticks, and closes the channel on navigation', () => {
+  vi.useFakeTimers()
+  const f = setup()
+  const cleared = { ...f.view, policy: { blocking: false, checking: false } }
+  f.publish({}, cleared)
+  vi.advanceTimersByTime(100)
+  f.publish({}, cleared)
+  vi.advanceTimersByTime(50)
+  expect(f.host.isConnected).toBe(false)
+  dom.window.dispatchEvent(new dom.window.Event('pagehide'))
+  expect(ipc.off).toHaveBeenCalledWith(MANDATORY_IPC.state, expect.any(Function))
+})
diff --git a/apps/desktop/tests/primary-runtime-preparation.spec.ts b/apps/desktop/tests/primary-runtime-preparation.spec.ts
index 2e0f802af5..ec9dda7edb 100644
--- a/apps/desktop/tests/primary-runtime-preparation.spec.ts
+++ b/apps/desktop/tests/primary-runtime-preparation.spec.ts
@@ -1,131 +1,18 @@
-import { createHash } from 'node:crypto'
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+/** Desktop carriers keep a complete interpreter payload even when SDK carriers choose Python-only. */
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { basename, join } from 'node:path'
-import { zipSync } from 'fflate'
+import { join } from 'node:path'
 import { expect, it } from 'vitest'
-import { downloadPrimaryRuntimeAsset, prepareOfficeSkillAssets, primaryRuntimePayloadDigest, smokePrimaryRuntime, unpackPrimaryRuntimeWheel } from '../scripts/prepare-primary-runtime.ts'
-import lock from '../scripts/primary-runtime-lock.json' with { type: 'json' }
+import { smokePrimaryRuntime } from '../scripts/prepare-primary-runtime.ts'
 
-const libraryWheel = Buffer.from('UEsDBAoAAAAAAASeLl0sYMPjDAAAAAwAAAAJAAAAc2FtcGxlLnB5c2FtcGxlID0gNDIKUEsBAh4DCgAAAAAABJ4uXSxgw+MMAAAADAAAAAkAAAAAAAAAAQAAAKSBAAAAAHNhbXBsZS5weVBLBQYAAAAAAQABADcAAAAzAAAAAAA=', 'base64')
-const relocatedWheel = Buffer.from('UEsDBAoAAAAAAASeLl3x0Nj9FAAAABQAAAAeAAAAc2FtcGxlLTEuMC5kYXRhL3NjcmlwdHMvc2FtcGxlcmVxdWlyZXMgcmVsb2NhdGlvbgpQSwECHgMKAAAAAAAEni5d8dDY/RQAAAAUAAAAHgAAAAAAAAABAAAApIEAAAAAc2FtcGxlLTEuMC5kYXRhL3NjcmlwdHMvc2FtcGxlUEsFBgAAAAABAAEATAAAAFAAAAAAAA==', 'base64')
-const externalLibraryWheel = Buffer.from('UEsDBBQAAAAAAAAAIVyBOE8OHAAAABwAAAAhAAAAc2FtcGxlLTEuMC5kYXRhL3B1cmVsaWIvc2FtcGxlLnB5cmVxdWlyZXMgbGlicmFyeSByZWxvY2F0aW9uClBLAQIUAxQAAAAAAAAAIVyBOE8OHAAAABwAAAAhAAAAAAAAAAAAAACAAQAAAABzYW1wbGUtMS4wLmRhdGEvcHVyZWxpYi9zYW1wbGUucHlQSwUGAAAAAAEAAQBPAAAAWwAAAAAA', 'base64')
-
-it.each(Object.entries(lock.targets))('records every locked wheel distribution and version for %s', (_target, artifact) => {
-  const normalize = (name: string): string => name.toLowerCase().replace(/[-_.]+/gu, '-')
-  const distributions = [...artifact.wheels, ...lock.wheels].map(({ url }) => {
-    const [name, version] = basename(new URL(url).pathname).split('-')
-    return [normalize(name!), version] as const
-  })
-  const declared = Object.entries(lock.pythonPackages).map(([name, version]) => [normalize(name), version] as const)
-  expect(new Set(distributions.map(([name]) => name)).size).toBe(distributions.length)
-  expect(new Set(declared.map(([name]) => name)).size).toBe(declared.length)
-  expect(Object.fromEntries(distributions)).toEqual(Object.fromEntries(declared))
-})
-
-it('keeps a target payload identity independent of other target archives', () => {
-  const changed = structuredClone(lock)
-  changed.targets['win-x64'].wheels[0]!.sha256 = 'a'.repeat(64)
-  expect(primaryRuntimePayloadDigest('mac-arm64', changed, '11.7.0')).toBe(primaryRuntimePayloadDigest('mac-arm64', lock, '11.7.0'))
-  expect(primaryRuntimePayloadDigest('win-x64', changed, '11.7.0')).not.toBe(primaryRuntimePayloadDigest('win-x64', lock, '11.7.0'))
-})
-
-it('invalidates payload identity for shared wheels, package versions and package-manager changes', () => {
-  const wheel = structuredClone(lock), distribution = structuredClone(lock)
-  wheel.wheels[0]!.sha256 = 'a'.repeat(64)
-  distribution.pythonPackages['python-docx'] = '1.2.1'
-  const original = primaryRuntimePayloadDigest('mac-arm64', lock, '11.7.0')
-  expect(primaryRuntimePayloadDigest('mac-arm64', wheel, '11.7.0')).not.toBe(original)
-  expect(primaryRuntimePayloadDigest('mac-arm64', distribution, '11.7.0')).not.toBe(original)
-  expect(primaryRuntimePayloadDigest('mac-arm64', lock, '11.7.1')).not.toBe(original)
-})
-
-it('reports missing distribution metadata before trying to execute a stale native payload', async () => {
-  const root = await mkdtemp(join(tmpdir(), 'desktop-stale-runtime-'))
+it('rejects a Python-only native Desktop payload before executing interpreters', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-python-only-'))
   try {
-    await writeFile(join(root, 'runtime.json'), JSON.stringify({ platform: process.platform, arch: process.arch }))
-    expect(() => { smokePrimaryRuntime(root) }).toThrow('missing Python distribution versions; prepare the payload')
-  } finally { await rm(root, { recursive: true, force: true }) }
-})
-
-it('extracts a hash-verified cached library without a Python installer or network request', async () => {
-  const root = await mkdtemp(join(tmpdir(), 'desktop-wheel-'))
-  try {
-    const hash = createHash('sha256').update(libraryWheel).digest('hex')
-    const archive = join(root, hash)
-    await writeFile(archive, libraryWheel)
-    expect(await downloadPrimaryRuntimeAsset('https://unused.invalid/library.whl', hash, root)).toBe(archive)
-    await unpackPrimaryRuntimeWheel(archive, join(root, 'site-packages'))
-    expect(await readFile(join(root, 'site-packages/sample.py'), 'utf8')).toBe('sample = 42\n')
-    await writeFile(archive, 'corrupt archive')
-    await expect(downloadPrimaryRuntimeAsset('https://unused.invalid/library.whl', hash, root)).rejects.toThrow('checksum mismatch')
-  } finally {
-    await rm(root, { recursive: true, force: true })
-  }
-})
-
-it('fully extracts a large deflate-compressed wheel entry', async () => {
-  const root = await mkdtemp(join(tmpdir(), 'desktop-large-wheel-'))
-  try {
-    const expected = Buffer.alloc(1024 * 1024)
-    // Seeded xorshift bytes keep the compressed entry larger than the stream buffers.
-    let state = 26
-    for (let index = 0; index < expected.length; index++) {
-      state ^= state << 13
-      state ^= state >>> 17
-      state ^= state << 5
-      expected[index] = state & 255
-    }
-    const archive = join(root, 'large.whl')
-    await writeFile(archive, zipSync({ 'large.bin': expected }, { level: 6 }))
-    await unpackPrimaryRuntimeWheel(archive, root)
-    expect(await readFile(join(root, 'large.bin'))).toEqual(expected)
-  } finally {
-    await rm(root, { recursive: true, force: true })
-  }
-})
-
-it('retains auxiliary wheel scripts without generating command wrappers', async () => {
-  const root = await mkdtemp(join(tmpdir(), 'desktop-wheel-'))
-  try {
-    const archive = join(root, 'relocated.whl')
-    await writeFile(archive, relocatedWheel)
-    await unpackPrimaryRuntimeWheel(archive, join(root, 'site-packages'))
-    expect(await readFile(join(root, 'site-packages/sample-1.0.data/scripts/sample'), 'utf8')).toBe('requires relocation\n')
-  } finally {
-    await rm(root, { recursive: true, force: true })
-  }
-})
-
-it('rejects library files requiring an unsupported installation scheme', async () => {
-  const root = await mkdtemp(join(tmpdir(), 'desktop-wheel-'))
-  try {
-    const archive = join(root, 'relocated.whl')
-    await writeFile(archive, externalLibraryWheel)
-    await expect(unpackPrimaryRuntimeWheel(archive, join(root, 'site-packages'))).rejects.toThrow('unsupported installation paths')
-  } finally {
-    await rm(root, { recursive: true, force: true })
-  }
-})
-
-it('copies complete Office resources outside the application archive and removes obsolete assets', async () => {
-  const root = await mkdtemp(join(tmpdir(), 'desktop-office-assets-'))
-  try {
-    const source = join(root, 'package', 'assets')
-    const destination = join(root, 'Contents', 'Resources', 'runtime', 'office-skills')
-    await mkdir(join(source, 'scripts'), { recursive: true })
-    await writeFile(join(source, 'scripts', 'check_office.py'), 'print("checker")\n')
-    for (const name of ['office-docx', 'office-pptx', 'office-xlsx']) {
-      await mkdir(join(source, name))
-      await writeFile(join(source, name, 'SKILL.md'), `# ${name}\n`)
-    }
-    await prepareOfficeSkillAssets(source, destination)
-    await writeFile(join(destination, 'obsolete.py'), 'old helper')
-    await prepareOfficeSkillAssets(source, destination)
-    for (const name of ['office-docx', 'office-pptx', 'office-xlsx']) {
-      expect(await readFile(join(destination, name, 'SKILL.md'), 'utf8')).toBe(`# ${name}\n`)
-    }
-    expect(await readFile(join(destination, 'scripts', 'check_office.py'), 'utf8')).toBe('print("checker")\n')
-    await expect(readFile(join(destination, 'obsolete.py'))).rejects.toMatchObject({ code: 'ENOENT' })
+    await writeFile(join(root, 'runtime.json'), JSON.stringify({
+      desktopVersion: '1.0.0', platform: process.platform, arch: process.arch,
+      python: '3.12.14', pythonPackages: { numpy: '2.3.5', pandas: '3.0.1' },
+    }))
+    expect(() => { smokePrimaryRuntime(root) }).toThrow('Desktop payload must declare node and pnpm')
   } finally { await rm(root, { recursive: true, force: true }) }
 })
diff --git a/apps/desktop/tests/primary-runtime-signing.spec.ts b/apps/desktop/tests/primary-runtime-signing.spec.ts
index 242c93f339..5c7b4aa080 100644
--- a/apps/desktop/tests/primary-runtime-signing.spec.ts
+++ b/apps/desktop/tests/primary-runtime-signing.spec.ts
@@ -26,6 +26,86 @@ async function fixture(names = ['a.exe', 'b.pyd', 'vendor.dll']): Promise<string
 
 afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) })
 
+it('bounds overlapping cache restores and verifies all hits before serial hardware misses', async () => {
+  const root = await fixture(['a.exe', 'b.exe', 'c.exe', 'd.exe'])
+  const entered = Promise.withResolvers<undefined>()
+  const release = Promise.withResolvers<undefined>()
+  const signed = new Set<string>()
+  const verified = new Set<string>()
+  let active = 0
+  let peak = 0
+  let hits = 0
+  const sign = vi.fn(async ({ path }: { path: string }) => {
+    expect(active).toBe(0)
+    expect(hits).toBe(2)
+    expect(verified.has(join(root, 'a.exe')) && verified.has(join(root, 'b.exe'))).toBe(true)
+    signed.add(path)
+  })
+  const operation = signWindowsCode(root, { thumbprint, record: () => {}, sign,
+    inspect: async (path) => {
+      if (!signed.has(path)) return unsigned
+      verified.add(path)
+      return valid
+    },
+    cache: { concurrency: 2, restore: async ({ path }) => {
+      active++
+      peak = Math.max(peak, active)
+      if (active === 2) entered.resolve(undefined)
+      await release.promise
+      active--
+      if (path.endsWith('a.exe') || path.endsWith('b.exe')) { signed.add(path); hits++; return true }
+      return false
+    } },
+  })
+  try {
+    await Promise.race([entered.promise, operation])
+    expect(sign).not.toHaveBeenCalled()
+  } finally { release.resolve(undefined); await operation }
+  expect(peak).toBe(2)
+  expect(sign.mock.calls.map(([request]) => request.path)).toEqual(['c.exe', 'd.exe'].map(name => join(root, name)))
+})
+
+it.each(['restore', 'verification', 'audit'])('drains active cache restores after %s failure without dispatching more work', async (failure) => {
+  const root = await fixture(['a.exe', 'b.exe', 'c.exe'])
+  const entered = Promise.withResolvers<undefined>()
+  const release = Promise.withResolvers<undefined>()
+  const failed = Promise.withResolvers<undefined>()
+  const restored = new Set<string>()
+  const calls: string[] = []
+  const sign = vi.fn(async () => {})
+  let settled = false
+  const operation = signWindowsCode(root, { thumbprint, sign,
+    record: (event) => {
+      if (failure === 'audit' && 'type' in event && event.type === 'windows-code-signature-verified') {
+        failed.resolve(undefined)
+        throw new Error('audit failed')
+      }
+    },
+    inspect: async (path) => {
+      if (!restored.has(path)) return unsigned
+      if (failure === 'verification' && path.endsWith('a.exe')) { failed.resolve(undefined); throw new Error('verification failed') }
+      return valid
+    },
+    cache: { concurrency: 2, restore: async ({ path }) => {
+      calls.push(path)
+      if (path.endsWith('b.exe')) { entered.resolve(undefined); await release.promise; return false }
+      await entered.promise
+      if (failure === 'restore') { failed.resolve(undefined); throw new Error('restore failed') }
+      restored.add(path)
+      return true
+    } },
+  }).then(() => { settled = true; return undefined }, (error: unknown) => { settled = true; return error })
+  try {
+    await Promise.race([failed.promise, operation])
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(settled).toBe(false)
+    expect(sign).not.toHaveBeenCalled()
+  } finally { release.resolve(undefined); await operation }
+  expect(await operation).toEqual(new Error(`${failure} failed`))
+  expect(calls).toEqual(['a.exe', 'b.exe'].map(name => join(root, name)))
+  expect(sign).not.toHaveBeenCalled()
+})
+
 it('selects real PE code, including .node, without signing foreign native modules or data', async () => {
   const root = await fixture(['runtime.node', 'python.exe', 'extensionless', 'custom.binary'])
   await mkdir(join(root, 'nested'))
diff --git a/apps/desktop/tests/update-overlay.spec.ts b/apps/desktop/tests/update-overlay.spec.ts
index 97bb5cc266..9f4a79878d 100644
--- a/apps/desktop/tests/update-overlay.spec.ts
+++ b/apps/desktop/tests/update-overlay.spec.ts
@@ -1,31 +1,11 @@
 import { EventEmitter } from 'node:events'
 import { expect, it, vi } from 'vitest'
 import type { BrowserWindow, BrowserWindowConstructorOptions } from 'electron'
-import { createMandatoryUpdateWindow } from '../src/update-overlay.ts'
+import { createUpdateOverlay } from '../src/update-overlay.ts'
 
 const native = vi.hoisted(() => ({ create: vi.fn<(options: BrowserWindowConstructorOptions) => object>() }))
 vi.mock('electron', () => ({ BrowserWindow: function (options: object) { return native.create(options) } }))
 
-it('gives the Windows mandatory modal native move, resize, and maximize controls', () => {
-  const window = Object.assign(new EventEmitter(), {
-    webContents: { setWindowOpenHandler: vi.fn() }, show: vi.fn(), isDestroyed: () => false,
-  })
-  native.create.mockReturnValue(window)
-  const parent = {} as BrowserWindow
-  expect(createMandatoryUpdateWindow(parent, 'owned', 'Update required', 'win32')).toBe(window)
-  expect(native.create).toHaveBeenCalledWith(expect.objectContaining({
-    parent, modal: true, show: false, title: 'Update required',
-    movable: true, resizable: true, maximizable: true,
-    minWidth: 480, minHeight: 360,
-  }))
-  const options = native.create.mock.calls[0]![0]
-  expect(options.webPreferences).toMatchObject({ preload: 'owned', sandbox: true, nodeIntegration: false })
-  expect(options).not.toHaveProperty('frame', false)
-  window.emit('ready-to-show')
-  expect(window.show).toHaveBeenCalledOnce()
-  expect(window.webContents.setWindowOpenHandler).toHaveBeenCalledOnce()
-})
-
 it('keeps the macOS mandatory overlay stationary and blocks parent keyboard input until close', () => {
   const platform = vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
   const parent = Object.assign(new EventEmitter(), {
@@ -39,7 +19,7 @@ it('keeps the macOS mandatory overlay stationary and blocks parent keyboard inpu
   })
   native.create.mockReturnValue(window)
   try {
-    createMandatoryUpdateWindow(parent as unknown as BrowserWindow, 'owned', 'Update required', 'darwin')
+    createUpdateOverlay(parent as unknown as BrowserWindow, 'owned', 'Update required', false)
     expect(native.create).toHaveBeenLastCalledWith(expect.objectContaining({ modal: false, transparent: true, frame: false }))
     const event = { preventDefault: vi.fn() }
     parent.webContents.emit('before-input-event', event)
diff --git a/apps/desktop/tests/update-presentation.spec.ts b/apps/desktop/tests/update-presentation.spec.ts
index 70ed16a168..9d3ce5009e 100644
--- a/apps/desktop/tests/update-presentation.spec.ts
+++ b/apps/desktop/tests/update-presentation.spec.ts
@@ -2,7 +2,7 @@ import { expect, it } from 'vitest'
 import { desktopUpdateErrorSummary, presentDesktopUpdate } from '../src/update-presentation.ts'
 import { en, zh } from '../src/locale.ts'
 import type { DesktopUpdateState, DshDesktopProductApi } from '../src/ipc.ts'
-import type { DesktopUpdateBridge } from '../../../packages/client/ui-settings-general/src/client/desktop-update-bridge.ts'
+import type { DesktopUpdateBridge } from '@deepseek-ai/dsh-client-ui-settings-general/types'
 
 it('keeps the Electron preload assignable to the product consumer', () => {
   const assign = (bridge: DshDesktopProductApi['updates']): DesktopUpdateBridge => bridge
diff --git a/apps/desktop/tests/upload-with-credentials.spec.ts b/apps/desktop/tests/upload-with-credentials.spec.ts
index 9a6a93f0a8..29688621ca 100644
--- a/apps/desktop/tests/upload-with-credentials.spec.ts
+++ b/apps/desktop/tests/upload-with-credentials.spec.ts
@@ -86,7 +86,7 @@ afterEach(async () => {
 
 describe('credential launcher destination', () => {
   const fileEnvironment = {
-    DSH_DESKTOP_AUTO_UPDATE_ENV: 'test', DOWNLOAD_TEST_ORIGIN: 'https://download-test.example.com',
+    DSH_DESKTOP_AUTO_UPDATE_ENV: 'test', DOWNLOAD_TEST_ORIGIN: 'https://download-test.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
     DOWNLOAD_TEST_COS_BUCKET: 'test-bucket', DOWNLOAD_TEST_COS_SECRET_ID: 'stale-id', DOWNLOAD_TEST_COS_SECRET_KEY: 'stale-key',
   }
   const injectedEnvironment = {
diff --git a/apps/desktop/tests/windows-asar-unpack.spec.ts b/apps/desktop/tests/windows-asar-unpack.spec.ts
index ddfaf15de2..2d5c79563b 100644
--- a/apps/desktop/tests/windows-asar-unpack.spec.ts
+++ b/apps/desktop/tests/windows-asar-unpack.spec.ts
@@ -168,7 +168,7 @@ it.each([true, false])('validates the real builder hook for unsigned=%s', async
     DSH_DESKTOP_APP_ID: 'com.example.unpack', DSH_DESKTOP_MANDATORY_UPDATE_TEST_ORIGIN: 'https://policy.example.com',
     DSH_DESKTOP_MANDATORY_UPDATE_CONFIG: JSON.stringify({ allowedAuthOrigins: ['https://login.example.com'] }),
     DSH_DESKTOP_TARGET_PLATFORM: 'win32', DSH_DESKTOP_TARGET_ARCH: 'x64', DSH_DESKTOP_UNSIGNED: unsigned ? '1' : '0',
-    DSH_DESKTOP_WINDOWS_CER_FILE: certificate, DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com',
+    DSH_DESKTOP_WINDOWS_CER_FILE: certificate, DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
   }, 'win32', 'x64', input.source)
   // Qualification replaces files after creating the base configuration; builder owns a separate config object.
   input.config.asarUnpack = [...config.asarUnpack]
diff --git a/apps/desktop/tests/windows-sign.spec.ts b/apps/desktop/tests/windows-sign.spec.ts
index 1b1440b0fe..e5d5a7cd3f 100644
--- a/apps/desktop/tests/windows-sign.spec.ts
+++ b/apps/desktop/tests/windows-sign.spec.ts
@@ -159,7 +159,7 @@ describe('Windows token signing', () => {
       await writeFile(signTool, 'fixture')
       await writeFile(path, 'fixture')
       validateDesktopPackageEnvironment({
-        DSH_DESKTOP_APP_ID: 'com.example.desktop', DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com',
+        DSH_DESKTOP_APP_ID: 'com.example.desktop', DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com', DOWNLOAD_TEST_RELEASE_ID: '0123456789abcdef0123456789abcdef',
         DSH_DESKTOP_MANDATORY_UPDATE_TEST_ORIGIN: 'https://policy.example.com',
         DSH_DESKTOP_MANDATORY_UPDATE_CONFIG: JSON.stringify({ allowedAuthOrigins: ['https://login.example.com'] }),
         DSH_DESKTOP_WINDOWS_CER_FILE: certificateFile, DSH_DESKTOP_WINDOWS_SIGNTOOL: signTool,
diff --git a/apps/desktop/tests/windows-signature-cache.spec.ts b/apps/desktop/tests/windows-signature-cache.spec.ts
index 975feb6fbe..9514b102e5 100644
--- a/apps/desktop/tests/windows-signature-cache.spec.ts
+++ b/apps/desktop/tests/windows-signature-cache.spec.ts
@@ -23,6 +23,22 @@ async function fixture(t: TestContext) {
   return { root, path, cache, state, options, request }
 }
 
+test('restore misses leave inputs and hardware untouched, then share a cached payload across targets', async (t) => {
+  const f = await fixture(t)
+  const signer = createCachedSigner(f.options)
+  assert.equal(await signer.restore(f.request), false)
+  assert.equal(f.state.hardwareCalls, 0)
+  assert.equal(signer.summary().misses, 0)
+  assert.equal(await readFile(f.path, 'utf8'), 'original')
+  await signer(f.request)
+  const targets = [join(f.root, 'first.node'), join(f.root, 'second.node')]
+  await Promise.all(targets.map(path => writeFile(path, 'original')))
+  assert.deepEqual(await Promise.all(targets.map(path => signer.restore({ ...f.request, path }))), [true, true])
+  assert.deepEqual(await Promise.all(targets.map(path => readFile(path, 'utf8'))), ['signed:original', 'signed:original'])
+  assert.equal(f.state.hardwareCalls, 1)
+  assert.equal(signer.summary().hits, 2)
+})
+
 test('unchanged bytes restored in another file avoid another hardware call', async (t) => {
   const f = await fixture(t)
   await createCachedSigner(f.options)(f.request)
@@ -71,7 +87,7 @@ test('different content or signing policy misses the cache', async (t) => {
   assert.equal(f.state.hardwareCalls, 3)
 })
 
-for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops without signing or replacing the input`, async (t) => {
+for (const restoreOnly of [false, true]) for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops without signing or replacing the input (restore-only: ${restoreOnly})`, async (t) => {
   const f = await fixture(t)
   await createCachedSigner(f.options)(f.request)
   await writeFile(f.path, 'original')
@@ -79,7 +95,7 @@ for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops
   assert(entry)
   await writeFile(join(f.cache, entry, corrupt), 'corrupt')
   const signer = createCachedSigner(f.options)
-  await assert.rejects(signer(f.request))
+  await assert.rejects(restoreOnly ? signer.restore(f.request) : signer(f.request))
   assert.equal(signer.summary().validationFailures, 1)
   assert.equal(signer.summary().avoidedSigningCalls, 0)
   assert.equal(f.state.hardwareCalls, 1)
diff --git a/apps/desktop/tsconfig.json b/apps/desktop/tsconfig.json
index 6811108afd..ad14bd9bb9 100644
--- a/apps/desktop/tsconfig.json
+++ b/apps/desktop/tsconfig.json
@@ -7,6 +7,7 @@
   "include": ["src"],
   "references": [
     { "path": "../../packages/boot/app-boot" },
+    { "path": "../../packages/client/ui-sidebar-browser/tsconfig.host.json" },
     { "path": "../../packages/util/home-paths" }
   ]
 }
diff --git a/apps/web/tests/README.i18n.yaml b/apps/web/tests/README.i18n.yaml
index cf707e6cb3..4d920402fa 100644
--- a/apps/web/tests/README.i18n.yaml
+++ b/apps/web/tests/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent 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/web/tests/README.md
-README.md: b2fa27bb7a60ed78309bf81e77b9cd5217bbee2a
-README.zh.md: 29ae2e86018257a4fc2379ea2563c8b5e5e9036f
+README.md: 8b9c58ce9e4cf2f5f6978c0c6eb5517fe000d3d2
+README.zh.md: 199ae3b56166aa2ffa1c0bed9a16b844ffd7b74f
diff --git a/apps/web/tests/README.md b/apps/web/tests/README.md
index b2fa27bb7a..8b9c58ce9e 100644
--- a/apps/web/tests/README.md
+++ b/apps/web/tests/README.md
@@ -4,6 +4,8 @@ English | [中文](README.zh.md)
 
 These tests boot the real web composition in-process and drive it with a real Chromium over real HTTP. The lane's mechanics — modes, fixtures, goldens, and the deliberate composition divergences from `dsh web` — are documented in [`scaffold.ts`](scaffold.ts) and the [browser e2e Agent Note](../../../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md).
 
+Ordinary scenarios begin with no registered Workspace or Session and a durable marker recording a removed default Workspace, so explicit folder-selection scenarios retain control of their cwd. `launchWebScaffold({ firstUse: true })` leaves initialization eligible for startup scenarios.
+
 ## Completion observations
 
 State-sensitive cases use Workspace, admission, attachment, and model-stream barriers to separate visible intermediate states from completed operations. Details close waits for frame transitions; archive verification assigns an explicit title to the seeded Session and follows that identity across reload. See the [CI fixture synchronization decision](../../../.agents/notes/implemented/testing/2026-09-08-ci-completion-observations.md).
diff --git a/apps/web/tests/README.zh.md b/apps/web/tests/README.zh.md
index 29ae2e8601..199ae3b561 100644
--- a/apps/web/tests/README.zh.md
+++ b/apps/web/tests/README.zh.md
@@ -4,6 +4,8 @@
 
 这些测试在进程内启动真实的 web 组合，并用真实 Chromium 通过真实 HTTP 驱动它。该 lane 的运行机制——模式、fixture（测试前置数据）、golden，以及与 `dsh web` 之间刻意保留的组合差异——记录在 [`scaffold.ts`](scaffold.ts) 和 [浏览器 e2e Agent Note](../../../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md) 中。
 
+普通场景以没有已登记 Workspace 或 Session、但持久化标记记录默认 Workspace 已被删除的状态启动，使显式文件夹选择场景自行决定 cwd。`launchWebScaffold({ firstUse: true })` 保留初始化资格，供启动场景使用。
+
 ## 完成状态观察
 
 依赖状态的用例使用 Workspace、接纳、附件和模型流屏障，区分可见中间状态与已完成操作。详情关闭等待框架过渡结束；归档验证为 seed Session 设置显式标题，并跨重载跟踪该身份。参见 [CI fixture 同步决策](../../../.agents/notes/implemented/testing/2026-09-08-ci-completion-observations.zh.md)。
diff --git a/apps/web/tests/agent-preset-authoring.e2e.ts b/apps/web/tests/agent-preset-authoring.e2e.ts
index 88ae171e85..2572b1a5ff 100644
--- a/apps/web/tests/agent-preset-authoring.e2e.ts
+++ b/apps/web/tests/agent-preset-authoring.e2e.ts
@@ -78,30 +78,68 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
     await dialog.getByRole('heading', { name: 'Agent 预设' }).waitFor({ timeout: 10_000 })
     // The intro copy also names 标准模式. Wait for the roster's own action so
     // the snapshot cannot land between the section shell and its cards.
-    await dialog.getByRole('button', { name: '查看: 标准模式', exact: true }).waitFor({ timeout: 10_000 })
+    await dialog.getByRole('button', { name: '查看配置: 标准模式', exact: true }).waitFor({ timeout: 10_000 })
 
     const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
 
     await compareOrRefreshGolden(SECTION_EXPECTED, snapshot, MODE)
-    const toggle = dialog.getByRole('switch', { name: '允许切换agent模式' })
+    const toggle = dialog.getByRole('switch', { name: '新任务可选择模式' })
     expect(await toggle.getAttribute('aria-checked')).toBe('true')
-    // The intro states the copy path directly, and the shipped rows offer
+    // The authoring entry is visible, and the shipped rows offer
     // view/copy but never delete or a location — their
     // install is overwritten by upgrades and is not the user's to manage.
-    expect(snapshot).toContain('或用「创造模式」让 Agent 帮你创建')
+    expect(snapshot).toContain('让 Agent 帮我创建预设模式')
     expect(snapshot).not.toContain('新建预设')
-    expect(snapshot).toContain('查看: 标准模式')
+    expect(snapshot).toContain('查看配置: 标准模式')
     expect(snapshot).not.toContain('删除: 标准模式')
     expect(snapshot).not.toContain('打开目录')
     // The rest of this scenario exercises the existing default and Creator
     // actions with the beta picker enabled by default.
   }, 60_000)
 
+  it('reads technical details and examples without changing the new-task default', async () => {
+    const settings = settingsDialog()
+    const trigger = settings.getByRole('button', { name: '模式说明: PTC 模式', exact: true })
+    await trigger.click()
+    const guide = page.getByRole('dialog', { name: 'PTC 模式', exact: true })
+    await guide.getByRole('heading', { name: '怎样调用工具', exact: true }).waitFor()
+    const beforeSwitch = await guide.boundingBox()
+    expect(await guide.textContent()).toContain('run_code')
+    await guide.getByRole('tab', { name: '如何使用', exact: true }).click()
+    await guide.getByRole('heading', { name: '批量检查配置文件', exact: true }).waitFor()
+    expect(await guide.boundingBox()).toEqual(beforeSwitch)
+    await guide.getByRole('tab', { name: '如何使用', exact: true }).press('ArrowLeft')
+    expect(await guide.getByRole('tab', { name: '模式说明', exact: true }).getAttribute('aria-selected')).toBe('true')
+    await guide.getByRole('tab', { name: '模式说明', exact: true }).press('Escape')
+    await guide.waitFor({ state: 'detached' })
+    expect(await trigger.evaluate(element => document.activeElement === element)).toBe(true)
+    expect(await settings.isVisible()).toBe(true)
+    expect(await settings.getByRole('button', { name: '新任务默认: 标准模式', exact: true }).getAttribute('aria-pressed')).toBe('true')
+
+    await settings.getByRole('button', { name: '如何使用: 创造模式', exact: true }).click()
+    const creator = page.getByRole('dialog', { name: '创造模式', exact: true })
+    await creator.getByRole('heading', { name: '添加一个界面', exact: true }).waitFor()
+    expect(await creator.getByRole('heading', { name: '添加一个工具', exact: true }).isVisible()).toBe(true)
+    const closePosition = await creator.getByRole('button', { name: '关闭', exact: true }).boundingBox()
+    const examples = creator.getByRole('tabpanel', { name: '如何使用', exact: true })
+    const scrolledTo = await examples.evaluate((element) => {
+      element.scrollTop = element.scrollHeight
+      return element.scrollTop
+    })
+    expect(scrolledTo).toBeGreaterThan(0)
+    expect(await creator.getByRole('button', { name: '关闭', exact: true }).boundingBox()).toEqual(closePosition)
+    await creator.getByRole('tab', { name: '模式说明', exact: true }).click()
+    await creator.getByRole('tab', { name: '如何使用', exact: true }).click()
+    expect(await examples.evaluate(element => element.scrollTop)).toBe(scrolledTo)
+    await creator.getByRole('button', { name: '关闭', exact: true }).click()
+    await creator.waitFor({ state: 'detached' })
+  }, 60_000)
+
   it('views a shipped composition read-only instead of editing it', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-preset-authoring-view'))
     const dialog = settingsDialog()
-    await dialog.getByRole('button', { name: '查看: 标准模式' }).click()
-    const viewer = page.getByRole('dialog', { name: '查看 · 标准模式' })
+    await dialog.getByRole('button', { name: '查看配置: 标准模式' }).click()
+    const viewer = page.getByRole('dialog', { name: '查看配置 · 标准模式' })
     await viewer.waitFor({ timeout: 10_000 })
 
     // The real shipped composition, not a golden: the viewer shows whatever
@@ -118,7 +156,7 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
   it('copies 极简模式 whole under a new id and lands in its files', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-preset-authoring-copy'))
     const dialog = settingsDialog()
-    await dialog.getByRole('button', { name: '复制: 极简模式' }).click()
+    await dialog.getByRole('button', { name: '复制预设: 极简模式' }).click()
     const copyDialog = page.getByRole('dialog', { name: '复制预设 · 复制自 极简模式' })
     await copyDialog.waitFor({ timeout: 10_000 })
 
@@ -131,7 +169,7 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
     expect(dialogSnapshot).not.toContain('描述')
 
     await copyDialog.getByPlaceholder('my-agent').fill('my-agent')
-    await copyDialog.getByPlaceholder('选择器中显示的名字，缺省用标识符').fill('我的模式')
+    await copyDialog.getByPlaceholder('在模式列表中显示的名称，不填则使用标识符').fill('我的模式')
     await copyDialog.getByRole('button', { name: '创建' }).click()
     await copyDialog.waitFor({ state: 'detached', timeout: 10_000 })
 
@@ -175,7 +213,7 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
     // The custom group outlives its only member: the heading stays with the
     // creator entry so the place to author a preset never disappears.
     expect(await dialog.getByRole('heading', { name: '自定义' }).count()).toBe(1)
-    expect(await dialog.getByRole('button', { name: '用「创造模式」创作自定义预设' }).count()).toBe(1)
+    expect(await dialog.getByRole('button', { name: '让 Agent 帮我创建预设模式' }).count()).toBe(1)
     expect(await dialog.getByText('标准模式').count()).toBeGreaterThan(0)
   }, 60_000)
 
@@ -205,10 +243,10 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
     expect(snapshot).toContain('not valid YAML')
     expect(snapshot).toContain('agent.cordis.yml is missing')
     expect(await dialog.getByRole('button', { name: '加载失败: broken-yaml' }).isDisabled()).toBe(true)
-    expect(await dialog.getByRole('button', { name: '复制: 幽灵预设' }).isDisabled()).toBe(true)
+    expect(await dialog.getByRole('button', { name: '复制预设: 幽灵预设' }).isDisabled()).toBe(true)
     // A broken card offers no "set default" affordance at all — the aria name
     // IS the broken marking, so the picking name must not exist.
-    expect(await dialog.getByRole('button', { name: '设为默认: broken-yaml' }).count()).toBe(0)
+    expect(await dialog.getByRole('button', { name: '设为新任务默认: broken-yaml' }).count()).toBe(0)
 
     // The ghost's way out is the card's own delete — and the id it blocked
     // is claimable again immediately afterwards.
@@ -220,13 +258,13 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
     await expect.poll(async () => dialog.getByText('幽灵预设').count(), { timeout: 10_000 }).toBe(0)
     expect(existsSync(join(userRoot, 'ghost'))).toBe(false)
 
-    await dialog.getByRole('button', { name: '复制: 极简模式' }).click()
+    await dialog.getByRole('button', { name: '复制预设: 极简模式' }).click()
     const copyDialog = page.getByRole('dialog', { name: '复制预设 · 复制自 极简模式' })
     await copyDialog.waitFor({ timeout: 10_000 })
     await copyDialog.getByPlaceholder('my-agent').fill('ghost')
     await copyDialog.getByRole('button', { name: '创建' }).click()
     await copyDialog.waitFor({ state: 'detached', timeout: 10_000 })
-    await dialog.getByRole('button', { name: '设为默认: ghost' }).waitFor({ timeout: 10_000 })
+    await dialog.getByRole('button', { name: '设为新任务默认: ghost' }).waitFor({ timeout: 10_000 })
 
     // Leave the roster as the earlier tests shaped it.
     await dialog.getByRole('button', { name: '删除: ghost' }).click()
@@ -248,7 +286,7 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
     const dialog = settingsDialog()
     await dialog.waitFor({ timeout: 10_000 })
     await dialog.getByRole('button', { name: 'Agent 预设' }).click()
-    await dialog.getByRole('button', { name: '用「创造模式」创作自定义预设' }).click()
+    await dialog.getByRole('button', { name: '让 Agent 帮我创建预设模式' }).click()
 
     // Leaving settings is part of the gesture: the flow lands on the
     // new-session screen with the self-referential preset staged, and the
diff --git a/apps/web/tests/agent-preset-selection.e2e.ts b/apps/web/tests/agent-preset-selection.e2e.ts
index b7facbb598..c4198ae414 100644
--- a/apps/web/tests/agent-preset-selection.e2e.ts
+++ b/apps/web/tests/agent-preset-selection.e2e.ts
@@ -265,7 +265,7 @@ describe('web e2e: agent-preset selection', () => {
     await page.getByRole('button', { name: 'Settings', exact: true }).click()
     const dialog = page.getByRole('dialog', { name: 'Settings' })
     await dialog.getByRole('button', { name: 'Agent presets' }).click()
-    const toggle = dialog.getByRole('switch', { name: 'Allow switching Agent modes' })
+    const toggle = dialog.getByRole('switch', { name: 'Choose a mode for new tasks' })
     await dialog.getByRole('button', { name: 'New task default: Standard mode' }).waitFor({ timeout: 10_000 })
     expect(await toggle.getAttribute('aria-checked')).toBe('true')
     await dialog.getByRole('button', { name: 'Close' }).last().click()
@@ -365,13 +365,13 @@ describe('web e2e: agent-preset selection', () => {
     await page.getByRole('button', { name: 'Settings', exact: true }).click()
     const dialog = page.getByRole('dialog', { name: 'Settings' })
     await dialog.getByRole('button', { name: 'Agent presets' }).click()
-    await dialog.getByRole('button', { name: 'Set as default: Minimal mode' }).click()
+    await dialog.getByRole('button', { name: 'Set as new task default: Minimal mode' }).click()
     await dialog.getByRole('button', { name: 'New task default: Minimal mode' }).waitFor({ timeout: 10_000 })
     await expect.poll(() => livePreset(scaffold), { timeout: 15_000 }).toBe('minimal')
-    const toggle = dialog.getByRole('switch', { name: 'Allow switching Agent modes' })
+    const toggle = dialog.getByRole('switch', { name: 'Choose a mode for new tasks' })
     await toggle.click()
     await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
-    await dialog.getByRole('button', { name: 'Default: Standard mode' }).waitFor({ timeout: 10_000 })
+    await dialog.getByRole('button', { name: 'Application default: Standard mode' }).waitFor({ timeout: 10_000 })
     await dialog.getByRole('button', { name: 'Close' }).last().click()
 
     await expect.poll(() => page.getByRole('button', { name: / mode$/ }).count()).toBe(0)
@@ -382,7 +382,7 @@ describe('web e2e: agent-preset selection', () => {
     await page.getByRole('button', { name: 'Settings', exact: true }).click()
     const reopened = page.getByRole('dialog', { name: 'Settings' })
     await reopened.getByRole('button', { name: 'Agent presets' }).click()
-    const reopenedToggle = reopened.getByRole('switch', { name: 'Allow switching Agent modes' })
+    const reopenedToggle = reopened.getByRole('switch', { name: 'Choose a mode for new tasks' })
     await reopenedToggle.click()
     await expect.poll(() => reopenedToggle.getAttribute('aria-checked')).toBe('true')
     await reopened.getByRole('button', { name: 'New task default: Minimal mode' }).waitFor({ timeout: 10_000 })
@@ -404,8 +404,9 @@ describe('web e2e: agent-preset selection', () => {
     await compareOrRefreshGolden(HEADER_EXPECTED, snapshot, MODE)
     expect(snapshot).toContain('Minimal mode')
     expect(snapshot).toContain('button "1 subagent"')
-    expect(snapshot.indexOf('button "1 subagent"')).toBeLessThan(snapshot.indexOf('Minimal mode'))
-    expect(snapshot.indexOf('Minimal mode')).toBeLessThan(snapshot.indexOf('button "More actions"'))
+    // The preset label leads the header band; delegation navigation follows it.
+    expect(snapshot.indexOf('Minimal mode')).toBeLessThan(snapshot.indexOf('button "1 subagent"'))
+    expect(snapshot.indexOf('button "1 subagent"')).toBeLessThan(snapshot.indexOf('button "More actions"'))
     // Static chrome, not a control: the header can only report a composition
     // the host would refuse to change.
     expect(snapshot).not.toContain('button "Minimal mode"')
diff --git a/apps/web/tests/assembled-remote.ts b/apps/web/tests/assembled-remote.ts
index 72a3db40db..8d7502264b 100644
--- a/apps/web/tests/assembled-remote.ts
+++ b/apps/web/tests/assembled-remote.ts
@@ -60,7 +60,6 @@ interface ControlBaseline {
   readonly type: 'baseline'
   readonly value: {
     readonly queues: Readonly<Record<string, readonly unknown[]>>
-    readonly jobs: Readonly<Record<string, readonly unknown[]>>
     readonly approvals: readonly unknown[]
     readonly questions: readonly unknown[]
     readonly projections: Readonly<Record<string, {
@@ -99,7 +98,7 @@ interface CapturedFixture {
 }
 
 export interface AssembledRemoteOptions {
-  /** Supply an enabled Host preference for diagnostic View scenarios. */
+  /** Override the schema-resolved Host preference for developer-tool scenarios. */
   readonly developerTools?: boolean
   /** Return the fixture's image-dimension admission error from Session prompt. */
   readonly rejectPrompt?: boolean
@@ -142,16 +141,14 @@ export function createAssembledRemote(options: AssembledRemoteOptions = {}): Ass
   const mock = RemoteMock.create().load(remoteDefaultResponses)
   mock.load({
     unary: {
-      'settings/describe': options.developerTools === true
-        ? ok({
-          ...fixture.settingsDescribe.value,
-          namespaces: [...fixture.settingsDescribe.value.namespaces, {
-            ns: 'ui-developer-tools',
-            schema: { type: 'object', dict: { enabled: { type: 'boolean' } } },
-            value: { enabled: true }, applies: 'live', secrets: [], revision: 0,
-          }],
-        })
-        : structuredClone(fixture.settingsDescribe),
+      'settings/describe': ok({
+        ...fixture.settingsDescribe.value,
+        namespaces: [...fixture.settingsDescribe.value.namespaces, {
+          ns: 'ui-developer-tools',
+          schema: { type: 'object', dict: { enabled: { type: 'boolean' } } },
+          value: { enabled: options.developerTools ?? true }, applies: 'live', secrets: [], revision: 0,
+        }],
+      }),
       'credentials/describe': structuredClone(fixture.credentialsDescribe),
       'session/modelCatalog': structuredClone(fixture.modelCatalog),
       'agentPresets/list': structuredClone(fixture.agentPresets),
@@ -181,6 +178,9 @@ export function createAssembledRemote(options: AssembledRemoteOptions = {}): Ass
   mock.stream('session/control', (_args, stream) => {
     stream.push(structuredClone(fixture.control))
   })
+  mock.stream('job/list', (_args, stream) => {
+    stream.push({ type: 'rows', jobs: [] })
+  })
   mock.stream('workspace/follow', (_args, stream) => {
     stream.push({
       type: 'baseline',
diff --git a/apps/web/tests/background-job-list.e2e.ts b/apps/web/tests/background-job-list.e2e.ts
index f4db98483a..44427ce945 100644
--- a/apps/web/tests/background-job-list.e2e.ts
+++ b/apps/web/tests/background-job-list.e2e.ts
@@ -1,6 +1,6 @@
 // Session-header background jobs driven by a real `ctx.jobs` entry. No model
 // call is involved.
-import { readFile } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
@@ -22,9 +22,12 @@ const RUNNING_EXPECTED = join(SNAPSHOT_DIR, 'running.expected.md')
 const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md')
 const MODE = webSnapshotMode()
 const SEED_ID = 'background-job-list-web-e2e'
-// Long enough that the running assertions never race the process exiting on
-// their own; the test kills it explicitly to reach the settled state.
-const COMMAND = 'sleep 45'
+// A hold on a barrier file the test owns in the job's cwd: the process never
+// exits on its own, so no CI stall can settle it before the scenario kills it.
+// The bounded loop only caps an orphan's lifetime if the runner dies before
+// `afterAll` releases the barrier.
+const RELEASE = '.background-job-list.release'
+const COMMAND = `for _ in $(seq 1 3000); do [ -e ${RELEASE} ] && break; sleep 0.2; done`
 
 /**
  * Wait for opening a session to publish its live Agent.
@@ -48,7 +51,6 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => {
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
   let agent: Agent
-  let jobId: JobId
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold({})
@@ -73,12 +75,14 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => {
   }, 120_000)
 
   afterAll(async () => {
+    if (scaffold !== undefined) await writeFile(join(scaffold.workspaceCwd, RELEASE), '')
     await browser?.close()
     await scaffold?.close()
   })
 
-  it('shows a running background job in the session header without a refresh', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-running'))
+  it('shows a running background job in the header without a refresh, then flips it to cancelled on settlement', async () => {
+    let phase = 'running'
+    onTestFailed(() => saveFailureShot(page, `web-e2e-background-job-${phase}`))
     // Polling for zero would pass at t=0 before delivery and prove nothing.
     const trigger = page.getByRole('button', { name: '1 background job running' })
     expect(await trigger.count()).toBe(0)
@@ -93,7 +97,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => {
     const reported = started.content.map(block => block.type === 'text' ? block.text : '').join('')
     const matched = /\bbash-\d+\b/.exec(reported)
     if (matched === null) throw new Error(`background bash reported no job id: ${reported}`)
-    jobId = JobId(matched[0])
+    const jobId = JobId(matched[0])
 
     await trigger.waitFor({ timeout: 15_000 })
     await trigger.click()
@@ -101,24 +105,22 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => {
     await row.waitFor({ timeout: 10_000 })
     await expect.poll(() => row.textContent()).toContain(COMMAND)
 
-    const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd)
-    await compareOrRefreshGolden(RUNNING_EXPECTED, snapshot, MODE)
+    const running = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(RUNNING_EXPECTED, running, MODE)
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
-  }, 60_000)
 
-  it('flips the open list to the cancelled outcome when the registry settles it', async () => {
-    onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-settled'))
-    expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested')
+    phase = 'settled'
+    expect(scaffold.ctx.jobs.kill(jobId, agent.id, 'web e2e cancellation')).toBe('requested')
 
     const idle = page.getByRole('button', { name: '1 background job', exact: true })
     await idle.waitFor({ timeout: 20_000 })
 
-    const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd)
-    await compareOrRefreshGolden(SETTLED_EXPECTED, snapshot, MODE)
+    const settled = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(SETTLED_EXPECTED, settled, MODE)
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
-  }, 60_000)
+  }, 90_000)
 
   it('keeps its snapshot inventory closed', async () => {
     await assertFixtureInventory(SNAPSHOT_DIR, ['running.expected.md', 'settled.expected.md'])
diff --git a/apps/web/tests/chat-continuous-conversation.e2e.ts b/apps/web/tests/chat-continuous-conversation.e2e.ts
index 810336de88..de94289607 100644
--- a/apps/web/tests/chat-continuous-conversation.e2e.ts
+++ b/apps/web/tests/chat-continuous-conversation.e2e.ts
@@ -340,9 +340,9 @@ describe('web e2e: continuous conversation grown through the composer', () => {
     ))).toHaveLength(TURN_COUNT)
     expect(sessionEvents.flatMap(event =>
       event.type === 'request/header' ? [event.data.reason] : [])).toEqual(['initial'])
-    expect(await page.getByRole('button', { name: 'System prompt' }).count()).toBe(1)
+    expect(await page.getByRole('button', { name: 'System prompt' }).count()).toBe(0)
     expect(await page.locator(
-      '[data-chat-flow-kind="system-prompt"][hidden="until-found"]',
+      '[data-chat-flow-kind="system-prompt"]',
     ).count()).toBe(0)
     expect(specs.at(-1)?.prompt.length).toBeGreaterThan(4_000)
     expect(sessionEvents.flatMap(event => (
diff --git a/apps/web/tests/clickable-links-gallery.e2e.ts b/apps/web/tests/clickable-links-gallery.e2e.ts
index 21e4f78bae..2cf02b02eb 100644
--- a/apps/web/tests/clickable-links-gallery.e2e.ts
+++ b/apps/web/tests/clickable-links-gallery.e2e.ts
@@ -318,7 +318,7 @@ describe('web e2e: clickable links gallery', () => {
     await seedSession(scaffold, galleryFixture(imageUrl), SEED_ID, undefined, { createdAt: GALLERY_TIME })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
-    await page.route(/https?:\/\/docs\.example\.test\/.*/u, async route => route.fulfill({
+    await page.context().route(/https?:\/\/docs\.example\.test\/.*/u, async route => route.fulfill({
       contentType: 'text/html',
       body: `<h1>${new URL(route.request().url()).pathname}</h1>`,
     }))
@@ -454,5 +454,31 @@ describe('web e2e: clickable links gallery', () => {
     await expect.poll(() => browserAddress.inputValue()).toBe(GUIDE_URL)
     await markdown.locator(`a[href="${HTTP_URL}"]`).click()
     await expect.poll(() => browserAddress.inputValue()).toBe(HTTP_URL)
+
+    await page.getByRole('button', { name: 'Settings', exact: true }).click()
+    await page.getByRole('button', { name: 'Built-in browser', exact: true }).click()
+    await page.getByRole('menuitem', { name: 'New browser tab', exact: true }).click()
+    await expect.poll(() => scaffold.ctx.settings.get('ui-chat')).toMatchObject({ linkOpening: 'new-tab' })
+    await page.keyboard.press('Escape')
+    const popupPromise = page.waitForEvent('popup')
+    await guideLink.click()
+    const popup = await popupPromise
+    try {
+      await popup.waitForURL(GUIDE_URL)
+      expect(await popup.evaluate(() => window.opener === null)).toBe(true)
+      expect(await browserAddress.inputValue()).toBe(HTTP_URL)
+    } finally {
+      await popup.close()
+    }
+
+    await page.reload()
+    await page.getByRole('button', { name: 'Settings', exact: true }).click()
+    await page.getByRole('button', { name: 'New browser tab', exact: true }).click()
+    await page.getByRole('menuitem', { name: 'Built-in browser', exact: true }).click()
+    await expect.poll(() => scaffold.ctx.settings.get('ui-chat')).toMatchObject({ linkOpening: 'sidebar' })
+    await page.keyboard.press('Escape')
+    await guideLink.click()
+    await expect.poll(() => browserAddress.inputValue()).toBe(GUIDE_URL)
+    expect(tripwire.pageErrors).toEqual([])
   }, 90_000)
 })
diff --git a/apps/web/tests/clickable-links-gallery.overlay.yml b/apps/web/tests/clickable-links-gallery.overlay.yml
index d8adc80e3b..ad0114d151 100644
--- a/apps/web/tests/clickable-links-gallery.overlay.yml
+++ b/apps/web/tests/clickable-links-gallery.overlay.yml
@@ -7,3 +7,5 @@
 - id: settings-controller
   config:
     nativeOpen: true
+- id: ui-sidebar-browser
+  disabled: false
diff --git a/apps/web/tests/deepseek-messages-chat.e2e.ts b/apps/web/tests/deepseek-messages-chat.e2e.ts
index 36b37a70ab..d6bbf88260 100644
--- a/apps/web/tests/deepseek-messages-chat.e2e.ts
+++ b/apps/web/tests/deepseek-messages-chat.e2e.ts
@@ -24,7 +24,6 @@ describe.skipIf(MODE === 'record')('web e2e: DeepSeek Messages conversation', ()
   beforeAll(async () => {
     replayFixture = await selectedSessionFixture(FIXTURE, false)
     scaffold = await launchWebScaffold({
-      deepSeekMessages: true,
       replayFixture,
       paceMs: 5,
       replayProviders: [{
@@ -36,6 +35,7 @@ describe.skipIf(MODE === 'record')('web e2e: DeepSeek Messages conversation', ()
         }],
       }],
     })
+    await scaffold.ctx.agentDefaultModel.saveSelection({ provider: 'deepseek-messages', model: 'deepseek-v4-flash' })
     browser = await chromium.launch()
     page = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE })
     tripwire = watchConsole(page)
diff --git a/apps/web/tests/deepseek-messages-settings.e2e.ts b/apps/web/tests/deepseek-messages-settings.e2e.ts
index 32fd2a613e..3018cc432e 100644
--- a/apps/web/tests/deepseek-messages-settings.e2e.ts
+++ b/apps/web/tests/deepseek-messages-settings.e2e.ts
@@ -1,4 +1,4 @@
-/** Opt-in Web Messages configuration, credential reuse, and recovery from a saved Chat Completions selection. */
+/** Web DeepSeek configuration, credential reuse, and saved model selection. */
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -12,14 +12,14 @@ import { connectFreshWorkspaceZh, saveFailureShot, ZH_BROWSER_LOCALE } from './s
 
 const EXPECTED = fileURLToPath(new URL('./expected/deepseek-messages-settings/', import.meta.url))
 
-describe.skipIf(webSnapshotMode() === 'record')('web e2e: DeepSeek Messages opt-in', () => {
+describe.skipIf(webSnapshotMode() === 'record')('web e2e: DeepSeek Messages settings', () => {
   let scaffold: WebScaffold
   let browser: Browser
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({ deepSeekMissingCredential: true, deepSeekMessages: true })
+    scaffold = await launchWebScaffold({ deepSeekMissingCredential: true })
     browser = await chromium.launch()
     page = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: ZH_BROWSER_LOCALE })
     tripwire = watchConsole(page)
@@ -68,7 +68,7 @@ describe.skipIf(webSnapshotMode() === 'record')('web e2e: DeepSeek Messages opt-
     await expect(scaffold.ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-flash')).resolves.toMatchObject({
       name: 'Messages Flash', inputModalities: ['text', 'image'], systemPromptUpdate: 'in-history',
     })
-    expect(scaffold.ctx.settings.get('llm-deepseek')).toMatchObject({ protocol: 'messages' })
+    expect(scaffold.ctx.settings.get('llm-deepseek')).not.toHaveProperty('protocol')
     expect(settings).not.toContain('sk-e2e-')
     const credentials = await readFile(join(scaffold.harnessHome, '.credentials.yaml'), 'utf8')
     expect(credentials).toContain('DEEPSEEK_API_KEY: sk-e2e-messages')
@@ -84,7 +84,7 @@ describe.skipIf(webSnapshotMode() === 'record')('web e2e: DeepSeek Messages opt-
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
-  it('keeps a saved Chat Completions selection available after the YAML protocol switch', async () => {
+  it('keeps a saved DeepSeek selection available after editing provider settings', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-deepseek-messages-default'))
     await page.keyboard.press('Escape')
     await scaffold.ctx.agentDefaultModel.saveSelection({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
diff --git a/apps/web/tests/default-workspace.e2e.ts b/apps/web/tests/default-workspace.e2e.ts
new file mode 100644
index 0000000000..d27f430fd3
--- /dev/null
+++ b/apps/web/tests/default-workspace.e2e.ts
@@ -0,0 +1,135 @@
+/** First-use startup prepares a durable Workspace through the shipped Web composition. */
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { chromium } from 'playwright'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import {
+  assertFinalWorkspaceSnapshot, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, launchWebScaffold,
+  selectedSessionFixture, watchConsole, webSnapshotMode,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/session.v3.jsonl', import.meta.url))
+const EXPECTED = fileURLToPath(new URL('../../../snapshots/web/default-workspace/ui.expected.md', import.meta.url))
+const FAILURE_EXPECTED = fileURLToPath(new URL('./expected/default-workspace/failure.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+
+describe.skipIf(MODE === 'record')('web e2e: default Workspace', () => {
+  it('prepares a blank Session on startup, reuses it after reload, and sends through the ordinary composer', async () => {
+    const fixture = await selectedSessionFixture(FIXTURE)
+    const scaffold = await launchWebScaffold({
+      firstUse: true,
+      replayFixture: fixture,
+      // The shared recording remains read-only; replay compares the complete persisted Session.
+      compareReplaySession: MODE === 'replay',
+      paceMs: 5,
+    })
+    onTestFinished(() => scaffold.close())
+    const browser = await chromium.launch()
+    try {
+      const page = await newEnglishPage(browser)
+      const tripwire = watchConsole(page)
+      try {
+        await page.goto(scaffold.authenticatedUrl)
+        const input = page.locator('[data-composer-input][contenteditable="true"]').first()
+        await input.waitFor()
+        expect(scaffold.ctx.workspaceRegistry.list()).toHaveLength(1)
+        const initialSession = scaffold.ctx.sessions.list()[0]!
+        expect(scaffold.ctx.sessions.list()).toHaveLength(1)
+        expect(initialSession.snapshotEvents().some(event => event.type === 'user/message')).toBe(false)
+        await page.reload()
+        await input.waitFor()
+        expect(scaffold.ctx.sessions.list().map(session => session.id)).toEqual([initialSession.id])
+        const prompt = fixtureUserPrompts(await readFile(fixture, 'utf8'))[0]!
+        await input.fill(prompt)
+        const settled = scaffold.whenTurnSettled()
+        await input.press('Enter')
+        const sessionId = await settled
+        const workspace = scaffold.ctx.workspaceRegistry.list()[0]!
+        expect(workspace.title).toBe('Default workspace')
+        expect(workspace.path).toBe(join(scaffold.workspaceCwd, 'Documents', 'deepseek-harness', 'Default workspace'))
+        expect((await stat(workspace.path)).isDirectory()).toBe(true)
+        expect(workspace.sessionIds).toContain(sessionId)
+        expect(scaffold.ctx.sessions.get(sessionId)?.header.cwd).toBe(workspace.path)
+        await assertFinalWorkspaceSnapshot(fileURLToPath(new URL('../../../snapshots/web/default-workspace', import.meta.url)), workspace.path)
+        await page.getByText('DONE', { exact: true }).waitFor()
+        await compareOrRefreshGolden(EXPECTED, await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd), MODE)
+        expect(tripwire.pageErrors).toEqual([])
+        expect(tripwire.warnings).toEqual([])
+      } catch (error) {
+        await saveFailureShot(page, 'web-e2e-default-workspace')
+        throw error
+      }
+    } finally {
+      await browser.close()
+    }
+  })
+
+  it('reports a startup directory conflict and opens the composed folder picker for recovery', async () => {
+    const scaffold = await launchWebScaffold({ firstUse: true })
+    onTestFinished(() => scaffold.close())
+    const parent = join(scaffold.workspaceCwd, 'Documents', 'deepseek-harness')
+    await mkdir(parent, { recursive: true })
+    await writeFile(join(parent, '默认工作区'), 'occupied')
+    const chosen = join(scaffold.workspaceCwd, 'chosen')
+    await mkdir(chosen)
+    const browser = await chromium.launch()
+    try {
+      const page = await browser.newPage({ locale: 'zh-CN', timezoneId: 'Asia/Shanghai' })
+      const tripwire = watchConsole(page)
+      try {
+        await page.goto(scaffold.authenticatedUrl)
+        const input = page.locator('[data-composer-input][contenteditable="true"]').first()
+        const notice = page.getByRole('alert').filter({ hasText: '无法创建默认工作区' })
+        await notice.waitFor()
+        expect(scaffold.ctx.workspaceRegistry.list()).toEqual([])
+        expect(scaffold.ctx.sessions.list()).toEqual([])
+        await compareOrRefreshGolden(FAILURE_EXPECTED, await notice.ariaSnapshot(), MODE)
+        expect(await page.getByRole('dialog').count()).toBe(0)
+        expect(await input.count()).toBe(0)
+        await page.getByRole('button', { name: '选择工作区', exact: true }).click()
+        const picker = page.getByRole('dialog', { name: '选择工作区目录' })
+        await picker.waitFor()
+        await picker.getByRole('button', { name: '编辑路径', exact: true }).click()
+        await picker.getByRole('textbox', { name: '编辑路径' }).fill(chosen)
+        await page.keyboard.press('Enter')
+        await picker.getByRole('button', { name: '打开', exact: true }).click()
+        await picker.waitFor({ state: 'hidden' })
+        await expect.poll(() => scaffold.ctx.workspaceRegistry.list().length).toBe(1)
+        await input.waitFor()
+        expect(await input.textContent()).toBe('')
+        expect(scaffold.ctx.workspaceRegistry.list()[0]?.path).toBe(chosen)
+        expect(scaffold.ctx.sessions.list()).toHaveLength(1)
+        expect(scaffold.ctx.sessions.list().every(session =>
+          session.snapshotEvents().every(event => event.type !== 'user/message'))).toBe(true)
+        expect(tripwire.pageErrors).toEqual([])
+        expect(tripwire.warnings).toEqual([])
+      } catch (error) {
+        await saveFailureShot(page, 'web-e2e-default-workspace-failure')
+        throw error
+      }
+    } finally {
+      await browser.close()
+    }
+  })
+
+  it('keeps an explicitly deleted default absent on startup', async () => {
+    const scaffold = await launchWebScaffold()
+    onTestFinished(() => scaffold.close())
+    const browser = await chromium.launch()
+    try {
+      const page = await newEnglishPage(browser)
+      const attempted = page.waitForResponse(response => response.url().includes('/api/workspace/initializeDefault'))
+      await page.goto(scaffold.authenticatedUrl)
+      expect((await attempted).ok()).toBe(true)
+      await page.getByRole('button', { name: 'Choose workspace', exact: true }).waitFor()
+      expect(await page.getByRole('alert').filter({ hasText: 'Unable to create default workspace' }).count()).toBe(0)
+      expect(await page.locator('[data-composer-input][contenteditable="true"]').count()).toBe(0)
+      expect(scaffold.ctx.workspaceRegistry.list()).toEqual([])
+      expect(scaffold.ctx.sessions.list()).toEqual([])
+    } finally {
+      await browser.close()
+    }
+  })
+})
diff --git a/apps/web/tests/details-session-lifecycle.e2e.ts b/apps/web/tests/details-session-lifecycle.e2e.ts
index 924105c184..50088b05f7 100644
--- a/apps/web/tests/details-session-lifecycle.e2e.ts
+++ b/apps/web/tests/details-session-lifecycle.e2e.ts
@@ -71,15 +71,22 @@ async function columns(page: Page): Promise<number[]> {
     getComputedStyle(element).gridTemplateColumns.split(' ').map(value => Math.round(Number.parseFloat(value))))
 }
 
+/** Select panes by visual column rather than retained-host DOM order. */
+function paneAt(column: Locator, index: number): Locator {
+  return column.locator(`[data-dockkit-pane][data-dockkit-column="${index}"]`)
+}
+
 /** Tab order and selection inside each docked pane, independent of generated ids. */
 async function paneSnapshot(page: Page) {
-  return await page.locator('[data-rightbar-col] [data-dockkit-pane]').evaluateAll(panes => panes.map(pane => ({
-    active: pane.hasAttribute('data-dockkit-pane-active'),
-    tabs: [...pane.querySelectorAll('[data-dockkit-tab]')].map(tab => ({
-      title: tab.querySelector('[data-dockkit-tab-title]')?.textContent?.trim(),
-      selected: tab.getAttribute('aria-selected') === 'true',
-    })),
-  })))
+  return await page.locator('[data-rightbar-col] [data-dockkit-pane]').evaluateAll(panes => panes
+    .sort((left, right) => Number(left.getAttribute('data-dockkit-column')) - Number(right.getAttribute('data-dockkit-column')))
+    .map(pane => ({
+      active: pane.hasAttribute('data-dockkit-pane-active'),
+      tabs: [...pane.querySelectorAll('[data-dockkit-tab]')].map(tab => ({
+        title: tab.querySelector('[data-dockkit-tab-title]')?.textContent?.trim(),
+        selected: tab.getAttribute('aria-selected') === 'true',
+      })),
+    })))
 }
 
 /** Product-visible geometry, pane state, and expanded Files directories at a settled checkpoint. */
@@ -311,16 +318,15 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
         await Promise.allSettled(frame.getAnimations().map(animation => animation.finished))
       })
       await expect.poll(() => detailsTrack(page)).toBe(0)
-      await panel.waitFor({ state: 'hidden' })
+      await panel.locator('[data-dockkit-pane]').first().waitFor({ state: 'hidden' })
     }
 
     await select(original, 'LIGHTHOUSE')
     await open()
     await column.locator('[data-sidebar-right-guide-entry="files"]').click()
-    // The content-box panel adds its one rendered border pixel outside the
-    // CSS width assigned by the grid solver.
+    // Pane borders stay inside the grid width; the shared panel owns no border.
     await expect.poll(() => sidebarSnapshot(page), { timeout: 5_000 })
-      .toMatchObject({ mode: 'push', panelContentWidth: normalWidth, panelOuterWidth: normalWidth + 1, resizeHandleWidth: 8 })
+      .toMatchObject({ mode: 'push', panelContentWidth: normalWidth, panelOuterWidth: normalWidth, resizeHandleWidth: 8 })
     await expect.poll(async () => ({
       filesVisible: await column.locator('[data-files-state="tree"]').isVisible(),
       errors: tripwire.pageErrors,
@@ -330,9 +336,9 @@ describe.skipIf(MODE === 'record')('web e2e: details panel follows the current S
     await expect.poll(() => split.isDisabled()).toBe(false)
     await split.click()
     await expect.poll(() => panes.count()).toBe(2)
-    await panes.last().locator('[data-sidebar-right-guide-entry="files"]').click()
-    await panes.first().locator('[data-dockkit-tab]').filter({ hasText: 'Files' }).click()
-    await expect.poll(() => panes.first().locator('[data-files-state="tree"]').count()).toBe(1)
+    await paneAt(column, 1).locator('[data-sidebar-right-guide-entry="files"]').click()
+    await paneAt(column, 0).locator('[data-dockkit-tab]').filter({ hasText: 'Files' }).click()
+    await expect.poll(() => paneAt(column, 0).locator('[data-files-state="tree"]').count()).toBe(1)
     const retainedA = await paneSnapshot(page)
     expect(retainedA.map(pane => pane.tabs.map(tab => tab.title))).toEqual([['Files', 'Start'], ['Files']])
     await checkpoint('A normal: two panes')
diff --git a/apps/web/tests/developer-tools-settings.e2e.ts b/apps/web/tests/developer-tools-settings.e2e.ts
index 16c0e6500a..889db40d16 100644
--- a/apps/web/tests/developer-tools-settings.e2e.ts
+++ b/apps/web/tests/developer-tools-settings.e2e.ts
@@ -1,4 +1,4 @@
-/** Shared settings are off on a fresh Host and survive browser reload through the ordinary settings UI. */
+/** Developer tools default on for a fresh Host and survive browser reload through the ordinary settings UI. */
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { chromium } from 'playwright'
@@ -7,7 +7,7 @@ import { launchWebScaffold } from './scaffold.ts'
 import { newEnglishPage } from './support.ts'
 
 it('persists developer tools in the Host settings document and restores the accepted choice', async () => {
-  const scaffold = await launchWebScaffold({ developerTools: false })
+  const scaffold = await launchWebScaffold()
   onTestFinished(() => scaffold.close())
   const browser = await chromium.launch()
   onTestFinished(() => browser.close())
@@ -15,15 +15,26 @@ it('persists developer tools in the Host settings document and restores the acce
   await page.goto(scaffold.authenticatedUrl)
   await page.getByRole('button', { name: 'Settings', exact: true }).click()
   const toggle = page.getByRole('switch', { name: 'Developer tools' })
-  expect(await toggle.getAttribute('aria-checked')).toBe('false')
+  expect(await toggle.getAttribute('aria-checked')).toBe('true')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).not.toContain('ui-developer-tools:')
   await toggle.click()
-  await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
-  expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n  enabled: true')
-  await page.reload()
-  await page.getByRole('button', { name: 'Settings', exact: true }).click()
-  await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
-  await toggle.click()
   await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
   expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n  enabled: false')
+  await page.reload()
+  await page.getByRole('button', { name: 'Settings', exact: true }).click()
+  await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
+
+  await page.getByRole('button', { name: 'Agent presets', exact: true }).click()
+  const pickerToggle = page.getByRole('switch', { name: 'Choose a mode for new tasks' })
+  await expect.poll(() => page.getByRole('heading', { name: 'Agent presets', exact: true }).count()).toBe(1)
+  expect(await pickerToggle.count()).toBe(0)
+  await scaffold.ctx.settings.update('ui-developer-tools', { enabled: true })
+  await expect.poll(() => pickerToggle.count()).toBe(1)
+  await expect.poll(() => pickerToggle.isEnabled()).toBe(true)
+  const pickerEnabled = await pickerToggle.getAttribute('aria-checked')
+  await scaffold.ctx.settings.update('ui-developer-tools', { enabled: false })
+  await expect.poll(() => pickerToggle.count()).toBe(0)
+  await scaffold.ctx.settings.update('ui-developer-tools', { enabled: true })
+  await expect.poll(() => pickerToggle.isEnabled()).toBe(true)
+  await expect.poll(() => pickerToggle.getAttribute('aria-checked')).toBe(pickerEnabled)
 })
diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts
index 31b2fd06b6..adefac10ee 100644
--- a/apps/web/tests/document-preview.e2e.ts
+++ b/apps/web/tests/document-preview.e2e.ts
@@ -89,8 +89,8 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
   let outsideRoot: string | undefined
   let nativeRoot: string | undefined
   let openLog = ''
-  const opened = async (): Promise<Array<{ path: string; action: 'open' | 'reveal' }>> =>
-    (await readFile(openLog, 'utf8')).split('\n').filter(Boolean).map(line => JSON.parse(line) as { path: string; action: 'open' | 'reveal' })
+  const opened = async (): Promise<Array<{ path: string; action: 'open' | 'reveal' | 'application' }>> =>
+    (await readFile(openLog, 'utf8')).split('\n').filter(Boolean).map(line => JSON.parse(line) as { path: string; action: 'open' | 'reveal' | 'application' })
 
   beforeAll(async () => {
     outsideRoot = await mkdtemp(join(tmpdir(), 'dsh-preview-outside-'))
@@ -102,10 +102,34 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
       const command = process.platform === 'darwin' ? 'open' : 'xdg-open'
       await writeFile(join(nativeRoot, command), `#!/usr/bin/env node
 const fs = require('node:fs');
-const path = process.argv[2] === '-R' ? process.argv[3] : process.argv[2];
-const action = process.argv[2] === '-R' || fs.statSync(path).isDirectory() ? 'reveal' : 'open';
+const path = process.argv[2] === '-a' ? process.argv[4] : process.argv[2] === '-R' ? process.argv[3] : process.argv[2];
+const action = process.argv[2] === '-a' ? 'application' : process.argv[2] === '-R' || fs.statSync(path).isDirectory() ? 'reveal' : 'open';
 fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) + '\\n');
 `, { mode: 0o700 })
+      if (process.platform === 'darwin') {
+        const apps = [
+          { id: '/Applications/Test Player.app', name: 'Test Player', default: true, icon: `data:image/png;base64,${TINY_PNG.toString('base64')}` },
+          { id: '/Applications/Other Player.app', name: 'Other Player', default: false, icon: null },
+        ]
+        await writeFile(join(nativeRoot, 'osascript'), `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(JSON.stringify(apps))});\n`, { mode: 0o700 })
+      }
+      if (process.platform === 'linux') {
+        const data = join(nativeRoot, 'data')
+        await mkdir(join(data, 'applications'), { recursive: true })
+        const icon = join(nativeRoot, 'icon.png')
+        await writeFile(icon, TINY_PNG)
+        await writeFile(join(data, 'applications', 'test.desktop'), `[Desktop Entry]\nName=Test Player\nIcon=${icon}\n`)
+        await writeFile(join(data, 'applications', 'other.desktop'), '[Desktop Entry]\nName=Other Player\n')
+        await writeFile(join(nativeRoot, 'gio'), `#!/usr/bin/env node
+const fs = require('node:fs');
+if (process.argv[2] === 'info') process.stdout.write('standard::content-type: video/mp4');
+else if (process.argv[2] === 'mime') process.stdout.write('Default application for video/mp4: test.desktop\\nRegistered applications:\\n  test.desktop\\n  other.desktop\\n');
+else if (process.argv[2] === 'launch') fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path: process.argv[4], action: 'application' }) + '\\n');
+else process.exit(1);
+`, { mode: 0o700 })
+        vi.stubEnv('XDG_DATA_HOME', data)
+        vi.stubEnv('XDG_DATA_DIRS', '')
+      }
       vi.stubEnv('PATH', `${nativeRoot}${delimiter}${process.env.PATH ?? ''}`)
     }
     // The Open In rows carry the default-application controls; the SSH marker
@@ -260,7 +284,7 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
     const restoredAdd = await addTab.count()
     expect(restoredFilesClose).toBe(1)
     expect(restoredAdd).toBe(1)
-    const preview = column.locator('[data-document-preview]')
+    const preview = column.locator('[data-textpreview-url]')
     const openFile = openPreviewFile.bind(undefined, column, filesTab, preview)
     const viewer = preview.locator('[data-document-viewer-menu]')
     const body = preview.locator('[data-textpreview-body]')
@@ -365,7 +389,7 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
     await successShot(page, 'html-basic')
     sections.push([
       '## Basic HTML', '',
-      '- Developer tools: off by default on Web and desktop',
+      '- Developer tools: disabled for this scenario',
       '- Sandbox: no permissions',
       `- Inline script: ${await basicHtml.locator('#result').innerText()}`,
       `- Local script: ${await basicHtml.locator('#local-result').innerText()}`,
@@ -547,7 +571,21 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
     await successShot(page, 'pdf-drag-selection')
     sections.push('## PDF drag selection\n\n- Table selection: forward and backward drags exclude later sections\n- Line-break highlight: transparent')
 
+    const pngResponse = page.waitForResponse(response => new URL(response.url()).pathname === '/api/workspaceFiles/readBytes'
+      && (response.request().postDataJSON() as { payload: { args: { path: string } } }).payload.args.path === 'tiny.png')
     await openFile('tiny.png')
+    const transferred = await pngResponse
+    expect(transferred.headers()['content-type']).toMatch(/^multipart\/form-data;/)
+    const transferredBody = await new Response(new Uint8Array(await transferred.body()), { headers: transferred.headers() }).formData()
+    const metadata = transferredBody.get('metadata')
+    if (typeof metadata !== 'string') throw new Error('missing PNG metadata')
+    const { attachments } = JSON.parse(metadata) as { attachments: { path: string[]; codec: string; part: string }[] }
+    expect(attachments).toHaveLength(1)
+    expect(attachments[0]).toMatchObject({ path: ['data'], codec: 'bytes' })
+    expect(attachments[0]!.part).toEqual(expect.any(String))
+    const transferredFile = transferredBody.get(attachments[0]!.part)
+    if (transferredFile === null || typeof transferredFile === 'string') throw new Error('missing PNG payload')
+    expect(Buffer.from(await transferredFile.arrayBuffer())).toEqual(TINY_PNG)
     const tinyImage = preview.getByRole('img', { name: 'Image preview: tiny.png', exact: true })
     await tinyImage.waitFor({ state: 'visible', timeout: 15_000 })
     expect(await viewer.count()).toBe(0)
@@ -696,7 +734,7 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
 
     const officeMenus: number[] = []
     const configurationGuide = 'Read failed: Office previews are unavailable. Enable the document preview service on the computer running DeepSeek Harness.'
-    for (const extension of ['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx']) {
+    for (const extension of ['doc', 'docx', 'ppt', 'pptx']) {
       await openFile(`unavailable.${extension}`)
       expect(await preview.locator('[data-document-viewer-menu]').count()).toBe(0)
       await preview.getByText(configurationGuide, { exact: true }).waitFor({ timeout: 15_000 })
@@ -707,12 +745,23 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
     await successShot(page, 'office-unavailable')
     sections.push([
       '## Office unavailable', '',
-      `- DOC, DOCX, XLS, XLSX, PPT, PPTX viewer menus: ${officeMenus.join(' | ')}`,
+      `- DOC, DOCX, PPT, PPTX viewer menus: ${officeMenus.join(' | ')}`,
       `- Guidance: ${configurationGuide}`,
       '- Binary text shown: false',
       '- Plain-text option and viewer picker: hidden',
     ].join('\n'))
 
+    const spreadsheetStates: string[] = []
+    for (const extension of ['xls', 'xlsx']) {
+      await openFile(`unavailable.${extension}`)
+      const spreadsheet = column.locator('[data-textpreview-state="unsupported"]')
+      await spreadsheet.waitFor({ timeout: 15_000 })
+      expect(await spreadsheet.getByText('Preview is not available for this file type yet.', { exact: true }).count()).toBe(1)
+      await spreadsheet.locator('[data-open-path-unpreviewable]').waitFor({ timeout: 15_000 })
+      spreadsheetStates.push(`${extension.toUpperCase()}: unsupported / Open in default app`)
+    }
+    sections.push(['## Spreadsheet preview', '', `- ${spreadsheetStates.join('\n- ')}`].join('\n'))
+
     await openFile('notes.unknown')
     const plainLines = preview.locator('[data-textpreview-line]')
     await expect.poll(() => plainLines.count()).toBe(2)
@@ -736,13 +785,16 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
     await headerOpen.waitFor({ timeout: 15_000 })
     const emptyOpen = unsupported.locator('[data-textpreview-unsupported] [data-open-path-unpreviewable]')
     await emptyOpen.waitFor({ timeout: 15_000 })
+    const prominent = unsupported.locator('[data-open-target="file"][data-size="large"]')
+    expect((await prominent.boundingBox())?.height).toBe(40)
+    expect((await unsupported.locator('[data-open-path]').boundingBox())?.height).toBe(24)
     await successShot(page, 'unsupported')
     sections.push([
       '## Unviewable binary', '',
       '- State: unsupported',
       `- Line: ${unsupportedLine.trim()}`,
-      `- Header control: ${await headerOpen.innerText()}`,
-      `- Empty-state control: ${await emptyOpen.innerText()}`,
+      `- Header control has no text: ${String(await headerOpen.innerText() === '')}`,
+      `- Empty-state control has text: ${String((await emptyOpen.innerText()).length > 0)}`,
     ].join('\n'))
     if (STUB_OPENER) {
       // Real Host gestures against the stubbed opener: default application from the empty state, reveal from the header menu.
@@ -750,19 +802,32 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action }) +
       await emptyOpen.click()
       await expect.poll(async () => (await opened()).length, { timeout: 15_000 }).toBe(1)
       await unsupported.locator('[data-open-path-more]').click()
-      await page.getByRole('menuitem', { name: 'Show file location', exact: true }).click()
+      await page.getByRole('menuitem', { name: /^Show file location/ }).click()
       await expect.poll(async () => (await opened()).length, { timeout: 15_000 }).toBe(2)
       const gestures = await opened()
-      expect(gestures[0]).toEqual({ path: clip, action: 'open' })
+      expect(gestures[0]?.action).toBe('open')
+      expect([clip, cwd]).toContain(gestures[0]?.path)
       expect(gestures[1]?.action).toBe('reveal')
       expect([clip, cwd]).toContain(gestures[1]?.path)
+      if (STUB_OPENER) {
+        await expect.poll(() => headerOpen.locator('img').count()).toBe(1)
+        await prominent.getByRole('button', { name: 'More ways to open' }).click()
+        await page.getByRole('menuitem', { name: 'Test Player (default)', exact: true }).waitFor()
+        await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'applications.expected.md'), await page.getByRole('menu').ariaSnapshot(), MODE)
+        await page.getByRole('menuitem', { name: 'Other Player', exact: true }).click()
+        await expect.poll(async () => (await opened()).length).toBe(3)
+        expect((await opened())[2]).toEqual({ path: clip, action: 'application' })
+        await headerOpen.click()
+        await expect.poll(async () => (await opened()).length).toBe(4)
+        expect((await opened())[3]).toEqual({ path: clip, action: 'open' })
+      }
       // Gesture facts stay out of the golden: the stub does not run on Windows.
       expect(await page.getByRole('alert').count()).toBe(0)
     }
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await compareOrRefreshGolden(EXPECTED, sections.join('\n\n'), MODE)
-    await assertFixtureInventory(SNAPSHOT_DIR, ['document.expected.md', 'paging.patch.yml'])
+    await assertFixtureInventory(SNAPSHOT_DIR, ['document.expected.md', 'applications.expected.md', 'paging.patch.yml'])
   })
 })
 
@@ -810,7 +875,7 @@ describe.skipIf(MODE === 'record')('web e2e: Host Office preview', () => {
       await column.locator('[data-files-state="tree"]').waitFor({ state: 'visible' })
       await column.locator('[data-files-reload]').click()
       const filesTab = column.locator('[data-dockkit-tab]').filter({ has: page.getByText('Files', { exact: true }) })
-      const preview = column.locator('[data-document-preview]')
+      const preview = column.locator('[data-textpreview-url]')
       await column.locator('[data-files-entry="file"]').getByRole('button', { name: 'chinese.docx', exact: true }).click()
       expect(await preview.locator('[data-document-viewer-menu]').count()).toBe(0)
       const canvas = preview.getByRole('img', { name: 'PDF page 1', exact: true })
@@ -885,30 +950,36 @@ describe.skipIf(MODE === 'record')('web e2e: Host Office preview', () => {
         `- Document top inset: ${topInset}px`,
       ].join('\n'), MODE)
       await successShot(page, 'office-docx')
-      for (const extension of ['doc', 'xls', 'xlsx', 'ppt', 'pptx']) {
+      for (const extension of ['doc', 'ppt', 'pptx']) {
         await openPreviewFile(column, filesTab, preview, `chinese.${extension}`)
         await preview.getByRole('img', { name: 'PDF page 1', exact: true }).waitFor({ state: 'visible', timeout: 60_000 })
         await expect.poll(async () => (await preview.locator('[data-pdf-text]').allTextContents()).join(''), { timeout: 30_000 }).toContain('中文文档')
-        if (['doc', 'xls', 'ppt'].includes(extension)) expect(await warning.count()).toBe(0)
+        if (['doc', 'ppt'].includes(extension)) expect(await warning.count()).toBe(0)
         await successShot(page, `office-${extension}`)
       }
-      expect(convert).toHaveBeenCalledTimes(6)
+      expect(convert).toHaveBeenCalledTimes(4)
+      for (const extension of ['xls', 'xlsx']) {
+        await openPreviewFile(column, filesTab, preview, `chinese.${extension}`)
+        await preview.getByText('Preview is not available for this file type yet.', { exact: true }).waitFor({ timeout: 15_000 })
+        expect(await preview.getByRole('img', { name: 'PDF page 1', exact: true }).count()).toBe(0)
+      }
+      expect(convert).toHaveBeenCalledTimes(4)
       await openPreviewFile(column, filesTab, preview, 'chinese.docx')
       await preview.getByRole('img', { name: 'PDF page 1', exact: true }).waitFor({ state: 'visible' })
       await preview.getByRole('button', { name: 'Read the file again', exact: true }).click()
-      await expect.poll(() => convert.mock.calls.length).toBe(7)
+      await expect.poll(() => convert.mock.calls.length).toBe(5)
       await preview.getByRole('img', { name: 'PDF page 1', exact: true }).waitFor({ state: 'visible' })
       await openPreviewFile(column, filesTab, preview, 'renamed.docx')
       await preview.getByText('Read failed: This Office file cannot be previewed. It may be damaged, password protected, or have the wrong extension.', { exact: true }).waitFor({ timeout: 30_000 })
       expect(await preview.locator('[data-textpreview-line]').count()).toBe(0)
       await successShot(page, 'office-invalid')
-      expect(convert).toHaveBeenCalledTimes(8)
-      for (const extension of ['doc', 'xls', 'ppt']) {
+      expect(convert).toHaveBeenCalledTimes(6)
+      for (const extension of ['doc', 'ppt']) {
         await openPreviewFile(column, filesTab, preview, `renamed.${extension}`)
         await preview.getByText('Read failed: This Office file cannot be previewed. It may be damaged, password protected, or have the wrong extension.', { exact: true }).waitFor({ timeout: 30_000 })
         expect(await preview.locator('[data-textpreview-line]').count()).toBe(0)
       }
-      expect(convert).toHaveBeenCalledTimes(11)
+      expect(convert).toHaveBeenCalledTimes(8)
       expect(tripwire.pageErrors).toEqual([])
     } finally { convert.mockRestore() }
   })
diff --git a/apps/web/tests/expected/agent-preset-authoring/copy-dialog.expected.md b/apps/web/tests/expected/agent-preset-authoring/copy-dialog.expected.md
index 6e0cbf8c14..f3d67b4e69 100644
--- a/apps/web/tests/expected/agent-preset-authoring/copy-dialog.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/copy-dialog.expected.md
@@ -1,13 +1,13 @@
 - dialog "复制预设 · 复制自 极简模式":
   - heading "复制预设 · 复制自 极简模式" [level=2]
   - button "关闭"
-  - paragraph: 整个预设会在本机复制一份。标识符将成为目录名，事后无法更改；其余内容之后直接在预设自己的文件里编辑。
+  - paragraph: 复制后会在本机保存一份预设，你可以打开目录修改配置。标识符用作目录名，创建后不能修改。
   - text: 标识符
   - textbox "标识符":
     - /placeholder: my-agent
   - text: 名称
   - textbox "名称":
-    - /placeholder: 选择器中显示的名字，缺省用标识符
+    - /placeholder: 在模式列表中显示的名称，不填则使用标识符
   - alert: 请填写标识符。
   - button "取消"
   - button "创建" [disabled]
diff --git a/apps/web/tests/expected/agent-preset-authoring/created.expected.md b/apps/web/tests/expected/agent-preset-authoring/created.expected.md
index f55d4098d2..20455df885 100644
--- a/apps/web/tests/expected/agent-preset-authoring/created.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/created.expected.md
@@ -8,46 +8,59 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "Agent 预设" [level=2]
-  - paragraph: 预设即一个会话的 Agent 所运行的插件组装 —— 它的工具、提示词与能力。复制一份既有预设改成自己的，或用「创造模式」让 Agent 帮你创建。
-  - text: 允许切换agent模式 beta
-  - paragraph: 开启后，新任务可选择标准、PTC、创造、极简及自定义模式；关闭后统一使用默认模式（默认为标准模式，可自定义）。仅影响新任务。
-  - switch "允许切换agent模式" [checked]
+  - paragraph: 选择 Agent 的工具和工作方式。日常任务用「标准模式」，扩展 DSH 的能力用「创造模式」。
+  - text: 新任务可选择模式 Beta
+  - paragraph: 开启后，可为每个新任务选择模式，并在这里设置默认值。关闭后，新任务使用应用配置的默认预设。已有任务不受影响。
+  - switch "新任务可选择模式" [checked]
   - heading "内置" [level=3]
   - list:
     - listitem:
       - 'button "新任务默认: 标准模式" [disabled] [pressed]':
-        - text: 标准模式 内置 新任务默认 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。
+        - text: 标准模式 新任务默认
         - code: standard
-      - 'button "查看: 标准模式"': 查看
-      - 'button "复制: 标准模式"': 复制
+        - text: 处理代码、文件和资料，适合大多数任务。Agent 会按需使用检索、编辑和终端等工具。
+      - 'button "模式说明: 标准模式"': 模式说明
+      - 'button "如何使用: 标准模式"': 如何使用
+      - 'button "查看配置: 标准模式"': 查看配置
+      - 'button "复制预设: 标准模式"': 复制预设
     - listitem:
-      - 'button "设为默认: PTC 模式"':
-        - text: PTC 模式 内置 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
+      - 'button "设为新任务默认: PTC 模式"':
+        - text: PTC 模式 内置
         - code: ptc
-      - 'button "查看: PTC 模式"': 查看
-      - 'button "复制: PTC 模式"': 复制
+        - text: 包含标准模式的所有能力，更适合批量调用工具，并对结果进行筛选、整理、去重、统计或汇总的任务。
+      - 'button "模式说明: PTC 模式"': 模式说明
+      - 'button "如何使用: PTC 模式"': 如何使用
+      - 'button "查看配置: PTC 模式"': 查看配置
+      - 'button "复制预设: PTC 模式"': 复制预设
     - listitem:
-      - 'button "设为默认: 极简模式"':
-        - text: 极简模式 内置 仅提供持久 shell 的单工具编码 Agent。
+      - 'button "设为新任务默认: 极简模式"':
+        - text: 极简模式 内置
         - code: minimal
-      - 'button "查看: 极简模式"': 查看
-      - 'button "复制: 极简模式"': 复制
+        - text: Agent 仅使用终端工具完成任务，适合测试和对比其基础表现。
+      - 'button "模式说明: 极简模式"': 模式说明
+      - 'button "如何使用: 极简模式"': 如何使用
+      - 'button "查看配置: 极简模式"': 查看配置
+      - 'button "复制预设: 极简模式"': 复制预设
     - listitem:
-      - 'button "设为默认: 创造模式"':
-        - text: 创造模式 内置 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、持久化插件管理和 preset 创作指导。
+      - 'button "设为新任务默认: 创造模式"':
+        - text: 创造模式 内置
         - code: cordis
-      - 'button "查看: 创造模式"': 查看
-      - 'button "复制: 创造模式"': 复制
+        - text: 用对话定制 DSH：让 Agent 编写插件，添加新功能或界面；也能组合工具和提示词，创建自己的模式。
+      - 'button "模式说明: 创造模式"': 模式说明
+      - 'button "如何使用: 创造模式"': 如何使用
+      - 'button "查看配置: 创造模式"': 查看配置
+      - 'button "复制预设: 创造模式"': 复制预设
   - heading "自定义" [level=3]
   - list:
     - listitem:
-      - 'button "设为默认: 我的模式"':
-        - text: 我的模式 自定义 仅提供持久 shell 的单工具编码 Agent。
+      - 'button "设为新任务默认: 我的模式"':
+        - text: 我的模式 自定义
         - code: my-agent
+        - text: 仅提供持久 shell 的单工具编码 Agent。
       - 'button "查看路径: 我的模式"': 查看路径
-      - 'button "复制: 我的模式"': 复制
+      - 'button "复制预设: 我的模式"': 复制预设
       - 'button "删除: 我的模式"': 删除
       - paragraph:
         - text: 预设文件：
         - code: {{presetRoot}}/my-agent
-  - button "用「创造模式」创作自定义预设"
+  - button "让 Agent 帮我创建预设模式"
diff --git a/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md b/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md
index 2d4db679fb..a7434c0336 100644
--- a/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md
@@ -8,52 +8,66 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "Agent 预设" [level=2]
-  - paragraph: 预设即一个会话的 Agent 所运行的插件组装 —— 它的工具、提示词与能力。复制一份既有预设改成自己的，或用「创造模式」让 Agent 帮你创建。
-  - text: 允许切换agent模式 beta
-  - paragraph: 开启后，新任务可选择标准、PTC、创造、极简及自定义模式；关闭后统一使用默认模式（默认为标准模式，可自定义）。仅影响新任务。
-  - switch "允许切换agent模式" [checked]
+  - paragraph: 选择 Agent 的工具和工作方式。日常任务用「标准模式」，扩展 DSH 的能力用「创造模式」。
+  - text: 新任务可选择模式 Beta
+  - paragraph: 开启后，可为每个新任务选择模式，并在这里设置默认值。关闭后，新任务使用应用配置的默认预设。已有任务不受影响。
+  - switch "新任务可选择模式" [checked]
   - heading "内置" [level=3]
   - list:
     - listitem:
       - 'button "新任务默认: 标准模式" [disabled] [pressed]':
-        - text: 标准模式 内置 新任务默认 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。
+        - text: 标准模式 新任务默认
         - code: standard
-      - 'button "查看: 标准模式"': 查看
-      - 'button "复制: 标准模式"': 复制
+        - text: 处理代码、文件和资料，适合大多数任务。Agent 会按需使用检索、编辑和终端等工具。
+      - 'button "模式说明: 标准模式"': 模式说明
+      - 'button "如何使用: 标准模式"': 如何使用
+      - 'button "查看配置: 标准模式"': 查看配置
+      - 'button "复制预设: 标准模式"': 复制预设
     - listitem:
-      - 'button "设为默认: PTC 模式"':
-        - text: PTC 模式 内置 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
+      - 'button "设为新任务默认: PTC 模式"':
+        - text: PTC 模式 内置
         - code: ptc
-      - 'button "查看: PTC 模式"': 查看
-      - 'button "复制: PTC 模式"': 复制
+        - text: 包含标准模式的所有能力，更适合批量调用工具，并对结果进行筛选、整理、去重、统计或汇总的任务。
+      - 'button "模式说明: PTC 模式"': 模式说明
+      - 'button "如何使用: PTC 模式"': 如何使用
+      - 'button "查看配置: PTC 模式"': 查看配置
+      - 'button "复制预设: PTC 模式"': 复制预设
     - listitem:
-      - 'button "设为默认: 极简模式"':
-        - text: 极简模式 内置 仅提供持久 shell 的单工具编码 Agent。
+      - 'button "设为新任务默认: 极简模式"':
+        - text: 极简模式 内置
         - code: minimal
-      - 'button "查看: 极简模式"': 查看
-      - 'button "复制: 极简模式"': 复制
+        - text: Agent 仅使用终端工具完成任务，适合测试和对比其基础表现。
+      - 'button "模式说明: 极简模式"': 模式说明
+      - 'button "如何使用: 极简模式"': 如何使用
+      - 'button "查看配置: 极简模式"': 查看配置
+      - 'button "复制预设: 极简模式"': 复制预设
     - listitem:
-      - 'button "设为默认: 创造模式"':
-        - text: 创造模式 内置 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、持久化插件管理和 preset 创作指导。
+      - 'button "设为新任务默认: 创造模式"':
+        - text: 创造模式 内置
         - code: cordis
-      - 'button "查看: 创造模式"': 查看
-      - 'button "复制: 创造模式"': 复制
+        - text: 用对话定制 DSH：让 Agent 编写插件，添加新功能或界面；也能组合工具和提示词，创建自己的模式。
+      - 'button "模式说明: 创造模式"': 模式说明
+      - 'button "如何使用: 创造模式"': 如何使用
+      - 'button "查看配置: 创造模式"': 查看配置
+      - 'button "复制预设: 创造模式"': 复制预设
   - heading "自定义" [level=3]
   - list:
     - listitem:
       - 'button "加载失败: broken-yaml" [disabled]':
-        - text: broken-yaml 加载失败 自定义 暂无描述。
-        - alert: "the composition is not valid YAML: unexpected end of the stream within a flow collection (3:1)"
+        - text: broken-yaml 加载失败 自定义
         - code: broken-yaml
+        - text: 暂无描述。
+        - alert: "the composition is not valid YAML: unexpected end of the stream within a flow collection (3:1)"
       - 'button "查看路径: broken-yaml"': 查看路径
-      - 'button "复制: broken-yaml" [disabled]': 预设加载失败，不能复制
+      - 'button "复制预设: broken-yaml" [disabled]': 预设加载失败，不能复制
       - 'button "删除: broken-yaml"': 删除
     - listitem:
       - 'button "加载失败: 幽灵预设" [disabled]':
-        - text: 幽灵预设 加载失败 自定义 composition 已被手动删除。
-        - alert: the composition file agent.cordis.yml is missing — the directory still occupies the id; delete it or restore the file
+        - text: 幽灵预设 加载失败 自定义
         - code: ghost
+        - text: composition 已被手动删除。
+        - alert: the composition file agent.cordis.yml is missing — the directory still occupies the id; delete it or restore the file
       - 'button "查看路径: 幽灵预设"': 查看路径
-      - 'button "复制: 幽灵预设" [disabled]': 预设加载失败，不能复制
+      - 'button "复制预设: 幽灵预设" [disabled]': 预设加载失败，不能复制
       - 'button "删除: 幽灵预设"': 删除
-  - button "用「创造模式」创作自定义预设"
+  - button "让 Agent 帮我创建预设模式"
diff --git a/apps/web/tests/expected/agent-preset-authoring/section.expected.md b/apps/web/tests/expected/agent-preset-authoring/section.expected.md
index 077c88b625..44b226efc0 100644
--- a/apps/web/tests/expected/agent-preset-authoring/section.expected.md
+++ b/apps/web/tests/expected/agent-preset-authoring/section.expected.md
@@ -8,35 +8,47 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "Agent 预设" [level=2]
-  - paragraph: 预设即一个会话的 Agent 所运行的插件组装 —— 它的工具、提示词与能力。复制一份既有预设改成自己的，或用「创造模式」让 Agent 帮你创建。
-  - text: 允许切换agent模式 beta
-  - paragraph: 开启后，新任务可选择标准、PTC、创造、极简及自定义模式；关闭后统一使用默认模式（默认为标准模式，可自定义）。仅影响新任务。
-  - switch "允许切换agent模式" [checked]
+  - paragraph: 选择 Agent 的工具和工作方式。日常任务用「标准模式」，扩展 DSH 的能力用「创造模式」。
+  - text: 新任务可选择模式 Beta
+  - paragraph: 开启后，可为每个新任务选择模式，并在这里设置默认值。关闭后，新任务使用应用配置的默认预设。已有任务不受影响。
+  - switch "新任务可选择模式" [checked]
   - heading "内置" [level=3]
   - list:
     - listitem:
       - 'button "新任务默认: 标准模式" [disabled] [pressed]':
-        - text: 标准模式 内置 新任务默认 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。
+        - text: 标准模式 新任务默认
         - code: standard
-      - 'button "查看: 标准模式"': 查看
-      - 'button "复制: 标准模式"': 复制
+        - text: 处理代码、文件和资料，适合大多数任务。Agent 会按需使用检索、编辑和终端等工具。
+      - 'button "模式说明: 标准模式"': 模式说明
+      - 'button "如何使用: 标准模式"': 如何使用
+      - 'button "查看配置: 标准模式"': 查看配置
+      - 'button "复制预设: 标准模式"': 复制预设
     - listitem:
-      - 'button "设为默认: PTC 模式"':
-        - text: PTC 模式 内置 功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。
+      - 'button "设为新任务默认: PTC 模式"':
+        - text: PTC 模式 内置
         - code: ptc
-      - 'button "查看: PTC 模式"': 查看
-      - 'button "复制: PTC 模式"': 复制
+        - text: 包含标准模式的所有能力，更适合批量调用工具，并对结果进行筛选、整理、去重、统计或汇总的任务。
+      - 'button "模式说明: PTC 模式"': 模式说明
+      - 'button "如何使用: PTC 模式"': 如何使用
+      - 'button "查看配置: PTC 模式"': 查看配置
+      - 'button "复制预设: PTC 模式"': 复制预设
     - listitem:
-      - 'button "设为默认: 极简模式"':
-        - text: 极简模式 内置 仅提供持久 shell 的单工具编码 Agent。
+      - 'button "设为新任务默认: 极简模式"':
+        - text: 极简模式 内置
         - code: minimal
-      - 'button "查看: 极简模式"': 查看
-      - 'button "复制: 极简模式"': 复制
+        - text: Agent 仅使用终端工具完成任务，适合测试和对比其基础表现。
+      - 'button "模式说明: 极简模式"': 模式说明
+      - 'button "如何使用: 极简模式"': 如何使用
+      - 'button "查看配置: 极简模式"': 查看配置
+      - 'button "复制预设: 极简模式"': 复制预设
     - listitem:
-      - 'button "设为默认: 创造模式"':
-        - text: 创造模式 内置 用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、持久化插件管理和 preset 创作指导。
+      - 'button "设为新任务默认: 创造模式"':
+        - text: 创造模式 内置
         - code: cordis
-      - 'button "查看: 创造模式"': 查看
-      - 'button "复制: 创造模式"': 复制
+        - text: 用对话定制 DSH：让 Agent 编写插件，添加新功能或界面；也能组合工具和提示词，创建自己的模式。
+      - 'button "模式说明: 创造模式"': 模式说明
+      - 'button "如何使用: 创造模式"': 如何使用
+      - 'button "查看配置: 创造模式"': 查看配置
+      - 'button "复制预设: 创造模式"': 复制预设
   - heading "自定义" [level=3]
-  - button "用「创造模式」创作自定义预设"
+  - button "让 Agent 帮我创建预设模式"
diff --git a/apps/web/tests/expected/agent-preset-selection/header.expected.md b/apps/web/tests/expected/agent-preset-selection/header.expected.md
index 32b0ea6a2a..2b87066124 100644
--- a/apps/web/tests/expected/agent-preset-selection/header.expected.md
+++ b/apps/web/tests/expected/agent-preset-selection/header.expected.md
@@ -1,6 +1,5 @@
-- navigation "Session hierarchy":
-  - text: Seeded turn /
-  - button "1 subagent"
+- navigation "Session hierarchy": Seeded turn
 - text: Minimal mode
+- button "1 subagent"
 - button "More actions"
 - button "Open right sidebar"
diff --git a/apps/web/tests/expected/agent-preset-selection/menu.expected.md b/apps/web/tests/expected/agent-preset-selection/menu.expected.md
index d6dfa09aad..76b76a3463 100644
--- a/apps/web/tests/expected/agent-preset-selection/menu.expected.md
+++ b/apps/web/tests/expected/agent-preset-selection/menu.expected.md
@@ -1,6 +1,6 @@
 - menu:
-  - menuitem "Standard mode Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows."
-  - menuitem "PTC mode Full coding agent without the workflow tool; other tools are exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program."
-  - menuitem "Minimal mode Single-tool coding agent with a persistent shell."
-  - menuitem "Creator mode Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, persistent plugin management, and preset-authoring guidance."
+  - menuitem "Standard mode Work with code, files, and information. Suitable for most tasks, with search, editing, terminal commands, and other tools available as needed."
+  - menuitem "PTC mode Includes all Standard mode capabilities. Better suited to tasks that call tools in batches and then filter, organize, deduplicate, count, or summarize the results."
+  - menuitem "Minimal mode The agent works using only a terminal tool. Useful for testing and comparing its basic performance."
+  - menuitem "Creator mode Customize DSH through conversation. Let the agent write plugins that add features or UI, or combine tools and prompts to create your own mode."
   - menuitem "Refusing mode Resolves, then refuses to start."
diff --git a/apps/web/tests/expected/cordis-history/ui.expected.md b/apps/web/tests/expected/cordis-history/ui.expected.md
index 2ddd03bddb..1b37b0484f 100644
--- a/apps/web/tests/expected/cordis-history/ui.expected.md
+++ b/apps/web/tests/expected/cordis-history/ui.expected.md
@@ -9,14 +9,13 @@
   - button "Jump to turn 1"
   - button "Jump to turn 2"
   - button "Jump to turn 3"
-- button "System prompt"
 - text: "Use only Cordis tools. First call cordis_inspect_self with no arguments. Then call cordis_define with plugin kind \"new\", idPrefix \"snap\", name \"snapshot noop\", purpose \"does nothing, for the snapshot\", code.host exactly \"return { name: \\\"snapshot-noop\\\", apply(ctx) {} }\" and code.client exactly \"return { inject: [\\\"slots\\\"], apply(ctx) { ctx.slots.register({ name: \\\"shell.overlay\\\", id: \\\"snapshot-probe\\\" }, () => React.createElement(\\\"div\\\", { \\\"data-snapshot-probe\\\": \\\"loaded\\\" })) } }\". Read its returned pluginId and packageId, then call cordis_run with those exact IDs and mode \"run\". After the run request returns, reply exactly CORDIS_UI_READY and stop. 9/1 {{clock}}"
 - button "Copy"
 - button "3 tool calls" [expanded]
 - button "Context injection runtime-context"
-- button "Think I will inspect the current Session's dynamic Cordis Plugins before defining the snapshot Package."
+- button "Think"
 - button "Inspect plugins 0 dynamic plugins"
-- button "Think No dynamic Plugins are present, so I will define the requested Host and Client Package."
+- button "Think"
 - button "Register Cordis Plugin snapshot noop does nothing, for the snapshot Ready" [expanded]
 - tablist "Plugin source":
   - tab "Client"
@@ -27,11 +26,11 @@
   - code: "return { name: \"snapshot-noop\", apply(ctx) {} }"
 - text: Result Defined snap-1/pkg-1 (snapshot noop); it is not running yet. Use cordis_run to activate this Package. Run controls live in the Cordis panel above Settings
 - button "Inspect"
-- button "Think The Host returned snap-1/pkg-1, so I will request its first activation."
+- button "Think"
 - text: Run Cordis Plugin snap-1 · pkg-1 Ready
 - button "Inspect"
 - text: snap-1/pkg-1 is awaiting user approval (run-1).
-- button "Think The activation request has been submitted, so I will return the requested readiness marker."
+- button "Think"
 - paragraph: CORDIS_UI_READY
 - button "Copy"
 - button "Good response"
diff --git a/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md b/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md
index 7df4c7ce8a..47440f7c24 100644
--- a/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md
+++ b/apps/web/tests/expected/deepseek-messages-settings/cards.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: DeepSeek
@@ -21,7 +21,7 @@
         - text: 自定义设置 API 地址
         - textbox "API 地址":
           - /placeholder: https://api.deepseek.com/anthropic
-        - text: 请填写与当前连接配置兼容的 API 地址。
+        - text: 请填写兼容 Anthropic Messages 协议的 API 地址。
         - region "模型目录":
           - text: 模型目录 正在使用适配器默认模型
           - textbox "模型 ID 1":
@@ -43,5 +43,4 @@
           - button "添加模型"
       - button "取消"
       - button "保存"
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/default-workspace/failure.expected.md b/apps/web/tests/expected/default-workspace/failure.expected.md
new file mode 100644
index 0000000000..c9624749f0
--- /dev/null
+++ b/apps/web/tests/expected/default-workspace/failure.expected.md
@@ -0,0 +1 @@
+- alert: 无法创建默认工作区，请通过“选择工作区”选择文件夹
diff --git a/apps/web/tests/expected/fork-mid-turn/ui.expected.md b/apps/web/tests/expected/fork-mid-turn/ui.expected.md
index 1350afec53..6c9e8eeaa5 100644
--- a/apps/web/tests/expected/fork-mid-turn/ui.expected.md
+++ b/apps/web/tests/expected/fork-mid-turn/ui.expected.md
@@ -1,12 +1,10 @@
-- button "System prompt"
 - text: "Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
-- button "Think The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."
+- button "Think"
 - text: Failed
 - 'button "Read The history inherited by this branch records this tool call starting but does not include its result. The parent session may have completed it after the fork point. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly."'
 - text: Failed
 - 'button "Tool call The history inherited by this branch has no record of this tool call starting. The parent session may have executed it after the fork point. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly."'
-- button "System prompt"
 - text: FORK_BRANCH_USER Summarize what this branch knows about the reads. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md b/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
index 4abbc3d013..6fbf824a1b 100644
--- a/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
+++ b/apps/web/tests/expected/github-ready-review/conversation-expanded.expected.md
@@ -16,7 +16,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - button "Thought for a while" [expanded]
 - button "Context injection webhook github webhook handled by review-pr-when-ready"
 - button "Context injection runtime-context"
diff --git a/apps/web/tests/expected/github-ready-review/conversation.expected.md b/apps/web/tests/expected/github-ready-review/conversation.expected.md
index 7c18886de2..1b30edc3e0 100644
--- a/apps/web/tests/expected/github-ready-review/conversation.expected.md
+++ b/apps/web/tests/expected/github-ready-review/conversation.expected.md
@@ -16,7 +16,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - button "Thought for a while"
 - paragraph: "Review complete: no actionable findings."
 - button "Copy"
diff --git a/apps/web/tests/expected/input-plugin-extensions.expected.md b/apps/web/tests/expected/input-plugin-extensions.expected.md
new file mode 100644
index 0000000000..512b4d0884
--- /dev/null
+++ b/apps/web/tests/expected/input-plugin-extensions.expected.md
@@ -0,0 +1,5 @@
+- textbox "Describe what you want to build, / commands, @ files or sessions":
+  - paragraph: Draft
+- button "Cancel activity"
+- button "Insert result"
+- button "Send message"
diff --git a/apps/web/tests/expected/models-settings-recovery/stored-error.expected.md b/apps/web/tests/expected/models-settings-recovery/stored-error.expected.md
index 69e631f4cd..84f93fc533 100644
--- a/apps/web/tests/expected/models-settings-recovery/stored-error.expected.md
+++ b/apps/web/tests/expected/models-settings-recovery/stored-error.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: openrouter
@@ -24,5 +24,4 @@
       - button "编辑 acme-gateway": 编辑
       - button "删除 acme-gateway": 删除
       - alert: "llm-pi-ai: provider \"acme-gateway\" model \"custom-model\" needs an api; the installed catalog does not describe it, so set the route's api to the wire protocol its endpoint speaks"
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/models-settings/catalog-inputs.expected.md b/apps/web/tests/expected/models-settings/catalog-inputs.expected.md
index e30e6cc2dd..d1047bfbb2 100644
--- a/apps/web/tests/expected/models-settings/catalog-inputs.expected.md
+++ b/apps/web/tests/expected/models-settings/catalog-inputs.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: minimax-cn
@@ -25,7 +25,7 @@
       - group:
         - text: 自定义设置 API 地址
         - textbox "API 地址":
-          - /placeholder: 提供方默认
+          - /placeholder: 提供商默认
         - region "模型目录":
           - text: 模型目录 已自定义模型目录
           - button "恢复默认模型"
@@ -59,5 +59,4 @@
       - text: Acme 网关 自定义
       - button "编辑 Acme 网关 (acme-gateway)": 编辑
       - button "删除 Acme 网关 (acme-gateway)": 删除
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/models-settings/configured.expected.md b/apps/web/tests/expected/models-settings/configured.expected.md
index f294ff5977..0380871342 100644
--- a/apps/web/tests/expected/models-settings/configured.expected.md
+++ b/apps/web/tests/expected/models-settings/configured.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - status: 已保存 minimax-cn。
   - list:
     - listitem:
@@ -16,5 +16,4 @@
       - img "API 密钥已配置"
       - button "编辑 minimax-cn": 编辑
       - button "删除 minimax-cn": 删除
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/models-settings/declared-edit.expected.md b/apps/web/tests/expected/models-settings/declared-edit.expected.md
index fcaeb76e56..6bc07d9474 100644
--- a/apps/web/tests/expected/models-settings/declared-edit.expected.md
+++ b/apps/web/tests/expected/models-settings/declared-edit.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: minimax-cn
@@ -33,9 +33,9 @@
           - text: https://gateway.acme.example/v1
         - text: API 协议
         - combobox "API 协议":
-          - option "openai-completions" [selected]
-          - option "openai-responses"
-          - option "anthropic-messages"
+          - option "OpenAI Chat Completions" [selected]
+          - option "OpenAI Responses"
+          - option "Anthropic Messages"
         - region "模型目录":
           - text: 模型目录 已自定义模型目录
           - button "恢复默认模型"
@@ -62,5 +62,4 @@
           - button "添加模型"
       - button "取消"
       - button "保存"
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/models-settings/declared.expected.md b/apps/web/tests/expected/models-settings/declared.expected.md
index d752bbb42a..269d5ebd35 100644
--- a/apps/web/tests/expected/models-settings/declared.expected.md
+++ b/apps/web/tests/expected/models-settings/declared.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: minimax-cn
@@ -19,5 +19,4 @@
       - text: Acme Gateway 自定义
       - button "编辑 Acme Gateway (acme-gateway)": 编辑
       - button "删除 Acme Gateway (acme-gateway)": 删除
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/models-settings/empty.expected.md b/apps/web/tests/expected/models-settings/empty.expected.md
index 8ce2f31098..4ddb04a13b 100644
--- a/apps/web/tests/expected/models-settings/empty.expected.md
+++ b/apps/web/tests/expected/models-settings/empty.expected.md
@@ -8,52 +8,57 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list
-  - text: 提供方
-  - combobox "提供方":
-    - option "amazon-bedrock"
-    - option "ant-ling"
-    - option "anthropic"
-    - option "azure-openai-responses"
-    - option "baseten"
-    - option "cerebras"
-    - option "cloudflare-ai-gateway"
-    - option "cloudflare-workers-ai"
-    - option "deepseek"
-    - option "fireworks"
-    - option "github-copilot"
-    - option "google"
-    - option "google-vertex"
-    - option "groq"
-    - option "huggingface"
-    - option "kimi-coding"
-    - option "minimax"
-    - option "minimax-cn" [selected]
-    - option "mistral"
-    - option "moonshotai"
-    - option "moonshotai-cn"
-    - option "nvidia"
-    - option "openai"
-    - option "openai-codex"
-    - option "opencode"
-    - option "opencode-go"
-    - option "openrouter"
-    - option "qwen-token-plan"
-    - option "qwen-token-plan-cn"
-    - option "qwen-token-plan-individual"
-    - option "together"
-    - option "vercel-ai-gateway"
-    - option "xai"
-    - option "xiaomi"
-    - option "xiaomi-token-plan-ams"
-    - option "xiaomi-token-plan-cn"
-    - option "xiaomi-token-plan-sgp"
-    - option "zai"
-    - option "zai-coding-cn"
-  - text: API 密钥
-  - textbox "API 密钥":
-    - /placeholder: 输入 API 密钥，或留空使用环境认证
-  - group: 自定义设置
-  - button "取消"
-  - button "保存"
+  - tablist "添加方式":
+    - tab "第三方模型提供商" [selected]
+    - tab "自定义模型 API"
+  - paragraph: 从内置目录中选择 OpenAI、Anthropic、Kimi 等提供商，填入其 API 密钥即可使用。
+  - tabpanel "第三方模型提供商":
+    - text: 提供商
+    - combobox "提供商":
+      - option "amazon-bedrock"
+      - option "ant-ling"
+      - option "anthropic"
+      - option "azure-openai-responses"
+      - option "baseten"
+      - option "cerebras"
+      - option "cloudflare-ai-gateway"
+      - option "cloudflare-workers-ai"
+      - option "deepseek"
+      - option "fireworks"
+      - option "github-copilot"
+      - option "google"
+      - option "google-vertex"
+      - option "groq"
+      - option "huggingface"
+      - option "kimi-coding"
+      - option "minimax"
+      - option "minimax-cn" [selected]
+      - option "mistral"
+      - option "moonshotai"
+      - option "moonshotai-cn"
+      - option "nvidia"
+      - option "openai"
+      - option "openai-codex"
+      - option "opencode"
+      - option "opencode-go"
+      - option "openrouter"
+      - option "qwen-token-plan"
+      - option "qwen-token-plan-cn"
+      - option "qwen-token-plan-individual"
+      - option "together"
+      - option "vercel-ai-gateway"
+      - option "xai"
+      - option "xiaomi"
+      - option "xiaomi-token-plan-ams"
+      - option "xiaomi-token-plan-cn"
+      - option "xiaomi-token-plan-sgp"
+      - option "zai"
+      - option "zai-coding-cn"
+    - text: API 密钥
+    - textbox "API 密钥":
+      - /placeholder: 输入 API 密钥，或留空使用环境认证
+    - group: 自定义设置
+    - button "取消"
+    - button "保存"
diff --git a/apps/web/tests/expected/models-settings/model-picker.expected.md b/apps/web/tests/expected/models-settings/model-picker.expected.md
index e02c9b2529..01fd8e7166 100644
--- a/apps/web/tests/expected/models-settings/model-picker.expected.md
+++ b/apps/web/tests/expected/models-settings/model-picker.expected.md
@@ -1,7 +1,7 @@
 - dialog "选择要添加的模型":
   - heading "选择要添加的模型" [level=2]
   - button "关闭"
-  - paragraph: 以下是模型提供方的可用模型，勾选要添加的模型。
+  - paragraph: 以下是模型提供商的可用模型，勾选要添加的模型。
   - searchbox "搜索模型"
   - button "取消全选"
   - list:
diff --git a/apps/web/tests/expected/new-session-refused/notice.expected.md b/apps/web/tests/expected/new-session-refused/notice.expected.md
new file mode 100644
index 0000000000..52e7072f0f
--- /dev/null
+++ b/apps/web/tests/expected/new-session-refused/notice.expected.md
@@ -0,0 +1 @@
+- alert: "新建会话失败：agent-preset/invalid: agent-presets: preset \"renamed-plugin\" failed to mount: row \"ghost\" names a plugin that cannot be resolved: @deepseek-ai/dsh-no-such-plugin"
diff --git a/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md b/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md
index be77e20835..803e82b6f0 100644
--- a/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md
+++ b/apps/web/tests/expected/onboarding-deepseek-config/default-models.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: DeepSeek
@@ -21,7 +21,7 @@
         - text: 自定义设置 API 地址
         - textbox "API 地址":
           - /placeholder: https://api.deepseek.com/anthropic
-        - text: 请填写与当前连接配置兼容的 API 地址。
+        - text: 请填写兼容 Anthropic Messages 协议的 API 地址。
         - region "模型目录":
           - text: 模型目录 正在使用适配器默认模型
           - textbox "模型 ID 1":
@@ -56,5 +56,4 @@
           - button "添加模型"
       - button "取消"
       - button "保存"
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md b/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md
index 9e344cc148..84a7261b65 100644
--- a/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md
+++ b/apps/web/tests/expected/onboarding-deepseek-config/models.expected.md
@@ -8,7 +8,7 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: DeepSeek
@@ -21,7 +21,7 @@
         - text: 自定义设置 API 地址
         - textbox "API 地址":
           - /placeholder: https://api.deepseek.com/anthropic
-        - text: 请填写与当前连接配置兼容的 API 地址。
+        - text: 请填写兼容 Anthropic Messages 协议的 API 地址。
         - region "模型目录":
           - text: 模型目录 已自定义模型目录
           - button "恢复默认模型"
@@ -50,5 +50,4 @@
           - button "添加模型"
       - button "取消"
       - button "保存"
-  - button "添加提供方"
-  - button "添加自定义提供方"
+  - button "添加模型提供商"
diff --git a/apps/web/tests/expected/onboarding-usable-provider/dismissed.expected.md b/apps/web/tests/expected/onboarding-usable-provider/dismissed.expected.md
index 0279600e91..f955841948 100644
--- a/apps/web/tests/expected/onboarding-usable-provider/dismissed.expected.md
+++ b/apps/web/tests/expected/onboarding-usable-provider/dismissed.expected.md
@@ -8,56 +8,61 @@
   - button "打开配置文件"
   - button "关闭"
   - heading "模型" [level=2]
-  - paragraph: 填入各提供方的 API 密钥即可使用其模型。
+  - paragraph: 填入各提供商的 API 密钥即可使用其模型。
   - list:
     - listitem:
       - text: DeepSeek
       - img "API 密钥缺失"
       - button "编辑 DeepSeek (deepseek-official)": 编辑
-  - text: 提供方
-  - combobox "提供方":
-    - option "amazon-bedrock"
-    - option "ant-ling"
-    - option "anthropic"
-    - option "azure-openai-responses"
-    - option "baseten"
-    - option "cerebras"
-    - option "cloudflare-ai-gateway"
-    - option "cloudflare-workers-ai"
-    - option "deepseek"
-    - option "fireworks"
-    - option "github-copilot"
-    - option "google"
-    - option "google-vertex"
-    - option "groq"
-    - option "huggingface"
-    - option "kimi-coding"
-    - option "minimax"
-    - option "minimax-cn" [selected]
-    - option "mistral"
-    - option "moonshotai"
-    - option "moonshotai-cn"
-    - option "nvidia"
-    - option "openai"
-    - option "openai-codex"
-    - option "opencode"
-    - option "opencode-go"
-    - option "openrouter"
-    - option "qwen-token-plan"
-    - option "qwen-token-plan-cn"
-    - option "qwen-token-plan-individual"
-    - option "together"
-    - option "vercel-ai-gateway"
-    - option "xai"
-    - option "xiaomi"
-    - option "xiaomi-token-plan-ams"
-    - option "xiaomi-token-plan-cn"
-    - option "xiaomi-token-plan-sgp"
-    - option "zai"
-    - option "zai-coding-cn"
-  - text: API 密钥
-  - textbox "API 密钥":
-    - /placeholder: 输入 API 密钥，或留空使用环境认证
-  - group: 自定义设置
-  - button "取消"
-  - button "保存"
+  - tablist "添加方式":
+    - tab "第三方模型提供商" [selected]
+    - tab "自定义模型 API"
+  - paragraph: 从内置目录中选择 OpenAI、Anthropic、Kimi 等提供商，填入其 API 密钥即可使用。
+  - tabpanel "第三方模型提供商":
+    - text: 提供商
+    - combobox "提供商":
+      - option "amazon-bedrock"
+      - option "ant-ling"
+      - option "anthropic"
+      - option "azure-openai-responses"
+      - option "baseten"
+      - option "cerebras"
+      - option "cloudflare-ai-gateway"
+      - option "cloudflare-workers-ai"
+      - option "deepseek"
+      - option "fireworks"
+      - option "github-copilot"
+      - option "google"
+      - option "google-vertex"
+      - option "groq"
+      - option "huggingface"
+      - option "kimi-coding"
+      - option "minimax"
+      - option "minimax-cn" [selected]
+      - option "mistral"
+      - option "moonshotai"
+      - option "moonshotai-cn"
+      - option "nvidia"
+      - option "openai"
+      - option "openai-codex"
+      - option "opencode"
+      - option "opencode-go"
+      - option "openrouter"
+      - option "qwen-token-plan"
+      - option "qwen-token-plan-cn"
+      - option "qwen-token-plan-individual"
+      - option "together"
+      - option "vercel-ai-gateway"
+      - option "xai"
+      - option "xiaomi"
+      - option "xiaomi-token-plan-ams"
+      - option "xiaomi-token-plan-cn"
+      - option "xiaomi-token-plan-sgp"
+      - option "zai"
+      - option "zai-coding-cn"
+    - text: API 密钥
+    - textbox "API 密钥":
+      - /placeholder: 输入 API 密钥，或留空使用环境认证
+    - group: 自定义设置
+    - button "取消"
+    - button "保存"
diff --git a/apps/web/tests/expected/plugin-manager/icons.expected.md b/apps/web/tests/expected/plugin-manager/icons.expected.md
new file mode 100644
index 0000000000..fb9df5edb1
--- /dev/null
+++ b/apps/web/tests/expected/plugin-manager/icons.expected.md
@@ -0,0 +1,5 @@
+Third-party bundle card: image, 36×36, decoded
+Disabled Agent Teams card: image, 36×36, decoded
+Agent Teams detail: image, 36×36, decoded
+Third-party bundle detail: image, 36×36, decoded
+Independent search row: image, 30×30, decoded
diff --git a/apps/web/tests/expected/reasoning-preview/running.expected.md b/apps/web/tests/expected/reasoning-preview/running.expected.md
new file mode 100644
index 0000000000..a7837c2d66
--- /dev/null
+++ b/apps/web/tests/expected/reasoning-preview/running.expected.md
@@ -0,0 +1,2 @@
+- text: Running
+- 'button "Think Next paragraph: inspect the loaded context and pending tools inspect the loaded context and pending tools inspect the loaded context and pending tools inspect the loaded context and pending tools inspect the loaded context and pending tools inspect the loaded context and pending tools inspect the loaded context and pending tools inspect the loaded context and pending tools"'
diff --git a/apps/web/tests/expected/settings-chrome/dialog-en.expected.md b/apps/web/tests/expected/settings-chrome/dialog-en.expected.md
index 41d6462e11..3f945d9cce 100644
--- a/apps/web/tests/expected/settings-chrome/dialog-en.expected.md
+++ b/apps/web/tests/expected/settings-chrome/dialog-en.expected.md
@@ -18,7 +18,7 @@
   - text: Font size Only affects conversation content 14
   - button "Increase font size"
   - button "Decrease font size"
-  - text: px Conversation display Controls process content in completed turns
+  - text: px Work details Controls how turns and steps expand by default
   - button "Compact"
   - text: Performance & usage Choose how much performance and usage information to show
   - button "Detailed"
@@ -26,3 +26,4 @@
   - switch "Developer tools"
   - text: Send behavior while busy What Enter and the Send button do while the agent is running; Cmd/Ctrl+Enter uses the other behavior
   - button "Queue"
+  - text: "Current version: {{version}}"
diff --git a/apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md b/apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md
new file mode 100644
index 0000000000..3f945d9cce
--- /dev/null
+++ b/apps/web/tests/expected/settings-chrome/dialog-no-browser.expected.md
@@ -0,0 +1,29 @@
+- dialog "Settings":
+  - navigation:
+    - text: Settings
+    - button "General"
+    - button "Models"
+    - button "Built-in plugins"
+    - button "Agent presets"
+  - button "Open configuration file"
+  - button "Close"
+  - text: Permission Choose the default permission mode for new sessions
+  - button "Workspace Write"
+  - text: Language
+  - button "English"
+  - text: Appearance
+  - button "Light"
+  - button "Dark"
+  - button "System" [pressed]
+  - text: Font size Only affects conversation content 14
+  - button "Increase font size"
+  - button "Decrease font size"
+  - text: px Work details Controls how turns and steps expand by default
+  - button "Compact"
+  - text: Performance & usage Choose how much performance and usage information to show
+  - button "Detailed"
+  - text: Developer tools Show tools and information for debugging and troubleshooting
+  - switch "Developer tools"
+  - text: Send behavior while busy What Enter and the Send button do while the agent is running; Cmd/Ctrl+Enter uses the other behavior
+  - button "Queue"
+  - text: "Current version: {{version}}"
diff --git a/apps/web/tests/expected/settings-chrome/dialog.expected.md b/apps/web/tests/expected/settings-chrome/dialog.expected.md
index 9a3776bcb7..c0a1b2ed35 100644
--- a/apps/web/tests/expected/settings-chrome/dialog.expected.md
+++ b/apps/web/tests/expected/settings-chrome/dialog.expected.md
@@ -18,11 +18,12 @@
   - text: 字号大小 仅影响会话内容的字号 14
   - button "增大字号"
   - button "减小字号"
-  - text: px 对话显示 控制已完成轮次的过程内容
-  - button "紧凑"
+  - text: px 工作过程展示 控制轮次和步骤的默认展开方式
+  - button "简洁"
   - text: 性能与用量 选择性能与用量信息展示的详细程度
   - button "详细"
   - text: 开发者工具 显示用于调试和排查问题的工具与信息
   - switch "开发者工具"
   - text: 繁忙时的发送行为 智能体运行时 Enter 键和发送按钮的行为；Cmd/Ctrl+Enter 使用另一行为
   - button "排队发送"
+  - text: 当前版本：{{version}}
diff --git a/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md b/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
index 1876f63c32..9540d8b21f 100644
--- a/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
+++ b/apps/web/tests/expected/skill-user-invoke/ui-expanded.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - button "/user-invoke-demo"
 - button "meeting notes.md"
 - text: and confirm the fixture wiring {{clock}}
diff --git a/apps/web/tests/expected/skill-user-invoke/ui.expected.md b/apps/web/tests/expected/skill-user-invoke/ui.expected.md
index b66832d25e..a1a363ff59 100644
--- a/apps/web/tests/expected/skill-user-invoke/ui.expected.md
+++ b/apps/web/tests/expected/skill-user-invoke/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - button "/user-invoke-demo"
 - button "meeting notes.md"
 - text: and confirm the fixture wiring {{clock}}
diff --git a/apps/web/tests/expected/steer-all/mid-steer.expected.md b/apps/web/tests/expected/steer-all/mid-steer.expected.md
index f3e9564660..13cc723a67 100644
--- a/apps/web/tests/expected/steer-all/mid-steer.expected.md
+++ b/apps/web/tests/expected/steer-all/mid-steer.expected.md
@@ -6,11 +6,10 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use the ask_user_question tool to ask me exactly one question with id "checkpoint", question "Ready to continue?", header "Checkpoint", and options labeled "Yes" and "No". After I answer, reply with one short sentence acknowledging my answer and stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
-- button "Think The user wants me to ask them a checkpoint question first, then continue with whatever they interject. Let me do exactly that."
+- button "Think"
 - status: Deep diving...
 - text: "Interjection: include the word BANANA in your final reply."
 - button "Copy"
diff --git a/apps/web/tests/expected/steer-all/settled-expanded.expected.md b/apps/web/tests/expected/steer-all/settled-expanded.expected.md
index 9538b35054..0cbd3e6544 100644
--- a/apps/web/tests/expected/steer-all/settled-expanded.expected.md
+++ b/apps/web/tests/expected/steer-all/settled-expanded.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use the ask_user_question tool to ask me exactly one question with id "checkpoint", question "Ready to continue?", header "Checkpoint", and options labeled "Yes" and "No". After I answer, reply with one short sentence acknowledging my answer and stop. {{clock}}
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to ask them a checkpoint question first, then continue with whatever they interject. Let me do exactly that."
+- button "Think"
 - button "Ask question 1/1 answered"
 - text: "Interjection: include the word BANANA in your final reply. {{clock}}"
 - button "Copy"
diff --git a/apps/web/tests/expected/steer-all/settled.expected.md b/apps/web/tests/expected/steer-all/settled.expected.md
index 870a712c04..92445bc6c1 100644
--- a/apps/web/tests/expected/steer-all/settled.expected.md
+++ b/apps/web/tests/expected/steer-all/settled.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use the ask_user_question tool to ask me exactly one question with id "checkpoint", question "Ready to continue?", header "Checkpoint", and options labeled "Yes" and "No". After I answer, reply with one short sentence acknowledging my answer and stop. {{clock}}
 - button "Copy"
 - button "1 tool call"
diff --git a/apps/web/tests/expected/workspace-new-session-folding/first-batch.expected.md b/apps/web/tests/expected/workspace-new-session-folding/first-batch.expected.md
new file mode 100644
index 0000000000..6009227833
--- /dev/null
+++ b/apps/web/tests/expected/workspace-new-session-folding/first-batch.expected.md
@@ -0,0 +1,18 @@
+- tree "Sessions":
+  - treeitem "{{workspace}}" [expanded]
+  - treeitem "New Session" [selected]
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} Session actions for {{workspace}} Archive session Pin session":
+    - text: {{workspace}}
+    - button "Session actions for {{workspace}}"
+    - button "Archive session"
+    - button "Pin session"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - treeitem "{{workspace}} 1min"
+  - button "Show 6 more sessions"
diff --git a/apps/web/tests/expected/workspace-new-session-folding/sidebar.expected.md b/apps/web/tests/expected/workspace-new-session-folding/sidebar.expected.md
index 8896ca5c5c..8778baac12 100644
--- a/apps/web/tests/expected/workspace-new-session-folding/sidebar.expected.md
+++ b/apps/web/tests/expected/workspace-new-session-folding/sidebar.expected.md
@@ -9,4 +9,4 @@
   - treeitem "{{workspace}} 1min"
   - treeitem "{{workspace}} 1min"
   - treeitem "{{workspace}} 1min"
-  - button "Show 1 more sessions"
+  - button "Show 11 more sessions"
diff --git a/apps/web/tests/fixtures/assembled-remote.fixture.json b/apps/web/tests/fixtures/assembled-remote.fixture.json
index 7a414d0a07..9d0d916a99 100644
--- a/apps/web/tests/fixtures/assembled-remote.fixture.json
+++ b/apps/web/tests/fixtures/assembled-remote.fixture.json
@@ -265,11 +265,6 @@
         "fx-beta": [],
         "fx-gamma": []
       },
-      "jobs": {
-        "fx-alpha": [],
-        "fx-beta": [],
-        "fx-gamma": []
-      },
       "approvals": [],
       "questions": [],
       "projections": {
diff --git a/apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg b/apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg
new file mode 100644
index 0000000000..ad85688706
--- /dev/null
+++ b/apps/web/tests/fixtures/plugins/fixture-bundle/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36"><circle cx="18" cy="18" r="14" fill="#145AF3" /></svg>
diff --git a/apps/web/tests/fixtures/plugins/fixture-bundle/package.json b/apps/web/tests/fixtures/plugins/fixture-bundle/package.json
index 3224dfa296..71aa6bbd5f 100644
--- a/apps/web/tests/fixtures/plugins/fixture-bundle/package.json
+++ b/apps/web/tests/fixtures/plugins/fixture-bundle/package.json
@@ -1,6 +1,7 @@
 {
   "name": "@fixture/bundle",
   "version": "0.0.1",
+  "icon": "./icon.svg",
   "private": true,
   "description": "Registry description for the fixture bundle.",
   "type": "module",
diff --git a/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json b/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json
index 52a0c0f420..79083aafff 100644
--- a/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json
+++ b/apps/web/tests/fixtures/plugins/fixture-bundle/search.package.json
@@ -1,4 +1,5 @@
 {
   "name": "Search plugin",
+  "icon": "./icon.svg",
   "description": "Search package introduction."
 }
diff --git a/apps/web/tests/fixtures/plugins/fixture-input-extension/client.js b/apps/web/tests/fixtures/plugins/fixture-input-extension/client.js
new file mode 100644
index 0000000000..6722f15db8
--- /dev/null
+++ b/apps/web/tests/fixtures/plugins/fixture-input-extension/client.js
@@ -0,0 +1,46 @@
+/** A published-protocol consumer of composer activities and bundle activation guidance. */
+window.__ModuleLoader__.load({
+  id: '@fixture/input-extension',
+  factory(require) {
+    const React = require('react')
+    const { Button, Modal, IconApiOutlineRegular } = require('@deepseek-ai/dsh-client-ui-primitives')
+    const h = React.createElement
+    return {
+      inject: ['slots', 'locale'],
+      apply(ctx) {
+        const labels = {
+          start: 'Input activity', cancel: 'Cancel activity', insert: 'Insert result', stale: 'Draft changed',
+          setup: 'Input plugin setup', details: 'Open setup', later: 'Later', config: 'Input plugin configuration',
+        }
+        ctx.effect(() => ctx.locale.register('fixtureInput', { en: labels, zh: labels }))
+        ctx.slots.inject('conversation.input.activity', () => ctx.slots.register({
+          name: 'conversation.input.activity', locale: 'fixtureInput',
+        }, ({ inputActions, onActiveChange, locked, t }) => {
+          const [span, setSpan] = React.useState(null)
+          const [stale, setStale] = React.useState(false)
+          React.useEffect(() => () => onActiveChange(false), [onActiveChange])
+          const close = () => { setSpan(null); setStale(false); onActiveChange(false) }
+          return span === null
+            ? h(Button, { disabled: locked, 'aria-label': t('start'), style: { width: 32, height: 32, padding: 0 }, onClick: () => {
+              setSpan(inputActions.captureInsertion()); onActiveChange(true)
+            } }, h(IconApiOutlineRegular, { size: 16 }))
+            : h('div', null,
+              h(Button, { onClick: close }, t('cancel')),
+              h(Button, { onClick: () => {
+                if (inputActions.insertText(' from plugin', span)) close()
+                else setStale(true)
+              } }, t('insert')),
+              stale ? h('span', { role: 'status' }, t('stale')) : null)
+        }))
+        ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
+          name: 'plugins.bundle.config', key: '@fixture/input-extension', locale: 'fixtureInput',
+        }, ({ t }) => h('p', null, t('config'))))
+        ctx.slots.inject('plugins.bundle.activation', () => ctx.slots.register({
+          name: 'plugins.bundle.activation', key: '@fixture/input-extension', locale: 'fixtureInput',
+        }, ({ onDismiss, onOpenDetails, t }) => h(Modal, {
+          open: true, title: t('setup'), closeLabel: t('later'), onClose: onDismiss,
+        }, h(Button, { onClick: onDismiss }, t('later')), h(Button, { onClick: onOpenDetails }, t('details')))))
+      },
+    }
+  },
+})
diff --git a/apps/web/tests/fixtures/plugins/fixture-input-extension/cordis.patch.yml b/apps/web/tests/fixtures/plugins/fixture-input-extension/cordis.patch.yml
new file mode 100644
index 0000000000..b31d3a8fb7
--- /dev/null
+++ b/apps/web/tests/fixtures/plugins/fixture-input-extension/cordis.patch.yml
@@ -0,0 +1,3 @@
+- insert:
+    - id: fixture-input-extension
+      name: '@fixture/input-extension'
diff --git a/apps/web/tests/fixtures/plugins/fixture-input-extension/index.js b/apps/web/tests/fixtures/plugins/fixture-input-extension/index.js
new file mode 100644
index 0000000000..7f53b13ca2
--- /dev/null
+++ b/apps/web/tests/fixtures/plugins/fixture-input-extension/index.js
@@ -0,0 +1,2 @@
+/** Host companion for the optional input extension fixture. */
+export function apply() {}
diff --git a/apps/web/tests/fixtures/plugins/fixture-input-extension/package.json b/apps/web/tests/fixtures/plugins/fixture-input-extension/package.json
new file mode 100644
index 0000000000..5590f85115
--- /dev/null
+++ b/apps/web/tests/fixtures/plugins/fixture-input-extension/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "@fixture/input-extension",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "index.js",
+  "exports": { ".": "./index.js", "./client": "./client.js" },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": { "platform": "web" }
+  }
+}
diff --git a/apps/web/tests/goal-multi-turn-actions.e2e.ts b/apps/web/tests/goal-multi-turn-actions.e2e.ts
index 9b6ebf857f..1361a476d3 100644
--- a/apps/web/tests/goal-multi-turn-actions.e2e.ts
+++ b/apps/web/tests/goal-multi-turn-actions.e2e.ts
@@ -155,9 +155,9 @@ describe('web e2e: Goal keeps one assistant action row per completed turn', () =
     expect(sessionEvents.flatMap(event =>
       event.type === 'request/header' ? [event.data.reason] : [])).toEqual(['initial', 'series'])
     await expect.poll(() => page.locator('[data-turn-process]').count(), { timeout: 15_000 }).toBe(2)
-    expect(await page.getByRole('button', { name: 'System prompt' }).count()).toBe(2)
+    expect(await page.getByRole('button', { name: 'System prompt' }).count()).toBe(0)
     expect(await page.locator(
-      '[data-chat-flow-kind="system-prompt"][hidden="until-found"]',
+      '[data-chat-flow-kind="system-prompt"]',
     ).count()).toBe(0)
     const branchButtons = page.getByRole('button', { name: 'Branch into a new conversation' })
     await expect.poll(() => branchButtons.count(), { timeout: 15_000 }).toBe(2)
diff --git a/apps/web/tests/hmr-live.e2e.ts b/apps/web/tests/hmr-live.e2e.ts
index 716176a176..87adea12cc 100644
--- a/apps/web/tests/hmr-live.e2e.ts
+++ b/apps/web/tests/hmr-live.e2e.ts
@@ -1,4 +1,4 @@
-/** Published dsh web + pnpm dev:web → browser HMR, with no page reload. */
+/** Built dsh web + the `pnpm run dev:web --no-serve` watchers → browser HMR, with no page reload. */
 
 import { existsSync, globSync, statSync } from 'node:fs'
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
@@ -108,12 +108,14 @@ it('hot-reloads a real client-plugin source edit without refreshing the page', a
   const failures: unknown[] = []
   try {
     subprocessFiber = await subprocessCtx.plugin(LocalSubprocessRuntime)
+    // Watchers only: the built `dsh web` below is the server under test, and the
+    // built tree is this lane's precondition rather than something to rebuild.
     watcher = subprocessCtx.subprocess.spawn(spawnSpec(
-      ['pnpm', 'run', 'dev:web'],
+      ['pnpm', 'run', 'dev:web', '--skip-build', '--no-serve'],
       REPO_ROOT,
       { ...clientBuildEnvironment },
     ))
-    await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web')
+    await waitForOutput(watcher, /dev-web: watching/, 'pnpm run dev:web --skip-build --no-serve')
     host = subprocessCtx.subprocess.spawn(spawnSpec(
       [process.execPath, binPath, 'web', '--no-open', '--port', '0'],
       world,
diff --git a/apps/web/tests/image-display.expected.e2e.ts b/apps/web/tests/image-display.expected.e2e.ts
index adbb742d0b..e3a98dc8f5 100644
--- a/apps/web/tests/image-display.expected.e2e.ts
+++ b/apps/web/tests/image-display.expected.e2e.ts
@@ -171,7 +171,10 @@ it('accepts a whole-page drop under the limits-labeled overlay and refuses an ov
   // desc line carries the projected limits — copy that can only render after
   // the imageLimits projection crossed the RemoteMock transport.
   const image = new File([new Uint8Array([137, 80, 78, 71])], 'dropped.png', { type: 'image/png' })
-  const dataTransfer = { types: ['Files'], files: [image], dropEffect: 'none' }
+  const dataTransfer = {
+    types: ['Files'], files: [image], dropEffect: 'none',
+    items: [{ kind: 'file', getAsFile: () => image, webkitGetAsEntry: () => ({ isDirectory: false }) }],
+  }
   fireEvent.dragEnter(document.body, { dataTransfer })
   const overlay = await screen.findByRole('status')
   expect(overlay.textContent).toContain('Drag files or images here to add them')
diff --git a/apps/web/tests/input-plugin-extensions.e2e.ts b/apps/web/tests/input-plugin-extensions.e2e.ts
new file mode 100644
index 0000000000..cd8548c6f3
--- /dev/null
+++ b/apps/web/tests/input-plugin-extensions.e2e.ts
@@ -0,0 +1,82 @@
+/** Optional input contributions mount through the real Loader and preserve editor ownership. */
+import { fileURLToPath } from 'node:url'
+import { chromium, type Browser } from 'playwright'
+import { expect, it, onTestFinished } from 'vitest'
+import {
+  captureStableAria, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage } from './support.ts'
+
+const bundle = fileURLToPath(new URL('./fixtures/plugins/fixture-input-extension', import.meta.url))
+const expected = fileURLToPath(new URL('./expected/input-plugin-extensions.expected.md', import.meta.url))
+
+async function fixture(enabled: boolean) {
+  const resources: { scaffold?: WebScaffold; browser?: Browser } = {}
+  onTestFinished(async () => {
+    try { await resources.browser?.close() } finally { await resources.scaffold?.close() }
+  })
+  const scaffold = await launchWebScaffold({ profile: { packages: [{ dir: bundle, enabled }] } })
+  resources.scaffold = scaffold
+  const browser = await chromium.launch()
+  resources.browser = browser
+  const page = await newEnglishPage(browser), tripwire = watchConsole(page)
+  await page.goto(scaffold.authenticatedUrl)
+  return { scaffold, page, tripwire }
+}
+
+it('expands an input activity and inserts one undoable result without overwriting subsequent edits', async () => {
+  const { scaffold, page, tripwire } = await fixture(true)
+  await connectFreshWorkspace(page, scaffold.workspaceCwd)
+  const input = page.locator('[data-composer-input]')
+  const start = page.getByRole('button', { name: 'Input activity', exact: true })
+  const model = page.getByRole('button', { name: /^Select model, current/ })
+  const send = page.getByRole('button', { name: 'Send message', exact: true })
+  await input.fill('Draft')
+  await input.press('End')
+  for (const width of [1280, 420]) {
+    await page.setViewportSize({ width, height: 900 })
+    await expect.poll(async () => {
+      const activityBox = await start.boundingBox(), modelBox = await model.boundingBox(), sendBox = await send.boundingBox()
+      return activityBox !== null && modelBox !== null && sendBox !== null
+        && activityBox.x >= modelBox.x + modelBox.width && activityBox.x + activityBox.width <= sendBox.x
+    }).toBe(true)
+  }
+  await start.click()
+  expect(await model.isVisible()).toBe(false)
+  expect(await send.isVisible()).toBe(true)
+  await compareOrRefreshGolden(expected,
+    await captureStableAria(page, '[data-composer-card]', scaffold.workspaceCwd), webSnapshotMode())
+  await page.getByRole('button', { name: 'Insert result', exact: true }).click()
+  await expect.poll(() => input.innerText()).toBe('Draft from plugin')
+  await input.press('ControlOrMeta+z')
+  await expect.poll(() => input.innerText()).toBe('Draft')
+  await start.click()
+  await input.fill('Newer draft')
+  await page.getByRole('button', { name: 'Insert result', exact: true }).click()
+  await page.getByRole('status').filter({ hasText: 'Draft changed' }).waitFor()
+  expect(await input.innerText()).toBe('Newer draft')
+  await page.getByRole('button', { name: 'Cancel activity', exact: true }).click()
+  expect(await model.isVisible()).toBe(true)
+  expect(tripwire.pageErrors).toEqual([])
+})
+
+it('offers bundle guidance only after explicit activation and navigates to its configuration', async () => {
+  const { page, tripwire } = await fixture(false)
+  await page.getByRole('button', { name: 'Plugins', exact: true }).click()
+  const toggle = page.getByRole('switch', { name: 'Enable @fixture/input-extension', exact: true })
+  await toggle.waitFor()
+  const dialog = page.getByRole('dialog', { name: 'Input plugin setup', exact: true })
+  expect(await dialog.count()).toBe(0)
+  await toggle.click()
+  await dialog.waitFor()
+  await dialog.getByRole('button', { name: 'Later', exact: true }).last().click()
+  await dialog.waitFor({ state: 'hidden' })
+  expect(await toggle.getAttribute('aria-checked')).toBe('true')
+  await toggle.click()
+  await page.getByRole('switch', { name: 'Enable @fixture/input-extension', exact: true, checked: false }).waitFor()
+  await toggle.click()
+  await dialog.getByRole('button', { name: 'Open setup', exact: true }).click()
+  await page.getByText('Input plugin configuration', { exact: true }).waitFor()
+  expect(await dialog.count()).toBe(0)
+  expect(tripwire.pageErrors).toEqual([])
+})
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 2948072fd0..0576d26412 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -227,14 +227,19 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
         document.body.append(probe)
         const actual = getComputedStyle(element)
         const reference = getComputedStyle(probe)
+        // The sibling access-mode trigger: the chip shares its corner
+        // curvature (the theme's superellipse, not a circular capsule).
+        const accessMode = document.querySelector('button[aria-label^="Access mode"]')
         const result = {
           color: actual.color,
           backgroundColor: actual.backgroundColor,
           height: actual.height,
           borderRadius: actual.borderRadius,
+          cornerShape: actual.getPropertyValue('corner-shape'),
           fontSize: actual.fontSize,
           referenceColor: reference.color,
           referenceBackgroundColor: reference.backgroundColor,
+          siblingCornerShape: accessMode === null ? null : getComputedStyle(accessMode).getPropertyValue('corner-shape'),
         }
         probe.remove()
         return result
@@ -242,7 +247,11 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
       expect(planStyle.color).toBe(planStyle.referenceColor)
       expect(planStyle.backgroundColor).toBe(planStyle.referenceBackgroundColor)
       expect(planStyle.height).toBe('28px')
-      expect(planStyle.borderRadius).toBe('999px')
+      // Half the 28px height, the compact Button geometry, under the theme's
+      // corner curvature; a 999px pill would need the circular opt-out.
+      expect(planStyle.borderRadius).toBe('14px')
+      expect(planStyle.siblingCornerShape).not.toBeNull()
+      expect(planStyle.cornerShape).toBe(planStyle.siblingCornerShape)
       expect(planStyle.fontSize).toBe('13px')
       await planButton.click()
       await expect.poll(() => planButton.count()).toBe(0)
@@ -314,10 +323,12 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
       const originalViewport = page.viewportSize() ?? { width: 1680, height: 1000 }
       if (MODE !== 'record') await page.setViewportSize({ width: 480, height: 1000 })
       const observedReasoning = Promise.withResolvers<undefined>()
+      const reasoningComplete = Promise.withResolvers<undefined>()
       const releaseStream = MODE === 'record' ? undefined : scaffold.ctx.on('llm/stream', async function* (_options, next) {
         let reasoning = false
         for await (const chunk of next()) {
           if (reasoning && chunk.type !== 'reasoning-delta') {
+            reasoningComplete.resolve(undefined)
             await observedReasoning.promise
           }
           if (chunk.type === 'reasoning-delta') reasoning = true
@@ -329,17 +340,10 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
         if (MODE !== 'record') {
           const thinking = page.locator('[data-variant="think"][data-state="running"]')
           await expect.poll(() => thinking.getByRole('button').getAttribute('aria-expanded')).toBe('false')
-          const liveTail = thinking.locator('[data-follow-end]')
-          await expect.poll(async () => {
-            if (await liveTail.count() !== 1) return false
-            return await liveTail.evaluate((element) => {
-              const text = element.firstElementChild
-              if (!(text instanceof HTMLElement)) return false
-              const viewport = element.getBoundingClientRect()
-              const content = text.getBoundingClientRect()
-              return content.width > viewport.width && Math.abs(content.right - viewport.right) <= 1
-            })
-          }, { timeout: 10_000, interval: 10 }).toBe(true)
+          await reasoningComplete.promise
+          expect(await thinking.getAttribute('data-preview')).toBeNull()
+          expect(await thinking.getByRole('button').getAttribute('aria-expanded')).toBe('false')
+          expect(await thinking.locator('[data-streaming]').isVisible()).toBe(false)
         }
         observedReasoning.resolve(undefined)
         return await settled
diff --git a/apps/web/tests/live-job-stream.e2e.ts b/apps/web/tests/live-job-stream.e2e.ts
new file mode 100644
index 0000000000..9aa70ec2bd
--- /dev/null
+++ b/apps/web/tests/live-job-stream.e2e.ts
@@ -0,0 +1,136 @@
+// Session-header job list driven by a real background bash run: the job row
+// arrives over the job roster stream, expanding it opens the output
+// observation stream, and the panel shows the process's real output while it
+// is still running. No model call is involved.
+import { readFile, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { JobId } from '@deepseek-ai/dsh-jobs'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/session.v2.jsonl', import.meta.url))
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/live-job-stream', import.meta.url))
+const STREAMING_EXPECTED = join(SNAPSHOT_DIR, 'streaming.expected.md')
+const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md')
+const MODE = webSnapshotMode()
+const SEED_ID = 'live-job-stream-web-e2e'
+// One fixed line of early output, then a hold on a barrier file the test owns
+// in the job's cwd: the process never exits on its own, so no CI stall can
+// settle it before the scenario kills it. The bounded loop only caps an
+// orphan's lifetime if the runner dies before `afterAll` releases the barrier.
+const RELEASE = '.live-job-stream.release'
+const COMMAND = `printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e ${RELEASE} ] && break; sleep 0.2; done`
+
+/**
+ * Wait for opening a session to publish its live Agent.
+ * @param scaffold - the booted web scaffold.
+ * @param sessionId - the opened session's identity.
+ * @returns the registered Agent instance.
+ */
+async function liveAgent(scaffold: WebScaffold, sessionId: SessionId): Promise<Agent> {
+  const deadline = Date.now() + 30_000
+  for (;;) {
+    const found = scaffold.ctx.agents.get(sessionId)
+    if (found !== undefined) return found
+    if (Date.now() > deadline) throw new Error(`opening session "${sessionId}" published no live Agent`)
+    await new Promise(resolve => setTimeout(resolve, 100))
+  }
+}
+
+describe.skipIf(MODE === 'record')('web e2e: live job stream', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+  let agent: Agent
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, await readFile(FIXTURE, 'utf8'), SEED_ID)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+
+    const groupRow = page.locator('[role="treeitem"]').first()
+    await groupRow.waitFor({ timeout: 15_000 })
+    await groupRow.click()
+    const sessionRow = page.locator('[role="treeitem"]').nth(1)
+    await sessionRow.waitFor({ timeout: 10_000 })
+    await sessionRow.click()
+
+    // Opening the session drives the Host's ordinary Agent resolution; the
+    // job owner must be that exact live instance, never a second one.
+    agent = await liveAgent(scaffold, SessionId(SEED_ID))
+  }, 120_000)
+
+  afterAll(async () => {
+    if (scaffold !== undefined) await writeFile(join(scaffold.workspaceCwd, RELEASE), '')
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('streams a running job\'s real output into the expanded panel, then settles it in place on kill', async () => {
+    let phase = 'streaming'
+    onTestFailed(() => saveFailureShot(page, `web-e2e-live-job-${phase}`))
+    const trigger = page.getByRole('button', { name: '1 background job running' })
+    expect(await trigger.count()).toBe(0)
+
+    const started = await scaffold.ctx.tools.execute({
+      signal: new AbortController().signal,
+      callId: ToolCallId('live-job-stream-e2e'),
+      name: 'bash',
+      arguments: { command: COMMAND, description: 'Emit one live line then hold', run_in_background: true },
+      agent,
+    })
+    const reported = started.content.map(block => block.type === 'text' ? block.text : '').join('')
+    const matched = /\bbash-\d+\b/.exec(reported)
+    if (matched === null) throw new Error(`background bash reported no job id: ${reported}`)
+    const jobId = JobId(matched[0])
+
+    // The job row reaches the header over the job roster stream.
+    await trigger.waitFor({ timeout: 15_000 })
+    await trigger.click()
+
+    // Expanding the row opens the output observation stream; the panel then renders
+    // the command's real stdout while the process is still running.
+    const expand = page.getByRole('button', { name: /Show live output/ })
+    await expand.waitFor({ timeout: 10_000 })
+    await expand.click()
+    await page.getByText('streamed-marker-line').waitFor({ timeout: 15_000 })
+
+    const streaming = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(STREAMING_EXPECTED, streaming, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+
+    phase = 'settled'
+    expect(scaffold.ctx.jobs.kill(jobId, agent.id, 'web e2e cancellation')).toBe('requested')
+
+    // Settlement arrives on the observation stream itself, so the open panel
+    // flips without any further interaction; the roster trigger follows.
+    const idle = page.getByRole('button', { name: '1 background job', exact: true })
+    await idle.waitFor({ timeout: 20_000 })
+    await page.getByText('streamed-marker-line').waitFor({ timeout: 10_000 })
+
+    const settled = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(SETTLED_EXPECTED, settled, MODE)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 90_000)
+
+  it('keeps its snapshot inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['settled.expected.md', 'streaming.expected.md'])
+  })
+})
diff --git a/apps/web/tests/markdown-inline-code-links.e2e.ts b/apps/web/tests/markdown-inline-code-links.e2e.ts
index 8fb8b5942c..fc7392c433 100644
--- a/apps/web/tests/markdown-inline-code-links.e2e.ts
+++ b/apps/web/tests/markdown-inline-code-links.e2e.ts
@@ -92,7 +92,9 @@ describe('web e2e: Markdown inline-code links', () => {
   let tripwire: ReturnType<typeof watchConsole>
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({})
+    scaffold = await launchWebScaffold({
+      extraOverlayPath: fileURLToPath(new URL('./sidebar-browser.overlay.yml', import.meta.url)),
+    })
     await seedSession(scaffold, markdownFixture(LINK_URL), SEED_ID)
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
diff --git a/apps/web/tests/message-actions.e2e.ts b/apps/web/tests/message-actions.e2e.ts
index fd4a0b2e9c..a4f07bb745 100644
--- a/apps/web/tests/message-actions.e2e.ts
+++ b/apps/web/tests/message-actions.e2e.ts
@@ -227,7 +227,7 @@ describe('web e2e: message IconActions and clocks on settled history', () => {
     await expect.poll(
       () => page.getByRole('button', { name: 'System prompt', exact: true }).count(),
       { timeout: 10_000 },
-    ).toBe(2)
+    ).toBe(0)
 
     // Focus-reveal the footers (hover:hover keeps them opacity-hidden until
     // hover/focus-within). Branch renders only under assistant answers — user
@@ -255,7 +255,10 @@ describe('web e2e: message IconActions and clocks on settled history', () => {
     const copy = page.getByRole('button', { name: 'Copy', exact: true }).last()
     const composer = page.locator('[data-composer-seat]')
     const tooltip = page.getByRole('tooltip', { name: 'Copy', exact: true })
+    const originalViewport = page.viewportSize()
+    if (originalViewport === null) throw new Error('tooltip probe requires a fixed viewport')
     try {
+      await page.setViewportSize({ width: originalViewport.width, height: 600 })
       // Grow the sticky seat upward so the bottom tooltip overlaps it without
       // depending on the fixture's resting composer height.
       await composer.evaluate((element) => { element.style.paddingTop = '48px' })
@@ -297,6 +300,7 @@ describe('web e2e: message IconActions and clocks on settled history', () => {
       await page.mouse.move(0, 0)
       if (await copy.count() > 0) await copy.evaluate((element) => { element.blur() })
       if (await tooltip.count() > 0) await tooltip.waitFor({ state: 'hidden', timeout: 5_000 })
+      await page.setViewportSize(originalViewport)
     }
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
diff --git a/apps/web/tests/models-settings-recovery.e2e.ts b/apps/web/tests/models-settings-recovery.e2e.ts
index 1087f8be3d..3e2d664b93 100644
--- a/apps/web/tests/models-settings-recovery.e2e.ts
+++ b/apps/web/tests/models-settings-recovery.e2e.ts
@@ -54,19 +54,21 @@ describe('web e2e: repairs a stored provider after catalog drift', () => {
     }
   })
 
-  it('shows the failed provider beside healthy providers and keeps both add actions usable', async () => {
+  it('shows the failed provider beside healthy providers and keeps the add action usable', async () => {
     onTestFailed(() => saveFailureShot(page, 'models-settings-recovery'))
     const dialog = page.getByRole('dialog', { name: '设置' })
     expect(await dialog.getByRole('button', { name: '编辑 openrouter', exact: true }).count()).toBe(1)
     expect(await dialog.getByRole('button', { name: '编辑 zai', exact: true }).count()).toBe(1)
     expect(await dialog.getByRole('button', { name: '编辑 acme-gateway', exact: true }).count()).toBe(1)
     expect(await dialog.getByText(CUSTOM_FAILURE, { exact: true }).count()).toBe(1)
-    expect(await dialog.getByRole('button', { name: '添加提供方', exact: true }).isEnabled()).toBe(true)
-    expect(await dialog.getByRole('button', { name: '添加自定义提供方', exact: true }).isEnabled()).toBe(true)
+    expect(await dialog.getByRole('button', { name: '添加模型提供商', exact: true }).isEnabled()).toBe(true)
     await compareOrRefreshGolden(EXPECTED, await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd), webSnapshotMode())
 
-    await dialog.getByRole('button', { name: '添加提供方', exact: true }).click()
-    await dialog.getByLabel('提供方', { exact: true }).selectOption('minimax-cn')
+    await dialog.getByRole('button', { name: '添加模型提供商', exact: true }).click()
+    // Both modes stay offered beside a failed route: the card opens on the
+    // third-party mode with the custom-API segment enabled.
+    expect(await dialog.getByRole('tab', { name: '自定义模型 API' }).isEnabled()).toBe(true)
+    await dialog.getByLabel('提供商', { exact: true }).selectOption('minimax-cn')
     await dialog.getByRole('button', { name: '保存', exact: true }).click()
     await dialog.getByText('已保存 minimax-cn。', { exact: true }).waitFor()
     expect(await readFile(join(home, 'settings.yaml'), 'utf8')).toContain('minimax-cn: {}')
diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts
index 888b5d5d54..a46439dcbb 100644
--- a/apps/web/tests/models-settings.e2e.ts
+++ b/apps/web/tests/models-settings.e2e.ts
@@ -1,5 +1,6 @@
 // Web e2e scenario: the Models settings page end to end through the real
-// wire — the add card offers the dormant pi-ai catalog, a blank key saves a
+// wire — the one add card offers the dormant pi-ai catalog on its third-party
+// mode and the create form on its custom-API mode, a blank key saves a
 // reference-free profile for provider-native auth, and typing an API key later
 // stores it write-only under the derived reference (`MINIMAX_CN_API_KEY`)
 // while the settings document records only that reference. Each saved row
@@ -74,16 +75,20 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const dialog = page.getByRole('dialog', { name: '设置' })
     await dialog.waitFor({ timeout: 10_000 })
-    await dialog.getByRole('button', { name: '模型' }).click()
-    await dialog.getByText('填入各提供方的 API 密钥即可使用其模型。').waitFor({ timeout: 10_000 })
+    await dialog.getByRole('button', { name: '模型', exact: true }).click()
+    await dialog.getByText('填入各提供商的 API 密钥即可使用其模型。').waitFor({ timeout: 10_000 })
     // The dormant pi-ai adapter contributes its whole installed catalog; no
     // provider is configured yet, so the page is one add button.
-    const add = dialog.getByRole('button', { name: '添加提供方' })
+    const add = dialog.getByRole('button', { name: '添加模型提供商' })
     await add.waitFor({ timeout: 10_000 })
     // The button enables once the dormant catalog lands in the join.
     await expect.poll(async () => add.isEnabled(), { timeout: 10_000 }).toBe(true)
     await add.click()
-    const pick = dialog.getByLabel('提供方')
+    // The card opens on the third-party mode, whose panel carries the select.
+    const modes = dialog.getByRole('tablist', { name: '添加方式' })
+    await modes.waitFor({ timeout: 10_000 })
+    expect(await modes.getByRole('tab', { name: '第三方模型提供商' }).getAttribute('aria-selected')).toBe('true')
+    const pick = dialog.getByLabel('提供商', { exact: true })
     await pick.waitFor({ timeout: 10_000 })
     await expect.poll(async () => pick.locator('option').count(), { timeout: 10_000 }).toBeGreaterThan(30)
     const options = await pick.locator('option').allTextContents()
@@ -239,22 +244,29 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
   it('declares a route the adapter does not ship', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-models-declare'))
     const dialog = page.getByRole('dialog', { name: '设置' })
-    const declare = dialog.getByRole('button', { name: '添加自定义提供方' })
-    await expect.poll(async () => declare.isEnabled(), { timeout: 10_000 }).toBe(true)
-    await declare.click()
-    await dialog.getByLabel('Provider ID').fill('acme-gateway')
-    await dialog.getByLabel('显示名称').fill('Acme Gateway')
-    await dialog.getByLabel('API 地址').fill('https://gateway.acme.example/v1')
+    const add = dialog.getByRole('button', { name: '添加模型提供商' })
+    await expect.poll(async () => add.isEnabled(), { timeout: 10_000 }).toBe(true)
+    await add.click()
+    // The custom-API mode is the second segment of the one add card; its
+    // purpose line replaces the catalog one.
+    await dialog.getByRole('tab', { name: '自定义模型 API' }).click()
+    await dialog.getByText('连接中转站、自部署服务或其他兼容 OpenAI / Anthropic 协议的接口，需填写 API 地址、协议和模型。').waitFor({ timeout: 10_000 })
+    // The third-party panel stays mounted, hidden, beside this one, so the
+    // form is addressed through its own panel.
+    const custom = dialog.getByRole('tabpanel', { name: '自定义模型 API' })
+    await custom.getByLabel('Provider ID').fill('acme-gateway')
+    await custom.getByLabel('显示名称').fill('Acme Gateway')
+    await custom.getByLabel('API 地址').fill('https://gateway.acme.example/v1')
     // No reasoning effort on a provider card at all: effort is a per-model
     // capability, the models under one provider disagree about it, and a
     // switch in the composer already records provider+model+effort together.
     expect(await dialog.getByLabel('推理强度').count()).toBe(0)
-    await dialog.getByRole('button', { name: '添加模型' }).click()
-    await dialog.getByLabel('模型 ID 1').fill('acme-large')
-    await dialog.getByRole('button', { name: '模型选项 1' }).click()
-    expect(await dialog.getByRole('group', { name: '输入类型 1' }).getByRole('checkbox', { name: '图片' }).isChecked()).toBe(false)
-    await dialog.getByRole('group', { name: '输入类型 1' }).getByRole('checkbox', { name: '图片' }).check()
-    await dialog.getByRole('button', { name: '创建提供方', exact: true }).click()
+    await custom.getByRole('button', { name: '添加模型', exact: true }).click()
+    await custom.getByLabel('模型 ID 1').fill('acme-large')
+    await custom.getByRole('button', { name: '模型选项 1' }).click()
+    expect(await custom.getByRole('group', { name: '输入类型 1' }).getByRole('checkbox', { name: '图片' }).isChecked()).toBe(false)
+    await custom.getByRole('group', { name: '输入类型 1' }).getByRole('checkbox', { name: '图片' }).check()
+    await custom.getByRole('button', { name: '创建提供商', exact: true }).click()
 
     const row = dialog.getByText('Acme Gateway', { exact: true }).first()
     await row.waitFor({ timeout: 10_000 })
diff --git a/apps/web/tests/new-session-refused.e2e.ts b/apps/web/tests/new-session-refused.e2e.ts
new file mode 100644
index 0000000000..80dcb8e990
--- /dev/null
+++ b/apps/web/tests/new-session-refused.e2e.ts
@@ -0,0 +1,70 @@
+/** An explicit New Session the Host refuses reports through the Workspace notice in the shipped Web composition. */
+import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { chromium } from 'playwright'
+import { describe, expect, it, onTestFinished } from 'vitest'
+import { compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode } from './scaffold.ts'
+import { saveFailureShot } from './support.ts'
+
+const NOTICE_EXPECTED = fileURLToPath(new URL('./expected/new-session-refused/notice.expected.md', import.meta.url))
+const MODE = webSnapshotMode()
+/** The default preset of this lane: its one row names a package the Host cannot resolve, as a preset copied before a plugin rename does. */
+const PRESET_ID = 'renamed-plugin'
+
+/**
+ * Seed a user preset root holding one preset the roster reads as broken.
+ *
+ * Discovery reports the unresolvable row before any mount, so the refusal
+ * carries no temp path and the notice text is stable across runs.
+ * @param root - the lane-owned preset root.
+ */
+async function seedBrokenPreset(root: string): Promise<void> {
+  const directory = join(root, PRESET_ID)
+  await mkdir(directory, { recursive: true })
+  await writeFile(join(directory, 'agent.cordis.yml'), '- id: ghost\n  name: \'@deepseek-ai/dsh-no-such-plugin\'\n')
+  await writeFile(join(directory, 'preset.yml'), 'name: Renamed plugin\ndescription: Names a plugin that no longer resolves.\n')
+}
+
+describe.skipIf(MODE === 'record')('web e2e: refused New Session', () => {
+  it('shows the Host refusal as a notice and leaves the Workspace without a Session', async () => {
+    const presetRoot = await realpath(await mkdtemp(join(tmpdir(), 'dsh-web-e2e-broken-preset-')))
+    onTestFinished(() => rm(presetRoot, { recursive: true, force: true }))
+    await seedBrokenPreset(presetRoot)
+    const scaffold = await launchWebScaffold({
+      firstUse: true,
+      agentPresets: { roots: [{ path: presetRoot, trust: 'user' }], default: PRESET_ID },
+    })
+    onTestFinished(() => scaffold.close())
+    const browser = await chromium.launch()
+    try {
+      const page = await browser.newPage({ locale: 'zh-CN', timezoneId: 'Asia/Shanghai' })
+      const tripwire = watchConsole(page)
+      try {
+        await page.goto(scaffold.authenticatedUrl)
+        // Startup prepares the default Workspace, and its own blank-Session
+        // attempt is refused without a notice: the hero stays on the picker.
+        await page.getByRole('button', { name: '选择工作区', exact: true }).waitFor()
+        await expect.poll(() => scaffold.ctx.workspaceRegistry.list().length).toBe(1)
+        expect(scaffold.ctx.sessions.list()).toEqual([])
+        expect(await page.getByRole('alert').count()).toBe(0)
+
+        await page.getByRole('button', { name: '新建会话', exact: true }).first().click()
+        const notice = page.getByRole('alert').filter({ hasText: '新建会话失败' })
+        await notice.waitFor()
+        await compareOrRefreshGolden(NOTICE_EXPECTED, await notice.ariaSnapshot(), MODE)
+        expect(scaffold.ctx.sessions.list()).toEqual([])
+        expect(scaffold.ctx.workspaceRegistry.list()).toHaveLength(1)
+        expect(await page.locator('[data-composer-input][contenteditable="true"]').count()).toBe(0)
+        expect(tripwire.pageErrors).toEqual([])
+        expect(tripwire.warnings).toEqual([])
+      } catch (error) {
+        await saveFailureShot(page, 'web-e2e-new-session-refused')
+        throw error
+      }
+    } finally {
+      await browser.close()
+    }
+  })
+})
diff --git a/apps/web/tests/no-sidebar-browser.overlay.yml b/apps/web/tests/no-sidebar-browser.overlay.yml
new file mode 100644
index 0000000000..2af93975a4
--- /dev/null
+++ b/apps/web/tests/no-sidebar-browser.overlay.yml
@@ -0,0 +1,3 @@
+# Exercise the settings surface without a built-in browser provider.
+- id: ui-sidebar-browser
+  disabled: true
diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index 96ddb5e24c..4b4f6e0929 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -99,7 +99,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const settings = page.getByRole('dialog', { name: '设置' })
     await settings.waitFor({ timeout: 10_000 })
-    await settings.getByRole('button', { name: '模型' }).click()
+    await settings.getByRole('button', { name: '模型', exact: true }).click()
     const deepSeekRow = settings.getByText('DeepSeek', { exact: true }).first()
     await deepSeekRow.waitFor({ timeout: 10_000 })
     await deepSeekRow.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click()
@@ -199,7 +199,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const settings = page.getByRole('dialog', { name: '设置' })
     await settings.waitFor({ timeout: 10_000 })
-    await settings.getByRole('button', { name: '模型' }).click()
+    await settings.getByRole('button', { name: '模型', exact: true }).click()
     const deepSeek = settings.getByText('DeepSeek', { exact: true }).first()
     await deepSeek.waitFor({ timeout: 10_000 })
     await deepSeek.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click()
@@ -233,7 +233,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     for (let index = 0; index < 2; index++) {
       await settings.getByRole('button', { name: /删除模型/ }).first().click()
     }
-    await settings.getByRole('button', { name: '添加模型' }).click()
+    await settings.getByRole('button', { name: '添加模型', exact: true }).click()
     const customModelId = settings.getByLabel('模型 ID 1')
     await customModelId.fill('private-preview')
     await settings.getByLabel('显示名称 1').fill('Private Preview')
diff --git a/apps/web/tests/onboarding-usable-provider.e2e.ts b/apps/web/tests/onboarding-usable-provider.e2e.ts
index d16ed51822..42a2593487 100644
--- a/apps/web/tests/onboarding-usable-provider.e2e.ts
+++ b/apps/web/tests/onboarding-usable-provider.e2e.ts
@@ -54,14 +54,14 @@ describe.skipIf(MODE === 'record')('web e2e: another usable provider ends first-
     await settings.waitFor({ timeout: 10_000 })
     // Dismissing the onboarding step leaves Settings closed, so enter the
     // Models section explicitly before exercising its normal cards.
-    await settings.getByRole('button', { name: '模型' }).click()
+    await settings.getByRole('button', { name: '模型', exact: true }).click()
     const setupKey = settings.getByRole('textbox', { name: 'API 密钥', exact: true })
     await setupKey.waitFor({ timeout: 10_000 })
 
-    const add = settings.getByRole('button', { name: '添加提供方' })
+    const add = settings.getByRole('button', { name: '添加模型提供商' })
     await expect.poll(async () => add.isEnabled(), { timeout: 10_000 }).toBe(true)
     await add.click()
-    const pick = settings.getByLabel('提供方')
+    const pick = settings.getByLabel('提供商', { exact: true })
     await pick.waitFor({ timeout: 10_000 })
     await pick.selectOption('minimax-cn')
     await expect.poll(
@@ -72,7 +72,7 @@ describe.skipIf(MODE === 'record')('web e2e: another usable provider ends first-
     // Cancelling the setup card must not close the independent add-provider
     // draft beside it.
     await settings.getByRole('button', { name: '取消', exact: true }).first().click()
-    expect(await settings.getByLabel('提供方').count()).toBe(1)
+    expect(await settings.getByLabel('提供商', { exact: true }).count()).toBe(1)
     await expect.poll(
       async () => settings.getByRole('textbox', { name: 'API 密钥', exact: true }).count(),
       { timeout: 10_000 },
@@ -115,7 +115,7 @@ describe.skipIf(MODE === 'record')('web e2e: another usable provider ends first-
     // setup card over a user who already has somewhere to send a request.
     await page.getByRole('button', { name: '设置', exact: true }).click()
     await settings.waitFor({ timeout: 10_000 })
-    await settings.getByRole('button', { name: '模型' }).click()
+    await settings.getByRole('button', { name: '模型', exact: true }).click()
     await settings.getByRole('button', { name: '编辑 DeepSeek (deepseek-official)' }).waitFor({ timeout: 10_000 })
     expect(await settings.getByRole('textbox', { name: 'API 密钥', exact: true }).count()).toBe(0)
 
diff --git a/apps/web/tests/open-in-app-ssh.e2e.ts b/apps/web/tests/open-in-app-ssh.e2e.ts
index 7323495984..ff57285d88 100644
--- a/apps/web/tests/open-in-app-ssh.e2e.ts
+++ b/apps/web/tests/open-in-app-ssh.e2e.ts
@@ -60,8 +60,7 @@ describe.skipIf(MODE === 'record')('web e2e: Open In under SSH', () => {
     ])
     expect(response.status()).toBe(200)
     expect(await response.json()).toEqual({ apps: [] })
-    expect(await page.getByRole('button', { name: /^Open workspace in / }).count()).toBe(0)
-    expect(await page.getByRole('button', { name: 'Choose an app to open in', exact: true }).count()).toBe(0)
+    expect(await page.locator('[data-open-target="directory"]').count()).toBe(0)
     expect(await page.evaluate(() => localStorage.getItem('dsh.open-in-app.choice'))).toBe('"vscode"')
     const snapshot = (await captureStableAria(page, 'role=banner', scaffold.workspaceCwd))
       .split(SEED_ID).join('{{seededId}}')
diff --git a/apps/web/tests/plan-review.e2e.ts b/apps/web/tests/plan-review.e2e.ts
index 5362264b42..788b6aa871 100644
--- a/apps/web/tests/plan-review.e2e.ts
+++ b/apps/web/tests/plan-review.e2e.ts
@@ -10,7 +10,7 @@
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
-import type { Browser, Page } from 'playwright'
+import type { Browser, ConsoleMessage, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
@@ -211,6 +211,51 @@ describe('web e2e: plan review takeover round trip', () => {
     }
   }, 60_000)
 
+  it.skipIf(MODE === 'record')('opens a review that arrives while a global panel is active', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-plan-review-panel-return'))
+    const agent = scaffold.ctx.agents.get(reviewedSession)
+    if (agent === undefined) throw new Error('The reviewed Session has no active agent')
+    // The Plugins panel replaces the Conversation and its right Sidebar. The
+    // review arrives while neither is mounted; returning mounts both in one
+    // commit, and the review's automatic open runs before the Sidebar's own
+    // effects. A crash there retires the opener for the rest of the page.
+    await page.getByRole('button', { name: 'Plugins', exact: true }).click()
+    await expect.poll(() => page.locator('[data-composer-input]').count()).toBe(0)
+    const crashes: string[] = []
+    const onConsole = (message: ConsoleMessage): void => {
+      if (message.type() === 'error' && /slot entry crashed/i.test(message.text())) crashes.push(message.text())
+    }
+    page.on('console', onConsole)
+    const controller = new AbortController()
+    const asked = scaffold.ctx.userQuestions.ask({
+      agent, signal: controller.signal,
+      questions: [{ id: 'off-screen', question: 'Approve this plan?',
+        detail: '# Off-screen review\n\nSubmitted while the Plugins panel was open.',
+        options: [{ label: 'Approve' }, { label: 'Keep planning' }], intent: { kind: 'plan-review', approve: 'Approve' },
+      }],
+    })
+    const outcome = asked.then(value => value, (error: unknown) => ({ error }))
+    try {
+      const row = page.locator('[role="treeitem"]').filter({ has: page.locator('[data-state="warning"]') }).first()
+      await row.waitFor({ timeout: 10_000 })
+      await row.click()
+      const card = page.locator('[data-plan-review-key]')
+      await card.waitFor({ timeout: 10_000 })
+      const preview = page.locator('[data-plan-preview^="dsh-resource://plan-review/"]')
+      await preview.waitFor({ state: 'visible', timeout: 10_000 })
+      expect(await preview.getByText('Submitted while the Plugins panel was open.').isVisible()).toBe(true)
+      expect(await card.getByRole('button', { name: 'Open plan in sidebar' }).count()).toBe(1)
+      expect(await page.locator('[data-slot-error]').count()).toBe(0)
+      expect(crashes).toEqual([])
+      expect(tripwire.pageErrors).toEqual([])
+      expect(tripwire.warnings).toEqual([])
+    } finally {
+      page.off('console', onConsole)
+      controller.abort()
+      await outcome
+    }
+  }, 60_000)
+
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'session.v3.jsonl', 'review.expected.md', 'sidebar.expected.md', 'preview.expected.md',
diff --git a/apps/web/tests/plugin-manager.e2e.ts b/apps/web/tests/plugin-manager.e2e.ts
index 373b0ba459..8ce5950d4c 100644
--- a/apps/web/tests/plugin-manager.e2e.ts
+++ b/apps/web/tests/plugin-manager.e2e.ts
@@ -140,6 +140,50 @@ describe('web e2e: plugin manager', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('decodes manifest icons for disabled bundles and independent plugin rows', async () => {
+    const panel = await openPluginsPanel()
+    const fixtureIcon = `data:image/svg+xml;base64,${(await readFile(join(FIXTURE_PLUGINS, 'fixture-bundle/icon.svg'))).toString('base64')}`
+    const teamIcon = `data:image/svg+xml;base64,${(await readFile(fileURLToPath(new URL('../../../packages/experimental/agent-team-profile/icon.svg', import.meta.url)))).toString('base64')}`
+    const images: string[] = []
+    const checkImage = async (selector: string, source: string, label: string) => {
+      const image = panel.locator(`${selector} img`).first()
+      await image.waitFor()
+      expect(await image.getAttribute('src')).toBe(source)
+      await image.evaluate(async (node: HTMLImageElement) => { await node.decode() })
+      const size = await image.evaluate((node: HTMLImageElement) => ({
+        width: node.width, height: node.height, naturalWidth: node.naturalWidth,
+      }))
+      expect(size.naturalWidth).toBeGreaterThan(0)
+      images.push(`${label}: image, ${size.width}×${size.height}, decoded`)
+    }
+    await checkImage('[data-plugin-package="@fixture/bundle"]', fixtureIcon, 'Third-party bundle card')
+    const team = panel.locator('[data-plugin-package="@deepseek-ai/dsh-experimental-agent-team-profile"]')
+    expect(await team.getByRole('switch').getAttribute('aria-checked')).toBe('false')
+    await checkImage('[data-plugin-package="@deepseek-ai/dsh-experimental-agent-team-profile"]', teamIcon, 'Disabled Agent Teams card')
+    try {
+      for (const colorScheme of ['light', 'dark'] as const) {
+        await page.emulateMedia({ colorScheme })
+        expect(await team.locator('img').evaluate((node: HTMLImageElement) => node.naturalWidth)).toBe(36)
+        if (MODE === 'refresh') {
+          const path = fileURLToPath(new URL(`../../../.artifacts/plugin-icons-${process.pid}-${colorScheme}.png`, import.meta.url))
+          await page.screenshot({ path })
+          console.log(`Plugin icon screenshot: ${path}`)
+        }
+      }
+    } finally {
+      await page.emulateMedia({ colorScheme: null })
+    }
+    await panel.getByRole('button', { name: '查看 智能体团队', exact: true }).click()
+    await checkImage('[data-plugin-detail]', teamIcon, 'Agent Teams detail')
+    await panel.getByRole('button', { name: '返回插件列表' }).click()
+    await panel.getByRole('button', { name: '查看 @fixture/bundle', exact: true }).click()
+    await checkImage('[data-plugin-detail]', fixtureIcon, 'Third-party bundle detail')
+    await checkImage('[data-plugin-row="fixture-search"]', fixtureIcon, 'Independent search row')
+    await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'icons.expected.md'), images.join('\n'), MODE)
+    await panel.getByRole('button', { name: '返回插件列表' }).click()
+    expect(tripwire.pageErrors).toEqual([])
+  })
+
   it('localizes independent exports and falls back per field without activating the plugins', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-plugin-manager-exports'))
     const panel = await openPluginsPanel()
@@ -331,7 +375,7 @@ describe('web e2e: plugin manager', () => {
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
-      'manager.expected.md', 'live-enabled.expected.md', 'missing-bundle.expected.md', 'exports.expected.md', 'exports-en.expected.md',
+      'manager.expected.md', 'live-enabled.expected.md', 'missing-bundle.expected.md', 'exports.expected.md', 'exports-en.expected.md', 'icons.expected.md',
     ])
   })
 })
diff --git a/apps/web/tests/present-svg.e2e.ts b/apps/web/tests/present-svg.e2e.ts
index 7c856df6f9..461b71e0e3 100644
--- a/apps/web/tests/present-svg.e2e.ts
+++ b/apps/web/tests/present-svg.e2e.ts
@@ -128,7 +128,7 @@ describe('web e2e: requested SVG is explicitly delivered', () => {
 
   it.skipIf(MODE === 'record')('replays the delivered file and Chinese conversation', async () => {
     await assertFinalWorkspaceSnapshot(DIR, cwd)
-    await expect.poll(() => page.getByRole('button', { name: `${FILE} 的更多文件操作`, exact: true }).isDisabled()).toBe(true)
+    expect(await page.locator('[data-presented-file] [data-open-target]').count()).toBe(0)
     // Delivery owns the transcript; navigation and composer chrome have separate scenarios.
     const aria = await captureExpandedTurnProcessAria(page, '[data-chat-flow]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(join(DIR, 'ui.expected.md'), aria, MODE)
diff --git a/apps/web/tests/present.e2e.ts b/apps/web/tests/present.e2e.ts
index 1c4c5fe44f..36d237857a 100644
--- a/apps/web/tests/present.e2e.ts
+++ b/apps/web/tests/present.e2e.ts
@@ -6,6 +6,7 @@ import { chromium, type Browser, type Page } from 'playwright'
 import { unzipSync, strFromU8 } from 'fflate'
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 import { tmpdir, release } from 'node:os'
+import { createLaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-tool-present/types'
 import {
@@ -53,10 +54,18 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
     vi.stubEnv('PATH', `${nativeRoot}${delimiter}${process.env.PATH ?? ''}`)
     await mkdir(DIR, { recursive: true })
     scaffold = await launchWebScaffold({
+      openInAppEnvironment: createLaunchEnvironmentSnapshot([{ source: 'process', values: { SSH_CONNECTION: '10.0.0.2 55000 10.0.0.9 22' } }]),
       extraOverlayPath: fileURLToPath(new URL('./present.overlay.yml', import.meta.url)),
       agentPresets: { roots: [], default: 'ptc' }, compareReplaySession: true,
       ...(MODE === 'record' ? {} : { replayFixture: FIXTURE }),
     })
+    // File associations belong to the desktop rather than the recorded Session.
+    const controller = scaffold.ctx.get('sessionController')
+    if (controller === undefined) throw new Error('present requires Session Controller')
+    const nativeQuery: unknown = Reflect.get(controller, 'fileApplications')
+    if (typeof nativeQuery !== 'function') throw new Error('present requires native association discovery')
+    Reflect.set(controller, 'fileApplications', async () => [{ id: 'test-editor', name: 'Test Editor', default: true, icon: null }])
+    scaffold.ctx.effect(() => () => { Reflect.set(controller, 'fileApplications', nativeQuery) }, 'present: native association fixture')
     disposeApproval = scaffold.ctx.on('approval/request', () => Promise.resolve('allowed-once'), { prepend: true })
     scaffold.ctx.on('session/event', (_session, event) => { events.push(event) })
     browser = await chromium.launch()
@@ -121,8 +130,20 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
       }
       const row = page.locator('[data-presented-files-row]')
       await row.waitFor()
-      expect(await row.getByRole('button', { name: /More file actions/ }).count()).toBe(2)
+      await expect.poll(() => row.getByRole('button', { name: 'More ways to open' }).count()).toBe(2)
       expect(await row.getByText('report.txt', { exact: true }).innerText()).toBe('report.txt')
+      const card = row.locator('[data-presented-file]').filter({ hasText: 'report.txt' })
+      await card.getByRole('button', { name: 'Open in Test Editor', exact: true }).hover()
+      await page.getByRole('tooltip', { name: 'Open in Test Editor', exact: true }).waitFor()
+      expect(await page.getByRole('tooltip').evaluate((tooltip) => {
+        const rect = tooltip.getBoundingClientRect()
+        const previous = tooltip.style.pointerEvents
+        tooltip.style.pointerEvents = 'auto'
+        const visible = document.elementFromPoint(rect.left + rect.width / 2, rect.bottom - 1) === tooltip
+        tooltip.style.pointerEvents = previous
+        return tooltip.parentElement === document.body && visible
+      })).toBe(true)
+      await page.mouse.move(0, 0)
       const beforePreview = (await opened()).length
       const column = page.locator('[data-rightbar-col]')
       for (const [name, content] of [['report.txt', 'EDITED_REPORT'], ['说明.txt', 'EDITED_NOTE']] as const) {
@@ -139,19 +160,16 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
       expect(downloads).toEqual([])
       await page.getByRole('button', { name: 'Collapse right sidebar', exact: true }).click()
       const beforeReveal = (await opened()).length
-      await row.getByRole('button', { name: 'More file actions for report.txt', exact: true }).click()
+      await row.locator('[data-presented-file]').filter({ hasText: 'report.txt' }).getByRole('button', { name: 'More ways to open', exact: true }).click()
       const revealResponse = page.waitForResponse(response => response.url().includes('action=reveal') && response.request().method() === 'POST')
-      await page.getByRole('menuitem', { name: process.platform === 'darwin' ? /Show in Finder/ : /Open containing folder/ }).click()
+      await page.getByRole('menuitem', { name: 'Show file location', exact: true }).click()
       expect((await revealResponse).status()).toBe(204)
-      expect(await row.getByRole('button', { name: 'Open report.txt in sidebar', exact: true })
-        .evaluate(button => button === document.activeElement)).toBe(true)
       await expect.poll(opened).toHaveLength(beforeReveal + 1)
       expect((await opened()).at(-1)).toEqual({ action: 'reveal', content: null, path: await realpath(process.platform === 'darwin' ? join(cwd, 'report.txt') : cwd) })
       for (const [name, bytes] of [['report.txt', 'EDITED_REPORT\n'], ['说明.txt', 'EDITED_NOTE\n']] as const) {
         const count = (await opened()).length
         const response = page.waitForResponse(response => response.url().includes('/api/present.open?') && response.request().method() === 'POST')
-        await row.getByRole('button', { name: `More file actions for ${name}`, exact: true }).click()
-        await page.getByRole('menuitem', { name: 'Open in default app', exact: true }).click()
+        await row.locator('[data-presented-file]').filter({ hasText: name }).getByRole('button', { name: 'Open in Test Editor', exact: true }).click()
         expect((await response).status()).toBe(204)
         await page.waitForFunction(() => document.querySelector('[data-presented-files-row] button:disabled') === null)
         expect(await opened()).toHaveLength(count + 1)
@@ -174,6 +192,7 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
     ])
     expect(exported).not.toContain('EDITED_REPORT')
     if (MODE !== 'record') {
+      await expect.poll(() => page.locator('[data-presented-file] [role="status"]').count(), { timeout: 10_000 }).toBe(0)
       const aria = await captureExpandedTurnProcessAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
       await compareOrRefreshGolden(join(DIR, 'ui.expected.md'), aria, MODE)
       await page.locator('[data-turn-process]').click()
@@ -215,9 +234,9 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
               .find(element => element.textContent === 'report.txt'),
           'report title',
         )
-        const description = requiredElement(report.querySelector<HTMLElement>('span[role="status"]'), 'report status')
+        const description = requiredElement(report.querySelector<HTMLElement>('[data-presented-description]'), 'report description')
         const open = requiredElement(
-          report.querySelector<HTMLButtonElement>('button[aria-label="Open report.txt in sidebar"]'),
+          report.querySelector<HTMLButtonElement>('[data-open-target] button'),
           'report open action',
         )
         const icon = requiredElement(report.querySelector<SVGElement>('svg'), 'report icon')
@@ -250,7 +269,7 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
       expect(geometry.iconWidth).toBe('20')
       expect(geometry.titleFontSize).toBe('13px')
       expect(geometry.descriptionFontSize).toBe('10px')
-      expect(geometry.openFontSize).toBe('12px')
+      expect(geometry.openFontSize).toBe('11px')
       await page.setViewportSize({ width: 480, height: 900 })
       const row = page.locator('[data-presented-files-row]')
       await row.scrollIntoViewIfNeeded()
@@ -263,9 +282,9 @@ fs.appendFileSync(${JSON.stringify(openLog)}, JSON.stringify({ path, action, con
     }
     const beforeDelete = (await opened()).length
     await unlink(join(cwd, 'report.txt'))
-    const missing = page.waitForResponse(response => response.url().includes('/api/present.open?'))
-    await page.locator('[data-presented-files-row]').getByRole('button', { name: 'More file actions for report.txt', exact: true }).click()
-    await page.getByRole('menuitem', { name: 'Open in default app', exact: true }).click()
+    const missing = page.waitForResponse(response => response.url().includes('/api/present.open?') && response.request().method() === 'POST')
+    await page.locator('[data-presented-file]').filter({ hasText: 'report.txt' })
+      .getByRole('button', { name: 'Open in Test Editor', exact: true }).click()
     expect((await missing).status()).toBe(404)
     await page.getByText('Could not open. Click to retry.', { exact: true }).waitFor()
     expect(await opened()).toHaveLength(beforeDelete)
diff --git a/apps/web/tests/preset-migration.snapshot.ts b/apps/web/tests/preset-migration.snapshot.ts
index d8fccb3271..37fdd06073 100644
--- a/apps/web/tests/preset-migration.snapshot.ts
+++ b/apps/web/tests/preset-migration.snapshot.ts
@@ -13,6 +13,7 @@ import type {} from '@deepseek-ai/dsh-api-session-controller'
 import { normalizeSessionSnapshots } from '@deepseek-ai/dsh-session-snapshot'
 import { launchWebScaffold, webSnapshotMode } from './scaffold.ts'
 
+const childFixturePath = fileURLToPath(new URL('../../../snapshots/web/preset-migration/session.1.v2.jsonl', import.meta.url))
 const fixturePath = fileURLToPath(new URL('../../../snapshots/web/preset-migration/session.v2.jsonl', import.meta.url))
 
 describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration through the Web Host', () => {
@@ -32,6 +33,33 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
       await mkdir(dirname(predecessor), { recursive: true })
       await writeFile(predecessor, source)
 
+      const childId = SessionId('preset-migration-child')
+      const brokenId = SessionId('preset-migration-broken-child')
+      const childFixture = (await readFile(childFixturePath, 'utf8')).trimEnd().split('\n')
+        .map((line): Record<string, unknown> => JSON.parse(line) as Record<string, unknown>)
+      const childRows: Record<string, unknown>[] = childFixture.slice(1).map((row, seq) => ({ ...row, seq, time: seq + 3 }))
+      const childHeader = { ...childFixture[0], id: childId, parentSession: id, cwd: scaffold.workspaceCwd }
+      const childSource = Buffer.concat([childHeader, ...childRows].map(row => zstdCompressSync(Buffer.from(JSON.stringify(row) + '\n'))))
+      const childPath = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, childId, 2, 'zstd')
+      const brokenPath = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, brokenId, 2, 'zstd')
+      await mkdir(dirname(childPath), { recursive: true })
+      await mkdir(dirname(brokenPath), { recursive: true })
+      await writeFile(childPath, childSource)
+      await writeFile(brokenPath, Buffer.concat([
+        zstdCompressSync(Buffer.from(JSON.stringify({ ...childHeader, id: brokenId }) + '\n')),
+        zstdCompressSync(Buffer.from('{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
+          data: { turn: 1, reason: { kind: 'completed' } } }) + '\n')),
+      ]))
+      const brokenSource = await readFile(brokenPath)
+      const corruptHeaderId = SessionId('preset-migration-corrupt-header')
+      const corruptHeaderPath = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, corruptHeaderId, 2, 'zstd')
+      const corruptHeaderSource = Buffer.from('invalid Zstandard header frame')
+      await mkdir(dirname(corruptHeaderPath), { recursive: true })
+      await writeFile(corruptHeaderPath, corruptHeaderSource)
+      const listed = await scaffold.ctx.sessionController.list({}, new AbortController().signal)
+      expect(listed.items.map(item => item.sessionId)).toEqual(expect.arrayContaining([id, childId, brokenId]))
+      expect(listed.items.map(item => item.sessionId)).not.toContain(corruptHeaderId)
+
       const reader = await scaffold.ctx.sessionPersistence.open(id, 'read')
       try {
         expect(reader.header.agentPreset).toBe('ptc')
@@ -48,7 +76,35 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
       expect(resolved.agent.session.snapshotEvents()
         .filter(event => event.type === 'agent-preset/selected')
         .map(event => event.data.agentPreset)).toEqual(withSelections ? ['ptc', 'standard', 'ptc'] : [])
+      expect(await scaffold.ctx.subagents.listChildren(id)).toEqual([
+        { id: brokenId, createdAt: childFixture[0]?.['createdAt'], mode: 'unknown' },
+        { id: childId, createdAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child' },
+      ])
 
+      const childSuccessor = generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, childId, SESSION_FORMAT_VERSION, 'zstd')
+      await expect(readFile(childSuccessor)).rejects.toMatchObject({ code: 'ENOENT' })
+      const signal = new AbortController().signal
+      const address = { kind: 'subagent', parentSessionId: id, childSessionId: childId, mode: 'one-shot' } as const
+      const childPage = await scaffold.ctx.sessionController.page({ address, throughSeq: childRows.length - 1 }, signal)
+      expect(childPage.records.map(record => record.event.type)).toEqual(childRows.map(row => row['type']))
+      await expect(scaffold.ctx.sessionController.page({ address: { ...address, childSessionId: brokenId, mode: 'unknown' }, throughSeq: 1 }, signal))
+        .rejects.toThrow()
+      await expect(scaffold.ctx.sessionController.page({ address: { kind: 'session', sessionId: id }, throughSeq: rows.length - 1 }, signal))
+        .resolves.toMatchObject({ hasMore: false })
+      const childWriter = await scaffold.ctx.sessionPersistence.open(childId, 'write')
+      await childWriter.close()
+      const childPublished = await readFile(childSuccessor)
+      const childText = Buffer.concat(scanZstdFrames(childPublished).frames
+        .map(({ start, end }) => zstdDecompressSync(childPublished.subarray(start, end)))).toString('utf8')
+      expect(childText.trimEnd().split('\n').map((line): unknown => JSON.parse(line))).toEqual([
+        { ...childHeader, version: SESSION_FORMAT_VERSION, agentPreset: 'ptc' }, ...childRows,
+      ])
+      expect(await readFile(childPath)).toEqual(childSource)
+      expect(await readFile(brokenPath)).toEqual(brokenSource)
+      await expect(readFile(generationLogPath(scaffold.persistenceRoot, scaffold.workspaceCwd, brokenId, SESSION_FORMAT_VERSION, 'zstd')))
+        .rejects.toMatchObject({ code: 'ENOENT' })
+
+      await scaffold.ctx.sessions.flush(resolved.agent.session)
       const publishedBytes = await readFile(successor)
       const published = Buffer.concat(scanZstdFrames(publishedBytes).frames
         .map(({ start, end }) => zstdDecompressSync(publishedBytes.subarray(start, end)))).toString('utf8')
@@ -58,12 +114,23 @@ describe.skipIf(webSnapshotMode() === 'record')('historical preset restoration t
           && (row['data'] as { agentPreset: string }).agentPreset === 'code'
           ? { ...row, data: { agentPreset: 'ptc' } }
           : row),
+        { type: 'subagent/catalog', seq: rows.length, time: rows.at(-1)?.['time'], data: {
+          version: 1, childId: brokenId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'unknown',
+        } },
+        { type: 'subagent/catalog', seq: rows.length + 1, time: rows.at(-1)?.['time'], data: {
+          version: 0, childId, childCreatedAt: childFixture[0]?.['createdAt'], mode: 'one-shot', label: 'historical child',
+        } },
         // Agent activation closes its restored prefix with a fresh seed marker.
-        { type: 'session/end-seed', seq: rows.length, time: 0, data: {} },
+        { type: 'session/end-seed', seq: rows.length + 2, time: 0, data: {} },
+        { type: 'permission/preset', seq: rows.length + 3, time: 0, data: { preset: 'workspace-write' } },
+        { type: 'sandbox/mode', seq: rows.length + 4, time: 0, data: { mode: 'workspace-write' } },
+        { type: 'approval/policy', seq: rows.length + 5, time: 0, data: { policy: 'ask' } },
       ].map(row => JSON.stringify(row)).join('\n') + '\n'
       const context = { sessionIds: [id], cwd: scaffold.workspaceCwd }
       expect(normalizeSessionSnapshots([published], context)).toEqual(normalizeSessionSnapshots([expected], context))
       expect(await readFile(predecessor)).toEqual(source)
+      await expect(scaffold.ctx.sessionPersistence.open(corruptHeaderId, 'read')).rejects.toThrow(/invalid frame magic/)
+      expect(await readFile(corruptHeaderPath)).toEqual(corruptHeaderSource)
       expect((await readdir(dirname(predecessor))).filter(name => name.endsWith('.jsonl.zstd')).sort())
         .toEqual(['session.v2.jsonl.zstd', `session.v${SESSION_FORMAT_VERSION}.jsonl.zstd`])
     } finally {
diff --git a/apps/web/tests/preview-boot.e2e.ts b/apps/web/tests/preview-boot.e2e.ts
index bde54fe69e..270f19a181 100644
--- a/apps/web/tests/preview-boot.e2e.ts
+++ b/apps/web/tests/preview-boot.e2e.ts
@@ -40,7 +40,7 @@ import {
   buildVfsExampleFiles,
 } from '../../../packages/experimental/webworker-runtime/tests/vfs-example-fixture.ts'
 import { captureStableAria, compareOrRefreshGolden, webSnapshotMode } from './scaffold.ts'
-import { newEnglishPage, REPO_ROOT, saveFailureShot } from './support.ts'
+import { expandOwningTurnProcess, newEnglishPage, REPO_ROOT, saveFailureShot } from './support.ts'
 
 const DIST_ROOT = fileURLToPath(new URL('../dist', import.meta.url))
 
@@ -418,12 +418,17 @@ async function bootPreview(origin: string, browser: Browser): Promise<void> {
     await page.getByText(SHOWCASE_TAIL, { exact: true }).waitFor({ timeout: 30_000 })
 
     expect(await page.getByText(SHOWCASE_OLDEST, { exact: true }).count()).toBe(0)
+    // Complete Turns can fold while earlier history is still unloaded.
+    const readTool = page.locator('[data-chat-call-id="preview-read"]')
+    await readTool.waitFor({ state: 'attached' })
+    expect(await readTool.isVisible()).toBe(false)
+    await expandOwningTurnProcess(page, readTool)
     await page.getByRole('button', { name: 'PREVIEW.md', exact: true }).waitFor()
     await page.getByRole('button', { name: 'src/preview.ts', exact: true }).waitFor()
     await page.getByText('Update to-do list', { exact: true }).waitFor()
     await page.getByText('Error: ENOENT: no such file, open missing.txt', { exact: true }).waitFor()
 
-    const subagents = page.getByRole('button', { name: '2 subagents' })
+    const subagents = page.getByRole('button', { name: '2 subagents', exact: true })
     await subagents.waitFor({ timeout: 15_000 })
     await subagents.hover()
     const catalog = page.getByRole('tree', { name: 'Subagent sessions' })
diff --git a/apps/web/tests/reasoning-preview.e2e.ts b/apps/web/tests/reasoning-preview.e2e.ts
new file mode 100644
index 0000000000..c69e4618f7
--- /dev/null
+++ b/apps/web/tests/reasoning-preview.e2e.ts
@@ -0,0 +1,98 @@
+/** Streaming reasoning previews through the assembled Chat and a paused model adapter. */
+import { fileURLToPath } from 'node:url'
+import { chromium } from 'playwright'
+import { expect, it } from 'vitest'
+import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import {
+  captureStableAria, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode,
+} from './scaffold.ts'
+import { connectFreshWorkspace, newEnglishPage, writeComposerDraft } from './support.ts'
+
+const SUMMARY = `Next paragraph: ${'inspect the loaded context and pending tools '.repeat(8).trim()}`
+const DELTAS = ['First paragraph', `\nDetails\n\n\n${SUMMARY}`, '\nMore detail']
+const UI_EXPECTED = fileURLToPath(new URL('./expected/reasoning-preview/running.expected.md', import.meta.url))
+
+class PausedReasoningAdapter extends LlmAdapter {
+  readonly stages = DELTAS.map(text => ({
+    text,
+    arrived: Promise.withResolvers<undefined>(),
+    proceed: Promise.withResolvers<undefined>(),
+  }))
+
+  release(): void {
+    for (const stage of this.stages) stage.proceed.resolve(undefined)
+  }
+
+  override async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    yield { type: 'block-start', index: 0, blockType: 'reasoning' }
+    for (const stage of this.stages) {
+      yield { type: 'reasoning-delta', index: 0, text: stage.text }
+      stage.arrived.resolve(undefined)
+      await stage.proceed.promise
+      options.signal?.throwIfAborted()
+    }
+    yield { type: 'block-end', index: 0, block: { type: 'reasoning', text: DELTAS.join('') } }
+    yield { type: 'block-start', index: 1, blockType: 'text' }
+    yield { type: 'text-delta', index: 1, text: 'Done' }
+    yield { type: 'block-end', index: 1, block: { type: 'text', text: 'Done' } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
+it('shows completed paragraph first lines across blank lines with a right-edge fade', async () => {
+  const scaffold = await launchWebScaffold()
+  const adapter = new PausedReasoningAdapter()
+  try {
+    scaffold.ctx.effect(() => scaffold.ctx.llm.registerAdapter(['reasoning-preview-test'], adapter))
+    await scaffold.ctx.agentDefaultModel.saveSelection({ provider: 'reasoning-preview-test', model: 'paused' })
+    const browser = await chromium.launch()
+    try {
+      const page = await newEnglishPage(browser)
+      const console = watchConsole(page)
+      await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+      await connectFreshWorkspace(page, scaffold.workspaceCwd)
+      await page.setViewportSize({ width: 480, height: 1000 })
+      const input = page.locator('[data-composer-input]').first()
+      const settled = scaffold.whenTurnSettled()
+      await writeComposerDraft(page, input, 'Show a streamed reasoning preview.')
+      await input.press('Enter')
+
+      const [first, second, third] = adapter.stages
+      if (first === undefined || second === undefined || third === undefined) throw new Error('preview stages are incomplete')
+      await first.arrived.promise
+      const reasoning = page.locator('[data-variant="think"][data-state="running"]')
+      await reasoning.waitFor()
+      expect(await reasoning.getAttribute('data-preview')).toBeNull()
+
+      first.proceed.resolve(undefined)
+      await second.arrived.promise
+      const preview = reasoning.locator('[data-streaming]')
+      await expect.poll(() => preview.textContent()).toBe('First paragraph')
+      expect(await preview.isVisible()).toBe(true)
+      await preview.evaluate((element) => { element.setAttribute('data-retained-preview', 'true') })
+
+      second.proceed.resolve(undefined)
+      await third.arrived.promise
+      await expect.poll(() => preview.textContent()).toBe(SUMMARY)
+      expect(await preview.getAttribute('data-retained-preview')).toBe('true')
+      expect(await preview.evaluate(element => getComputedStyle(element).maskImage)).toContain('linear-gradient')
+      expect(await preview.evaluate(element => element.scrollWidth > element.clientWidth)).toBe(true)
+      expect(await reasoning.getByRole('button').getAttribute('aria-expanded')).toBe('false')
+      await compareOrRefreshGolden(UI_EXPECTED,
+        await captureStableAria(page, '[data-variant="think"]', scaffold.workspaceCwd), webSnapshotMode())
+
+      third.proceed.resolve(undefined)
+      await settled
+      await page.getByText('Done', { exact: true }).waitFor()
+      expect(console.pageErrors).toEqual([])
+      expect(console.warnings).toEqual([])
+    } finally {
+      adapter.release()
+      await browser.close()
+    }
+  } finally {
+    adapter.release()
+    await scaffold.close()
+  }
+})
diff --git a/apps/web/tests/replay-round-trip.e2e.ts b/apps/web/tests/replay-round-trip.e2e.ts
index 8bddaee2d7..7604dba970 100644
--- a/apps/web/tests/replay-round-trip.e2e.ts
+++ b/apps/web/tests/replay-round-trip.e2e.ts
@@ -4,20 +4,26 @@
 // or the live adapter (record). Drive steps run in every mode and wait only
 // on generic completion (whenTurnSettled — never model-content selectors, so
 // record cannot hang on a live model answering differently); assertion steps
-// run in replay/refresh only. Settled states only — streaming fidelity is
-// asserted from the durable embedded Assistant stream, not transient DOM.
+// run in replay/refresh only. Streaming fidelity is asserted from the durable
+// embedded Assistant stream, not transient DOM.
 // Record: DSH_SNAPSHOT=record writes session.v3.jsonl, then a keyless
 // DSH_SNAPSHOT=refresh regenerates ui.expected.md.
+// Suite setup (beforeAll, not per step): one fixed page clock
+// (page.clock.setFixedTime) and one routed Remote mux socket
+// (page.routeWebSocket) serve every step below, so the reconnect checkpoints
+// rely on both without re-pinning or re-routing them.
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { Browser, Page } from 'playwright'
+import type { Browser, Page, Route, WebSocketRoute } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import { ToolCallId, expandAssistantStream } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionListValue } from '@deepseek-ai/dsh-api-session-controller/types'
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
 import {
-  assertFixtureInventory, captureExpandedTurnProcessAria, captureStableAria,
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureExpandedTurnProcessAria, captureStableAria,
   compareOrRefreshGolden, fixtureUserPrompts,
   launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
@@ -29,6 +35,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/fresh-round-t
 const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/session.v3.jsonl', import.meta.url))
 const UI_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/ui.expected.md', import.meta.url))
 const ECHO_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/submission-echo.expected.md', import.meta.url))
+const ACCEPTED_RECONNECT_EXPECTED = join(SNAPSHOT_DIR, 'accepted-reconnect.expected.md')
 const BLANK_EXPECTED = join(SNAPSHOT_DIR, 'blank-reload.expected.md')
 const UI_EXPANDED_EXPECTED = fileURLToPath(
   new URL('../../../snapshots/web/fresh-round-trip/ui-expanded.expected.md', import.meta.url),
@@ -41,6 +48,8 @@ const MODE = webSnapshotMode()
 // drift apart.
 const PROMPT = 'Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop.'
 
+type SessionListResponse = { result: RemoteResult<SessionListValue> }
+
 /** Rendered text of the system prompt surface node, or undefined when the surface carries none. */
 function systemPromptText(session: Session): string | undefined {
   const message = session.deriveMessages().find(candidate => candidate.role === 'system')
@@ -53,7 +62,9 @@ describe('web e2e: fresh round trip through the real assembly', () => {
   let page: Page
   let tripwire: ReturnType<typeof watchConsole>
   let settledSessionId: SessionId | undefined
+  let remoteSocket: WebSocketRoute | undefined
   const sessionEvents: SessionEvent[] = []
+  const browserNow = Date.now()
 
   beforeAll(async () => {
     scaffold = await launchWebScaffold({
@@ -63,6 +74,11 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
+    await page.clock.setFixedTime(browserNow)
+    await page.routeWebSocket('**/api/remote.mux', (route) => {
+      remoteSocket = route
+      route.connectToServer()
+    })
     tripwire = watchConsole(page)
     await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
@@ -94,26 +110,104 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     }
     const input = page.locator('[data-composer-input]').first()
     await input.waitFor({ timeout: 10_000 })
-    // Arm the host-side settled barrier BEFORE the send click.
-    const settled = scaffold.whenTurnSettled()
-    await input.fill(PROMPT)
-    const echoSnapshot = await input.evaluate(async (element, prompt) => {
-      element.dispatchEvent(new KeyboardEvent('keydown', {
-        key: 'Enter', code: 'Enter', bubbles: true, cancelable: true,
-      }))
-      // sendSession registered its paint yield first. This frame observes the
-      // committed echo while admission remains queued on the following task.
-      await new Promise<void>((resolve) => { requestAnimationFrame(() => { resolve() }) })
-      const echo = document.querySelector<HTMLElement>('[data-submission-echo]')
-      return [
-        `echo: ${echo?.textContent?.includes(prompt) === true ? prompt : '(missing)'}`,
-        `composer: ${JSON.stringify(element.textContent ?? '')}`,
-        `contenteditable: ${element.getAttribute('contenteditable')}`,
-      ].join('\n')
-    }, PROMPT)
-    await compareOrRefreshGolden(ECHO_EXPECTED, echoSnapshot, MODE)
-    const sessionId = await settled
-    settledSessionId = sessionId
+    const sessionId = await page.evaluate(() => {
+      const selected = JSON.parse(localStorage.getItem('dsh.sessions.current')!) as { sessionId: string }
+      return selected.sessionId
+    }) as SessionId
+    const agent = scaffold.ctx.agents.get(sessionId)
+    if (agent === undefined) throw new Error('the selected Web Session has no live Agent')
+    await agent.whenIdle()
+    const release = Promise.withResolvers<undefined>()
+    // Maintenance leaves status idle and accepts inbox input without starting a turn.
+    const maintenance = agent.runMaintenance(() => release.promise)
+    let accepted = false
+    try {
+      await input.fill(PROMPT)
+      const admitted = page.waitForResponse('**/api/session/prompt')
+      const [echoSnapshot, response] = await Promise.all([
+        input.evaluate(async (element, prompt) => {
+          element.dispatchEvent(new KeyboardEvent('keydown', {
+            key: 'Enter', code: 'Enter', bubbles: true, cancelable: true,
+          }))
+          // sendSession registered its paint yield first. This frame observes the
+          // committed echo while admission remains queued on the following task.
+          await new Promise<void>((resolve) => { requestAnimationFrame(() => { resolve() }) })
+          const echo = document.querySelector<HTMLElement>('[data-submission-echo]')
+          return [
+            `echo: ${echo?.textContent?.includes(prompt) === true ? prompt : '(missing)'}`,
+            `composer: ${JSON.stringify(element.textContent ?? '')}`,
+            `contenteditable: ${element.getAttribute('contenteditable')}`,
+          ].join('\n')
+        }, PROMPT),
+        admitted,
+      ])
+      expect(await response.json()).toMatchObject({ result: { ok: true, value: { accepted: true } } })
+      accepted = true
+      await compareOrRefreshGolden(ECHO_EXPECTED, echoSnapshot, MODE)
+      const row = page.getByRole('tree', { name: 'Sessions', exact: true })
+        .locator('[role="treeitem"][aria-selected="true"]')
+      await expect.poll(() => row.getAttribute('draggable'), { timeout: 5_000 }).toBe('true')
+      expect(sessionEvents.some(event => event.type === 'turn/start')).toBe(false)
+
+      const disconnected = remoteSocket
+      if (disconnected === undefined) throw new Error('the Web Remote socket never connected')
+      const warningStart = tripwire.warnings.length
+      // Only this list response carries the 2d timestamp. Its rendered label
+      // confirms the refresh reached the row, without altering blank/running.
+      const listUrl = new URL('/api/session/list', scaffold.baseUrl).href
+      const markListResponse = async (route: Route): Promise<void> => {
+        const response = await route.fetch()
+        try {
+          const body = await response.json() as SessionListResponse
+          if (body.result.ok) {
+            body.result = { ...body.result, value: {
+              ...body.result.value,
+              items: body.result.value.items.map(item => item.sessionId === sessionId
+                ? { ...item, updatedAt: browserNow - 2 * 86_400_000 }
+                : item),
+            } }
+          }
+          await route.fulfill({ response, json: body })
+        } finally {
+          await response.dispose()
+        }
+      }
+      await page.route(listUrl, markListResponse, { times: 1 })
+      try {
+        const refreshing = page.waitForResponse(listUrl)
+        const [, refreshed] = await Promise.all([disconnected.close(), refreshing])
+        // Cross-network reconnect: allow more than expect.poll's default.
+        await expect.poll(() => remoteSocket !== disconnected, { timeout: 15_000 }).toBe(true)
+        const baseline = await refreshed.json() as SessionListResponse
+        expect(baseline.result.ok).toBe(true)
+        if (!baseline.result.ok) throw new Error('the reconnect list request failed')
+        const hostSummary = baseline.result.value.items.find(item => item.sessionId === sessionId)
+        expect(hostSummary).toMatchObject({ blank: true, running: false })
+        await row.getByText('2d', { exact: true }).waitFor()
+        expect(await row.getAttribute('draggable')).toBe('true')
+        expect(await row.getByText('New Session', { exact: true }).count()).toBe(0)
+        expect(sessionEvents.some(event => event.type === 'turn/start')).toBe(false)
+        const checkpoint = [
+          `selected sidebar rows: ${await row.count()}`,
+          `new-session labels: ${await row.getByText('New Session', { exact: true }).count()}`,
+          `row draggable: ${await row.getAttribute('draggable')}`,
+          `host history blank: ${hostSummary?.blank}`,
+          `composer: ${JSON.stringify(await input.textContent())}`,
+          `contenteditable: ${await input.getAttribute('contenteditable')}`,
+        ].join('\n')
+        await compareOrRefreshGolden(ACCEPTED_RECONNECT_EXPECTED, checkpoint, MODE)
+        acknowledgeReloadConnectionLoss(tripwire, warningStart)
+      } finally {
+        await page.unroute(listUrl, markListResponse)
+      }
+    } finally {
+      // No turn can settle before maintenance releases the accepted input.
+      const settled = accepted ? scaffold.whenTurnSettled() : undefined
+      release.resolve(undefined)
+      await maintenance
+      if (settled !== undefined) settledSessionId = await settled
+      await agent.whenIdle()
+    }
     if (MODE === 'record') {
       await recordFixture(scaffold, sessionId, FIXTURE)
     }
@@ -202,24 +296,13 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     await compareOrRefreshGolden(UI_EXPANDED_EXPECTED, expanded, MODE)
   })
 
-  it.skipIf(MODE === 'record')('renders the system prompt disclosure inside the expanded Turn process', async () => {
+  it.skipIf(MODE === 'record')('omits system prompt rows even when the Turn process is expanded', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-round-trip-system-prompt'))
     await expandTurnProcesses(page)
-    const disclosure = page.getByRole('button', { name: 'System prompt', exact: true })
-    const body = page.locator('[data-system-prompt-body]')
-    await expect.poll(() => disclosure.count(), { timeout: 10_000 }).toBe(1)
-    await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('false')
-    expect(await body.count()).toBe(0)
-
-    await disclosure.click()
-    await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('true')
-    const opaque = body.locator('[data-context-text]')
-    await expect.poll(() => opaque.count(), { timeout: 5_000 }).toBe(1)
-    expect(await opaque.textContent()).toContain('You are an AI agent powered by DeepSeek Harness.')
-
-    await disclosure.click()
-    await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('false')
-    await expect.poll(() => body.count()).toBe(0)
+    expect(sessionEvents.some(event => event.type === 'system/message')).toBe(true)
+    expect(await page.locator('[data-chat-flow-kind="system-prompt"]').count()).toBe(0)
+    expect(await page.getByRole('button', { name: 'System prompt', exact: true }).count()).toBe(0)
+    expect(await page.locator('[data-system-prompt-body]').count()).toBe(0)
   })
 
   it.skipIf(MODE === 'record')('expands and collapses the reasoning fold from its click target', async () => {
@@ -237,12 +320,13 @@ describe('web e2e: fresh round trip through the real assembly', () => {
     await expect.poll(() => think.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('false')
   })
 
-  it.skipIf(MODE === 'record')('stayed clean: no pageerrors, no reconnect self-healing, no server errors', async () => {
+  it.skipIf(MODE === 'record')('stayed clean after the intentional reconnect: no pageerrors or server errors', async () => {
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'blank-reload.expected.md',
       'session.v3.jsonl',
+      'accepted-reconnect.expected.md',
       'submission-echo.expected.md',
       'system-prompt.expected.md',
       'tool-schemas.expected.json',
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index e7249a0b67..90f6387c7d 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -261,10 +261,9 @@ class RouteOnlyAdapter extends LlmAdapter {
   }
 }
 
-function replayProviders(contextWindow: number | undefined, messages: boolean): typeof REPLAY_PROVIDERS {
+function replayProviders(contextWindow: number | undefined): typeof REPLAY_PROVIDERS {
   return REPLAY_PROVIDERS.map(provider => ({
     ...provider,
-    id: messages ? 'deepseek-messages' : provider.id,
     models: provider.models.map(model => ({
       ...model,
       ...contextWindow === undefined ? {} : { contextWindow },
@@ -302,12 +301,12 @@ export interface WebScaffold {
 
 /** Options for {@link launchWebScaffold}. */
 export interface LaunchOptions {
-  /** The scaffold enables developer tools unless false preserves the shipped default. */
+  /** Override the developer-tools preference; omitted uses the shipped default. */
   developerTools?: boolean
   /** Enable the real Open In rows with deterministic launch-environment facts. */
   openInAppEnvironment?: LaunchEnvironmentSnapshot
-  /** Compare the replayed root session with `replayFixture`; defaults on for a manifest-owned canonical recording. */
-  compareReplaySession?: boolean
+  /** Compare the replayed root Session; `read-only` also forbids refresh writes to a borrowed fixture. */
+  compareReplaySession?: boolean | 'read-only'
   /**
    * Optional product overlay applied after the shipped Web surface and before
    * the scaffold's hermetic test patches, matching the launcher's `--patch`
@@ -391,10 +390,10 @@ export interface LaunchOptions {
    * keyless first-run configuration lane; the default disables the adapter.
    */
   deepSeekMissingCredential?: boolean
-  /** Record or replay a Messages scenario; older scenarios explicitly retain their recorded Chat Completions route. */
-  deepSeekMessages?: boolean
   /** Leave the current welcome notice pending; ordinary scenarios pre-acknowledge it before browser boot. */
   welcomeNoticePending?: boolean
+  /** Leave first-use Workspace initialization eligible; ordinary scenarios start after the default was removed. */
+  firstUse?: boolean
   /**
    * Patch the shipped DeepSeek search row to a deterministic endpoint and
    * credential reference. Browser search scenarios keep the real provider and
@@ -494,7 +493,6 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     throw new Error('deepSeekMissingCredential is a keyless replay/refresh option')
   }
   const maskDeepSeekCredential = mode !== 'record' && options.deepSeekMissingCredential === true
-  const messages = options.deepSeekMessages === true
   const originalDeepSeekCredential = process.env.DEEPSEEK_API_KEY
   let credentialEnvironmentRestored = false
   const restoreCredentialEnvironment = (): void => {
@@ -571,13 +569,9 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     // Without HMR the profile applies configuration changes at its next start.
     ...options.profile?.hmr === false ? [{ id: 'hmr', disabled: true }] : [],
     { id: 'session-log-deepseek', config: { enabled: false } },
-    // The historical Messages fixture retains its recorded route during replay;
-    // live configuration uses the shared DeepSeek route. Explicit overlays win.
-    ...messages
-      ? [{ id: 'agent-default-model', config: { provider: mode === 'record' || maskDeepSeekCredential ? 'deepseek-official' : 'deepseek-messages', model: maskDeepSeekCredential ? 'deepseek-flash' : 'deepseek-v4-flash' } }]
-      : mode === 'record' || options.deepSeekMissingCredential === true
-        ? []
-        : [{ id: 'agent-default-model', config: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } }],
+    ...mode === 'record' || options.deepSeekMissingCredential === true
+      ? []
+      : [{ id: 'agent-default-model', config: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } }],
     ...extraOverlayPatches,
     // The roster's shipped presets are the plugin's own, bundled inside
     // `dsh-agent-presets` and prepended by it. Pin only the machine-local
@@ -600,6 +594,8 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     // to an absolute temp root (removed with the workspace at close) so tests
     // never write the user's harness home.
     { id: 'storage-json', config: { root: join(workspaceCwd, '.dsh-storages') } },
+    // First-use initialization must create directories only inside this scaffold's temporary world.
+    { id: 'workspace-controller', config: { documentsDirectory: join(workspaceCwd, 'Documents') } },
     // Skill discovery is model-visible input. Pin every host-level root inside
     // the owned temp world so ~/.dsh, ~/.agents, and a bundled-root env setting
     // cannot change replay requests or conversation goldens. Project roots stay
@@ -693,10 +689,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
           baseURL: options.deepSeekSearch.baseURL,
         },
       }],
-    ...maskDeepSeekCredential && !messages ? [] : [
-      { id: 'llm-deepseek', disabled: mode !== 'record' && !maskDeepSeekCredential,
-        config: messages ? {} : { protocol: 'chat-completions' } },
-    ],
+    { id: 'llm-deepseek', disabled: mode !== 'record' && !maskDeepSeekCredential },
   ]
   const patches: PatchOptions[] = [...basePatches, ...surfacePatches, ...overlayPatches]
 
@@ -737,7 +730,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
       return {
         packageName: manifest.name,
         packageDir,
-        patchPath: join(packageDir, 'cordis.patch.yml'),
+        patchPaths: [join(packageDir, 'cordis.patch.yml')],
         patches: [],
       }
     }))
@@ -818,14 +811,18 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     }
     await ctx.loader.await()
     await auditStartupEntries(ctx, 'web e2e scaffold')
-    if (options.developerTools !== false) {
-      await ctx.settings.update('ui-developer-tools', { enabled: true })
+    if (options.developerTools !== undefined) {
+      await ctx.settings.update('ui-developer-tools', { enabled: options.developerTools })
     }
     if (options.welcomeNoticePending !== true) {
       await ctx.settings.mutate(WELCOME_NOTICE_SETTINGS_NAMESPACE, [{
         op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION,
       }])
     }
+    if (options.firstUse !== true && ctx.workspaceRegistry.list().length === 0) {
+      const initial = await ctx.workspaceRegistry.initializeDefault(async () => ({ path: workspaceCwd, title: 'Workspace' }))
+      if (initial !== undefined) await ctx.workspaceRegistry.delete(initial.id)
+    }
     const boundPort = ctx.get('webServer')?.port
     if (boundPort === undefined) {
       throw new Error('web e2e scaffold: webServer service missing after settled boot')
@@ -870,7 +867,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     if (mode !== 'record' && replayFixture !== undefined) {
       replayHandle = installLlmReplay(ctx, {
         file: replayFixture,
-        providers: (options.replayProviders ?? replayProviders(options.replayContextWindow, messages)).map(provider => ({
+        providers: (options.replayProviders ?? replayProviders(options.replayContextWindow)).map(provider => ({
           ...provider,
           ...(options.replayRetryPolicy === undefined ? {} : { retryPolicy: options.replayRetryPolicy }),
         })),
@@ -885,8 +882,8 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
       // a fixture would, with streaming that still fails loud: the scenario
       // issues no model calls, and one that slipped in must not pass quietly.
       ctx.effect(() => ctx.llm.registerAdapter(
-        replayProviders(options.replayContextWindow, messages).map(provider => provider.id),
-        new RouteOnlyAdapter(replayProviders(options.replayContextWindow, messages)),
+        replayProviders(options.replayContextWindow).map(provider => provider.id),
+        new RouteOnlyAdapter(replayProviders(options.replayContextWindow)),
       ), 'web e2e scaffold: route-only adapter')
     }
     if (publicProxy === undefined || publicHost === undefined || publicPrefix === undefined) {
@@ -968,7 +965,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
           await assertReplaySession(
             [...observedSessions.values()],
             replayFixture,
-            mode,
+            compareReplaySession === 'read-only' ? 'replay' : mode,
             `http://${browserHost}:${port}`,
             harnessHome,
           )
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index b31b33bba0..969ade598a 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -228,6 +228,13 @@ describe('web e2e: seeded history renders through cold resume', () => {
       ],
       openInAppEnvironment: createLaunchEnvironmentSnapshot([{ source: 'process', values: { SSH_CONNECTION: '10.0.0.2 55000 10.0.0.9 22' } }]),
     })
+    // Application registrations belong to the host desktop, not to the recorded Session.
+    const controller = scaffold.ctx.get('sessionController')
+    if (controller === undefined) throw new Error('seeded-history requires Session Controller')
+    const nativeQuery: unknown = Reflect.get(controller, 'fileApplications')
+    if (typeof nativeQuery !== 'function') throw new Error('seeded-history requires the native file-association adapter')
+    Reflect.set(controller, 'fileApplications', async () => [])
+    scaffold.ctx.effect(() => () => { Reflect.set(controller, 'fileApplications', nativeQuery) }, 'seeded-history: native association fixture')
     // Composer recording uses a child workspace; seedSession owns the scaffold root.
     const sessionCwd = MODE === 'record' ? join(scaffold.workspaceCwd, 'workspace') : scaffold.workspaceCwd
     await mkdir(sessionCwd, { recursive: true })
@@ -518,7 +525,8 @@ describe('web e2e: seeded history renders through cold resume', () => {
       await expect.poll(() => path.textContent()).toBe(absolutePath)
       expect(await path.getAttribute('title')).toBe(absolutePath)
       await expect.poll(() => column.locator('[data-textpreview-line="1"]').textContent()).toBe('alpha\n')
-      await column.locator('[data-open-path-open]').waitFor({ timeout: 5_000 })
+      await column.getByRole('button', { name: 'Show file location', exact: true }).waitFor({ timeout: 5_000 })
+      await expect.poll(() => column.locator('[data-open-path-open]').isEnabled()).toBe(true)
       const preview = await captureStableAria(page, '[data-textpreview-state="text"]', scaffold.workspaceCwd)
       await compareOrRefreshGolden(FILE_PREVIEW_EXPECTED, preview, MODE)
     } finally {
@@ -721,24 +729,21 @@ describe('web e2e: seeded history renders through cold resume', () => {
     if (bodyError !== undefined) throw bodyError
   })
 
-  it.skipIf(MODE === 'record')('an Access-chip switch lands one command row: bare name, non-repeating settlement text', async () => {
+  it.skipIf(MODE === 'record')('an Access-chip switch persists its command without adding a Chat row', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-command-row'))
-    // The Access chip submits `/permission <preset>` — a host command with no
-    // model call, so the settled row renders keylessly over this cold history.
-    // The row copy is the assertion: `permission · preset read-only`,
-    // where neither half repeats the other (the dispatched `/` and its
-    // argument stay out of the title, and the settlement text never restates
-    // the command's own name).
     await page.getByRole('button', { name: 'Access mode, current: Workspace Write' }).click()
     await page.getByRole('menuitem', { name: 'Read Only' }).click()
     const access = page.getByRole('button', { name: 'Access mode, current: Read Only' })
     await expect.poll(() => access.isEnabled(), { timeout: 10_000 }).toBe(true)
-    // Scoped to the row itself, so unrelated page text that happens to read
-    // `permission` (a future resident slash menu) cannot satisfy or break it.
     const row = page.locator('[data-variant="others"]').filter({ hasText: 'preset read-only' })
-    await expect.poll(() => row.count(), { timeout: 10_000 }).toBe(1)
-    expect(await row.getByText('permission', { exact: true }).count()).toBe(1)
-    expect(await row.getByText('/permission read-only', { exact: true }).count()).toBe(0)
+    expect(await row.count()).toBe(0)
+    const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))
+    if (agent === undefined) throw new Error('seeded session did not attach an agent')
+    const events = agent.session.snapshotEvents()
+    const run = events.findLast(event => event.type === 'command/run' && event.data.name === 'permission')
+    if (run?.type !== 'command/run') throw new Error('permission command was not persisted')
+    expect(events.find(event => event.type === 'command/done' && event.data.commandId === run.data.commandId)?.data)
+      .toMatchObject({ kind: 'success', text: 'preset read-only' })
     const snapshot = (await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd))
       .split(SEED_ID).join('{{seededId}}')
     await compareOrRefreshGolden(COMMAND_ROW_EXPECTED, snapshot, MODE)
diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts
index d84614d33c..0d21a890ac 100644
--- a/apps/web/tests/settings-chrome.e2e.ts
+++ b/apps/web/tests/settings-chrome.e2e.ts
@@ -29,6 +29,8 @@ const PLUGIN_INSTANCES_EXPECTED = join(SNAPSHOT_DIR, 'plugin-instances.expected.
 const DIALOG_EN_EXPECTED = join(SNAPSHOT_DIR, 'dialog-en.expected.md')
 const PLUGIN_ROW_SELECTOR = '[data-plugin-scope="preset"] [data-plugin-entry="tool-subagent"]'
 const MODE = webSnapshotMode()
+const { version } = JSON.parse(await readFile(new URL('../../../package.json', import.meta.url), 'utf8')) as { version: string }
+const versionCapture = { replacements: [[version, '{{version}}']] as const }
 
 describe('web e2e: settings modal and General preferences', () => {
   let scaffold: WebScaffold
@@ -93,12 +95,13 @@ describe('web e2e: settings modal and General preferences', () => {
     await expect.poll(() => openRequests, { timeout: 5_000 }).toBe(1)
     await expect.poll(() => openDocument.isEnabled(), { timeout: 5_000 }).toBe(true)
     await page.unroute('**/api/settings/openSettingsDocument')
+    await dialog.getByText(`当前版本：${version}`, { exact: true }).waitFor()
     // Golden of the freshly opened dialog (default zh, General active).
-    const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd)
+    const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd, versionCapture)
     await compareOrRefreshGolden(DIALOG_EXPECTED, snapshot, MODE)
     // Section switch: aria-current moves (the Models page itself has its own scenario file).
-    await dialog.getByRole('button', { name: '模型' }).click()
-    await expect.poll(() => dialog.getByRole('button', { name: '模型' }).getAttribute('aria-current'), { timeout: 5_000 }).toBe('true')
+    await dialog.getByRole('button', { name: '模型', exact: true }).click()
+    await expect.poll(() => dialog.getByRole('button', { name: '模型', exact: true }).getAttribute('aria-current'), { timeout: 5_000 }).toBe('true')
     expect(await dialog.getByRole('button', { name: '通用设置' }).getAttribute('aria-current')).toBeNull()
     // Built-in plugins: the read-only Plugin list, a projection of the same
     // assembled Loader tree, shown as the section's one page; management and
@@ -140,7 +143,7 @@ describe('web e2e: settings modal and General preferences', () => {
     expect(await dialog.getByRole('button', { name: '内置插件', exact: true }).getAttribute('aria-current')).toBe('true')
     // One contribution shows as the page itself, without a tab row.
     expect(await dialog.getByRole('tab').count()).toBe(0)
-    expect(await dialog.getByRole('button', { name: '模型' }).getAttribute('aria-current')).toBeNull()
+    expect(await dialog.getByRole('button', { name: '模型', exact: true }).getAttribute('aria-current')).toBeNull()
     const pluginsSnapshot = await captureStableAria(
       page,
       PLUGIN_ROW_SELECTOR,
@@ -187,6 +190,50 @@ describe('web e2e: settings modal and General preferences', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('scrolls overflowing section navigation independently of the title and settings content', async () => {
+    const overflowPage = await browser.newPage({ viewport: { width: 1280, height: 768 }, locale: ZH_BROWSER_LOCALE })
+    onTestFinished(() => overflowPage.close())
+    onTestFailed(() => saveFailureShot(overflowPage, 'web-e2e-settings-navigation'))
+    const console = watchConsole(overflowPage)
+    await overflowPage.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+    await overflowPage.getByRole('button', { name: '设置', exact: true }).click()
+    const dialog = overflowPage.getByRole('dialog', { name: '设置', exact: true })
+    const navigation = dialog.getByRole('navigation')
+    const list = navigation.locator('[class*="_navList"]')
+    const title = navigation.getByText('设置', { exact: true })
+    const options = dialog.locator('[class*="_options"]')
+    const last = navigation.getByRole('button').last()
+    await last.waitFor()
+    expect(await list.evaluate(el => el.scrollHeight > el.clientHeight)).toBe(false)
+
+    // A short viewport overflows the shipped sections without synthetic registrations.
+    await overflowPage.setViewportSize({ width: 1280, height: 240 })
+    expect(await list.evaluate(el => el.scrollHeight > el.clientHeight)).toBe(true)
+    const titleBefore = await title.boundingBox()
+    const contentBefore = await options.innerText()
+    await navigation.getByRole('button').first().hover()
+    await overflowPage.mouse.wheel(0, 1000)
+    await expect.poll(() => last.evaluate((el) => {
+      const rect = el.getBoundingClientRect()
+      return el.contains(document.elementFromPoint(rect.x + rect.width / 2, rect.y + rect.height / 2))
+    })).toBe(true)
+    const navScroll = await list.evaluate(el => el.scrollTop)
+    expect(navScroll).toBeGreaterThan(0)
+    expect(await title.boundingBox()).toEqual(titleBefore)
+    expect(await options.evaluate(el => el.scrollTop)).toBe(0)
+
+    await options.hover()
+    await overflowPage.mouse.wheel(0, 1000)
+    await expect.poll(() => options.evaluate(el => el.scrollTop)).toBeGreaterThan(0)
+    expect(await list.evaluate(el => el.scrollTop)).toBe(navScroll)
+    expect(await title.boundingBox()).toEqual(titleBefore)
+    await last.click()
+    await expect.poll(() => last.getAttribute('aria-current')).toBe('true')
+    await expect.poll(() => options.innerText()).not.toBe(contentBefore)
+    expect(console.pageErrors).toEqual([])
+    expect(console.warnings).toEqual([])
+  })
+
   it('stores Permission as the default for future sessions without changing an existing session', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-settings-permission'))
     const existing = scaffold.ctx.sessions.create(SessionId('settings-permission-before'))
@@ -501,17 +548,20 @@ describe('web e2e: settings modal and General preferences', () => {
     expect(tripwire.pageErrors).toEqual([])
   }, 90_000)
 
-  it('persists the completed-Turn transcript mode across reload', async () => {
+  it.each([
+    ['detailed', '详细'], ['expanded', '完全展开'],
+  ] as const)('persists the %s work-details mode across reload', async (mode, label) => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-settings-transcript-view'))
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const dialog = page.getByRole('dialog', { name: '设置' })
     await dialog.waitFor({ timeout: 10_000 })
-    await dialog.getByText('对话显示', { exact: true }).waitFor({ timeout: 10_000 })
-    await dialog.getByRole('button', { name: '紧凑', exact: true }).click()
-    await page.getByRole('menuitem', { name: '标准', exact: true }).click()
-    await dialog.getByRole('button', { name: '标准', exact: true }).waitFor({ timeout: 10_000 })
+    await dialog.getByText('工作过程展示', { exact: true }).waitFor({ timeout: 10_000 })
+    const details = dialog.getByText('工作过程展示', { exact: true }).locator('../..')
+    await details.getByRole('button', { name: '简洁', exact: true }).click()
+    await page.getByRole('menuitem', { name: label, exact: true }).click()
+    await details.getByRole('button', { name: label, exact: true }).waitFor({ timeout: 10_000 })
     await expect.poll(async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'), { timeout: 5_000 })
-      .toMatch(/ui-chat:\n\s+transcriptView: normal/)
+      .toContain(`transcriptView: ${mode}`)
     await page.keyboard.press('Escape')
 
     const warningStart = tripwire.warnings.length
@@ -520,11 +570,12 @@ describe('web e2e: settings modal and General preferences', () => {
     acknowledgeReloadConnectionLoss(tripwire, warningStart)
     await page.getByRole('button', { name: '设置', exact: true }).click()
     const reloaded = page.getByRole('dialog', { name: '设置' })
-    await reloaded.getByRole('button', { name: '标准', exact: true }).waitFor({ timeout: 10_000 })
+    const restoredDetails = reloaded.getByText('工作过程展示', { exact: true }).locator('../..')
+    await restoredDetails.getByRole('button', { name: label, exact: true }).waitFor({ timeout: 10_000 })
 
-    await reloaded.getByRole('button', { name: '标准', exact: true }).click()
-    await page.getByRole('menuitem', { name: '紧凑', exact: true }).click()
-    await reloaded.getByRole('button', { name: '紧凑', exact: true }).waitFor({ timeout: 10_000 })
+    await restoredDetails.getByRole('button', { name: label, exact: true }).click()
+    await page.getByRole('menuitem', { name: '简洁', exact: true }).click()
+    await restoredDetails.getByRole('button', { name: '简洁', exact: true }).waitFor({ timeout: 10_000 })
     await expect.poll(async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'), { timeout: 5_000 })
       .toMatch(/ui-chat:\n\s+transcriptView: compact/)
     await page.keyboard.press('Escape')
@@ -603,6 +654,7 @@ describe('web e2e: settings modal and General preferences', () => {
     // ...and the attribute follows that switch, in the assembled app.
     await expect.poll(() => page.evaluate(() => document.documentElement.lang), { timeout: 5_000 }).toBe('en')
     expect(await enDialog.getByRole('button', { name: 'General' }).getAttribute('aria-current')).toBe('true')
+    await enDialog.getByText(`Current version: ${version}`, { exact: true }).waitFor()
     await expect.poll(() => enDialog.getByText('Appearance', { exact: true }).count(), { timeout: 5_000 }).toBe(1)
     expect(await page.evaluate(() => localStorage.getItem('dsh.locale'))).toBeNull()
     await expect.poll(async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'), { timeout: 5_000 })
@@ -712,7 +764,8 @@ describe('web e2e: settings modal and General preferences', () => {
       // Golden of the English fallback dialog — the visible output this change
       // produces. The zh golden above covers the detected-locale surface, so
       // the pair pins both directions of the resolution.
-      const snapshot = await captureStableAria(frPage, '[role="dialog"]', fresh.workspaceCwd)
+      await dialog.getByText(`Current version: ${version}`, { exact: true }).waitFor()
+      const snapshot = await captureStableAria(frPage, '[role="dialog"]', fresh.workspaceCwd, versionCapture)
       await compareOrRefreshGolden(DIALOG_EN_EXPECTED, snapshot, MODE)
       expect(frTripwire.pageErrors).toEqual([])
       expect(frTripwire.warnings).toEqual([])
@@ -722,10 +775,31 @@ describe('web e2e: settings modal and General preferences', () => {
     }
   }, 90_000)
 
+  it('hides link-opening settings when the built-in browser is disabled', async () => {
+    const fresh = await launchWebScaffold({
+      developerTools: false,
+      extraOverlayPath: fileURLToPath(new URL('./no-sidebar-browser.overlay.yml', import.meta.url)),
+    })
+    onTestFinished(() => fresh.close())
+    const withoutBrowser = await browser.newPage({ viewport: { width: 1680, height: 1000 }, locale: 'en-US' })
+    onTestFinished(() => withoutBrowser.close())
+    const browserConsole = watchConsole(withoutBrowser)
+    await withoutBrowser.goto(fresh.authenticatedUrl, { waitUntil: 'load' })
+    await withoutBrowser.getByRole('button', { name: 'Settings', exact: true }).click()
+    const dialog = withoutBrowser.getByRole('dialog', { name: 'Settings' })
+    await dialog.getByRole('button', { name: 'Detailed', exact: true }).waitFor()
+    expect(await dialog.getByText('Open chat links in', { exact: true }).count()).toBe(0)
+    const snapshot = await captureStableAria(withoutBrowser, '[role="dialog"]', fresh.workspaceCwd, versionCapture)
+    await compareOrRefreshGolden(join(SNAPSHOT_DIR, 'dialog-no-browser.expected.md'), snapshot, MODE)
+    expect(browserConsole.pageErrors).toEqual([])
+    expect(browserConsole.warnings).toEqual([])
+  })
+
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'dialog-en.expected.md',
+      'dialog-no-browser.expected.md',
       'dialog.expected.md',
       'plugin-instances.expected.md',
       'plugins.expected.md',
diff --git a/apps/web/tests/sidebar-browser.e2e.ts b/apps/web/tests/sidebar-browser.e2e.ts
index 7a3334bb1b..ca26a11a4c 100644
--- a/apps/web/tests/sidebar-browser.e2e.ts
+++ b/apps/web/tests/sidebar-browser.e2e.ts
@@ -29,7 +29,11 @@ describe.skipIf(MODE === 'record')('web e2e: Sidebar Browser', () => {
   let tripwire: ReturnType<typeof watchConsole>
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({ replayFixture: FIXTURE, compareReplaySession: false })
+    scaffold = await launchWebScaffold({
+      replayFixture: FIXTURE,
+      compareReplaySession: false,
+      extraOverlayPath: fileURLToPath(new URL('./sidebar-browser.overlay.yml', import.meta.url)),
+    })
     browser = await chromium.launch()
     page = await newEnglishPage(browser)
     await page.route('https://browser.test/**', async (route) => {
diff --git a/apps/web/tests/sidebar-browser.overlay.yml b/apps/web/tests/sidebar-browser.overlay.yml
new file mode 100644
index 0000000000..66012abfce
--- /dev/null
+++ b/apps/web/tests/sidebar-browser.overlay.yml
@@ -0,0 +1,3 @@
+# Opt in to Browser for its integration scenarios.
+- id: ui-sidebar-browser
+  disabled: false
diff --git a/apps/web/tests/sidebar-right.e2e.ts b/apps/web/tests/sidebar-right.e2e.ts
index 49be02de85..af37b968e1 100644
--- a/apps/web/tests/sidebar-right.e2e.ts
+++ b/apps/web/tests/sidebar-right.e2e.ts
@@ -85,17 +85,24 @@ async function pointIn(locator: Locator, fx: number, fy: number): Promise<{ x: n
   return { x: box.x + box.width * fx, y: box.y + box.height * fy }
 }
 
-/** Pause the panel's next real transform transition after observing its initial frame geometry. */
+/** Select panes by CSS column; retained tab hosts keep their independent DOM order. */
+function paneAt(column: Locator, index: number): Locator {
+  return column.locator(`[data-dockkit-pane][data-dockkit-column="${index}"]`)
+}
+
+/** Pause a docked host's next real transform transition at its midpoint. */
 async function holdPanelSlide(panel: Locator) {
   return await panel.evaluateHandle((node) => {
     const controller = new AbortController()
     const state = { animation: null as Animation | null, columnsAtStart: '', dispose: () => { controller.abort() } }
     node.addEventListener('transitionrun', (event) => {
-      if (event.target !== node || (event as TransitionEvent).propertyName !== 'transform') return
+      const target = event.target
+      if (!(target instanceof Element) || !target.matches('[data-dockkit-host="dock"]')
+        || (event as TransitionEvent).propertyName !== 'transform') return
       const frame = node.closest('[style*="grid-template-columns"]')
       if (frame === null) throw new Error('panel frame is unavailable')
       state.columnsAtStart = getComputedStyle(frame).gridTemplateColumns
-      const slide = node.getAnimations().find(animation =>
+      const slide = target.getAnimations().find(animation =>
         'transitionProperty' in animation && animation.transitionProperty === 'transform')
       if (slide === undefined || slide.effect === null) throw new Error('panel transform transition is unavailable')
       slide.pause()
@@ -409,7 +416,8 @@ describe('web e2e: shipped right Sidebar', () => {
       }
 
       await expect.poll(async () => await tabTitles(column)).toEqual(['Start'])
-      await expect.poll(async () => await column.locator('[data-sidebar-right-guide-entry]').count()).toBe(3)
+      await expect.poll(async () => await column.locator('[data-sidebar-right-guide-entry]').count()).toBe(2)
+      expect(await column.locator('[data-sidebar-right-guide-entry="browser"]').count()).toBe(0)
       await column.locator('[data-sidebar-right-guide-entry="files"]').click()
 
       // A manual guide is closable beside Files and suppresses another add
@@ -493,7 +501,9 @@ describe('web e2e: shipped right Sidebar', () => {
       await expect.poll(() => panel.boundingBox()).toEqual({ x: 0, y: 0, ...viewport })
       await column.locator('[data-sidebar-right-toggle]').click()
       await Promise.all([
-        panel.evaluate(async (node) => { await Promise.allSettled(node.getAnimations().map(animation => animation.finished)) }),
+        panel.evaluate(async (node) => {
+          await Promise.allSettled(node.getAnimations({ subtree: true }).map(animation => animation.finished))
+        }),
         frame.evaluate(async (node) => { await Promise.allSettled(node.getAnimations().map(animation => animation.finished)) }),
       ])
       const closedColumns = (await geometry()).columns
@@ -506,7 +516,7 @@ describe('web e2e: shipped right Sidebar', () => {
       try {
         await expandOf(page).click()
         await expect.poll(() => held.evaluate(state => state.animation?.playState)).toBe('paused')
-        const entering = await panel.boundingBox()
+        const entering = await paneAt(column, 0).boundingBox()
         if (entering === null) throw new Error('entering panel is not rendered')
         expect(entering.x).toBeGreaterThan(0)
         expect(entering.x).toBeLessThan(viewport.width)
@@ -524,7 +534,7 @@ describe('web e2e: shipped right Sidebar', () => {
           await column.locator('[data-sidebar-right-toggle]').click()
           await expect.poll(() => exit.evaluate(state => state.animation?.playState)).toBe('paused')
           expect(await exit.evaluate(state => state.columnsAtStart)).toBe(closedColumns)
-          const leaving = await panel.boundingBox()
+          const leaving = await paneAt(column, 0).boundingBox()
           if (leaving === null) throw new Error('leaving panel is not rendered')
           expect(leaving.x).toBeGreaterThan(0)
           expect(leaving.x).toBeLessThan(viewport.width)
@@ -718,7 +728,7 @@ describe('web e2e: shipped right Sidebar', () => {
       onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-content'))
       const column = page.locator('[data-rightbar-col]')
       const panes = column.locator('[data-dockkit-pane]')
-      const floats = page.locator('[data-sidebar-right-float-host] [data-dockkit-float]')
+      const floats = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]')
 
       // Observation before action: does the read ever leave the browser? The
       // assertion states the healthy answer so a failure prints the real one.
@@ -750,7 +760,7 @@ describe('web e2e: shipped right Sidebar', () => {
       await expect.poll(async () => await tabTitles(column)).toEqual(['Files', SAMPLE_NAME])
 
       // Opening the same content again focuses rather than duplicating.
-      await panes.first().locator('[data-dockkit-tab]').first().click()
+      await paneAt(column, 0).locator('[data-dockkit-tab]').first().click()
       await chip.click()
       await expect.poll(async () => await tabTitles(column)).toEqual(['Files', SAMPLE_NAME])
 
@@ -775,20 +785,20 @@ describe('web e2e: shipped right Sidebar', () => {
       expect(await folders.count()).toBe(await page.locator('[data-changed-files]').getByRole('button', { name: /folder/i }).count())
 
       // Split, then dock-drag: the kit's gestures drive the store's actions.
-      await panes.first().locator('[data-dockkit-split-button]').click()
+      await paneAt(column, 0).locator('[data-dockkit-split-button]').click()
       await expect.poll(async () => await panes.count()).toBe(2)
       await dragTo(
         page,
         column.locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME }).first(),
-        await pointIn(panes.nth(1), 0.5, 0.94),
+        await pointIn(paneAt(column, 1), 0.5, 0.94),
       )
       await expect.poll(async () => await panes.count()).toBe(2)
 
-      const splitGuide = panes.nth(1).locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
+      const splitGuide = paneAt(column, 1).locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
       expect(await splitGuide.locator('[data-dockkit-tab-close]').count()).toBe(1)
-      await dragTo(page, splitGuide, await pointIn(panes.first(), 0.5, 0.5))
-      await expect.poll(async () => await tabTitles(panes.nth(1))).toEqual([SAMPLE_NAME])
-      const movedGuide = panes.first().locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
+      await dragTo(page, splitGuide, await pointIn(paneAt(column, 0), 0.5, 0.5))
+      await expect.poll(async () => await tabTitles(paneAt(column, 1))).toEqual([SAMPLE_NAME])
+      const movedGuide = paneAt(column, 0).locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
       await movedGuide.hover()
       await movedGuide.locator('[data-dockkit-tab-close]').click()
 
@@ -797,12 +807,15 @@ describe('web e2e: shipped right Sidebar', () => {
       await expect.poll(async () => await filePane.locator('[data-dockkit-add-tab]').count()).toBe(1)
       expect(await column.locator('[data-dockkit-add-tab]').count()).toBe(2)
 
-      // Floating leaves the column entirely, and survives collapsing it. The
-      // pane the tab was alone in goes with it: an emptied pane never stays.
+      // A float stays in the DOM column but draws outside it and survives collapse.
       const tab = column.locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME }).first()
       await floatByDrag(page, tab)
       await expect.poll(async () => await floats.count()).toBe(1)
-      expect(await column.locator('[data-dockkit-float]').count()).toBe(0)
+      expect(await column.locator('[data-dockkit-float]').count()).toBe(1)
+      const floatBox = await floats.first().boundingBox()
+      const columnBox = await column.boundingBox()
+      if (floatBox === null || columnBox === null) throw new Error('float or column is not rendered')
+      expect(floatBox.x).toBeLessThan(columnBox.x)
       await expect.poll(async () => await panes.count()).toBe(1)
       await shot(page, '04-split-and-float')
 
@@ -890,7 +903,7 @@ describe('web e2e: shipped right Sidebar', () => {
       onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-right-gestures'))
       const column = await resetSidebar(page)
       const panes = column.locator('[data-dockkit-pane]')
-      const floats = page.locator('[data-sidebar-right-float-host] [data-dockkit-float]')
+      const floats = page.locator('[data-sidebar-right-session]:not([hidden]) [data-dockkit-float]')
 
       // Chromium cancels pointer capture if a render replaces the pressed
       // element; jsdom cannot establish that the whole gesture survives.
@@ -898,7 +911,7 @@ describe('web e2e: shipped right Sidebar', () => {
       // 1. Reorder inside one strip: drop the last tab left of its neighbours.
       //    The first pane needs two tabs for this — and for the move below to
       //    leave it standing, since a pane emptied by a move is dropped.
-      const first = panes.first()
+      const first = paneAt(column, 0)
       const strip = first.locator('[data-dockkit-strip]')
       await proseChip(page).click()
       await expect.poll(async () => await tabTitles(first)).toEqual(['Files', SAMPLE_NAME])
@@ -917,8 +930,8 @@ describe('web e2e: shipped right Sidebar', () => {
       }
       const moving = first.locator('[data-dockkit-tab]').first()
       const title = await moving.locator('[data-dockkit-tab-title]').innerText()
-      await dragTo(page, moving, await pointIn(panes.nth(1), 0.5, 0.5))
-      await expect.poll(async () => await tabTitles(panes.nth(1))).toContain(title)
+      await dragTo(page, moving, await pointIn(paneAt(column, 1), 0.5, 0.5))
+      await expect.poll(async () => await tabTitles(paneAt(column, 1))).toContain(title)
 
       const splitButtons = column.locator('[data-dockkit-split-button]')
       await expect.poll(async () => await splitButtons.count()).toBe(0)
@@ -927,14 +940,14 @@ describe('web e2e: shipped right Sidebar', () => {
       await expect.poll(async () => await splitButtons.count()).toBe(0)
 
       const outer = column.locator('[data-dockkit-divider]').first()
-      const before = await width(panes.last())
+      const before = await width(paneAt(column, 1))
       const grip = await centre(outer)
       await dragElement(page, outer, { x: grip.x - 100, y: grip.y })
-      await expect.poll(async () => await width(panes.last())).toBeGreaterThan(before)
+      await expect.poll(async () => await width(paneAt(column, 1))).toBeGreaterThan(before)
       await dragElement(page, outer, { x: 0, y: grip.y })
       const ratio = async (): Promise<number> => {
-        const left = await width(panes.first())
-        const right = await width(panes.last())
+        const left = await width(paneAt(column, 0))
+        const right = await width(paneAt(column, 1))
         return left / (left + right)
       }
       await expect.poll(ratio).toBeCloseTo(0.2, 2)
@@ -946,7 +959,7 @@ describe('web e2e: shipped right Sidebar', () => {
       expect(await splitButtons.count()).toBe(0)
 
       // 5. The split's guide and the document float while Files stays docked.
-      const floatOne = panes.last().locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME })
+      const floatOne = paneAt(column, 1).locator('[data-dockkit-tab]').filter({ hasText: SAMPLE_NAME })
       await floatByDrag(page, floatOne)
       await expect.poll(async () => await floats.count()).toBe(1)
       const box = await floats.first().boundingBox()
@@ -954,8 +967,8 @@ describe('web e2e: shipped right Sidebar', () => {
       await dragElement(page, floats.first().locator('[data-dockkit-float-grip]'), { x: box.x + 140, y: box.y + 90 })
       await expect.poll(async () => (await floats.first().boundingBox())?.x ?? box.x).not.toBe(box.x)
 
-      await expect.poll(async () => await tabTitles(panes.last())).toEqual(['Start'])
-      const second = panes.last().locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
+      await expect.poll(async () => await tabTitles(paneAt(column, 1))).toEqual(['Start'])
+      const second = paneAt(column, 1).locator('[data-dockkit-tab]').filter({ hasText: 'Start' })
       await floatByDrag(page, second)
       await expect.poll(async () => await floats.count()).toBe(2)
 
@@ -975,14 +988,14 @@ describe('web e2e: shipped right Sidebar', () => {
       const panes = column.locator('[data-dockkit-pane]')
       expect(await column.locator('[data-dockkit-tab-close]').count()).toBe(1)
       await proseChip(page).click()
-      await expect.poll(async () => await tabTitles(panes.first())).toEqual(['Files', SAMPLE_NAME])
-      await panes.first().locator('[data-dockkit-split-button]').click()
+      await expect.poll(async () => await tabTitles(paneAt(column, 0))).toEqual(['Files', SAMPLE_NAME])
+      await paneAt(column, 0).locator('[data-dockkit-split-button]').click()
       await expect.poll(async () => await panes.count()).toBe(2)
 
       // Closing a pane's last tab drops the pane: there is no separate
       // "close pane" gesture, and none is needed.
-      await panes.nth(1).locator('[data-dockkit-tab]').first().hover()
-      await panes.nth(1).locator('[data-dockkit-tab-close]').first().click()
+      await paneAt(column, 1).locator('[data-dockkit-tab]').first().hover()
+      await paneAt(column, 1).locator('[data-dockkit-tab-close]').first().click()
       await expect.poll(async () => await panes.count()).toBe(1)
       await expect.poll(async () => await tabTitles(column)).toEqual(['Files', SAMPLE_NAME])
 
diff --git a/apps/web/tests/sidebar-title-hover-scroll.e2e.ts b/apps/web/tests/sidebar-title-hover-scroll.e2e.ts
index 2a0fe8caf4..5f797f19e2 100644
--- a/apps/web/tests/sidebar-title-hover-scroll.e2e.ts
+++ b/apps/web/tests/sidebar-title-hover-scroll.e2e.ts
@@ -1,9 +1,10 @@
-// Web e2e scenario: hovering a sidebar session row reveals a title wider than
-// its cell. The jsdom lane pins only the scroll position the handler writes;
-// the assembled browser is where the title really clips, really reaches its own
-// hovered extent (the trailing relative-time cell yields to the row menu while
-// the pointer rests on the row, so the hovered cell is wider than the resting
-// one), and really returns to its start when the pointer leaves.
+// Web e2e scenario: hovering a sidebar session row marquees a title wider than
+// its cell. The jsdom lane pins only the positions the handler writes; the
+// assembled browser is where the title really clips, really crawls toward its
+// own hovered extent (the trailing relative-time cell yields to the row menu
+// while the pointer rests on the row, so the hovered cell is wider than the
+// resting one), really fades its moved left edge, and really returns to its
+// start when the pointer leaves.
 //
 // Zero model calls: seeding one renamed session and hovering its row touches no
 // provider.
@@ -16,10 +17,10 @@ import { launchWebScaffold, seedSession, watchConsole, type WebScaffold } from '
 import { newEnglishPage, saveFailureShot } from './support.ts'
 
 const SEED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/session.v3.jsonl', import.meta.url))
-/** Wider than the sidebar cell, under the 80-byte title limit, with a far-edge suffix the reveal must reach. */
+/** Wider than the sidebar cell, under the 80-byte title limit, with a far-edge suffix the marquee must reach. */
 const TITLE = 'Forked session clipped before its suffix (1)'
 
-describe('web e2e: hovering a clipped session title scrolls it to its far edge', () => {
+describe('web e2e: hovering a clipped session title marquees it to its far edge', () => {
   let scaffold: WebScaffold
   let browser: Browser
   let page: Page
@@ -43,7 +44,7 @@ describe('web e2e: hovering a clipped session title scrolls it to its far edge',
     await scaffold?.close()
   })
 
-  it('reveals the clipped title under the pointer and restores its start after', async () => {
+  it('crawls the clipped title under the pointer and restores its start after', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-title-hover-scroll'))
     const row = page.getByRole('treeitem').filter({ has: page.getByText(TITLE, { exact: true }) })
     await row.waitFor({ timeout: 20_000 })
@@ -53,34 +54,56 @@ describe('web e2e: hovering a clipped session title scrolls it to its far edge',
     expect(await title.evaluate(el => el.scrollWidth - el.clientWidth)).toBeGreaterThan(0)
     expect(await title.evaluate(el => getComputedStyle(el).textOverflow)).toBe('ellipsis')
     expect(await title.evaluate(el => el.scrollLeft)).toBe(0)
-    expect(await title.evaluate(el => getComputedStyle(el).scrollBehavior)).toBe('smooth')
 
     await row.hover()
-    // Poll against the live extent: the reveal must reach the far edge of the
-    // hovered cell (the wider one — the relative-time label yields to the row
-    // menu), whatever width the handler itself read.
+    // The marquee crawls instead of jumping: the title is caught mid-travel,
+    // strictly between its start and its far edge, with both cut edges
+    // publishing their fade-mask hooks.
+    await expect.poll(
+      async () => title.evaluate(el => el.scrollLeft > 0),
+      { timeout: 5_000 },
+    ).toBe(true)
+    expect(await title.evaluate(el => el.scrollLeft < el.scrollWidth - el.clientWidth - 1)).toBe(true)
+    expect(await title.evaluate(el => el.hasAttribute('data-scrolled'))).toBe(true)
+    expect(await title.evaluate(el => el.hasAttribute('data-clipped'))).toBe(true)
+    expect(await title.evaluate(el => getComputedStyle(el).maskImage)).toContain('linear-gradient')
+    // The crawl still reaches the far edge of the hovered cell (the wider
+    // one — the relative-time label yields to the row menu) and rests there,
+    // lifting the right fade so the final character reads at full strength.
+    // The fade lifts on the frame that lands exactly on the far edge, one or
+    // two frames after scrollLeft first rounds within a pixel of it.
     await expect.poll(
       async () => title.evaluate(el => el.scrollLeft >= el.scrollWidth - el.clientWidth - 1),
-      { timeout: 10_000 },
+      { timeout: 20_000 },
     ).toBe(true)
-    // Scrolled to its end, the title must not paint the ellipsis over the
-    // characters the reveal reached.
+    await expect.poll(
+      async () => title.evaluate(el => el.hasAttribute('data-clipped')),
+      { timeout: 5_000 },
+    ).toBe(false)
+    // At its extent, the title must not paint the ellipsis over the
+    // characters the marquee reached.
     expect(await title.evaluate(el => getComputedStyle(el).textOverflow)).toBe('clip')
 
-    // Leaving returns in one step: a smooth return would still be travelling
-    // inside this window, and it would carry the resting ellipsis back with it.
+    // Leaving returns in one step: a crawl back would still be travelling
+    // inside this window, and it would carry the resting ellipsis with it.
     await page.mouse.move(0, 0)
     await expect.poll(
       async () => title.evaluate(el => el.scrollLeft),
       { timeout: 150, interval: 20 },
     ).toBe(0)
+    expect(await title.evaluate(el => el.hasAttribute('data-scrolled'))).toBe(false)
     expect(await title.evaluate(el => getComputedStyle(el).textOverflow)).toBe('ellipsis')
 
-    // The reduce override reaches the real stylesheet, so the reveal jumps
-    // instead of gliding.
+    // Reduced motion reaches the handler's matchMedia probe: the reveal jumps
+    // to the far edge instead of crawling.
     await page.emulateMedia({ reducedMotion: 'reduce' })
-    expect(await title.evaluate(el => getComputedStyle(el).scrollBehavior)).toBe('auto')
+    await row.hover()
+    await expect.poll(
+      async () => title.evaluate(el => el.scrollLeft >= el.scrollWidth - el.clientWidth - 1),
+      { timeout: 500, interval: 20 },
+    ).toBe(true)
+    await page.mouse.move(0, 0)
     await page.emulateMedia({ reducedMotion: null })
     expect(tripwire.pageErrors).toEqual([])
-  }, 60_000)
+  }, 90_000)
 })
diff --git a/apps/web/tests/skill-tool-row.e2e.ts b/apps/web/tests/skill-tool-row.e2e.ts
index 628803ad48..1b6a9e7f10 100644
--- a/apps/web/tests/skill-tool-row.e2e.ts
+++ b/apps/web/tests/skill-tool-row.e2e.ts
@@ -8,11 +8,12 @@ import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
 import {
   assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
-  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+  launchWebScaffold, seedSession, selectedSessionFixture, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { expandOwningTurnProcess, newEnglishPage, saveFailureShot } from './support.ts'
 
-const FIXTURE = fileURLToPath(new URL('../../../snapshots/session/skill-load/session.v3.jsonl', import.meta.url))
+// Any generation path names the role; the owner's highest committed generation replays.
+const FIXTURE = fileURLToPath(new URL('../../../snapshots/session/skill-load/session.v4.jsonl', import.meta.url))
 const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/skill-tool-row', import.meta.url))
 const UI_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/skill-tool-row/ui.expected.md', import.meta.url))
 const MODE = webSnapshotMode()
@@ -26,7 +27,7 @@ describe.skipIf(MODE === 'record')('web e2e: dedicated Skill tool row', () => {
   let tripwire: ReturnType<typeof watchConsole>
 
   beforeAll(async () => {
-    const fixture = await readFile(FIXTURE, 'utf8')
+    const fixture = await readFile(await selectedSessionFixture(FIXTURE), 'utf8')
     expect(fixtureUserPrompts(fixture)).toEqual([PROMPT])
     scaffold = await launchWebScaffold({})
     await seedSession(scaffold, fixture, SEED_ID)
diff --git a/apps/web/tests/snapshots/live-job-stream/settled.expected.md b/apps/web/tests/snapshots/live-job-stream/settled.expected.md
new file mode 100644
index 0000000000..ada83b7f3e
--- /dev/null
+++ b/apps/web/tests/snapshots/live-job-stream/settled.expected.md
@@ -0,0 +1,6 @@
+- list "Background jobs":
+  - listitem:
+    - button "Hide live output of printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done" [expanded]: "bash printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done signal: SIGTERM; web e2e cancellation {{duration}}"
+    - text: $ printf 'streamed-%s\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done
+    - button "Copy"
+    - text: streamed-marker-line
diff --git a/apps/web/tests/snapshots/live-job-stream/streaming.expected.md b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md
new file mode 100644
index 0000000000..566aea30c0
--- /dev/null
+++ b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md
@@ -0,0 +1,6 @@
+- list "Background jobs":
+  - listitem:
+    - button "Hide live output of printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done" [expanded]: printf 'streamed-%s\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done {{duration}} bash running
+    - text: $ printf 'streamed-%s\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done
+    - button "Copy"
+    - text: streamed-marker-line
diff --git a/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md b/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md
index 27e4c283ae..19c2becc76 100644
--- a/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md
+++ b/apps/web/tests/snapshots/streaming-fence-highlight/mid-stream.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Stream one TypeScript fence for the highlighting snapshot. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/apps/web/tests/turn-tail-actions.e2e.ts b/apps/web/tests/turn-tail-actions.e2e.ts
index 7ea13e1c9c..f4f33e8f1d 100644
--- a/apps/web/tests/turn-tail-actions.e2e.ts
+++ b/apps/web/tests/turn-tail-actions.e2e.ts
@@ -232,7 +232,9 @@ describe('web e2e: assistant IconActions wait for the turn to end', () => {
     expect(tripwire.warnings).toEqual([])
   }, 60_000)
 
-  it.skipIf(MODE === 'record')('switches a completed Turn between Compact and Normal', async () => {
+  it.skipIf(MODE === 'record').each([
+    ['detailed', 'Detailed'], ['expanded', 'Expanded'],
+  ] as const)('preserves whole-Turn folding in %s mode', async (mode, label) => {
     await launch()
     onTestFailed(() => saveFailureShot(page, 'web-e2e-turn-process-setting'))
     const { settled } = await sendPrompt()
@@ -245,18 +247,21 @@ describe('web e2e: assistant IconActions wait for the turn to end', () => {
 
     await page.getByRole('button', { name: 'Settings', exact: true }).click()
     const dialog = page.getByRole('dialog', { name: 'Settings' })
-    await dialog.getByRole('button', { name: 'Compact', exact: true }).click()
-    await page.getByRole('menuitem', { name: 'Normal', exact: true }).click()
+    await dialog.getByText('Work details', { exact: true }).locator('../..')
+      .getByRole('button', { name: 'Compact', exact: true }).click()
+    await page.getByRole('menuitem', { name: label, exact: true }).click()
     await page.keyboard.press('Escape')
 
-    await expect.poll(() => process.count(), { timeout: 10_000 }).toBe(0)
-    await tool.waitFor({ state: 'visible', timeout: 10_000 })
+    expect(await process.count()).toBe(1)
+    expect(await process.getAttribute('aria-expanded')).toBe('false')
+    expect(await tool.isVisible()).toBe(false)
     await expect.poll(async () => readFile(join(scaffold!.harnessHome, 'settings.yaml'), 'utf8'), { timeout: 5_000 })
-      .toMatch(/ui-chat:\n\s+transcriptView: normal/)
+      .toContain(`transcriptView: ${mode}`)
 
     await page.getByRole('button', { name: 'Settings', exact: true }).click()
     const restored = page.getByRole('dialog', { name: 'Settings' })
-    await restored.getByRole('button', { name: 'Normal', exact: true }).click()
+    await restored.getByText('Work details', { exact: true }).locator('../..')
+      .getByRole('button', { name: label, exact: true }).click()
     await page.getByRole('menuitem', { name: 'Compact', exact: true }).click()
     await page.keyboard.press('Escape')
     await process.waitFor({ timeout: 10_000 })
diff --git a/apps/web/tests/workspace-new-session-folding.e2e.ts b/apps/web/tests/workspace-new-session-folding.e2e.ts
index 21bdd58871..e23e0e9a80 100644
--- a/apps/web/tests/workspace-new-session-folding.e2e.ts
+++ b/apps/web/tests/workspace-new-session-folding.e2e.ts
@@ -22,7 +22,7 @@ const EXPECTED_DIR = fileURLToPath(new URL('./expected/workspace-new-session-fol
 const SIDEBAR_EXPECTED = join(EXPECTED_DIR, 'sidebar.expected.md')
 const SEED = fileURLToPath(new URL('../../../snapshots/web/message-feedback-protocol/session.v3.jsonl', import.meta.url))
 const MODE = webSnapshotMode()
-const EXISTING_SESSION_COUNT = 6
+const EXISTING_SESSION_COUNT = 16
 
 describe('web e2e: blank New Session folding quota', () => {
   let scaffold: WebScaffold
@@ -72,7 +72,7 @@ describe('web e2e: blank New Session folding quota', () => {
     await expect.poll(() => sidebar.getByRole('treeitem').count(), { timeout: 15_000 }).toBe(7)
     expect(await sidebar.getByText('New Session', { exact: true }).count()).toBe(1)
     expect(await sidebar.getByText(basename(scaffold.workspaceCwd), { exact: true }).count()).toBe(6)
-    const showMore = sidebar.getByRole('button', { name: 'Show 1 more sessions' })
+    const showMore = sidebar.getByRole('button', { name: 'Show 11 more sessions' })
     await showMore.waitFor({ timeout: 15_000 })
     await compareOrRefreshGolden(
       SIDEBAR_EXPECTED,
@@ -81,11 +81,20 @@ describe('web e2e: blank New Session folding quota', () => {
     )
 
     await showMore.click()
-    await expect.poll(() => sidebar.getByRole('treeitem').count(), { timeout: 10_000 }).toBe(8)
-    expect(await sidebar.getByText(basename(scaffold.workspaceCwd), { exact: true }).count()).toBe(7)
+    await expect.poll(() => sidebar.getByRole('treeitem').count(), { timeout: 10_000 }).toBe(12)
+    expect(await sidebar.getByText(basename(scaffold.workspaceCwd), { exact: true }).count()).toBe(11)
+    await compareOrRefreshGolden(
+      join(EXPECTED_DIR, 'first-batch.expected.md'),
+      await captureStableAria(page, '[role="tree"][aria-label="Sessions"]', scaffold.workspaceCwd),
+      MODE,
+    )
+    await sidebar.getByRole('button', { name: 'Show 6 more sessions' }).click()
+    await expect.poll(() => sidebar.getByRole('treeitem').count()).toBe(17)
+    await sidebar.getByRole('button', { name: 'Show 1 more sessions' }).click()
+    await expect.poll(() => sidebar.getByRole('treeitem').count()).toBe(18)
     await sidebar.getByRole('button', { name: 'Show less' }).click()
     await expect.poll(() => sidebar.getByRole('treeitem').count()).toBe(7)
-    await assertFixtureInventory(EXPECTED_DIR, ['sidebar.expected.md'])
+    await assertFixtureInventory(EXPECTED_DIR, ['sidebar.expected.md', 'first-batch.expected.md'])
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
   })
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 4508e03def..30e2d212b5 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -44,12 +44,14 @@
     "tests/chat-scroll-fixture.ts",
     "tests/trajectory-virtualization.e2e.ts",
     "tests/lifecycle-chrome.e2e.ts",
+    "tests/reasoning-preview.e2e.ts",
     "tests/details-session-lifecycle.e2e.ts",
     "tests/sessionless-header.e2e.ts",
     "tests/document-preview.e2e.ts",
     "tests/office-fixture.ts",
     "tests/sidebar-browser.e2e.ts",
     "tests/plugin-config.e2e.ts",
+    "tests/input-plugin-extensions.e2e.ts",
     "tests/plugin-manager.e2e.ts",
     "tests/plugin-install-cancel.e2e.ts",
     "tests/plugin-install-approve.e2e.ts",
@@ -63,6 +65,8 @@
     "tests/deepseek-messages-chat.e2e.ts",
     "tests/models-settings-recovery.e2e.ts",
     "tests/default-model.e2e.ts",
+    "tests/default-workspace.e2e.ts",
+    "tests/new-session-refused.e2e.ts",
     "tests/github-ready-review.e2e.ts",
     "tests/streaming-fence-highlight.e2e.ts",
     "tests/declared-reasoning.e2e.ts",
@@ -132,6 +136,7 @@
     "tests/subagent-interrupt-ui.e2e.ts",
     "tests/sidebar-subagent-activity.e2e.ts",
     "tests/background-job-list.e2e.ts",
+    "tests/live-job-stream.e2e.ts",
     "tests/auto-review-denial.e2e.ts",
     "tests/bash-abort-row.e2e.ts",
     "tests/skill-tool-row.e2e.ts",
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index ddf3683c59..9984bf38de 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -10,7 +10,7 @@ import { productWebBundleIsolation } from './product-isolation.ts'
 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` together with `pnpm run dev:web`.'
+  + 'For client-plugin HMR, run `pnpm run dev:web`, which starts `dsh web` and the rebuild watchers together.'
 const DEFAULT_CLIENT_TITLE = 'DSH Local Build'
 
 /** Escape build-time text before placing it in the HTML title element. */
diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml
index fa62039df7..e11ee881f4 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: 2cf7b2f345991fd20639e1294662cc64fc02093d
-api-gateway.zh.md: 5b80db08de49591b27751e187aa6278384a7444e
+api-gateway.md: 957f40775857d8f57af436a44690fd5a453aeeae
+api-gateway.zh.md: 1062adcc89909d5ce3701ac82b55c5d0ece21ab0
diff --git a/docs/api-gateway.md b/docs/api-gateway.md
index 2cf7b2f345..957f407758 100644
--- a/docs/api-gateway.md
+++ b/docs/api-gateway.md
@@ -2,7 +2,7 @@
 
 English | [中文](api-gateway.zh.md)
 
-This is the current-state reference for the Typert API Gateway. It describes how business services declare unary Remote methods, how the build generates Host and Client contracts, and how calls reuse the Connection RPC and `/api` route. Session events, incremental data, and other streaming protocols are outside this document's scope; they may use the same Connection but do not use Remote method descriptors.
+This is the current-state reference for the Typert API Gateway. It describes how business services declare unary and stream Remote methods, how the build generates Host and Client contracts, and how calls reuse the Connection RPC and `/api` route. Session events, incremental data, and other streaming protocols are outside this document's scope; they may use the same Connection but do not use Remote method descriptors.
 
 ## Programming model
 
@@ -55,6 +55,8 @@ export class GoalService extends TypertRemoteService {
 
 Remote methods may return a value synchronously or return a Promise. For cooperative cancellation, the final parameter in the Host signature must be `signal: AbortSignal` using the global type; it is recorded in the descriptor instead of entering `args`, while the generated Client method accepts an optional final `AbortSignal`.
 
+`@Remote({ mode: 'stream' })` marks a method that returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out, In>`: the Gateway delivers each yielded item, a value the Host method produced, over its multiplexed `/api/remote.mux` WebSocket or an in-process carrier, and the generated Client method returns a `RemoteStreamHandle<Out, In>` that iterates the items and exposes `send`, `end`, and `dispose` for the Client-to-Host uplink of the same logical stream. The second type argument of `RemoteStream<Out, In>` declares the uplink item type; the Gateway validates each item the Client sends, because it arrives from the browser, with the generated `In` codec before the Host method reads it through `this.ctx.invocation.uplink<In>()`. The uplink enters neither `args` nor the parameter list; the [Gateway README](../packages/api/gateway/README.md) owns the frame, half-close, cancellation, and inbox-bound contracts.
+
 The Client uses concrete functions on ordinary objects, not a JavaScript Proxy. Direct and scoped calls appear under `ctx.remote.<namespace>` and `agentCtx.remote.<namespace>`. Each namespace is a traced Cordis child Service registered as `remote.<namespace>`; the Client assembly mounts contributions through `ctx.remote.$mount()`, and the namespace unloads after its last method is withdrawn. Dependency declarations belong to the actual caller: only a business package that reads `ctx.remote.<namespace>` or `agentCtx.remote.<namespace>` declares both `remote` and `remote.<namespace>` in its own `inject`; assemblies that only mount contributions and higher-level runtimes that do not call that namespace do not declare the namespace dependency on the business package's behalf. When an `@Remote` method has exactly one lookup parameter and a same-named `TypertContextMap` uses the same wire identity, the generated scoped signature omits that identity parameter. `@RemoteScope` generates only the scoped invocation interface.
 
 ```ts ignore-check
@@ -120,9 +122,9 @@ Strict analysis requires a Remote to be a public, non-static instance method wit
 
 Remote calls use the Connection's `/api` route. The Client Remote calls `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`; the HTTP carrier maps this to `POST /api/<namespace>/<method>`, with a payload containing only a named `args` object.
 
-The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; feature-owned exact Fetch routes handle non-JSON responses, and other requests return 404. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface.
+The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; it projects binary Remote fields into JSON-compatible metadata and result-relative byte attachments, which Connection frames as multipart responses. Feature-owned exact Fetch routes handle responses outside the RPC envelope, and other requests return 404. Connection owns transport, RPC ids, response envelopes, and request cancellation, while Gateway owns the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface.
 
-For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code.
+For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, and invokes the service method targeted by the binding. The Client Gateway validates decoded binary results with the generated result codec; ordinary JSON results retain their existing handling. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code.
 
 The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `gateway/lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard resolver semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. A resume failure and an ownership fence raise a `RemoteError` carrying their own code, `session/not-found` or `session/agent-busy`, which the Gateway encodes onto the wire unchanged; only an unclassified throw folds into `gateway/internal`.
 
@@ -138,14 +140,13 @@ SRC solves only dispatch for a Host process running from source. The Client does
 
 ## Development mode
 
-Web development prepares current Host, Client, and Web artifacts with `pnpm run build`, then runs the source Host and the Client plugin watcher in separate terminals:
+Web development runs one command, which builds current Host, Client, and Web artifacts, starts the source Host, and keeps Client bundles rebuilt:
 
 ```sh
-pnpm dsh web
 pnpm run dev:web
 ```
 
-`dsh` starts the Host source through tsx, so the Host can use the SRC fallback; `dev:web` watches only Client plugins with a `dsh.client` declaration and rewrites their `lib/client.js`. It does not analyze Host decorators or generate Remote Client DTS.
+`dsh` starts the Host source through tsx, so the Host can use the SRC fallback; the `dev:web` watchers rebuild the client-face type emit, Client plugin and library bundles, and the Web shell on source edits. They do not analyze Host decorators or generate Remote Client DTS; only the complete build that `dev:web` runs first (or `pnpm run build`) does.
 
 Changing only a Remote method's implementation body without changing its contract does not require regenerating the Typert files. After adding or removing a decorator or changing an export name, namespace, parameter, return value, lookup, Context, or cancellation signature, rerun the ordered lib build so the Host generates the strict contract before the Client compiles and bundles the new contribution:
 
@@ -157,8 +158,8 @@ The running Client watcher consumes these generated files when it rebundles. If
 
 ## Boundaries
 
-Remote handles only unary method calls with one request and one result. Session event streams, pagination, incremental reduce, projection, and entity substreams require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
+Remote handles unary method calls with one request and one result, and stream methods whose items flow Host → Client while the Client's items reach the running Host method through `this.ctx.invocation.uplink()`. Session event streams, pagination, incremental reduce, projection, and entity substreams still require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors.
 
-The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and Typert RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. A feature that needs a streamed or browser-native response registers an exact Connection Fetch route instead of defining a Remote method.
+The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and Typert RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. Unary results containing `Uint8Array`, including nested fields and array entries, use [binary Remote transfer](../.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md). A feature that needs a response outside the RPC envelope registers an exact Connection Fetch route.
 
 Lookup policy is configured per key, so all `agent` or `session` parameters share the cold-resume behavior. Accepting live objects only would require an explicit per-parameter or per-endpoint policy, which does not exist; the business method must not guess whether the object came from restoration.
diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md
index 5b80db08de..1062adcc89 100644
--- a/docs/api-gateway.zh.md
+++ b/docs/api-gateway.zh.md
@@ -2,7 +2,7 @@
 
 [English](api-gateway.md) | 中文
 
-本文是 Typert API Gateway 的当前状态参考。它描述业务服务如何声明一元 Remote 方法、构建如何生成 Host 与 Client 约定，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
+本文是 Typert API Gateway 的当前状态参考。它描述业务服务如何声明一元与流式 Remote 方法、构建如何生成 Host 与 Client 约定，以及调用如何复用 Connection 的 RPC 与 `/api` 路由。会话事件、增量数据和其他流协议不属于本文范围；它们可以使用同一个 Connection，但不使用 Remote 方法描述符。
 
 ## 编程模型
 
@@ -55,6 +55,8 @@ export class GoalService extends TypertRemoteService {
 
 Remote 方法可以同步返回或返回 Promise。若需要协作式取消，Host 签名的最后一个参数必须是全局类型的 `signal: AbortSignal`；它记录在描述符中而不是进入 `args`，Client 生成的方法则接受最后一个可选的 `AbortSignal`。
 
+`@Remote({ mode: 'stream' })` 标记返回 `Iterable`、`AsyncIterable` 或 `RemoteStream<Out, In>` 的方法：Gateway 把每个产出的项（Host 方法产出的值）经其多路复用的 `/api/remote.mux` WebSocket 或进程内载体投递，Client 生成的方法返回一个 `RemoteStreamHandle<Out, In>`，它迭代这些项，并为同一条逻辑流上从 Client 到 Host 的上行提供 `send`、`end` 与 `dispose`。`RemoteStream<Out, In>` 的第二个类型参数声明上行项类型；Gateway 在 Host 方法通过 `this.ctx.invocation.uplink<In>()` 读取之前，用生成的 `In` codec 校验 Client 发送的每一项——它们来自浏览器。上行既不进入 `args` 也不进入参数列表；帧、半关闭、取消与 inbox 上限的约定由 [Gateway README](../packages/api/gateway/README.zh.md) 拥有。
+
 Client 使用普通对象上的具体函数，不使用 JavaScript Proxy。直接调用与作用域调用分别出现在 `ctx.remote.<namespace>` 和 `agentCtx.remote.<namespace>`。每个 namespace 都是注册为 `remote.<namespace>` 的可追踪 Cordis 子服务；Client assembly 通过 `ctx.remote.$mount()` 挂载贡献，最后一个方法撤回后该 namespace 随即卸载。依赖声明归实际调用方所有：只有读取 `ctx.remote.<namespace>` 或 `agentCtx.remote.<namespace>` 的业务包才在自己的 `inject` 中同时声明 `remote` 与 `remote.<namespace>`；只负责挂载 contribution 的 assembly，以及不调用该 namespace 的上层运行时，不代业务包声明 namespace 依赖。当一个 `@Remote` 方法恰好有一个 lookup 参数、且同名 `TypertContextMap` 使用相同 wire identity 时，生成的作用域签名会省略该 identity 参数。`@RemoteScope` 只生成作用域调用接口。
 
 ```ts ignore-check
@@ -120,9 +122,9 @@ Remote Client 声明中的参数名来自 wire 字段，参数和返回类型则
 
 Remote 调用使用 Connection 的 `/api` 路由。Client Remote 调用 `connection.rpc.call('/api', '<namespace>/<method>', { args }, signal)`；HTTP carrier 对应 `POST /api/<namespace>/<method>`，payload 只包含一个具名 `args` 对象。
 
-Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；功能自有的精确 Fetch 路由处理非 JSON 响应，其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消，Gateway 只拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。
+Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查，再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint；它把二进制 Remote 字段投影为 JSON 兼容元数据及相对于结果的字节附件，再由 Connection 封装为 multipart 响应。功能自有的精确 Fetch 路由处理 RPC 信封之外的响应，其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消，Gateway 拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。
 
-Gateway 每次调用都从当前注册表解析描述符和实时服务，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context 提供方解析对象或接收者，最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。
+Gateway 每次调用都从当前注册表解析描述符和实时服务，不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致，先用 codec 校验 wire 值，再通过注册的 lookup 或 Context 提供方解析对象或接收者，最后调用 binding 指向的服务方法。Client Gateway 使用生成的结果 codec 校验解码后的二进制结果；普通 JSON 结果保持原有处理方式。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。
 
 lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver；`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载；没有提供方时调用仍以 `gateway/lookup-unavailable` 失败，配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 resolver 语义：复用 live Agent，自动恢复普通冷会话，对并发恢复去重，并拒绝由 subagent routing 拥有的 identity；`session` lookup 返回该 Agent 的 Session。恢复失败与 ownership fence 抛出携带自有码的 `RemoteError`（`session/not-found` 或 `session/agent-busy`），Gateway 原样编码上 wire；只有未归类的 throw 才折成 `gateway/internal`。
 
@@ -138,14 +140,13 @@ SRC 只解决 Host 源码进程的分发问题。Client 不会从运行中的 Ho
 
 ## 开发模式
 
-Web 开发先使用 `pnpm run build` 准备当前 Host、Client 与 Web 产物，然后在两个终端中分别运行源码 Host 和 Client plugin watcher：
+Web 开发只需一条命令：它先构建当前 Host、Client 与 Web 产物，再启动源码 Host，并持续重建 Client bundle：
 
 ```sh
-pnpm dsh web
 pnpm run dev:web
 ```
 
-`dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 只监听带 `dsh.client` 声明的 Client 插件并重写其 `lib/client.js`，它不会分析 Host decorator，也不会生成 Remote Client DTS。
+`dsh` 通过 tsx 启动 Host 源码，所以 Host 可以使用 SRC 回退；`dev:web` 的 watcher 会在源码修改时重建 client 侧类型输出、Client 插件与库 bundle 以及 Web 壳层。它们不会分析 Host decorator，也不会生成 Remote Client DTS；只有 `dev:web` 首先执行的完整构建（或 `pnpm run build`）才会。
 
 只修改 Remote 方法实现体而不改变约定时，无需重新生成 Typert 文件。新增或删除 decorator、修改导出名、namespace、参数、返回值、lookup、Context 或取消签名时，重新执行有序 lib 构建，让 Host 先生成严格约定，再让 Client 编译并打包新的贡献：
 
@@ -157,8 +158,8 @@ pnpm run build:lib
 
 ## 边界
 
-Remote 只处理有单个请求与单个结果的一元方法调用。会话事件流、分页、增量 reduce、projection 和实体子流需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
+Remote 处理单请求单结果的一元方法调用，以及项沿 Host → Client 方向流动、而 Client 的项经 `this.ctx.invocation.uplink()` 到达正在运行的 Host 方法的流方法。会话事件流、分页、增量 reduce、projection 和实体子流仍需要独立的数据协议与注册模型；即使它们复用 Connection，也不应伪装成 Remote 方法或放入调用描述符。
 
-API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 Typert RPC 层位于 `packages/api`；Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。需要流式或浏览器原生响应的功能注册精确的 Connection Fetch 路由，而不定义 Remote 方法。
+API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 Typert RPC 层位于 `packages/api`；Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。包含 `Uint8Array` 的一元结果（包括嵌套字段和数组条目）使用[二进制 Remote 传输](../.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md)。需要 RPC 信封之外响应的功能注册精确的 Connection Fetch 路由。
 
 lookup 策略按 key 配置，因此所有 `agent` 或 `session` 参数共享冷恢复行为。只接受 live 对象需要显式的逐参数或逐 endpoint 策略，而这种策略并不存在；不能通过业务方法内部猜测对象是否来自恢复。
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 3d9fba9385..a31bcf99da 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/architecture.md
-architecture.md: 0bbf5ef7f4c0444635178ba0ba85fbb9527d76ec
-architecture.zh.md: 0d28dc349fd9c655529bcc43deabc47055e0d394
+architecture.md: 514bd52cfa8f50fe8cf73c391094d34942b3cca3
+architecture.zh.md: 848fa1b3810403e4a3906ac491c8552052e4ee4e
diff --git a/docs/architecture.md b/docs/architecture.md
index 0bbf5ef7f4..514bd52cfa 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -44,7 +44,7 @@ Composition mechanics are in [app-boot](../packages/boot/app-boot/README.md#prof
 
 Supported Node applications launch through named `dsh` profiles. The shipped profiles are `web`, `headless`, `sdk`, `sdk-minimal`, and `acp`, selected with `dsh --profile <name>` or `dsh <name>`. `plugin` names the management command; a profile with that name requires `--profile plugin`. The TypeScript SDK resolves its same-version `dsh` dependency and selects `sdk`; custom plugin composition remains a profile plus ordered patch files, not another executable or inline application tree. `sdk-minimal` is a repository-owned standalone bundle behind the same launcher, not a caller-supplied Cordis tree.
 
-Vendored CLIs, build-only and test-only executables, direct in-process plugin mounting, and the private browser WebWorker preview are not Harness application launchers. [`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts) keeps every package bin, executable source, and root demo in an explicit class and rejects a Node application path that bypasses `dsh`.
+Vendored CLIs, build-only and test-only executables, direct in-process plugin mounting, and the private browser WebWorker preview are not Harness application launchers. [`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts) keeps every package bin, executable source, root demo, and the root `start:web` and `dev:web` scripts in an explicit class and rejects a Node application path that bypasses `dsh`.
 
 The Python SDK follows the same application architecture. Its runtime wheel packages the normal `dsh` CLI as `deepseek-harness-sdk-runtime-<platform>-<arch>`, and the client launches `dsh --profile sdk` with an explicit Harness home by default. The minimal example selects the shipped `sdk-minimal` profile. Python exposes profile selection and ordered patch files rather than a complete Cordis tree; persistent external plugins are installed through `dsh plugin`. The removed private direct-config carrier has no compatibility bin or fallback parser.
 
@@ -112,7 +112,7 @@ One inbox feeds the driver; injected context waits for a waking message. AgentLo
 
 `agent/pre-step` decides the accepted input. Listeners may rewrite or reject claimed messages; a rejected or empty first claim closes a durable turn without a step. An enter decision may set `startsRequestSeries`: the loop logs a fresh `request/header` (reason `series`, or `change` with `startsSeries: true` when the envelope also changed). Wrapping listeners preserve that declaration with `{ ...decision, messages }`. After assembly and `step/start`, `agent/request` and `prepareCall()` resolve the actual route before the system prompt and accepted users are committed; cancellation during either async phase commits neither. The prepared call capability governs prompt admission, not the preceding `request/context`. Every attempt synchronously reconciles the same rendered assembly, appends users only on the first attempt, logs header/context as needed, and derives and freezes the request before streaming the bound call. Retries do not repeat assembly or `agent/pre-step`. Surface replacements and image-offload decisions after attachment start a new request series, including during the first resumed pre-step; unchanged resume continues the series. The first admitted step reserves the system head before user messages even for an empty prompt (no wire message). The prompt travels only as `system/message` history: an empty rendering clears all active system nodes, leaving no old prompt model-visible; capable routes can append non-empty updates after the cached prefix; incapable routes and new request series consolidate non-empty prompt text at the first system node, with logged empty replacements for non-empty later system nodes ([decision](../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md); [decision rule](../packages/core/agent-loop/README.md#understand-the-implementation)).
 
-The loop sends immutable requests while keeping cancellation live. It reuses message-freeze evidence only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction rules.
+The loop sends immutable requests while keeping cancellation live. It reuses message-freeze evidence only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction and cancellation-cause rules.
 
 Details: the [sequence diagram](agent-lifecycle.md), the [tool pipeline](tool-execution-pipeline.md), and [cancellation and error recovery](subsystems/core.md#the-agent-handle).
 
@@ -146,7 +146,7 @@ New behavior attaches to a documented extension point. Changing the loop itself
 | Add shell execution | register a `ctx.shell` backend; the local one spawns through `ctx.subprocess` |
 | Add persistent terminal execution | register a `ctx.terminals` backend plus `dsh-tool-terminal` |
 | Add a human command | register on `ctx.commands`; it dispatches without a model turn |
-| Add background work | register on `ctx.jobs`; `job_*` tools collect or stop it |
+| Manage background jobs | register on `ctx.jobs`; `job_*` tools read or stop jobs |
 | Start a Session from an external webhook | register a trusted rule on `ctx.webhookRuntime` and mount a provider adapter |
 | Add filesystem access or policy | register a `ctx.fs` provider or listen to `fs/*` events |
 | Confine spawned processes | use a `ctx.sandbox` backend; consumers wrap argv before spawning |
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 0d28dc349f..848fa1b381 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -44,7 +44,7 @@ dsh --profile web --dump-config
 
 受支持的 Node 应用通过具名 `dsh` profile 启动。随附 profile 为 `web`、`headless`、`sdk`、`sdk-minimal` 和 `acp`，可通过 `dsh --profile <name>` 或 `dsh <name>` 选择。`plugin` 表示管理命令；同名 profile 必须用 `--profile plugin` 选择。TypeScript SDK 会解析其同版本 `dsh` 依赖并选择 `sdk`；自定义插件组合继续由 profile 与有序 patch 文件表达，而不是另一个可执行文件或内联应用树。`sdk-minimal` 是位于同一 launcher 后的仓库自有独立组合包，而不是由调用方提供的 Cordis 配置树。
 
-Vendored CLI、仅用于构建和测试的可执行文件、进程内直接挂载插件以及私有浏览器 WebWorker 预览都不属于 Harness 应用启动器。[`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts)将每个包 bin、可执行源码与根 demo 归入显式类别，并拒绝任何绕过 `dsh` 的 Node 应用路径。
+Vendored CLI、仅用于构建和测试的可执行文件、进程内直接挂载插件以及私有浏览器 WebWorker 预览都不属于 Harness 应用启动器。[`verify-application-entrypoints`](../scripts/verify-application-entrypoints.ts)将每个包 bin、可执行源码、根 demo 以及根脚本 `start:web` 与 `dev:web` 归入显式类别，并拒绝任何绕过 `dsh` 的 Node 应用路径。
 
 Python SDK 遵循相同的应用架构。其运行时 wheel 把普通 `dsh` CLI 打包为 `deepseek-harness-sdk-runtime-<platform>-<arch>`，客户端默认以显式 Harness home 启动 `dsh --profile sdk`。极简示例选择随附的 `sdk-minimal` profile。Python 暴露 profile 选择与有序 patch 文件，而不是完整 Cordis 树；持久外部插件通过 `dsh plugin` 安装。已删除的私有直读配置载体没有兼容 bin 或回退 parser。
 
@@ -116,7 +116,7 @@ turn/end
 
 `agent/pre-step` 决定接纳的输入。监听器可以改写或拒绝已领取消息；首次领取被拒绝或为空时，关闭不含步骤的持久轮次。enter 决策可设置 `startsRequestSeries`：循环记录新的 `request/header`（原因为 `series`，或在封装同时变化时为携带 `startsSeries: true` 的 `change`）。包装监听器通过 `{ ...decision, messages }` 保留该声明。组装与 `step/start` 之后，`agent/request` 和 `prepareCall()` 先解析实际路由，再提交系统提示词与已接纳用户消息；在任一异步阶段取消都不会提交这两者。提示词准入依据已准备调用的能力，而非先前的 `request/context`。每次尝试同步协调同一份已渲染组装结果、仅在首次尝试追加用户消息、按需记录 header/context、派生并冻结请求，再通过绑定调用发起流式请求。重试不重复组装或 `agent/pre-step`。附接后的 surface 替换和图片省略决定开启新请求序列，包括恢复后的首次 pre-step 中发生的替换；未变化的恢复延续序列。首次接纳的步骤在用户消息之前预留系统头节点，即使提示词为空（不产生协议消息）。提示词仅通过 `system/message` 历史传递：空渲染文本清除所有生效的系统节点，模型不再看到旧提示词；具备能力的路由可在缓存前缀之后追加非空更新；不具备能力的路由与新请求序列将非空提示词文本归并到首个系统节点，并为非空的后续系统节点记录空内容替换（[决策](../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.zh.md)；[决策规则](../packages/core/agent-loop/README.zh.md#understand-the-implementation)）。
 
-循环发送不可变请求，同时保留实时取消能力。只有已由该循环完整冻结的消息对象身份才能复用冻结证明；[agent-loop](../packages/core/agent-loop/README.zh.md)拥有请求构造规则。
+循环发送不可变请求，同时保留实时取消能力。只有已由该循环完整冻结的消息对象身份才能复用冻结证明；[agent-loop](../packages/core/agent-loop/README.zh.md)拥有请求构造与取消原因记录规则。
 
 详情见[时序图](agent-lifecycle.zh.md)、[工具流水线](tool-execution-pipeline.zh.md)和[取消与错误恢复](subsystems/core.zh.md#the-agent-handle)。
 
@@ -150,7 +150,7 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统
 | 添加 shell 执行 | 注册 `ctx.shell` 后端；本地后端通过 `ctx.subprocess` spawn 进程 |
 | 添加持久化终端执行 | 注册 `ctx.terminals` 后端和 `dsh-tool-terminal` |
 | 添加用户命令 | 在 `ctx.commands` 上注册；它无需模型轮次即可分派 |
-| 添加后台工作 | 在 `ctx.jobs` 上注册；`job_*` 工具负责收集或停止 |
+| 管理后台任务 | 在 `ctx.jobs` 上注册；`job_*` 工具读取或停止任务 |
 | 从外部 webhook 启动 Session | 在 `ctx.webhookRuntime` 上注册可信规则，并挂载提供方适配器 |
 | 添加文件系统访问或策略 | 注册 `ctx.fs` 提供方，或监听 `fs/*` 事件 |
 | 限制所启动的进程 | 使用 `ctx.sandbox` 后端；消费方在启动进程前包装 argv |
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index 8c28ee4357..b5c8b49223 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: edb8cd688768ec49ee3699c3775409a66975129d
-capability-seams.zh.md: b06d9378616669407b79ffa1da205924ff6ad757
+capability-seams.md: eea821874c1932d7daa5f0a2aec3f18653757142
+capability-seams.zh.md: c7794eae7bfd6456b7878a5b98a27fdec9f2adab
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index edb8cd6887..eea821874c 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -67,6 +67,8 @@ flowchart LR
   svc_sessionController["ctx.sessionController<br/>Host Session Remote controller"]
   svc_sessionFileReferences["ctx.sessionFileReferences<br/>Session-addressed file-reference Remote adapter"]
   svc_sessionSkillCatalog["ctx.sessionSkillCatalog<br/>Session-addressed skill Remote adapter"]
+  pkg_api_job_controller["api-job-controller"]
+  svc_jobController["ctx.jobController<br/>Host job Remote controller"]
   pkg_api_settings_controller["api-settings-controller"]
   svc_credentialsController["ctx.credentialsController<br/>Host credential-surface Remote controller"]
   svc_settingsController["ctx.settingsController<br/>Host settings-surface Remote controller"]
@@ -259,6 +261,7 @@ flowchart LR
   pkg_agent_loop --> svc_agentLoop
   pkg_agent_presets --> svc_agentPresets
   pkg_api_gateway --> svc_typertGateway
+  pkg_api_job_controller --> svc_jobController
   pkg_api_session_controller --> svc_sessionController
   pkg_api_session_controller --> svc_sessionFileReferences
   pkg_api_session_controller --> svc_sessionSkillCatalog
@@ -432,8 +435,10 @@ flowchart LR
   svc_invariants --> pkg_agent_loop
   svc_invariants --> pkg_scope
   svc_invariants --> pkg_session
+  svc_jobs --> pkg_api_job_controller
   svc_jobs --> pkg_tool_bash
   svc_jobs --> pkg_tool_jobs
+  svc_jobs --> pkg_tool_pwsh
   svc_jobs --> pkg_tool_subagent
   svc_jobs --> pkg_tool_terminal
   svc_llm --> pkg_agent_loop
@@ -555,6 +560,7 @@ flowchart LR
 | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Owns Session commands, cold reads, durable-event following, live control state, model catalogs, workspace opening, and Agent activation policy. |
 | `ctx.sessionFileReferences` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Delegates file-reference discovery through the Session Controller's established Agent lookup policy. |
 | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Lists the Session composition's user-invocable skills without activating a cold Agent. |
+| `ctx.jobController` | `core` | [`api-job-controller`](../packages/api/job-controller) | - | - | - | Streams one background job's observation record over the generated Remote namespace; the roster stays on the session control stream. |
 | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the credential-reference seam onto the generated Remote namespace: batch fan-out, view projection, and refusal mapping live here, not on the seam Definition. |
 | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition. |
 | `ctx.workspaceFiles` | `core` | [`api-workspace-files`](../packages/api/workspace-files) | - | - | - | Serves stat, paged text, byte windows, directory listings, and the change feed for files inside a Session's workspace root, confined by lstat, containment, and a stat re-check. |
@@ -608,7 +614,7 @@ flowchart LR
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`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.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | Owns the implicit-root roster, durable peer mailbox, shared task DAG, continuable-child lifecycle, and generated Team Remote methods; tool-agent-team contributes model controls and client-ui-agent-team mounts the browser contribution. |
 | `ctx.inspector` | `core` | `inspector` | - | - | - | Owns the Worker-hosted CDP target and the transport-independent Host and Client observation and Cordis-tree query API. |
-| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry. |
+| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`api-job-controller`](../packages/api/job-controller) | - | Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-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-http`](../packages/web/web-fetch-http) | [`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` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | 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 b06d937861..c7794eae7b 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -69,6 +69,8 @@ flowchart LR
   svc_sessionController["ctx.sessionController<br/>Host Session Remote controller"]
   svc_sessionFileReferences["ctx.sessionFileReferences<br/>Session-addressed file-reference Remote adapter"]
   svc_sessionSkillCatalog["ctx.sessionSkillCatalog<br/>Session-addressed skill Remote adapter"]
+  pkg_api_job_controller["api-job-controller"]
+  svc_jobController["ctx.jobController<br/>Host job Remote controller"]
   pkg_api_settings_controller["api-settings-controller"]
   svc_credentialsController["ctx.credentialsController<br/>Host credential-surface Remote controller"]
   svc_settingsController["ctx.settingsController<br/>Host settings-surface Remote controller"]
@@ -261,6 +263,7 @@ flowchart LR
   pkg_agent_loop --> svc_agentLoop
   pkg_agent_presets --> svc_agentPresets
   pkg_api_gateway --> svc_typertGateway
+  pkg_api_job_controller --> svc_jobController
   pkg_api_session_controller --> svc_sessionController
   pkg_api_session_controller --> svc_sessionFileReferences
   pkg_api_session_controller --> svc_sessionSkillCatalog
@@ -434,8 +437,10 @@ flowchart LR
   svc_invariants --> pkg_agent_loop
   svc_invariants --> pkg_scope
   svc_invariants --> pkg_session
+  svc_jobs --> pkg_api_job_controller
   svc_jobs --> pkg_tool_bash
   svc_jobs --> pkg_tool_jobs
+  svc_jobs --> pkg_tool_pwsh
   svc_jobs --> pkg_tool_subagent
   svc_jobs --> pkg_tool_terminal
   svc_llm --> pkg_agent_loop
@@ -557,6 +562,7 @@ flowchart LR
 | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 负责 Session 命令、冷读取、持久事件跟随、实时控制状态、模型目录、workspace 打开与 Agent 激活策略。 |
 | `ctx.sessionFileReferences` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 通过 Session Controller 的既有 Agent lookup 策略委托文件引用发现。 |
 | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 在不激活冷 Agent 的前提下列出 Session 组合中允许用户调用的 skill。 |
+| `ctx.jobController` | `core` | [`api-job-controller`](../packages/api/job-controller) | - | - | - | 经生成的 Remote namespace 流式发送一个后台任务的观测 record；名册仍在会话控制流上。 |
 | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把凭据引用 seam 投影到生成的 Remote namespace：批量扇出、视图投影与拒绝映射都在这里，而不在 seam Definition 上。 |
 | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把用户设置 seam 投影到生成的 Remote namespace：读取一律脱敏，所有拒绝在这里分类，而不在 seam Definition 上。 |
 | `ctx.workspaceFiles` | `core` | [`api-workspace-files`](../packages/api/workspace-files) | - | - | - | 为会话工作区根内的文件提供 stat、分页文本、字节窗口、目录列举与变更流，经 lstat、包含关系与 stat 重检限定。 |
@@ -610,7 +616,7 @@ flowchart LR
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`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.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | 负责隐式 Root roster、持久 peer mailbox、共享任务 DAG、continuable child 生命周期与生成式 Team Remote method；tool-agent-team 提供模型控制工具，client-ui-agent-team 挂载浏览器 contribution。 |
 | `ctx.inspector` | `core` | `inspector` | - | - | - | 负责 Worker 托管的 CDP target，以及独立于传输的 Host 和 Client observation 与 Cordis tree query API。 |
-| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-jobs 是面向模型的控制器，用于读取、列出和终止这些工作；jobs-local 是进程本地注册表。 |
+| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`api-job-controller`](../packages/api/job-controller) | - | 生产方（后台 bash/pwsh、PTY 发送和 subagent 委派）登记正在运行的工作；声明 record 的 job 还为非消费观察者流式提供原始输出；tool-jobs 是面向模型的控制器，用于读取、列出和终止这些工作；jobs-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-http`](../packages/web/web-fetch-http) | [`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` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | 带判别标记的交互能力：原生后端在 Host 显示设备上打开一个操作系统选择器，浏览后端为应用内浏览器提供列表与创建原语；双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot（不通过协议发布）。 |
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index e36833a8bc..63b1766591 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: a2128ab66c46c4b9e4e080331feaf3905da3bad6
-config-catalog.zh.md: 08761df3513c1662fdf572b2b9f6f53a9d533c07
+config-catalog.md: 59b15e7bbb518abdee55308c191b109547b5185e
+config-catalog.zh.md: 4e89ea92944f6e1f2ae8ae0b57f0bec9e9f835d9
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a2128ab66c..59b15e7bbb 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -194,10 +194,30 @@ Requires: `typert`
 export interface Config {
   /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
   readonly websocketHeartbeatIntervalMs?: number
+  /** Buffered uplink frame bytes one logical stream may hold before it fails with `gateway/uplink-overflow`. @default 262144 */
+  readonly streamInboxBytes?: number
 }
 ```
 
-Source: [`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts)
+Source: [`packages/api/gateway/src/index.ts:144`](../packages/api/gateway/src/index.ts)
+
+<a id="deepseek-aidsh-api-job-controller"></a>
+
+## `@deepseek-ai/dsh-api-job-controller`
+
+Requires: `jobs` · `typert`
+
+```ts config-catalog
+/** Job Controller deployment policy. */
+export interface Config {
+  /** Coalescing window after a registry commit before the next rows or output read, in milliseconds (default 100). */
+  readonly observeFlushMs?: number
+  /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */
+  readonly observeMaxFrameBytes?: number
+}
+```
+
+Source: [`packages/api/job-controller/src/index.ts:33`](../packages/api/job-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-session-controller"></a>
 
@@ -213,7 +233,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/api/session-controller/src/index.ts:77`](../packages/api/session-controller/src/index.ts)
+Source: [`packages/api/session-controller/src/index.ts:78`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 
@@ -274,6 +294,24 @@ export interface Config {
 
 Source: [`packages/api/terminal-controller/src/index.ts:26`](../packages/api/terminal-controller/src/index.ts)
 
+<a id="deepseek-aidsh-api-workspace-controller"></a>
+
+## `@deepseek-ai/dsh-api-workspace-controller`
+
+Requires: `typert` · `workspaceRegistry`
+
+```ts config-catalog
+/** First-use directory policy for the Host account. */
+export interface Config {
+  /** Override the system Documents directory with a fully qualified path. */
+  documentsDirectory?: string
+  /** Maximum duration of the operating system's Documents lookup. */
+  documentsLookupTimeoutMs?: number
+}
+```
+
+Source: [`packages/api/workspace-controller/src/index.ts:34`](../packages/api/workspace-controller/src/index.ts)
+
 <a id="deepseek-aidsh-api-workspace-files"></a>
 
 ## `@deepseek-ai/dsh-api-workspace-files`
@@ -300,7 +338,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/api/workspace-files/src/index.ts:69`](../packages/api/workspace-files/src/index.ts)
+Source: [`packages/api/workspace-files/src/index.ts:70`](../packages/api/workspace-files/src/index.ts)
 
 <a id="deepseek-aidsh-attachment-local"></a>
 
@@ -428,7 +466,7 @@ export interface ConnectionRecoveryConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:87`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:92`](../packages/client/connection/src/index.ts)
 
 <a id="deepseek-aidsh-client-hmr"></a>
 
@@ -1140,10 +1178,20 @@ export interface Config {
    * omission defaults to 10.
    */
   maxConcurrentJobsPerOwner?: number
+  /** Live ring retention per job in UTF-8 bytes; omission defaults to 262144. */
+  retainBytes?: number
+  /**
+   * Ring retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384.
+   * Settlement keeps every byte the model cursor has not consumed on top of
+   * this cap; the first terminal model read then trims to it.
+   */
+  settledRetainBytes?: number
+  /** Poll interval for a job's pull sources, in milliseconds; omission defaults to 150. */
+  pumpPollMs?: number
 }
 ```
 
-Source: [`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts)
+Source: [`packages/jobs/jobs-local/src/index.ts:45`](../packages/jobs/jobs-local/src/index.ts)
 
 <a id="deepseek-aidsh-llm-deepseek"></a>
 
@@ -1161,8 +1209,6 @@ Requires: `llm`
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Wire protocol; defaults to messages. Configure through Cordis YAML. */
-  protocol?: DeepSeekProtocol
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
@@ -1203,9 +1249,6 @@ export interface Config {
   retryPolicy?: RetryPolicyConfig
 }
 
-/** Supported wire implementations; Responses is not yet implemented. */
-export type DeepSeekProtocol = 'chat-completions' | 'messages'
-
 /** One optional model entry advertised by the direct-fetch adapter. */
 export interface DeepSeekCatalogModel {
   /** Wire model id accepted by the configured endpoint. */
@@ -2923,7 +2966,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/core/system-prompt/src/index.ts:248`](../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:247`](../packages/core/system-prompt/src/index.ts)
 
 <a id="deepseek-aidsh-terminal-bash"></a>
 
@@ -3158,14 +3201,14 @@ export interface Config {
 }
 
 /**
- * How an unreported completion reaches an owner that is already idle: `wakeup`
+ * How an uncollected completion reaches an owner that is already idle: `wakeup`
  * opens a turn for it, `quiet` leaves it pending until something else wakes the
  * owner. A busy owner is injected either way.
  */
 export type CompletionDelivery = 'quiet' | 'wakeup'
 ```
 
-Source: [`packages/jobs/tool-jobs/src/index.ts:37`](../packages/jobs/tool-jobs/src/index.ts)
+Source: [`packages/jobs/tool-jobs/src/index.ts:52`](../packages/jobs/tool-jobs/src/index.ts)
 
 <a id="deepseek-aidsh-tool-lsp"></a>
 
@@ -3217,7 +3260,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/shell/tool-pwsh/src/index.ts:51`](../packages/shell/tool-pwsh/src/index.ts)
+Source: [`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts)
 
 <a id="deepseek-aidsh-tool-pwsh-persistent"></a>
 
@@ -3402,7 +3445,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts)
+Source: [`packages/terminal/tool-terminal/src/index.ts:36`](../packages/terminal/tool-terminal/src/index.ts)
 
 <a id="deepseek-aidsh-tool-todo"></a>
 
@@ -3472,6 +3515,28 @@ export interface Config {
 
 Source: [`packages/workflow/tool-workflow/src/index.ts:32`](../packages/workflow/tool-workflow/src/index.ts)
 
+<a id="deepseek-aidsh-tool-workspace-dependencies"></a>
+
+## `@deepseek-ai/dsh-tool-workspace-dependencies`
+
+Requires: `tools`
+
+```ts config-catalog
+/** Payload location and optional installation directory. */
+export interface Config {
+  /** Payload directory carrying `runtime.json` and `dependencies/`. */
+  readonly source: string
+  /**
+   * Installation directory under the Harness home. When set, the payload is copied there on the
+   * first call (the Desktop behavior); when omitted, the payload is used in place without copying,
+   * which suits read-only carriers such as container image layers.
+   */
+  readonly root?: string
+}
+```
+
+Source: [`packages/skill/tool-workspace-dependencies/src/index.ts:15`](../packages/skill/tool-workspace-dependencies/src/index.ts)
+
 <a id="deepseek-aidsh-tools"></a>
 
 ## `@deepseek-ai/dsh-tools`
@@ -3783,7 +3848,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-acp-app` — requires `cmdlineArgs` ([`packages/bundle/acp-app/src/index.ts`](../packages/bundle/acp-app/src/index.ts))
 - `@deepseek-ai/dsh-agent` ([`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts))
 - `@deepseek-ai/dsh-api-remotes` — requires `typertGateway` ([`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts))
-- `@deepseek-ai/dsh-api-workspace-controller` — requires `typert` · `workspaceRegistry` ([`packages/api/workspace-controller/src/index.ts`](../packages/api/workspace-controller/src/index.ts))
 - `@deepseek-ai/dsh-authorization` — requires `credentials` ([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts))
 - `@deepseek-ai/dsh-browser-use` ([`packages/browser-use/browser-use/src/index.ts`](../packages/browser-use/browser-use/src/index.ts))
 - `@deepseek-ai/dsh-client-file-upload` — requires `agents` · `attachments` · `commands` · `connection` ([`packages/client/file-upload/src/index.ts`](../packages/client/file-upload/src/index.ts))
@@ -3867,7 +3931,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-terminal` ([`packages/terminal/terminal/src/index.ts`](../packages/terminal/terminal/src/index.ts))
 - `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userQuestions` ([`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-call-timeout-policy` — requires `tools` ([`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts))
-- `@deepseek-ai/dsh-tool-cordis` — requires `tools` · `systemPrompt` · `cordisInspect` ([`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts))
+- `@deepseek-ai/dsh-tool-cordis` — requires `tools` · `cordisInspect` ([`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts))
 - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
 - `@deepseek-ai/dsh-user-questions` ([`packages/interaction/user-questions/src/index.ts`](../packages/interaction/user-questions/src/index.ts))
 - `@deepseek-ai/dsh-webhook` — requires `agents` · `agentDefaultModel` · `agentPresets` · `permissionPresets` · `sessionTitle` · `workspaceRegistry` ([`packages/webhook/webhook/src/index.ts`](../packages/webhook/webhook/src/index.ts))
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 08761df351..4e89ea9294 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -196,10 +196,32 @@ Depends on: [`ToolPresentationMode`](subsystems/tools.zh.md)
 export interface Config {
   /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
   readonly websocketHeartbeatIntervalMs?: number
+  /** Buffered uplink frame bytes one logical stream may hold before it fails with `gateway/uplink-overflow`. @default 262144 */
+  readonly streamInboxBytes?: number
 }
 ```
 
-来源：[`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts)
+来源：[`packages/api/gateway/src/index.ts:144`](../packages/api/gateway/src/index.ts)
+
+<a id="deepseek-aidsh-api-job-controller"></a>
+
+## `@deepseek-ai/dsh-api-job-controller`
+
+需要：`jobs` · `typert`
+
+```ts config-catalog
+/** Job Controller deployment policy. */
+export interface Config {
+  /** Coalescing window after a registry commit before the next rows or output read, in milliseconds (default 100). */
+  readonly observeFlushMs?: number
+  /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */
+  readonly observeMaxFrameBytes?: number
+}
+```
+
+来源：[`packages/api/job-controller/src/index.ts:33`](../packages/api/job-controller/src/index.ts)
+
+<a id="deepseek-aidsh-api-session-controller"></a>
 
 <a id="deepseek-aidsh-api-session-controller"></a>
 
@@ -215,7 +237,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/api/session-controller/src/index.ts:77`](../packages/api/session-controller/src/index.ts)
+来源：[`packages/api/session-controller/src/index.ts:78`](../packages/api/session-controller/src/index.ts)
 
 <a id="deepseek-aidsh-api-settings-controller"></a>
 
@@ -276,6 +298,24 @@ export interface Config {
 
 来源： [`packages/api/terminal-controller/src/index.ts:26`](../packages/api/terminal-controller/src/index.ts)
 
+<a id="deepseek-aidsh-api-workspace-controller"></a>
+
+## `@deepseek-ai/dsh-api-workspace-controller`
+
+需要：`typert` · `workspaceRegistry`
+
+```ts config-catalog
+/** First-use directory policy for the Host account. */
+export interface Config {
+  /** Override the system Documents directory with a fully qualified path. */
+  documentsDirectory?: string
+  /** Maximum duration of the operating system's Documents lookup. */
+  documentsLookupTimeoutMs?: number
+}
+```
+
+源码：[`packages/api/workspace-controller/src/index.ts:34`](../packages/api/workspace-controller/src/index.ts)
+
 <a id="deepseek-aidsh-api-workspace-files"></a>
 
 ## `@deepseek-ai/dsh-api-workspace-files`
@@ -302,7 +342,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/api/workspace-files/src/index.ts:69`](../packages/api/workspace-files/src/index.ts)
+来源：[`packages/api/workspace-files/src/index.ts:70`](../packages/api/workspace-files/src/index.ts)
 
 <a id="deepseek-aidsh-attachment-local"></a>
 
@@ -430,7 +470,7 @@ export interface ConnectionRecoveryConfig {
 }
 ```
 
-来源： [`packages/client/connection/src/index.ts:87`](../packages/client/connection/src/index.ts)
+来源： [`packages/client/connection/src/index.ts:92`](../packages/client/connection/src/index.ts)
 
 <a id="deepseek-aidsh-client-hmr"></a>
 
@@ -1142,10 +1182,20 @@ export interface Config {
    * omission defaults to 10.
    */
   maxConcurrentJobsPerOwner?: number
+  /** Live ring retention per job in UTF-8 bytes; omission defaults to 262144. */
+  retainBytes?: number
+  /**
+   * Ring retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384.
+   * Settlement keeps every byte the model cursor has not consumed on top of
+   * this cap; the first terminal model read then trims to it.
+   */
+  settledRetainBytes?: number
+  /** Poll interval for a job's pull sources, in milliseconds; omission defaults to 150. */
+  pumpPollMs?: number
 }
 ```
 
-来源：[`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts)
+来源：[`packages/jobs/jobs-local/src/index.ts:45`](../packages/jobs/jobs-local/src/index.ts)
 
 <a id="deepseek-aidsh-llm-deepseek"></a>
 
@@ -1163,8 +1213,6 @@ export interface Config {
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Wire protocol; defaults to messages. Configure through Cordis YAML. */
-  protocol?: DeepSeekProtocol
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
@@ -1205,9 +1253,6 @@ export interface Config {
   retryPolicy?: RetryPolicyConfig
 }
 
-/** Supported wire implementations; Responses is not yet implemented. */
-export type DeepSeekProtocol = 'chat-completions' | 'messages'
-
 /** One optional model entry advertised by the direct-fetch adapter. */
 export interface DeepSeekCatalogModel {
   /** Wire model id accepted by the configured endpoint. */
@@ -2925,7 +2970,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/core/system-prompt/src/index.ts:248`](../packages/core/system-prompt/src/index.ts)
+来源：[`packages/core/system-prompt/src/index.ts:247`](../packages/core/system-prompt/src/index.ts)
 
 <a id="deepseek-aidsh-terminal-bash"></a>
 
@@ -3160,7 +3205,7 @@ export interface Config {
 }
 
 /**
- * How an unreported completion reaches an owner that is already idle: `wakeup`
+ * How an uncollected completion reaches an owner that is already idle: `wakeup`
  * opens a turn for it, `quiet` leaves it pending until something else wakes the
  * owner. A busy owner is injected either way.
  */
@@ -3219,7 +3264,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/shell/tool-pwsh/src/index.ts:51`](../packages/shell/tool-pwsh/src/index.ts)
+来源：[`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts)
 
 <a id="deepseek-aidsh-tool-pwsh-persistent"></a>
 
@@ -3404,7 +3449,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts)
+来源：[`packages/terminal/tool-terminal/src/index.ts:36`](../packages/terminal/tool-terminal/src/index.ts)
 
 <a id="deepseek-aidsh-tool-todo"></a>
 
@@ -3474,6 +3519,28 @@ export interface Config {
 
 来源：[`packages/workflow/tool-workflow/src/index.ts:32`](../packages/workflow/tool-workflow/src/index.ts)
 
+<a id="deepseek-aidsh-tool-workspace-dependencies"></a>
+
+## `@deepseek-ai/dsh-tool-workspace-dependencies`
+
+依赖：`tools`
+
+```ts config-catalog
+/** Payload location and optional installation directory. */
+export interface Config {
+  /** Payload directory carrying `runtime.json` and `dependencies/`. */
+  readonly source: string
+  /**
+   * Installation directory under the Harness home. When set, the payload is copied there on the
+   * first call (the Desktop behavior); when omitted, the payload is used in place without copying,
+   * which suits read-only carriers such as container image layers.
+   */
+  readonly root?: string
+}
+```
+
+来源：[`packages/skill/tool-workspace-dependencies/src/index.ts:15`](../packages/skill/tool-workspace-dependencies/src/index.ts)
+
 <a id="deepseek-aidsh-tools"></a>
 
 ## `@deepseek-ai/dsh-tools`
@@ -3785,7 +3852,6 @@ export interface Config {
 - `@deepseek-ai/dsh-acp-app` — 需要 `cmdlineArgs`（[`packages/bundle/acp-app/src/index.ts`](../packages/bundle/acp-app/src/index.ts)）
 - `@deepseek-ai/dsh-agent`（[`packages/core/agent/src/index.ts`](../packages/core/agent/src/index.ts)）
 - `@deepseek-ai/dsh-api-remotes` — 需要 `typertGateway`（[`packages/api/remotes/src/index.ts`](../packages/api/remotes/src/index.ts)）
-- `@deepseek-ai/dsh-api-workspace-controller` — 需要 `typert` · `workspaceRegistry`（[`packages/api/workspace-controller/src/index.ts`](../packages/api/workspace-controller/src/index.ts)）
 - `@deepseek-ai/dsh-authorization` — 需要 `credentials`（[`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)）
 - `@deepseek-ai/dsh-browser-use` ([`packages/browser-use/browser-use/src/index.ts`](../packages/browser-use/browser-use/src/index.ts))
 - `@deepseek-ai/dsh-client-file-upload` — 需要 `agents` · `attachments` · `commands` · `connection`（[`packages/client/file-upload/src/index.ts`](../packages/client/file-upload/src/index.ts)）
diff --git a/docs/cookbook/adding-a-package.i18n.yaml b/docs/cookbook/adding-a-package.i18n.yaml
index b2b0467564..8c94de4306 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: 8c818bc371b4fcd646878ec440dd713f8c116083
-adding-a-package.zh.md: f6a09b411e246c50fcf3f44117c05433b12cbd4c
+adding-a-package.md: 60b5d6e047da5f9cdfab3ab504104a0f29b208f7
+adding-a-package.zh.md: 44a613bcf002009c4c58a34c0f68cab85ef097f3
diff --git a/docs/cookbook/adding-a-package.md b/docs/cookbook/adding-a-package.md
index 8c818bc371..60b5d6e047 100644
--- a/docs/cookbook/adding-a-package.md
+++ b/docs/cookbook/adding-a-package.md
@@ -143,7 +143,9 @@ Fields fall back independently before view-specific name formatting, using the e
 - Title: locale `meta.title` → `package.json.name` → complete Cordis plugin name.
 - Description: locale `meta.description` → `package.json.description` → no description.
 
-Export `<package name>/locale/en.json` for locale lookup; expose `<package name>/package.json` when package-field fallback is needed.
+Export `<package name>/locale/en.json` for locale lookup; expose `<package name>/package.json` for package-field fallback or an icon declaration.
+
+For an image on bundle cards, details, and component rows, set top-level `"icon": "./icon.svg"` in that exported manifest and include the image in `files`. The path is relative to the declaring manifest's directory, including for independently exported plugin manifests. SVG, PNG, JPEG (`.jpg`/`.jpeg`), and WebP files are supported up to 256 KiB. Absolute paths, URLs, paths outside that directory, and symlinks resolving outside it are rejected. Images need no separate export and must be self-contained; SVG is rendered as an image, not inline HTML. The Host returns a data URL without activating the plugin. Invalid declarations or unreadable files produce a metadata diagnostic while retaining valid text; missing or undecodable images use the panel's default artwork.
 
 Installed bundle cards and details, component lists and configuration details, and Settings' plugin inventory display this metadata, including disabled and preset plugins. Reads do not activate plugins.
 
diff --git a/docs/cookbook/adding-a-package.zh.md b/docs/cookbook/adding-a-package.zh.md
index f6a09b411e..44a613bcf0 100644
--- a/docs/cookbook/adding-a-package.zh.md
+++ b/docs/cookbook/adding-a-package.zh.md
@@ -143,7 +143,9 @@ Append-only, prefix-stable, replacing, or independent behavior, including the ex
 - 标题：locale `meta.title` → `package.json.name` → 完整 Cordis 插件名。
 - 描述：locale `meta.description` → `package.json.description` → 不显示描述。
 
-导出 `<包名>/locale/en.json` 供 locale 查询；需要包字段回退时，再开放 `<包名>/package.json`。
+导出 `<包名>/locale/en.json` 供 locale 查询；需要包字段回退或声明图标时，开放 `<包名>/package.json`。
+
+要在组合包卡片、详情和组件行显示图片，在该导出清单顶层设置 `"icon": "./icon.svg"`，并将图片加入 `files`。路径相对于声明清单所在目录，独立导出的插件清单也遵循此规则。支持不超过 256 KiB 的 SVG、PNG、JPEG（`.jpg`/`.jpeg`）和 WebP 文件。绝对路径、URL、目录外路径，以及解析到目录外的符号链接均被拒绝。图片不需要单独导出，且必须自包含；SVG 作为图片渲染，不作为内联 HTML。Host 返回 data URL，不激活插件。声明无效或文件不可读时，显示元信息诊断并保留有效文本；图片缺失或无法解码时使用面板的默认插画。
 
 已安装 bundle 的卡片和详情、组件列表与配置详情、设置中的插件清单都展示这些元信息，包括禁用插件和预设内插件。读取时不激活插件。
 
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index cc1209ff9e..e6cf6f864d 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: 659f87bf88ac7fc4b8bc7dd65672c86e6b4326f6
-adding-a-tool.zh.md: 4804c22b22e5761e27c59392d76a322a7407af99
+adding-a-tool.md: 2deb608fb3f25cb3c816150ed678fa685892ef66
+adding-a-tool.zh.md: 5ad488c8b4c7f4678f11f31ea3669c425e3ea1b7
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index 659f87bf88..2deb608fb3 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -52,7 +52,7 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool. S
 
 Gate `run_in_background` with producer config, then register through `ctx.jobs.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', jobId }`; its Native renderer may keep human prose such as `started background job bash-1`, but PTC 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.jobs.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; `job_kill`, owner disposal, and service teardown own that lifetime. Foreground work remains coupled to `exec.signal`. See the [background job runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer.
+The spec supplies synchronous `cancel`, a non-rejecting `done` that settles after resource cleanup, and either pull `output` sources the registry pumps into the job's output ring or pushes through the `JobHandle` its starter receives; `dsh-tool-jobs` renders the model's consuming read from that ring. A pre-aborted call is a failure because no task exists whose id could satisfy the successful output schema. Once `ctx.jobs.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; `job_kill`, owner disposal, and service teardown own that lifetime. Foreground work remains coupled to `exec.signal`. See the [background job runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer.
 
 ## Execution policy and observation
 
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index 4804c22b22..5ad488c8b4 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -52,7 +52,7 @@ export function apply(ctx: Context) {
 
 通过 producer 配置控制 `run_in_background`，然后使用 `ctx.jobs.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败；运行时会在 `run()` 启动工作前校验 owner 和任务控制器是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄，如 `{ kind: 'background', jobId }`；其 Native 渲染器可以保留 `started background job bash-1` 这类供人阅读的自然语言，但 PTC mode 绝不能通过解析该文本取得 id。
 
-producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.jobs.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `job_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)与 `dsh-tool-bash`。
+spec 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及由注册表泵入 job 输出环的拉取式 `output` 源或经 starter 收到的 `JobHandle` 推送的追加；模型的消费式读取由 `dsh-tool-jobs` 从该环渲染。预先中止的调用属于失败，因为此时没有任务，其 id 无法满足成功输出 schema。`ctx.jobs.start()` 发布 id 后，应使用任务自有的取消信号，而不是 `exec.signal`：之后取消外层调用只会停止等待本次调用，不会终止已经发布的工作；该生命周期归 `job_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)与 `dsh-tool-bash`。
 
 <a id="execution-policy-and-observation"></a>
 
diff --git a/docs/cordis-api/inherited.md b/docs/cordis-api/inherited.md
index bb6cd40bb3..cc62683cb5 100644
--- a/docs/cordis-api/inherited.md
+++ b/docs/cordis-api/inherited.md
@@ -21,16 +21,18 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie
 
 ## Inherited events (cordis core + loader/hmr/timer)
 
-- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:328`](../../vendor/cordis/src/events.ts))
-- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:330`](../../vendor/cordis/src/events.ts))
-- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:332`](../../vendor/cordis/src/events.ts))
-- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:334`](../../vendor/cordis/src/events.ts))
-- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:336`](../../vendor/cordis/src/events.ts))
-- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:338`](../../vendor/cordis/src/events.ts))
-- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:340`](../../vendor/cordis/src/events.ts))
-- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:342`](../../vendor/cordis/src/events.ts))
-- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:23`](../../vendor/loader/src/index.ts))
-- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:24`](../../vendor/loader/src/index.ts))
-- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
-- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
-- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
+- `internal/plugin` — A plugin fiber was created. ([`vendor/cordis/src/events.ts:331`](../../vendor/cordis/src/events.ts))
+- `internal/status` — A fiber changed lifecycle state. ([`vendor/cordis/src/events.ts:333`](../../vendor/cordis/src/events.ts))
+- `internal/service` — Interception hook for a service binding (no core producer). ([`vendor/cordis/src/events.ts:341`](../../vendor/cordis/src/events.ts))
+- `internal/update` — Waterfall: a fiber config update is being applied. ([`vendor/cordis/src/events.ts:343`](../../vendor/cordis/src/events.ts))
+- `internal/config` — Waterfall: a fiber config is being resolved before validation. ([`vendor/cordis/src/events.ts:339`](../../vendor/cordis/src/events.ts))
+- `internal/get` — Waterfall: a service is being read from the store. ([`vendor/cordis/src/events.ts:345`](../../vendor/cordis/src/events.ts))
+- `internal/set` — Waterfall: a service is being written to the store. ([`vendor/cordis/src/events.ts:347`](../../vendor/cordis/src/events.ts))
+- `internal/listener` — A listener was registered. ([`vendor/cordis/src/events.ts:349`](../../vendor/cordis/src/events.ts))
+- `internal/dispatch` — An event is being dispatched to listeners. ([`vendor/cordis/src/events.ts:351`](../../vendor/cordis/src/events.ts))
+- `exit` — The process is exiting on a signal. ([`vendor/loader/src/index.ts:25`](../../vendor/loader/src/index.ts))
+- `loader/config-update` — The loader config tree changed. ([`vendor/loader/src/index.ts:26`](../../vendor/loader/src/index.ts))
+- `loader/entry-init` — A config entry is being initialized. ([`vendor/loader/src/index.ts:27`](../../vendor/loader/src/index.ts))
+- `loader/partial-dispose` — An entry is being partially disposed on reload. ([`vendor/loader/src/index.ts:28`](../../vendor/loader/src/index.ts))
+- `loader/patch-context` — A context is being patched during a reload. ([`vendor/loader/src/index.ts:41`](../../vendor/loader/src/index.ts))
+- `loader/volatile-update` — Volatile config values committed into the running fiber without a remount; dispatched to the owning fiber only. ([`vendor/loader/src/index.ts:34`](../../vendor/loader/src/index.ts))
diff --git a/docs/cordis-tutorial/05-config.i18n.yaml b/docs/cordis-tutorial/05-config.i18n.yaml
index 2e7c3b22ec..3eb71ac95b 100644
--- a/docs/cordis-tutorial/05-config.i18n.yaml
+++ b/docs/cordis-tutorial/05-config.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cordis-tutorial/05-config.md
-05-config.md: 17cccce2ec43be65477ce527800ee6a636ee5d96
-05-config.zh.md: e19dcb3ab0082cdc6ba2457158491ba47223409d
+05-config.md: f278e8d06ef867d2944c279d067c36970582167f
+05-config.zh.md: 65e9ea73a5ce31776dc1603339fa7c1c0250f856
diff --git a/docs/cordis-tutorial/05-config.md b/docs/cordis-tutorial/05-config.md
index 17cccce2ec..f278e8d06e 100644
--- a/docs/cordis-tutorial/05-config.md
+++ b/docs/cordis-tutorial/05-config.md
@@ -67,6 +67,33 @@ ValidationError: invalid config:
 
 The plugin's fiber goes to FAILED, and this tutorial's launcher exits with status 1 after printing the error. A plugin should also reject schema-valid config that names an unavailable resource or provider as soon as it can resolve that reference.
 
+<a id="volatile-fields"></a>
+## Volatile fields
+
+Use `.volatile()` for a field that the plugin reads during each operation. A change to that field updates its stable reference without remounting the plugin. Read it with `.get()`:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import Schema from '@deepseek-ai/schemastery'
+
+export const Config = Schema.object({
+  greeting: Schema.string().default('Hello').volatile(),
+})
+
+export function apply(ctx: Context, config: ReturnType<typeof Config>) {
+  ctx.on('loader/volatile-update', () => {
+    console.log(config.greeting.get())
+  })
+}
+```
+
+A direct `Config(raw)` call also returns references. An optional field without a default still has a reference; `.get()` returns `undefined` when it is absent. Keep the reference, or capture its value for one operation, including across `await`. Do not retain that value for later operations. Object and array values are detached, recursively frozen snapshots of plain data; functions, class instances, and cycles are rejected.
+
+Loader compares raw config while ignoring schema-declared volatile fields. A volatile-only change is parsed through the plugin’s `internal/config` hook and validated; when every ordinary effective value still matches, Loader commits the new values into the running references and emits one instance-local `loader/volatile-update` with the changed paths as arrays of keys, bypassing the target plugin’s `internal/update`. Equal values do not notify. An invalid candidate is logged and leaves the running references unchanged until the next activation. A changed ordinary effective value, including a changed expression result, and simultaneous ordinary-field changes retain the existing update flow, leaving old references unchanged and unnotified. Group/Include still dispatch child updates. Direct `fiber.update()`, code replacement, and dependency replacement retain their lifecycle; `noSave` still controls direct-update persistence. Notifications use ordinary `emit` without awaiting resource reconfiguration.
+
+Declare volatile fields at fixed object paths, or mark an entire object or array volatile. Independent references inside arrays, dictionaries, union or intersect branches, lazy schemas, transforms, or another volatile value are rejected. Configuration files store ordinary values; `simplify()` unwraps references. Serialized schemas preserve their field types, defaults, roles, and volatile marker for schema-driven forms. Existing settings consumers continue to use their own settings interfaces.
+
 ## Computed config values
 
 The loader used in this repo supports a `!!js` tag for config values that must be computed at load time:
diff --git a/docs/cordis-tutorial/05-config.zh.md b/docs/cordis-tutorial/05-config.zh.md
index e19dcb3ab0..65e9ea73a5 100644
--- a/docs/cordis-tutorial/05-config.zh.md
+++ b/docs/cordis-tutorial/05-config.zh.md
@@ -67,6 +67,33 @@ ValidationError: invalid config:
 
 插件的 fiber 进入 FAILED 状态，本教程的启动器打印错误后以状态码 1 退出。如果某个插件的配置通过了 schema 验证，但其中指定的资源或提供方不可用，该插件也应当在能解析该引用时立即拒绝。
 
+<a id="volatile-fields"></a>
+## Volatile 字段
+
+对于插件在每次操作中读取的字段，可以使用 `.volatile()`。字段变化会更新稳定引用，无需重新挂载插件。通过 `.get()` 读取：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import Schema from '@deepseek-ai/schemastery'
+
+export const Config = Schema.object({
+  greeting: Schema.string().default('Hello').volatile(),
+})
+
+export function apply(ctx: Context, config: ReturnType<typeof Config>) {
+  ctx.on('loader/volatile-update', () => {
+    console.log(config.greeting.get())
+  })
+}
+```
+
+直接调用 `Config(raw)` 也会返回引用。没有默认值的可选字段仍然具有引用；字段缺省时，`.get()` 返回 `undefined`。可以保存引用，也可以在单次操作中保存读取值，包括跨越 `await`，但不能将该值用于后续操作。对象和数组值是脱离输入、递归冻结的普通数据快照；函数、类实例和循环引用会被拒绝。
+
+Loader 比较原始配置时忽略 schema 声明的 volatile 字段。仅 volatile 变化会经目标插件的 `internal/config` 钩子解析并校验；当所有普通字段的有效值仍然一致时，Loader 把新值提交到运行中的引用，并向所属实例发出一次 `loader/volatile-update`，参数是以键数组表示的变化路径，不进入目标插件的 `internal/update`。等值更新不通知。无效候选会记录日志，运行中的引用保持不变，直到下次激活。普通字段有效值变化（包括表达式求值结果变化）以及普通字段同时变化时沿用原更新流程，旧引用不更新也不接收通知。Group/Include 仍分发子条目更新。直接 `fiber.update()`、代码替换和依赖替换保留原有生命周期；`noSave` 仍控制直接更新的持久化。通知使用普通 `emit`，不等待资源重新配置完成。
+
+在固定对象路径上声明 volatile 字段，或将整个对象、数组标记为 volatile。数组、字典、union 或 intersect 分支、lazy、transform 或另一个 volatile 值内部的独立引用会被拒绝。配置文件保存普通值；`simplify()` 会解包引用。序列化 schema 保留字段类型、默认值、角色和 volatile 标记，供基于 schema 的表单使用。现有 settings 消费者继续使用原有 settings 接口。
+
 ## 计算得到的配置值
 
 本仓库使用的 loader 支持 `!!js` 标签，用于必须在加载时计算的配置值：
diff --git a/docs/deepseek-llm-api-wire-extensions.i18n.yaml b/docs/deepseek-llm-api-wire-extensions.i18n.yaml
index 7329ae0f17..547583134d 100644
--- a/docs/deepseek-llm-api-wire-extensions.i18n.yaml
+++ b/docs/deepseek-llm-api-wire-extensions.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/deepseek-llm-api-wire-extensions.md
-deepseek-llm-api-wire-extensions.md: f45508f375d3e624b4d5eded26393a737c3a0907
-deepseek-llm-api-wire-extensions.zh.md: ff72d62a9cdc2a33f6d6fd5fb08975b73839cae7
+deepseek-llm-api-wire-extensions.md: 47ecc9db5438d5992f3b84c1ba3cc9b15561dc2b
+deepseek-llm-api-wire-extensions.zh.md: d79f97fc3a029cce04801cdf58eb713007b2eb43
diff --git a/docs/deepseek-llm-api-wire-extensions.md b/docs/deepseek-llm-api-wire-extensions.md
index f45508f375..47ecc9db54 100644
--- a/docs/deepseek-llm-api-wire-extensions.md
+++ b/docs/deepseek-llm-api-wire-extensions.md
@@ -2,7 +2,7 @@
 
 English | [中文](deepseek-llm-api-wire-extensions.zh.md)
 
-This reference defines every DeepSeek Harness-specific HTTP header and additive JSON field sent by [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.md) on `deepseek-official` Messages and Chat Completions requests. It does not redefine fields owned by the upstream DeepSeek API. The provider-neutral LLM interface and `llm-pi-ai` do not implement these additions.
+This reference defines every DeepSeek Harness-specific HTTP header and additive JSON field sent by [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.md) on `deepseek-official` Messages requests. It does not redefine fields owned by the upstream DeepSeek API. The provider-neutral LLM interface and `llm-pi-ai` do not implement these additions.
 
 The adapter sends the additions to its resolved `baseURL`, including a configured gateway. They remain outside `messages`, system prompts, and tool schemas, so they do not add model-input tokens or alter the model-visible prefix.
 
diff --git a/docs/deepseek-llm-api-wire-extensions.zh.md b/docs/deepseek-llm-api-wire-extensions.zh.md
index ff72d62a9c..d79f97fc3a 100644
--- a/docs/deepseek-llm-api-wire-extensions.zh.md
+++ b/docs/deepseek-llm-api-wire-extensions.zh.md
@@ -2,7 +2,7 @@
 
 [English](deepseek-llm-api-wire-extensions.md) | 中文
 
-本参考文档定义 [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.zh.md) 在 `deepseek-official` Messages 与 Chat Completions 请求中发送的全部 DeepSeek Harness 特有 HTTP 标头和附加 JSON 字段。本文不重复定义 DeepSeek 上游 API 持有的字段。提供方无关的 LLM（大语言模型）接口与 `llm-pi-ai` 均不实现这些扩展。
+本参考定义 [`@deepseek-ai/dsh-llm-deepseek`](../packages/llm/llm-deepseek/README.zh.md) 在 `deepseek-official` Messages 请求中发送的全部 DeepSeek Harness 专用 HTTP 标头与附加 JSON 字段。它不重新定义上游 DeepSeek API 自有字段。提供方无关的 LLM 接口与 `llm-pi-ai` 不实现这些扩展。
 
 适配器将这些扩展发送至已解析的 `baseURL`，包括已配置的网关。扩展位于 `messages`、系统提示词和工具 schema 之外，因此不会增加模型输入 token，也不会改变模型可见前缀。
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 8959b05a1d..fd6198a8ca 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/development.md
-development.md: ce8f1e7746562e696c96e6359ec9fcfde596d6e2
-development.zh.md: 85e95946dfd7210201f0807880d5ed1a92859356
+development.md: 7e8d0ded70ca880ce986cb3879d959fbe2a04304
+development.zh.md: 84d0d76d8c76f829c0ed928d28336df3e58ed7f0
diff --git a/docs/development.md b/docs/development.md
index ce8f1e7746..7e8d0ded70 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -83,7 +83,7 @@ Both tsdown passes use the same complete workspace match. They neither scan buil
 
 Typert runs only during Host tsdown, seeded by `tsconfig.host.json`. It analyzes Host types and generates both Host reflection artifacts and the Host-for-Client Remote projection; Client tsdown does not start Typert. Consequently, `pnpm run typecheck` runs the complete Host lib phase before Client tsc, while `pnpm run build` continues through Client tsdown and the Web build.
 
-`pnpm run build` embeds the root package version, the seven-character source commit, and a dirty marker when Git reports local changes; it also inherits other caller-supplied `DSH_CLIENT_*` values. `pnpm run build:official` is the cross-platform local equivalent of the CI and release artifact build and omits the local dirty marker. Each successful complete build writes a gitignored record that binds the exact public values to the Vite output and dynamic client bundles; release packing and built Web tests reject a missing record or artifacts changed by a later partial build. `pnpm run dev:web` still requires the artifact tree from a prior complete build, but it samples the current version and Git state once at startup and shares that environment across every watcher stage for the session; it does not validate the complete-build record because the watcher stages rewrite its recorded artifacts.
+`pnpm run build` embeds the root package version, the seven-character source commit, and a dirty marker when Git reports local changes; it also inherits other caller-supplied `DSH_CLIENT_*` values. `pnpm run build:official` is the cross-platform local equivalent of the CI and release artifact build and omits the local dirty marker. Each successful complete build writes a gitignored record that binds the exact public values to the Vite output and dynamic client bundles; release packing and built Web tests reject a missing record or artifacts changed by a later partial build. `pnpm run dev:web` runs that complete build first (`--skip-build` reuses an existing artifact tree instead), then samples the current version and Git state once and shares that environment across every watcher stage for the session; it does not validate the complete-build record because the watcher stages rewrite its recorded artifacts.
 
 Static analysis and tests resolve workspace imports through the base `paths` map to `src` and must pass on a clean tree; gates that consume built `lib/` output declare that dependency explicitly. Generated Host-for-Client Remote declarations are the deliberate exception: the public `typecheck`, `lint`, and `doc-typecheck` commands generate them first, while internal `*:contracts-ready` scripts assume that an invoking public command or scheduler gate already depends on the Typert contract-generation pass or the complete build. See the [ts-build-config note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.md) for tsc-first emit ownership and the [Typert Remote note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) for the gate-preparation contract.
 
@@ -156,6 +156,19 @@ The PTC mode demo runs the same headless profile with code presentation enabled:
 pnpm run demo:ptc -- "summarize this workspace"
 ```
 
+### Application commands
+
+Web and Desktop share one command pair. `start:*` launches the artifacts of a prior `pnpm run build`; `dev:*` runs that build first and then launches. Web additionally keeps client bundles rebuilt on source edits, because its Host runs from source while the browser loads built bundles:
+
+```sh
+pnpm run start:web       # serve built Web artifacts through the source launcher (the same launch as pnpm dsh web)
+pnpm run dev:web         # build, serve, and rebuild Web client bundles on source edits
+pnpm run start:desktop   # launch built Desktop artifacts
+pnpm run dev:desktop     # build, then launch Desktop
+```
+
+Arguments after a Web command reach `dsh web`, for example `pnpm run dev:web --no-open --port 3081`; `dev:web` also accepts `--skip-build` to reuse the existing artifact tree and `--no-serve` to run only the rebuild watchers beside a server started elsewhere. Both Web commands use the normal Harness home, while the Desktop commands use the isolated development home described in the [Desktop README](../apps/desktop/README.md). The root `Makefile` names the same commands as `make web`, `make dev-web`, `make desktop`, `make dev-desktop`, and `make build`; `ARGS='--no-open'` forwards options.
+
 ### TODO markers
 
 Use one of three comment tags to flag known issues in the code, ordered by urgency:
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 85e95946df..84d0d76d8c 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -87,7 +87,7 @@ pnpm run build:web
 
 Typert 只在 Host tsdown 中以 `tsconfig.host.json` 为种子运行。它分析 Host 类型并生成 Host 反射产物及 Host-for-Client Remote 投影；Client tsdown 不启动 Typert。`pnpm run typecheck` 因此先执行完整 Host lib 阶段，再运行 Client tsc；`pnpm run build` 继续执行 Client tsdown 和 Web 构建。
 
-`pnpm run build` 会内联根包版本、七位源码 commit，并在 Git 报告本地变化时内联 dirty 标记；调用方提供的其他 `DSH_CLIENT_*` 值也会被继承。`pnpm run build:official` 是与 CI 和 release 产物构建等价的跨平台本地命令，并省略本地 dirty 标记。每次完整构建成功后都会写入一份被 gitignore 的记录，把精确公开值与 Vite 输出及动态 client bundle 绑定；release 打包和 built Web 测试会拒绝缺少记录或被后续局部构建改动的产物。`pnpm run dev:web` 仍需要先执行完整构建来准备产物树，但会在启动时读取一次当前版本和 Git 状态，并在本次会话的所有 watcher stage 之间共享该环境；它不会校验完整构建记录，因为 watcher stage 会重写记录覆盖的产物。
+`pnpm run build` 会内联根包版本、七位源码 commit，并在 Git 报告本地变化时内联 dirty 标记；调用方提供的其他 `DSH_CLIENT_*` 值也会被继承。`pnpm run build:official` 是与 CI 和 release 产物构建等价的跨平台本地命令，并省略本地 dirty 标记。每次完整构建成功后都会写入一份被 gitignore 的记录，把精确公开值与 Vite 输出及动态 client bundle 绑定；release 打包和 built Web 测试会拒绝缺少记录或被后续局部构建改动的产物。`pnpm run dev:web` 会先执行这次完整构建（`--skip-build` 则复用现有产物树），再读取一次当前版本和 Git 状态，并在本次会话的所有 watcher stage 之间共享该环境；它不会校验完整构建记录，因为 watcher stage 会重写记录覆盖的产物。
 
 静态分析和测试通过 base 的 `paths` 映射把工作区 import 解析到 `src`，且必须在干净树上通过；消费构建产物 `lib/` 的门禁显式声明该依赖。生成的 Host-for-Client Remote 声明是有意设置的例外：公共 `typecheck`、`lint` 和 `doc-typecheck` 命令会先生成这些声明，而内部 `*:contracts-ready` 脚本假定调用它的公共命令或调度器门禁已经依赖 Typert 约定生成阶段或完整构建。tsc-first 发射职责见 [ts-build-config Note](../.agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md)，门禁准备约定见 [Typert Remote Agent Note](../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)。
 
@@ -160,6 +160,19 @@ PTC mode 演示启用代码式工具展示，并运行同一个 headless profile
 pnpm run demo:ptc -- "summarize this workspace"
 ```
 
+### 应用命令
+
+Web 与 Desktop 共用同一对命令。`start:*` 启动上一次 `pnpm run build` 的产物；`dev:*` 先执行该构建再启动。Web 还会在源码修改时持续重建 client bundle，因为它的 Host 从源码运行，而浏览器加载的是构建产物：
+
+```sh
+pnpm run start:web       # serve built Web artifacts through the source launcher (the same launch as pnpm dsh web)
+pnpm run dev:web         # build, serve, and rebuild Web client bundles on source edits
+pnpm run start:desktop   # launch built Desktop artifacts
+pnpm run dev:desktop     # build, then launch Desktop
+```
+
+Web 命令后面的参数会传给 `dsh web`，例如 `pnpm run dev:web --no-open --port 3081`；`dev:web` 还接受 `--skip-build` 复用现有产物树，以及 `--no-serve` 只运行重建 watcher、配合别处启动的服务器。两个 Web 命令使用正常的 Harness home，而 Desktop 命令使用 [Desktop README](../apps/desktop/README.zh.md) 描述的隔离开发 home。根目录 `Makefile` 以 `make web`、`make dev-web`、`make desktop`、`make dev-desktop` 和 `make build` 命名同一套命令；`ARGS='--no-open'` 用于转发参数。
+
 ### TODO 标记
 
 请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index f4e736efa4..bb2e2b647b 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
-event-producer-consumer.md: 0fa3e7ffaae73a714bcffc6b7f8cd69e24f5e0c4
-event-producer-consumer.zh.md: 9f14a99ad80959be9963821100a6228700eca2b8
+event-producer-consumer.md: 2b373821a2d0c9acf2284c4195a928947700f1ce
+event-producer-consumer.zh.md: 90ca2a4c76ac477265a60dad80c5f65d04509e90
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 0fa3e7ffaa..2b373821a2 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -21,16 +21,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:353`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:280`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:381`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-changes`](../packages/deliverables/workspace-changes) |
-| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:614`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:594`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:621`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:600`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:607`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:603`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:583`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:610`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:589`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:596`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
 | `compaction/summary-error` | `waterfall` | [`packages/compaction/compaction/src/index.ts:106`](../packages/compaction/compaction/src/index.ts) | [`compaction-basic`](../packages/compaction/compaction-basic) (`waterfall`) | [`compaction-image-offload`](../packages/compaction/compaction-image-offload) |
-| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:62`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
+| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:67`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
@@ -41,9 +41,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:90`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`credentials`](../packages/credentials/credentials), `remotes` |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` |
 | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:58`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) |
-| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
-| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` |
-| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
+| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
+| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` |
+| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) |
 | `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:150`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) |
 | `hmr/change` | `emit` | [`packages/boot/hmr/src/index.ts:30`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 9f14a99ad8..90ca2a4c76 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -23,16 +23,16 @@
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/runtime-types.ts:353`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compaction-basic`](../packages/compaction/compaction-basic), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:280`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:381`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-changes`](../packages/deliverables/workspace-changes) |
-| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:614`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:594`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:621`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:600`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
-| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:607`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:617`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:597`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:624`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:603`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
+| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:610`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` |
 | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` |
 | `compaction/summary-error` | `waterfall` | [`packages/compaction/compaction/src/index.ts:106`](../packages/compaction/compaction/src/index.ts) | [`compaction-basic`](../packages/compaction/compaction-basic) (`waterfall`) | [`compaction-image-offload`](../packages/compaction/compaction-image-offload) |
-| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:62`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
+| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:67`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - |
 | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
 | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` |
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index feb1c96792..bab89e6efd 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -150,7 +150,7 @@
 | merge | 合并 | | | |
 | message | 消息 | | | |
 | mod | 模组 | | | |
-| model provider | 模型提供方 | | | |
+| model provider | 模型提供商 | | | 指为模型提供 API 的厂商或网关：模型设置页文案、用户指南 providers 与 `ui-settings-models` README 用「提供商」；llm seam 的开发者文档（可配置提供方目录、dormant 等）沿用「提供方」 |
 | model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |
 | module | 模块 | | | |
 | non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |
@@ -168,7 +168,7 @@
 | plugin | 插件 | | | |
 | postmortem | 事故复盘 | 事故复盘（postmortem） | 事后分析、事故记录 | 事故记录与分析文档；目录或路径中的 `postmortem` 保持代码形式 |
 | prompt | 提示词 | | | |
-| provider | 提供方 | | | |
+| provider | 提供方 | | | 泛指的提供方（搜索、检查、settings 文件、subagent 等）；模型厂商或网关见 model provider 行 |
 | provider-neutral | 提供方无关 | | 提供方中立 | |
 | quality gate | 质量门禁 | | | |
 | quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 |
diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml
index d0a861e280..e22d460cd0 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: 03ca817a5b83a0e8795a86d123d4ec6a48b17366
-module-graph.zh.md: 6efdbea22497754f8510f70127ed0515ec2aecd0
+module-graph.md: af297ec0b0d143ad8917eac00e2faf44f3477b5d
+module-graph.zh.md: f56bdc422d9e74d922cb015c9d35e020cbd69b89
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 03ca817a5b..af297ec0b0 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -65,6 +65,7 @@ flowchart TD
     pkg_skill_filesystem["skill-filesystem"]
     pkg_skill_office["skill-office"]
     pkg_tool_skill["tool-skill"]
+    pkg_tool_workspace_dependencies["tool-workspace-dependencies"]
   end
   subgraph group_subagent["packages/subagent"]
     pkg_subagent["subagent"]
@@ -113,6 +114,7 @@ flowchart TD
   end
   subgraph group_api["packages/api"]
     pkg_api_gateway["api-gateway"]
+    pkg_api_job_controller["api-job-controller"]
     pkg_api_remotes["api-remotes"]
     pkg_api_session_controller["api-session-controller"]
     pkg_api_settings_controller["api-settings-controller"]
@@ -413,16 +415,11 @@ flowchart TD
   pkg_credentials --> pkg_invariants
   pkg_experimental_inspector --> pkg_client_modules
   pkg_experimental_inspector --> pkg_host_webserver
-  pkg_experimental_webworker_runtime --> pkg_client_connection
-  pkg_experimental_webworker_runtime --> pkg_client_modules
-  pkg_experimental_webworker_runtime --> pkg_host_webserver
   pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse
   pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native
   pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
   pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
   pkg_host_directory_picker_auto --> pkg_host_webserver
-  pkg_host_frontend_static --> pkg_client_connection
-  pkg_host_frontend_static --> pkg_host_webserver
   pkg_anonymous_user_id --> pkg_brand
   pkg_anonymous_user_id --> pkg_home_paths
   pkg_lsp --> pkg_brand
@@ -432,6 +429,7 @@ flowchart TD
   pkg_storage_json --> pkg_storage
   pkg_storage_sqlite --> pkg_storage
   pkg_subprocess --> pkg_http_proxy
+  pkg_remote_mock --> pkg_typert_protocol
   pkg_typert_loader --> pkg_typert_registry
   pkg_session --> pkg_scope
   pkg_system_prompt --> pkg_invariants
@@ -450,6 +448,7 @@ flowchart TD
   pkg_api_terminal_controller --> pkg_subprocess
   pkg_attachment_local --> pkg_attachment
   pkg_attachment_local --> pkg_home_paths
+  pkg_client_connection --> pkg_scope
   pkg_client_file_upload --> pkg_scope
   pkg_authorization --> pkg_credentials
   pkg_authorization --> pkg_invariants
@@ -467,9 +466,15 @@ flowchart TD
   pkg_spill --> pkg_brand
   pkg_spill --> pkg_llm
   pkg_spill --> pkg_session
+  pkg_api_gateway --> pkg_client_connection
   pkg_app_boot --> pkg_home_paths
   pkg_app_boot --> pkg_launch_environment
   pkg_app_boot --> pkg_system_prompt
+  pkg_experimental_webworker_runtime --> pkg_client_connection
+  pkg_experimental_webworker_runtime --> pkg_client_modules
+  pkg_experimental_webworker_runtime --> pkg_host_webserver
+  pkg_host_frontend_static --> pkg_client_connection
+  pkg_host_frontend_static --> pkg_host_webserver
   pkg_persona --> pkg_system_prompt
   pkg_sandbox --> pkg_llm
   pkg_sandbox --> pkg_session
@@ -776,6 +781,7 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
+  pkg_tool_workspace_dependencies --> pkg_tools
   pkg_tool_web --> pkg_llm
   pkg_tool_web --> pkg_system_prompt
   pkg_tool_web --> pkg_tools
@@ -988,7 +994,6 @@ flowchart TD
   pkg_experimental_auto_review --> pkg_tools
   pkg_tool_cordis --> pkg_agent
   pkg_tool_cordis --> pkg_cordis_host_runner
-  pkg_tool_cordis --> pkg_system_prompt
   pkg_tool_cordis --> pkg_tools
   pkg_host_plugin_inventory --> pkg_agent_presets
   pkg_host_plugin_inventory --> pkg_brand
@@ -1175,7 +1180,6 @@ flowchart TD
   pkg_api_session_controller --> pkg_commands
   pkg_api_session_controller --> pkg_file_reference
   pkg_api_session_controller --> pkg_fs
-  pkg_api_session_controller --> pkg_jobs
   pkg_api_session_controller --> pkg_llm
   pkg_api_session_controller --> pkg_native_command
   pkg_api_session_controller --> pkg_scope
@@ -1320,14 +1324,13 @@ flowchart TD
 | [`util-workspace-path`](../packages/util/workspace-path) | `util` | — |
 | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — |
 | [`llm`](../packages/llm/llm) | `llm` | — |
-| [`api-gateway`](../packages/api/gateway) | `api` | — |
+| [`api-job-controller`](../packages/api/job-controller) | `api` | — |
 | [`api-workspace-files`](../packages/api/workspace-files) | `api` | — |
 | [`cmdline`](../packages/boot/cmdline) | `boot` | — |
 | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — |
 | [`base`](../packages/bundle/base) | `bundle` | — |
 | [`sdk-app`](../packages/bundle/sdk-app) | `bundle` | — |
 | [`sdk-minimal`](../packages/bundle/sdk-minimal) | `bundle` | — |
-| [`client-connection`](../packages/client/connection) | `client` | — |
 | [`client-hmr`](../packages/client/hmr) | `client` | — |
 | [`client-locale`](../packages/client/locale) | `client` | — |
 | [`client-modules`](../packages/client/modules) | `client` | — |
@@ -1399,7 +1402,6 @@ flowchart TD
 | [`storage`](../packages/storage/storage) | `storage` | — |
 | [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | — |
 | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | — |
-| [`remote-mock`](../packages/test-support/remote-mock) | `test-support` | — |
 | [`typert-generator`](../packages/typert/generator) | `typert` | — |
 | [`typert-protocol`](../packages/typert/protocol) | `typert` | — |
 | [`typert-registry`](../packages/typert/registry) | `typert` | — |
@@ -1410,15 +1412,14 @@ flowchart TD
 | [`computer-use`](../packages/computer-use/computer-use) | `computer-use` | [`brand`](../packages/util/brand) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) |
-| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver) |
-| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver) |
 | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`storage`](../packages/storage/storage) |
 | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`storage`](../packages/storage/storage) |
 | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`http-proxy`](../packages/util/http-proxy) |
+| [`remote-mock`](../packages/test-support/remote-mock) | `test-support` | [`typert-protocol`](../packages/typert/protocol) |
 | [`typert-loader`](../packages/typert/loader) | `typert` | [`typert-registry`](../packages/typert/registry) |
 | [`session`](../packages/core/session) | `core` | [`scope`](../packages/core/scope) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
@@ -1429,6 +1430,7 @@ flowchart TD
 | [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) |
 | [`api-terminal-controller`](../packages/api/terminal-controller) | `api` | [`subprocess`](../packages/subprocess/subprocess) |
 | [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths) |
+| [`client-connection`](../packages/client/connection) | `client` | [`scope`](../packages/core/scope) |
 | [`client-file-upload`](../packages/client/file-upload) | `client` | [`scope`](../packages/core/scope) |
 | [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment) |
@@ -1438,7 +1440,10 @@ flowchart TD
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`skill`](../packages/skill/skill) |
 | [`skill-office`](../packages/skill/skill-office) | `skill` | [`skill`](../packages/skill/skill) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection) |
 | [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) |
+| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) |
+| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver) |
 | [`persona`](../packages/preset/persona) | `preset` | [`system-prompt`](../packages/core/system-prompt) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-format-catalog`](../packages/session/session-format-catalog) | `session` | [`session`](../packages/core/session) |
@@ -1509,6 +1514,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
+| [`tool-workspace-dependencies`](../packages/skill/tool-workspace-dependencies) | `skill` | [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
 | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
@@ -1550,7 +1556,7 @@ flowchart TD
 | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
 | [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) |
 | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) |
 | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-resources`](../packages/mcp/mcp-resources), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
@@ -1577,7 +1583,7 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
+| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
 | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`spill`](../packages/spill/spill), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
 | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index 6efdbea224..f56bdc422d 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -67,6 +67,7 @@ flowchart TD
     pkg_skill_filesystem["skill-filesystem"]
     pkg_skill_office["skill-office"]
     pkg_tool_skill["tool-skill"]
+    pkg_tool_workspace_dependencies["tool-workspace-dependencies"]
   end
   subgraph group_subagent["packages/subagent"]
     pkg_subagent["subagent"]
@@ -115,6 +116,7 @@ flowchart TD
   end
   subgraph group_api["packages/api"]
     pkg_api_gateway["api-gateway"]
+    pkg_api_job_controller["api-job-controller"]
     pkg_api_remotes["api-remotes"]
     pkg_api_session_controller["api-session-controller"]
     pkg_api_settings_controller["api-settings-controller"]
@@ -415,16 +417,11 @@ flowchart TD
   pkg_credentials --> pkg_invariants
   pkg_experimental_inspector --> pkg_client_modules
   pkg_experimental_inspector --> pkg_host_webserver
-  pkg_experimental_webworker_runtime --> pkg_client_connection
-  pkg_experimental_webworker_runtime --> pkg_client_modules
-  pkg_experimental_webworker_runtime --> pkg_host_webserver
   pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse
   pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native
   pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse
   pkg_host_directory_picker_auto --> pkg_host_directory_picker_native
   pkg_host_directory_picker_auto --> pkg_host_webserver
-  pkg_host_frontend_static --> pkg_client_connection
-  pkg_host_frontend_static --> pkg_host_webserver
   pkg_anonymous_user_id --> pkg_brand
   pkg_anonymous_user_id --> pkg_home_paths
   pkg_lsp --> pkg_brand
@@ -434,6 +431,7 @@ flowchart TD
   pkg_storage_json --> pkg_storage
   pkg_storage_sqlite --> pkg_storage
   pkg_subprocess --> pkg_http_proxy
+  pkg_remote_mock --> pkg_typert_protocol
   pkg_typert_loader --> pkg_typert_registry
   pkg_session --> pkg_scope
   pkg_system_prompt --> pkg_invariants
@@ -452,6 +450,7 @@ flowchart TD
   pkg_api_terminal_controller --> pkg_subprocess
   pkg_attachment_local --> pkg_attachment
   pkg_attachment_local --> pkg_home_paths
+  pkg_client_connection --> pkg_scope
   pkg_client_file_upload --> pkg_scope
   pkg_authorization --> pkg_credentials
   pkg_authorization --> pkg_invariants
@@ -469,9 +468,15 @@ flowchart TD
   pkg_spill --> pkg_brand
   pkg_spill --> pkg_llm
   pkg_spill --> pkg_session
+  pkg_api_gateway --> pkg_client_connection
   pkg_app_boot --> pkg_home_paths
   pkg_app_boot --> pkg_launch_environment
   pkg_app_boot --> pkg_system_prompt
+  pkg_experimental_webworker_runtime --> pkg_client_connection
+  pkg_experimental_webworker_runtime --> pkg_client_modules
+  pkg_experimental_webworker_runtime --> pkg_host_webserver
+  pkg_host_frontend_static --> pkg_client_connection
+  pkg_host_frontend_static --> pkg_host_webserver
   pkg_persona --> pkg_system_prompt
   pkg_sandbox --> pkg_llm
   pkg_sandbox --> pkg_session
@@ -778,6 +783,7 @@ flowchart TD
   pkg_tool_skill --> pkg_llm
   pkg_tool_skill --> pkg_skill
   pkg_tool_skill --> pkg_tools
+  pkg_tool_workspace_dependencies --> pkg_tools
   pkg_tool_web --> pkg_llm
   pkg_tool_web --> pkg_system_prompt
   pkg_tool_web --> pkg_tools
@@ -990,7 +996,6 @@ flowchart TD
   pkg_experimental_auto_review --> pkg_tools
   pkg_tool_cordis --> pkg_agent
   pkg_tool_cordis --> pkg_cordis_host_runner
-  pkg_tool_cordis --> pkg_system_prompt
   pkg_tool_cordis --> pkg_tools
   pkg_host_plugin_inventory --> pkg_agent_presets
   pkg_host_plugin_inventory --> pkg_brand
@@ -1177,7 +1182,6 @@ flowchart TD
   pkg_api_session_controller --> pkg_commands
   pkg_api_session_controller --> pkg_file_reference
   pkg_api_session_controller --> pkg_fs
-  pkg_api_session_controller --> pkg_jobs
   pkg_api_session_controller --> pkg_llm
   pkg_api_session_controller --> pkg_native_command
   pkg_api_session_controller --> pkg_scope
@@ -1322,14 +1326,13 @@ flowchart TD
 | [`util-workspace-path`](../packages/util/workspace-path) | `util` | — |
 | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — |
 | [`llm`](../packages/llm/llm) | `llm` | — |
-| [`api-gateway`](../packages/api/gateway) | `api` | — |
+| [`api-job-controller`](../packages/api/job-controller) | `api` | — |
 | [`api-workspace-files`](../packages/api/workspace-files) | `api` | — |
 | [`cmdline`](../packages/boot/cmdline) | `boot` | — |
 | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — |
 | [`base`](../packages/bundle/base) | `bundle` | — |
 | [`sdk-app`](../packages/bundle/sdk-app) | `bundle` | — |
 | [`sdk-minimal`](../packages/bundle/sdk-minimal) | `bundle` | — |
-| [`client-connection`](../packages/client/connection) | `client` | — |
 | [`client-hmr`](../packages/client/hmr) | `client` | — |
 | [`client-locale`](../packages/client/locale) | `client` | — |
 | [`client-modules`](../packages/client/modules) | `client` | — |
@@ -1401,7 +1404,6 @@ flowchart TD
 | [`storage`](../packages/storage/storage) | `storage` | — |
 | [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | — |
 | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | — |
-| [`remote-mock`](../packages/test-support/remote-mock) | `test-support` | — |
 | [`typert-generator`](../packages/typert/generator) | `typert` | — |
 | [`typert-protocol`](../packages/typert/protocol) | `typert` | — |
 | [`typert-registry`](../packages/typert/registry) | `typert` | — |
@@ -1412,15 +1414,14 @@ flowchart TD
 | [`computer-use`](../packages/computer-use/computer-use) | `computer-use` | [`brand`](../packages/util/brand) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`invariants`](../packages/runtime-diagnostics/invariants) |
 | [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) |
-| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver) |
-| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver) |
 | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths) |
 | [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`storage`](../packages/storage/storage) |
 | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`storage`](../packages/storage/storage) |
 | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`http-proxy`](../packages/util/http-proxy) |
+| [`remote-mock`](../packages/test-support/remote-mock) | `test-support` | [`typert-protocol`](../packages/typert/protocol) |
 | [`typert-loader`](../packages/typert/loader) | `typert` | [`typert-registry`](../packages/typert/registry) |
 | [`session`](../packages/core/session) | `core` | [`scope`](../packages/core/scope) |
 | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
@@ -1431,6 +1432,7 @@ flowchart TD
 | [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) |
 | [`api-terminal-controller`](../packages/api/terminal-controller) | `api` | [`subprocess`](../packages/subprocess/subprocess) |
 | [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths) |
+| [`client-connection`](../packages/client/connection) | `client` | [`scope`](../packages/core/scope) |
 | [`client-file-upload`](../packages/client/file-upload) | `client` | [`scope`](../packages/core/scope) |
 | [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) |
 | [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment) |
@@ -1440,7 +1442,10 @@ flowchart TD
 | [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`skill`](../packages/skill/skill) |
 | [`skill-office`](../packages/skill/skill-office) | `skill` | [`skill`](../packages/skill/skill) |
 | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`api-gateway`](../packages/api/gateway) | `api` | [`client-connection`](../packages/client/connection) |
 | [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) |
+| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver) |
+| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver) |
 | [`persona`](../packages/preset/persona) | `preset` | [`system-prompt`](../packages/core/system-prompt) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`session-format-catalog`](../packages/session/session-format-catalog) | `session` | [`session`](../packages/core/session) |
@@ -1511,6 +1516,7 @@ flowchart TD
 | [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
+| [`tool-workspace-dependencies`](../packages/skill/tool-workspace-dependencies) | `skill` | [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
 | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) |
@@ -1552,7 +1558,7 @@ flowchart TD
 | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) |
 | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) |
 | [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) |
 | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) |
 | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-resources`](../packages/mcp/mcp-resources), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
@@ -1579,7 +1585,7 @@ flowchart TD
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
+| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-file-upload`](../packages/client/file-upload), [`commands`](../packages/interaction/commands), [`file-reference`](../packages/context/file-reference), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-values`](../packages/util/values), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) |
 | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`spill`](../packages/spill/spill), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) |
 | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 251a673f01..60dba9fa9e 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: 4e62b69e07daf5809d6070bcc182b71305e70151
-persistence-catalog.zh.md: c001f06e98ac3b7e331044510639b73ec640eb85
+persistence-catalog.md: dd52352ecff33c833154a5aa933767f0b2544b4a
+persistence-catalog.zh.md: 71c0866cc2499ebaf573bc078ecb9f72a32ba128
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index 4e62b69e07..dd52352ecf 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -57,7 +57,7 @@ The [format references](persistence-changes/historical-formats/README.md) cover
 | `event:session/title-llm-request` | event | `fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d) |
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
-| `event:subagent/catalog` | event | `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871) |
+| `event:subagent/catalog` | event | `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -894,13 +894,13 @@ Source: [`packages/core/session/src/types.ts:299`](../packages/core/session/src/
 
 ```ts persistence-catalog
 /**
- * A direct child's complete discovery fact.
+ * A direct child's identity and available discovery fields.
  * @param data - versioned parent-owned catalog entry.
  */
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-Source: [`packages/subagent/subagent/src/catalog.ts:40`](../packages/subagent/subagent/src/catalog.ts)
+Source: [`packages/subagent/subagent/src/catalog.ts:43`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -2787,6 +2787,14 @@ SHA-256: `2c4c21f19f426a58f2dac914e34313aa43f8408972de857a486d1f086d5adb6c`
 
 `"unavailable"`
 
+<a id="persistence-type-sha256-05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04"></a>
+
+### `"unknown"`
+
+SHA-256: `05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04`
+
+`"unknown"`
+
 <a id="persistence-type-sha256-0bdaf9cb63594be4ef034b68901fffe792fe09d6d5f6bac42d7f56f6e7834fb9"></a>
 
 ### `"usage"`
@@ -4547,7 +4555,7 @@ One of:
 - [`{ type: "finish" }`](#persistence-type-sha256-a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1)
 - [`{ type: "usage" }`](#persistence-type-sha256-f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515)
 
-<a id="persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e"></a>
+<a id="persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0"></a>
 
 <a id="persistence-type-packagessubagentsubagentsrccatalogtssubagentcatalogevent"></a>
 
@@ -4555,14 +4563,17 @@ One of:
 
 ### `SubagentCatalogEvent`
 
-SHA-256: `3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e`
+SHA-256: `1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0`
 
-Sources: [`packages/subagent/subagent/src/catalog.ts:24`](../packages/subagent/subagent/src/catalog.ts)
+Sources: [`packages/subagent/subagent/src/catalog.ts:28`](../packages/subagent/subagent/src/catalog.ts)
 
 One of:
 
 - [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd)
+- [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187)
 - [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499)
 
 <a id="persistence-type-sha256-86d1d0e9cfebb240421187e3dc37fb71cc38a1501885cf32f8f9adef7b0a2bde"></a>
 
@@ -5304,7 +5315,7 @@ Array of `number`.
 
 SHA-256: `4cd48f3e5108bd6ebedf7301c3638839b8b2b9db8dbd493974177fbdeb91a01b`
 
-Sources: [`packages/api/session-controller/src/types.ts:394`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:20`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:10`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/webhook/webhook/src/brand.ts:12`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:6`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:9`](../packages/webhook/webhook/src/brand.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts)
+Sources: [`packages/api/session-controller/src/types.ts:396`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:20`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:10`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/webhook/webhook/src/brand.ts:12`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:6`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:9`](../packages/webhook/webhook/src/brand.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts)
 
 `string`
 
@@ -5612,6 +5623,20 @@ SHA-256: `0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd`
 | `mode` | required | `"continuable"` |
 | `version` | required | `0` |
 
+<a id="persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187"></a>
+
+### `{ childCreatedAt, childId, label, mode, … }`
+
+SHA-256: `e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187`
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | required | `string` |
+| `mode` | required | `"continuable"` |
+| `version` | required | `1` |
+
 <a id="persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694"></a>
 
 ### `{ childCreatedAt, childId, label?, mode, … }`
@@ -5626,6 +5651,34 @@ SHA-256: `5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694`
 | `mode` | required | `"one-shot"` |
 | `version` | required | `0` |
 
+<a id="persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499`
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | optional | `string` |
+| `mode` | required | `"unknown"` |
+| `version` | required | `1` |
+
+<a id="persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a`
+
+| Property | Presence | Type |
+|---|---|---|
+| `childCreatedAt` | required | `number` |
+| `childId` | required | `string` |
+| `label` | optional | `string` |
+| `mode` | required | `"one-shot"` |
+| `version` | required | `1` |
+
 <a id="persistence-type-sha256-a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735"></a>
 
 ### `{ code, name, reason? }`
@@ -7195,7 +7248,7 @@ Sources: [`packages/core/tools/src/index.ts:34`](../packages/core/tools/src/inde
 
 SHA-256: `6a4f72e2e179e17b922f2a9392c0e1c8f8c707f32494372454850a3eb184a6e7`
 
-Sources: [`packages/api/session-controller/src/types.ts:399`](../packages/api/session-controller/src/types.ts)
+Sources: [`packages/api/session-controller/src/types.ts:401`](../packages/api/session-controller/src/types.ts)
 
 | Property | Presence | Type |
 |---|---|---|
@@ -8221,17 +8274,17 @@ SHA-256: `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986`
 | `time` | required | `number` |
 | `type` | required | `"step/start"` |
 
-<a id="persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871"></a>
+<a id="persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"></a>
 
 <a id="persistence-type-eventsubagentcatalog"></a>
 
 ### `{ type: "subagent/catalog" }`
 
-SHA-256: `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871`
+SHA-256: `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604`
 
 | Property | Presence | Type |
 |---|---|---|
-| `data` | required | [`SubagentCatalogEvent`](#persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e) |
+| `data` | required | [`SubagentCatalogEvent`](#persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0) |
 | `ignorable` | optional | `true` |
 | `seq` | required | `number` |
 | `time` | required | `number` |
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index c001f06e98..71c0866cc2 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -59,7 +59,7 @@
 | `event:session/title-llm-request` | event | `fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d` | [`{ type: "session/title-llm-request" }`](#persistence-type-sha256-fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d) |
 | `event:step/end` | event | `e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05` | [`{ type: "step/end" }`](#persistence-type-sha256-e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05) |
 | `event:step/start` | event | `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986` | [`{ type: "step/start" }`](#persistence-type-sha256-4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986) |
-| `event:subagent/catalog` | event | `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871) |
+| `event:subagent/catalog` | event | `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604` | [`{ type: "subagent/catalog" }`](#persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604) |
 | `event:subagent/descriptor` | event | `b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5` | [`{ type: "subagent/descriptor" }`](#persistence-type-sha256-b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5) |
 | `event:subagent/model-selection-policy` | event | `a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc` | [`{ type: "subagent/model-selection-policy" }`](#persistence-type-sha256-a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc) |
 | `event:system/message` | event | `69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1` | [`{ type: "system/message" }`](#persistence-type-sha256-69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1) |
@@ -896,13 +896,13 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 ```ts persistence-catalog
 /**
- * A direct child's complete discovery fact.
+ * A direct child's identity and available discovery fields.
  * @param data - versioned parent-owned catalog entry.
  */
 'subagent/catalog': SubagentCatalogEvent
 ```
 
-来源：[`packages/subagent/subagent/src/catalog.ts:40`](../packages/subagent/subagent/src/catalog.ts)
+来源：[`packages/subagent/subagent/src/catalog.ts:43`](../packages/subagent/subagent/src/catalog.ts)
 
 <a id="subagentdescriptor--log-only"></a>
 
@@ -2789,6 +2789,14 @@ SHA-256: `2c4c21f19f426a58f2dac914e34313aa43f8408972de857a486d1f086d5adb6c`
 
 `"unavailable"`
 
+<a id="persistence-type-sha256-05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04"></a>
+
+### `"unknown"`
+
+SHA-256: `05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04`
+
+`"unknown"`
+
 <a id="persistence-type-sha256-0bdaf9cb63594be4ef034b68901fffe792fe09d6d5f6bac42d7f56f6e7834fb9"></a>
 
 ### `"usage"`
@@ -4549,7 +4557,7 @@ SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180`
 - [`{ type: "finish" }`](#persistence-type-sha256-a2b49331716ba0a7078b026d145306a70eae64b7313c3e6204bd931e75ec3bb1)
 - [`{ type: "usage" }`](#persistence-type-sha256-f1a96afe7503ac1817de769cd0ba13d9b80111c7034c50106b3344ecc14cc515)
 
-<a id="persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e"></a>
+<a id="persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0"></a>
 
 <a id="persistence-type-packagessubagentsubagentsrccatalogtssubagentcatalogevent"></a>
 
@@ -4557,14 +4565,17 @@ SHA-256: `47e9095591ae36e7c39ee62553097772f2bfa16304536a72dbbc3f691f605180`
 
 ### `SubagentCatalogEvent`
 
-SHA-256: `3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e`
+SHA-256: `1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0`
 
-来源：[`packages/subagent/subagent/src/catalog.ts:24`](../packages/subagent/subagent/src/catalog.ts)
+来源：[`packages/subagent/subagent/src/catalog.ts:28`](../packages/subagent/subagent/src/catalog.ts)
 
 以下类型之一：
 
 - [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd)
+- [`{ childCreatedAt, childId, label, mode, … }`](#persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187)
 - [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a)
+- [`{ childCreatedAt, childId, label?, mode, … }`](#persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499)
 
 <a id="persistence-type-sha256-86d1d0e9cfebb240421187e3dc37fb71cc38a1501885cf32f8f9adef7b0a2bde"></a>
 
@@ -5306,7 +5317,7 @@ SHA-256: `5d03ba38734809bcbd2a55221bd938b3b3fc34b49bb686c6113e9e4931e3aa78`
 
 SHA-256: `4cd48f3e5108bd6ebedf7301c3638839b8b2b9db8dbd493974177fbdeb91a01b`
 
-来源：[`packages/api/session-controller/src/types.ts:394`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:20`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:10`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/webhook/webhook/src/brand.ts:12`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:6`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:9`](../packages/webhook/webhook/src/brand.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts)
+来源：[`packages/api/session-controller/src/types.ts:396`](../packages/api/session-controller/src/types.ts) · [`packages/attachment/attachment/src/brand.ts:6`](../packages/attachment/attachment/src/brand.ts) · [`packages/compaction/compaction/src/brand.ts:4`](../packages/compaction/compaction/src/brand.ts) · [`packages/core/session/src/types.ts:20`](../packages/core/session/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:20`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:32`](../packages/experimental/agent-team/src/types.ts) · [`packages/experimental/agent-team/src/types.ts:8`](../packages/experimental/agent-team/src/types.ts) · [`packages/feedback/message-feedback/src/types.ts:14`](../packages/feedback/message-feedback/src/types.ts) · [`packages/goal/goal/src/types.ts:17`](../packages/goal/goal/src/types.ts) · [`packages/interaction/commands/src/brand.ts:31`](../packages/interaction/commands/src/brand.ts) · [`packages/interaction/user-approval/src/types.ts:17`](../packages/interaction/user-approval/src/types.ts) · [`packages/llm/llm-retry/src/brand.ts:4`](../packages/llm/llm-retry/src/brand.ts) · [`packages/llm/llm/src/brand.ts:16`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:31`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:43`](../packages/llm/llm/src/brand.ts) · [`packages/llm/llm/src/brand.ts:67`](../packages/llm/llm/src/brand.ts) · [`packages/schedule/schedule/src/types.ts:10`](../packages/schedule/schedule/src/types.ts) · [`packages/session/session-title/src/index.ts:42`](../packages/session/session-title/src/index.ts) · [`packages/session/session-title/src/types.ts:17`](../packages/session/session-title/src/types.ts) · [`packages/webhook/webhook/src/brand.ts:12`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:6`](../packages/webhook/webhook/src/brand.ts) · [`packages/webhook/webhook/src/brand.ts:9`](../packages/webhook/webhook/src/brand.ts) · [`packages/workflow/workflow/src/types.ts:13`](../packages/workflow/workflow/src/types.ts)
 
 `string`
 
@@ -5614,6 +5625,20 @@ SHA-256: `0e10d7c096b47e61defe372a5fc8bd37d835199410eac44367f95c45082498bd`
 | `mode` | 必需 | `"continuable"` |
 | `version` | 必需 | `0` |
 
+<a id="persistence-type-sha256-e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187"></a>
+
+### `{ childCreatedAt, childId, label, mode, … }`
+
+SHA-256: `e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 必需 | `string` |
+| `mode` | 必需 | `"continuable"` |
+| `version` | 必需 | `1` |
+
 <a id="persistence-type-sha256-5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694"></a>
 
 ### `{ childCreatedAt, childId, label?, mode, … }`
@@ -5628,6 +5653,34 @@ SHA-256: `5d542ac7bdf13310c46e1a884dec9fb18ad8c6e153cff207e639cd7bf9d7e694`
 | `mode` | 必需 | `"one-shot"` |
 | `version` | 必需 | `0` |
 
+<a id="persistence-type-sha256-a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 可选 | `string` |
+| `mode` | 必需 | `"unknown"` |
+| `version` | 必需 | `1` |
+
+<a id="persistence-type-sha256-b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a"></a>
+
+### `{ childCreatedAt, childId, label?, mode, … }`
+
+SHA-256: `b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a`
+
+| 属性 | 存在性 | 类型 |
+|---|---|---|
+| `childCreatedAt` | 必需 | `number` |
+| `childId` | 必需 | `string` |
+| `label` | 可选 | `string` |
+| `mode` | 必需 | `"one-shot"` |
+| `version` | 必需 | `1` |
+
 <a id="persistence-type-sha256-a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735"></a>
 
 ### `{ code, name, reason? }`
@@ -7197,7 +7250,7 @@ SHA-256: `8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543`
 
 SHA-256: `6a4f72e2e179e17b922f2a9392c0e1c8f8c707f32494372454850a3eb184a6e7`
 
-来源：[`packages/api/session-controller/src/types.ts:399`](../packages/api/session-controller/src/types.ts)
+来源：[`packages/api/session-controller/src/types.ts:401`](../packages/api/session-controller/src/types.ts)
 
 | 属性 | 存在性 | 类型 |
 |---|---|---|
@@ -8223,17 +8276,17 @@ SHA-256: `4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986`
 | `time` | 必需 | `number` |
 | `type` | 必需 | `"step/start"` |
 
-<a id="persistence-type-sha256-ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871"></a>
+<a id="persistence-type-sha256-3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"></a>
 
 <a id="persistence-type-eventsubagentcatalog"></a>
 
 ### `{ type: "subagent/catalog" }`
 
-SHA-256: `ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871`
+SHA-256: `3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604`
 
 | 属性 | 存在性 | 类型 |
 |---|---|---|
-| `data` | 必需 | [`SubagentCatalogEvent`](#persistence-type-sha256-3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e) |
+| `data` | 必需 | [`SubagentCatalogEvent`](#persistence-type-sha256-1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0) |
 | `ignorable` | 可选 | `true` |
 | `seq` | 必需 | `number` |
 | `time` | 必需 | `number` |
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml b/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
new file mode 100644
index 0000000000..60ad1d8f73
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/persistence-changes/2026-09-20-unknown-child-catalog.md
+2026-09-20-unknown-child-catalog.md: ba729661d60856ff948854641a1520339ab30210
+2026-09-20-unknown-child-catalog.zh.md: 468b4c9a3d3afab56ec8a9b03359016c9c0307e0
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
new file mode 100644
index 0000000000..ba729661d6
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.md
@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-20-unknown-child-catalog
+
+English | [中文](2026-09-20-unknown-child-catalog.zh.md)
+
+## Summary
+
+Retain unreadable historical children in subagent/catalog with unknown mode.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-20-unknown-child-catalog
+baseline: false
+changes:
+  - root: "event:subagent/catalog"
+    previous: "2026-09-11-initial"
+    after: "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Catalog payload v0 remains unchanged. Payload v1 adds unknown mode, and current readers accept v0 and v1. Complete facts still use v0; migration emits v1 for unknown children. Existing logs need no rewrite, and the Session header remains V4. Older readers reject v1. The classifier allows higher event payload versions only when all old payload alternatives remain unchanged; same-version widening and removal of old readers stay breaking.
+
+<a id="verification"></a>
+## Verification
+
+Migration, restoration, projection, and Web regressions retain unknown membership and child-local errors. Classifier tests accept higher payload versions with preserved predecessors and reject same-version additions, invalid versions, changed or removed old alternatives, and header/surface changes.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
new file mode 100644
index 0000000000..14c4b254ad
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.schema.json
@@ -0,0 +1,250 @@
+{
+  "formatVersion": 2,
+  "roots": [
+    {
+      "key": "event:subagent/catalog",
+      "kind": "event",
+      "event": "subagent/catalog",
+      "surface": false,
+      "digest": "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 14,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 15,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "union",
+            "types": [
+              2,
+              7,
+              9,
+              11,
+              12
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog"
+          }
+        ]
+      }
+    }
+  ],
+  "types": []
+}
diff --git a/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
new file mode 100644
index 0000000000..468b4c9a3d
--- /dev/null
+++ b/docs/persistence-changes/2026-09-20-unknown-child-catalog.zh.md
@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-20-unknown-child-catalog
+
+[English](2026-09-20-unknown-child-catalog.md) | 中文
+
+## 概述
+
+在 subagent/catalog 中使用 unknown 模式保留不可读的历史子会话。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-20-unknown-child-catalog
+baseline: false
+changes:
+  - root: "event:subagent/catalog"
+    previous: "2026-09-11-initial"
+    after: "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+Catalog 载荷 v0 保持不变。载荷 v1 增加 unknown 模式，当前读取器支持 v0 和 v1。完整事实继续使用 v0；迁移为未知子会话写入 v1。已有日志无需改写，Session header 保持 V4。旧读取器拒绝 v1。分类器仅在所有旧载荷分支保持不变时允许增加更高的事件载荷版本；同版本扩展和移除旧版读取支持仍属于破坏性变更。
+
+<a id="verification"></a>
+## 验证
+
+迁移、恢复、投影和 Web 回归覆盖未知成员保留与子会话局部报错。分类器测试接受保留前代的更高载荷版本，并拒绝同版本新增、无效版本、旧分支修改或删除，以及 header/model-surface 变更。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。
diff --git a/docs/persistence-changes/README.i18n.yaml b/docs/persistence-changes/README.i18n.yaml
index 830e77b05e..c2d80f8829 100644
--- a/docs/persistence-changes/README.i18n.yaml
+++ b/docs/persistence-changes/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-changes/README.md
-README.md: 3fd95e48548fdb9c1d04330c2925096d072850d1
-README.zh.md: f4ab3b3d22b1aa2f7f5923e84fd4effc339874db
+README.md: 2f3d2dd50adee751d9dce9ab250649ae13e45521
+README.zh.md: d2cec933b2210cc5652a7aa6c725517e1baff948
diff --git a/docs/persistence-changes/README.md b/docs/persistence-changes/README.md
index 3fd95e4854..2f3d2dd50a 100644
--- a/docs/persistence-changes/README.md
+++ b/docs/persistence-changes/README.md
@@ -53,15 +53,18 @@ Every detected structural change requires an acknowledgement. Record creation an
 | Add an optional event-body property, including its complete subtree | `same-version` |
 | Make a required event-body property optional | `same-version` |
 | Add an ordinary event type | `same-version` |
+| Add a higher numeric `data.version` to an ordinary event while retaining every old payload alternative unchanged | `same-version` |
 | Add an explicitly qualified attribution kind to a user/developer source slot whose before and after schemas carry the same supported policy | `same-version` |
 | Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | `version-bump` |
 | Change the Session header or event envelope | `version-bump` |
 
 A finalized checkpoint protects the accepted baseline without replacing these compatibility rules. At V4, optional additions, ordinary events, and qualified attribution additions can receive new same-version records. Breaking differences require a higher writer version and an acknowledgement containing its own header increase. The accepted V4 record cannot be updated to reuse its original 3→4 transition.
 
+An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided all existing alternatives remain structurally unchanged. The reader must retain support for the old payloads; adding variants at an existing version, dropping old versions, and changing the Session header or envelope remain breaking. Older readers may reject the new payload version. The [catalog acknowledgement](2026-09-20-unknown-child-catalog.md) records one such transition.
+
 The extractor accepts an explicit `@persistenceSource` binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its `MessageSourceMap` entry with `@persistenceAttribution`. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal `kind` discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated breaking changes remain strict. Multiple context-form alternatives with the same wire kind form one group.
 
-A same-version explanation states why old records can omit the addition and why older readers can ignore it without changing replay. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
+A same-version explanation states how old records remain readable and how older readers handle new records. Optional additions explain why older readers can ignore them without changing replay; a new payload version records the older-reader rejection. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
 
 When a reader rejects a JSON property by name, declare the property as optional `never` and mark it with argument-free `@persistenceReserved`. The extractor retains the forbidden field, so allowing a JSON value later requires an existing-field type change. Required or JSON-valued properties cannot carry this marker. Unmarked optional `never` and `undefined` properties retain their existing omission behavior.
 
diff --git a/docs/persistence-changes/README.zh.md b/docs/persistence-changes/README.zh.md
index f4ab3b3d22..d2cec933b2 100644
--- a/docs/persistence-changes/README.zh.md
+++ b/docs/persistence-changes/README.zh.md
@@ -53,15 +53,18 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 | 添加可选事件体属性，包括其完整子树 | `same-version` |
 | 将必选事件体属性改为可选 | `same-version` |
 | 添加普通事件类型 | `same-version` |
+| 为普通事件增加更高的数字 `data.version`，并原样保留所有旧载荷分支 | `same-version` |
 | 在前后 schema 均带有相同受支持策略的 user/developer 消息源字段中，添加显式声明为归属信息的 kind | `same-version` |
 | 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `version-bump` |
 | 更改会话头或事件封装 | `version-bump` |
 
 定稿检查点保护已接受基线，不替换这些兼容性规则。在 V4 中，可选新增、普通事件及符合条件的归属 kind 新增可以使用新的同版本记录。破坏性差异要求更高的写入器版本，以及包含自身头版本递增的确认记录。不能更新已接受 V4 记录以复用其原有 3→4 转换。
 
+普通事件可增加具有必选、非负整数 `data.version` 的载荷分支，新版本必须高于所有已有载荷版本，且所有已有分支结构保持不变。读取器必须保留旧载荷支持；在已有版本中增加分支、移除旧版本，以及修改 Session header 或事件封装仍属于破坏性变更。旧读取器可能拒绝新载荷版本。[Catalog 确认记录](2026-09-20-unknown-child-catalog.zh.md) 记录了此类演进。
+
 提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 `@persistenceSource` 绑定，不会从未标记类型中推断绑定。生产者用 `@persistenceAttribution` 标记其 `MessageSourceMap` 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 `kind` 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关破坏性变更继续采用严格规则。同一 wire kind 的多个上下文形式分支归为一组。
 
-同版本说明须解释旧记录为何可以缺少新增内容，以及旧读取器为何可以忽略它而不改变回放。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
+同版本说明须解释旧记录如何保持可读，以及旧读取器如何处理新记录。可选新增须说明旧读取器为何可以忽略它而不改变回放；新增载荷版本须记录旧读取器的拒绝行为。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
 
 当读取器按属性名拒绝 JSON 字段时，将该属性声明为可选 `never`，并添加无参数的 `@persistenceReserved` 标记。提取器保留这一禁止字段，因此后续允许 JSON 值属于已有字段类型变更。必选属性或允许 JSON 值的属性不能携带该标记。未标记的可选 `never` 和 `undefined` 属性保留现有省略行为。
 
diff --git a/docs/persistence-changes/historical-formats/README.i18n.yaml b/docs/persistence-changes/historical-formats/README.i18n.yaml
index 15481ef915..1f6bfd547a 100644
--- a/docs/persistence-changes/historical-formats/README.i18n.yaml
+++ b/docs/persistence-changes/historical-formats/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-changes/historical-formats/README.md
-README.md: 9bcfaa1246a03446d4d4fc95dd19f9ca60196301
-README.zh.md: 1f17367beb484feaeb289a42b3e5de50d3139be5
+README.md: a1064e815879d709fe466441bb4e8441c10b3aae
+README.zh.md: 87c9d32fa6ca5248886dad663a926afc6983406f
diff --git a/docs/persistence-changes/historical-formats/README.md b/docs/persistence-changes/historical-formats/README.md
index 9bcfaa1246..a1064e8158 100644
--- a/docs/persistence-changes/historical-formats/README.md
+++ b/docs/persistence-changes/historical-formats/README.md
@@ -32,7 +32,7 @@ The index is generated from validated snapshots and the current writer constant.
 | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 583 |
+| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 587 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-changes/historical-formats/README.zh.md b/docs/persistence-changes/historical-formats/README.zh.md
index 1f17367beb..87c9d32fa6 100644
--- a/docs/persistence-changes/historical-formats/README.zh.md
+++ b/docs/persistence-changes/historical-formats/README.zh.md
@@ -32,7 +32,7 @@ description: "查找从 V0 到工作区写入器版本的每个 Session 格式
 | 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 |
 | 3 | PR #4320 | [V3](v3.zh.md) | [JSON](v3.schema.json) | 60 / 467 |
-| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 583 |
+| 4 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 62 / 587 |
 
 <!-- persistence-format-index:end -->
 
diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json
index db1c54ff38..c4e1c3b950 100644
--- a/docs/persistence-schema.json
+++ b/docs/persistence-schema.json
@@ -14850,7 +14850,7 @@
       "kind": "event",
       "event": "subagent/catalog",
       "surface": false,
-      "digest": "ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871",
+      "digest": "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604",
       "schema": {
         "root": 0,
         "nodes": [
@@ -14864,7 +14864,7 @@
               },
               {
                 "name": "ignorable",
-                "type": 9,
+                "type": 14,
                 "optional": true
               },
               {
@@ -14879,7 +14879,7 @@
               },
               {
                 "name": "type",
-                "type": 10,
+                "type": 15,
                 "optional": false
               }
             ],
@@ -14889,7 +14889,10 @@
             "kind": "union",
             "types": [
               2,
-              7
+              7,
+              9,
+              11,
+              12
             ]
           },
           {
@@ -14939,6 +14942,41 @@
             "kind": "literal",
             "value": 0
           },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 5,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
           {
             "kind": "object",
             "properties": [
@@ -14959,7 +14997,7 @@
               },
               {
                 "name": "mode",
-                "type": 8,
+                "type": 10,
                 "optional": false
               },
               {
@@ -14974,6 +15012,72 @@
             "kind": "literal",
             "value": "one-shot"
           },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
           {
             "kind": "literal",
             "value": true
@@ -21691,6 +21795,20 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "05a2796621b1ee6c03ef7abe560b25116bb4da4d592312117242a78415a32b04",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "literal",
+            "value": "unknown"
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "05d2ae1e0c7f8770f83f9a09047afb39a335d8ac986df3193659aa1e581472cf",
       "schema": {
@@ -30929,6 +31047,213 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "1de64ea9a0849ce631b7e4e1255ae773fabd94a4a7c8d27e716f8012302e12c0",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "union",
+            "types": [
+              1,
+              6,
+              8,
+              10,
+              11
+            ]
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 0
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 9,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 5,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 9,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 12,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 7,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          }
+        ]
+      },
+      "names": [
+        "packages/subagent/subagent/src/catalog.ts#SubagentCatalogEvent"
+      ],
+      "sources": [
+        "packages/subagent/subagent/src/catalog.ts:28"
+      ]
+    },
     {
       "digest": "1df34a6c086866ffdc2dd9e8e5c581c3751a010cdf6b8538a7327f7a3237f0b4",
       "schema": {
@@ -35234,15 +35559,49 @@
       ]
     },
     {
-      "digest": "3ac1196f59d5e9e0e9345122c8c403b102478b526404a2e591a38f613483321e",
+      "digest": "3abae7324356f155cb42450c00b806d134ec93bd6439d2063b8d724162d58604",
       "schema": {
         "root": 0,
         "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 14,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 15,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
           {
             "kind": "union",
             "types": [
-              1,
-              6
+              2,
+              7,
+              9,
+              11,
+              12
             ]
           },
           {
@@ -35250,28 +35609,28 @@
             "properties": [
               {
                 "name": "childCreatedAt",
-                "type": 2,
+                "type": 3,
                 "optional": false
               },
               {
                 "name": "childId",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "mode",
                 "type": 4,
                 "optional": false
               },
               {
-                "name": "version",
+                "name": "label",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "mode",
                 "type": 5,
                 "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
+                "optional": false
               }
             ],
             "indices": []
@@ -35297,27 +35656,62 @@
             "properties": [
               {
                 "name": "childCreatedAt",
-                "type": 2,
+                "type": 3,
                 "optional": false
               },
               {
                 "name": "childId",
-                "type": 3,
+                "type": 4,
                 "optional": false
               },
               {
                 "name": "label",
-                "type": 3,
-                "optional": true
+                "type": 4,
+                "optional": false
               },
               {
                 "name": "mode",
-                "type": 7,
+                "type": 5,
                 "optional": false
               },
               {
                 "name": "version",
-                "type": 5,
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 6,
                 "optional": false
               }
             ],
@@ -35326,15 +35720,85 @@
           {
             "kind": "literal",
             "value": "one-shot"
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 10,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 4,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 4,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 13,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 8,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "subagent/catalog"
           }
         ]
       },
-      "names": [
-        "packages/subagent/subagent/src/catalog.ts#SubagentCatalogEvent"
-      ],
-      "sources": [
-        "packages/subagent/subagent/src/catalog.ts:24"
-      ]
+      "names": [],
+      "sources": []
     },
     {
       "digest": "3b04790e08b35241ffa0d38f6d7e4f8788aa921341f6c0d7574a329397c59408",
@@ -44144,7 +44608,7 @@
         "packages/workflow/workflow/src/types.ts#WorkflowRunId"
       ],
       "sources": [
-        "packages/api/session-controller/src/types.ts:394",
+        "packages/api/session-controller/src/types.ts:396",
         "packages/attachment/attachment/src/brand.ts:6",
         "packages/compaction/compaction/src/brand.ts:4",
         "packages/core/session/src/types.ts:20",
@@ -57727,7 +58191,7 @@
       },
       "names": [],
       "sources": [
-        "packages/api/session-controller/src/types.ts:399"
+        "packages/api/session-controller/src/types.ts:401"
       ]
     },
     {
@@ -68069,6 +68533,63 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "a0f25b5aeeebf2bf1542ce67726b095e3b139a39c71861d57e827f12dea1f499",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "unknown"
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "a0f906856fc06f1c6f2083eb970e5a657a82b1a84c06c095445e5d6d161cda80",
       "schema": {
@@ -70165,144 +70686,6 @@
       "names": [],
       "sources": []
     },
-    {
-      "digest": "ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871",
-      "schema": {
-        "root": 0,
-        "nodes": [
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "data",
-                "type": 1,
-                "optional": false
-              },
-              {
-                "name": "ignorable",
-                "type": 9,
-                "optional": true
-              },
-              {
-                "name": "seq",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "time",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "type",
-                "type": 10,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "union",
-            "types": [
-              2,
-              7
-            ]
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "mode",
-                "type": 5,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "primitive",
-            "type": "number"
-          },
-          {
-            "kind": "primitive",
-            "type": "string"
-          },
-          {
-            "kind": "literal",
-            "value": "continuable"
-          },
-          {
-            "kind": "literal",
-            "value": 0
-          },
-          {
-            "kind": "object",
-            "properties": [
-              {
-                "name": "childCreatedAt",
-                "type": 3,
-                "optional": false
-              },
-              {
-                "name": "childId",
-                "type": 4,
-                "optional": false
-              },
-              {
-                "name": "label",
-                "type": 4,
-                "optional": true
-              },
-              {
-                "name": "mode",
-                "type": 8,
-                "optional": false
-              },
-              {
-                "name": "version",
-                "type": 6,
-                "optional": false
-              }
-            ],
-            "indices": []
-          },
-          {
-            "kind": "literal",
-            "value": "one-shot"
-          },
-          {
-            "kind": "literal",
-            "value": true
-          },
-          {
-            "kind": "literal",
-            "value": "subagent/catalog"
-          }
-        ]
-      },
-      "names": [],
-      "sources": []
-    },
     {
       "digest": "ae63d9d1080ed8945031594d93f8d96651d7101b848719cc3e1475875cd3d649",
       "schema": {
@@ -71795,6 +72178,63 @@
       "names": [],
       "sources": []
     },
+    {
+      "digest": "b6896938660a1dfe4ddd100fb3164d9f8fa57feeabfe37441a80106c9942697a",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": true
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "one-shot"
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "b6ef9c6210be8350cd465f485cf520031fffa6bf3809c61a1e713e834c5982d0",
       "schema": {
@@ -81359,6 +81799,63 @@
         "packages/schedule/schedule/src/types.ts:105"
       ]
     },
+    {
+      "digest": "e2ad8f5bcd813f268ffef1b10a12d7ddd2b8ced8b9b6d0275b3f6b7ed094a187",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "childCreatedAt",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "childId",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "label",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "mode",
+                "type": 3,
+                "optional": false
+              },
+              {
+                "name": "version",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "primitive",
+            "type": "string"
+          },
+          {
+            "kind": "literal",
+            "value": "continuable"
+          },
+          {
+            "kind": "literal",
+            "value": 1
+          }
+        ]
+      },
+      "names": [],
+      "sources": []
+    },
     {
       "digest": "e2d0367e5716bc188435e51718ebff8ce873190625fa93b1c5331102d98758fa",
       "schema": {
diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml
index e1fd460b35..3c4fdb398a 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: bba024e8ee4cb89ceac4698bf66f060c7f74dcd6
-core.zh.md: 2e04d5a9a078f3411b2a0d338835ec7d71296f10
+core.md: a1e876dcfcd31dfb9fd4840d0d0e217bb71e43bb
+core.zh.md: a63e38cf6381d97656f2350cc16502030772b1a7
diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md
index bba024e8ee..a1e876dcfc 100644
--- a/docs/subsystems/core.md
+++ b/docs/subsystems/core.md
@@ -297,7 +297,7 @@ type AgentCancelCause =
   | { readonly kind: 'disposed' }
 ```
 
-The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` records the outcome as `{ kind: 'aborted', reason: TurnEndCancelCause }`, so the cancel cause lands in the terminal result.
+The cause is a TypeScript-enforced same-process input. An active cancellation holder exposes that same object as the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` records the outcome as `{ kind: 'aborted', reason: TurnEndCancelCause }`, so the cancel cause lands in the terminal result.
 
 The [event taxonomy](../architecture.md#events) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md
index 2e04d5a9a0..a63e38cf63 100644
--- a/docs/subsystems/core.zh.md
+++ b/docs/subsystems/core.zh.md
@@ -301,7 +301,7 @@ type AgentCancelCause =
   | { readonly kind: 'disposed' }
 ```
 
-cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 以 `{ kind: 'aborted', reason: TurnEndCancelCause }` 记录结果，取消原因随终态结果一起持久化。
+cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者把同一个对象暴露为仅运行时的 `AbortSignal.reason`；signal 不授予协作监听器任何分类权限。持久 `turn/end` 以 `{ kind: 'aborted', reason: TurnEndCancelCause }` 记录结果，取消原因随终态结果一起持久化。
 
 [事件分类](../architecture.zh.md#events)负责 `agent/*` 生命周期、检查点与 waterfall（瀑布式事件）约定。轮次和步骤边界是持久会话事件，而不是 agent emit。
 
diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml
index 06d2e4aa51..c04ea7446f 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: a4ed5460ac333b57520b241f31f5c809e574f858
-filesystem.zh.md: 6f06c140c1a9a2c685aebd6339cd1ee97d4303bb
+filesystem.md: d099e619b208f5984db6ff4561cd203d13910ff0
+filesystem.zh.md: 6e907d07b82c72453ef45d67e6bcb9809431e20a
diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md
index a4ed5460ac..d099e619b2 100644
--- a/docs/subsystems/filesystem.md
+++ b/docs/subsystems/filesystem.md
@@ -300,7 +300,7 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea
  * @returns a promise resolving once observation is active, with an asynchronous close function.
  * @throws when the provider does not support watching or cannot initialize the watcher.
  */
-abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>
+watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>
 
 /**
  * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md
index 6f06c140c1..6e907d07b8 100644
--- a/docs/subsystems/filesystem.zh.md
+++ b/docs/subsystems/filesystem.zh.md
@@ -300,7 +300,7 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea
  * @returns a promise resolving once observation is active, with an asynchronous close function.
  * @throws when the provider does not support watching or cannot initialize the watcher.
  */
-abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>
+watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>
 
 /**
  * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
diff --git a/docs/subsystems/jobs.i18n.yaml b/docs/subsystems/jobs.i18n.yaml
index 20d4e50962..f69e46f9a0 100644
--- a/docs/subsystems/jobs.i18n.yaml
+++ b/docs/subsystems/jobs.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/jobs.md
-jobs.md: 4be335207b7dd94f08015ecda595a6b1cc301a7f
-jobs.zh.md: 9dc390eb30901664edb47c6727a54ddd83839fa7
+jobs.md: d54b1ecdd8957c162268c8abbc1df6d764695ac7
+jobs.zh.md: 3b0db7c654d02ace451e73203923d816e9262230
diff --git a/docs/subsystems/jobs.md b/docs/subsystems/jobs.md
index 4be335207b..d54b1ecdd8 100644
--- a/docs/subsystems/jobs.md
+++ b/docs/subsystems/jobs.md
@@ -2,7 +2,7 @@
 
 English | [中文](jobs.zh.md)
 
-Types shared by long-running producers, `ctx.jobs`, and job controls. The [runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) owns the design; this page records the exact fields and variants from [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts).
+Types shared by long-running producers, `ctx.jobs`, and job controls. The [seam consolidation Agent Note](../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md) owns the current design and the [runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) its origin; this page records the exact fields and variants from [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) and the client-safe [`view.ts`](../../packages/jobs/jobs/src/view.ts) leaf.
 
 ## Ids and status
 
@@ -19,45 +19,83 @@ interface JobKindMap {
 }
 ```
 
-`JobStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `JobSnapshot.detail`.
+`JobStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `JobView.progress` while the job runs and in `JobView.detail` once it settled.
 
 ## Producer contract
 
-`JobStart` declares identity and a starter. The runtime finishes preflight before calling `run()` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state.
+A `JobSpec` declares identity, the owning session, optional pull `output` sources, and a starter. The runtime finishes preflight before calling `run()` with the job's `JobHandle` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, lifecycle state, and the output ring.
 
 ```ts type-equiv
 /**
  * Producer declaration passed to {@link JobRegistry.start}. The runtime
  * preflights access and cleanup before invoking {@link run}; the producer owns
- * execution resources while the runtime owns identity and lifecycle state.
+ * execution resources while the runtime owns identity, lifecycle state, and
+ * the output ring.
  */
-interface JobStart {
+interface JobSpec {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
   kind: JobKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
+  /**
+   * Owning session. Access is fenced by it, and the owner's live Agent must be
+   * the one currently registered under that id: its disposal cancels and
+   * awaits the job. Omitting the owner creates an unowned job, open to any
+   * caller until service disposal.
+   */
+  owner?: SessionId
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including controller status metadata.
+   * output read, including controller status metadata. Independent of ring
+   * retention: it bounds the consuming model surface, never observers.
    */
   outputLimitBytes?: number
   /**
-   * Owning live agent. Access is fenced by its session id, and agent disposal
-   * cancels and awaits the job. The instance must be the one currently
-   * registered under its agent id. Omitting the owner creates an unowned job,
-   * open to any caller until service disposal.
+   * Pull sources the registry pumps into the ring at its own cadence.
+   * Producers that narrate their own progress use {@link JobHandle.append}
+   * instead; a job may use both.
    */
-  owner?: Agent
+  output?: readonly JobOutputSource[]
   /**
    * Start the work after preflight and synchronously return its hooks. Called
-   * once; a throw leaves nothing registered, and the producer must clean up any
-   * partially started resources.
+   * once with the job's producer face; a throw leaves nothing registered (the
+   * spent ordinal is skipped), and the producer must clean up any partially
+   * started resources.
+   * @param job - the issued id plus the ring append and progress writers.
    */
-  run(): JobHooks
+  run(job: JobHandle): JobHooks
 }
 ```
 
-`JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. Optional `readOutput` distinguishes consuming stream jobs from final-output-only jobs.
+```ts type-equiv
+/**
+ * Producer face of one registered job, handed to {@link JobSpec.run} and
+ * valid for the job's whole life. All methods are synchronous. Writes staged
+ * inside the starter call are retained and become visible with the
+ * registration commit; after settlement — the producer's own outcome, a kill,
+ * or a registry-forced teardown end — writes log and drop instead of
+ * throwing, so a producer's trailing flush cannot break its own teardown path.
+ */
+interface JobHandle {
+  /** The registry-issued id (`<kind>-N`). */
+  readonly id: JobId
+  /**
+   * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8
+   * byte length; an empty chunk is dropped without waking observers.
+   * @param text - the chunk text, exactly as produced.
+   * @param options - stream label and gap marker.
+   */
+  append(text: string, options?: JobAppendOptions): void
+  /**
+   * Replace the live progress line (`3/10`, the current phase). Settlement
+   * clears it; the terminal reason travels in {@link JobOutcome.detail}.
+   * @param line - the new progress line.
+   */
+  updateProgress(line: string): void
+}
+```
+
+`JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. A job whose result is a value rather than a stream — a subagent's report, a workflow's rendered result — returns it as `JobOutcome.result`; the model's first read after settlement carries it once.
 
 ```ts type-equiv
 /** Hooks through which the runtime controls and observes producer work. */
@@ -74,12 +112,6 @@ interface JobHooks {
    * registry record without claiming that the work stopped.
    */
   done: Promise<JobOutcome>
-  /**
-   * Consume output produced since the previous call. The producer formats
-   * truncation and spill notices. Absence marks a final-output-only job; each
-   * job has one consuming cursor.
-   */
-  readOutput?(): string
 }
 ```
 
@@ -88,73 +120,207 @@ interface JobHooks {
 interface JobOutcome {
   /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
   status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
+  /**
+   * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`).
+   * When the job settles `killed` after a {@link JobRegistry.kill} with a
+   * reason, the registry appends that reason.
+   */
   detail?: string
-  /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
-  output?: string
+  /**
+   * Return value for jobs whose result is a value rather than a stream (a
+   * workflow's rendered result, a subagent's report). The output ring carries
+   * the stream; this is handed out once by the model's next {@link JobRegistry.read}.
+   */
+  result?: string
+}
+```
+
+A pull source hands the registry a non-consuming offset reader — the subprocess `readFrom` family. The registry pumps every source at its own cadence (`pumpPollMs` on `dsh-jobs-local`) and drains it once more before settlement closes the ring, so producers fold nothing into `done`.
+
+```ts type-equiv
+/**
+ * A pull source the registry pumps into the job's output ring — the subprocess
+ * `readFrom` family. The registry owns the cadence and drains every source one
+ * last time before settlement closes the ring, so a producer folds nothing
+ * into its `done`.
+ */
+interface JobOutputSource {
+  /** Stream label attached to every chunk this source yields. */
+  channel?: JobChannel
+  /**
+   * Read everything captured since `fromByte` without consuming it.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first).
+   * @returns the delta text, the next offset, the lossy flag, and the spill path the source currently keeps.
+   */
+  read(fromByte: number): JobSourceRead
+}
+```
+
+```ts type-equiv
+/** One incremental read from a {@link JobOutputSource}. */
+interface JobSourceRead {
+  /** Text captured since the requested offset (the whole retained tail when lossy). */
+  text: string
+  /** Whole-stream offset to resume from on the next read. */
+  nextOffset: number
+  /** True when the requested offset slid out of the source's retained window. */
+  lossy: boolean
+  /**
+   * Host path of a file holding the complete stream, when the source
+   * currently keeps an intact one. Reported on every read, so the registry
+   * tracks it as source metadata: a later read without it withdraws the file.
+   */
+  spillPath?: string
+}
+```
+
+## The output ring
+
+Every job owns one bounded ring. Pull sources are pumped into it and `JobHandle.append` pushes land whole; the model consumes the ring through a registry-kept cursor (`JobRegistry.read`), any number of observers read it at absolute byte offsets (`JobRegistry.readAt`), and neither disturbs the other. `JobChannel` labels `stdout`, `stderr`, and `log`; `log` is producer narration that reaches observers only, never the model's consuming read. Settlement ends the stream and trims retention to the settled cap — the ring has no separate lifecycle. The spill file a pull source keeps is job metadata (`JobView.output.spillPaths`, refreshed by every pump read), not per-chunk metadata, so the model's dropped-output notice names it after the ring evicted the bytes and even after the gap chunk itself is gone. Browsers reach the roster and the ring through `job.list` and `job.follow`, the Remote streams of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below.
+
+```ts type-equiv
+/** One chunk of a job's output ring: absolute offset, text, channel, and loss marker. */
+interface JobChunk {
+  /** Absolute offset of the chunk's first byte; offsets never move once assigned. */
+  readonly at: number
+  /** Chunk text exactly as appended (possibly tail-trimmed by retention). */
+  readonly text: string
+  /** Stream label, when the producer supplied one. */
+  readonly channel?: JobChannel
+  /** Bytes immediately before this chunk were lost, at the producer or to retention. */
+  readonly gapBefore?: true
+}
+```
+
+```ts type-equiv
+/** Result of one non-consuming {@link JobRegistry.readAt}. */
+interface JobOutputRead {
+  /** Retained chunks overlapping `[from, total)`, in offset order. */
+  chunks: readonly JobChunk[]
+  /**
+   * Offset to resume from — the ring's current `total`. Always a chunk
+   * boundary: appends land whole and trimming only advances chunk starts, and
+   * consumers concatenate `chunks` under that assumption, so a provider
+   * serving partial chunks would silently duplicate text.
+   */
+  next: number
+  /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
 }
 ```
 
 ## 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 reporter has delivered or committed to deliver the terminal state, including the teardown cancel that drains an owner or the service.
+`JobView` is the one projection every reader consumes: the model tools, the browser roster, and the observation stream. `owner` carries the session id that fences access; the registry resolves the live `Agent` behind it for lifecycle cleanup and never hands the object out. `progress` is the producer's live line and is cleared at settlement; `detail` is the terminal reason, with a recorded kill reason merged in.
 
 ```ts type-equiv
 /**
- * A read-only projection of one job, safe to hand to listeners and tools —
- * a fresh object per call, never live registry state.
+ * Read-only projection of one job — a fresh object per call, never live
+ * registry state. The model tools, the browser roster, and the observation
+ * stream all consume this one shape.
  */
-interface JobSnapshot {
+interface JobView {
   /** The registry-issued id (`<kind>-N`). */
-  id: JobId
-  /** The producer kind the job was registered with. */
-  kind: JobKind
+  readonly id: JobId
+  /**
+   * The producer kind the job was registered with: a Host-registered
+   * `JobKind`, carried as an open string because a browser bundle or a Remote
+   * codec sees only the `JobKindMap` merges its own program compiles.
+   */
+  readonly kind: string
   /** The producer-supplied one-line label. */
-  label: string
-  /** Producer-owned cap for complete model-facing notices and output reads. */
-  outputLimitBytes?: number
-  /**
-   * Owner session id used for authorization and correlation; absent for
-   * unowned jobs. Completion listeners receive the exact {@link Agent}
-   * separately through {@link JobDoneListener}.
-   */
-  ownerSession?: SessionId
+  readonly label: string
+  /** Owning session; absent for an unowned job, which every caller can see. */
+  readonly owner?: SessionId
+  /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */
+  readonly outputLimitBytes?: number
   /** Current lifecycle state. */
-  status: JobStatus
-  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
-  detail?: string
+  readonly status: JobStatus
+  /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */
+  readonly progress?: string
+  /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */
+  readonly detail?: string
   /** Epoch ms when the job was registered. */
-  startedAt: number
-  /** Epoch ms when the job settled; absent while `running`/`stopping`. */
-  finishedAt?: number
+  readonly startedAt: number
+  /** Epoch ms when the job settled; absent while live. */
+  readonly finishedAt?: number
   /**
-   * True when a kill, read, wait, or teardown cancel has reported or committed
-   * to report the terminal state. Completion reporters suppress redundant
-   * notices when set. Teardown claims it because the owner or service being
-   * destroyed leaves no reader: a reporter that opens a turn on notice would
-   * otherwise spend a model request per teardown layer.
+   * The output ring's absolute coordinates and the complete-stream files
+   * behind it. `total` is the offset the next chunk starts at (0 while
+   * nothing was written); `earliest` is the oldest retained byte, greater
+   * than zero exactly when retention dropped the head. `spillPaths` lists the
+   * spill files the job's pull sources currently keep, in source order and
+   * deduplicated, and is absent while no source keeps one: it outlives any
+   * chunk, so a reader below `earliest` can still name where the bytes went.
    */
-  reported: boolean
+  readonly output: { readonly total: number; readonly earliest: number; readonly spillPaths?: readonly string[] }
 }
 ```
 
+`JobRegistry.list`, `get`, `read`, `readAt`, `kill`, and `wait` each accept the caller’s `SessionId`; omitting it permits only unowned jobs, while a session may also access its own jobs.
+
 ```ts type-equiv
-/** Output and post-read state returned by {@link JobRegistry.read}. */
+/** Output and post-read state returned by the consuming {@link JobRegistry.read}. */
 interface JobRead {
-  /**
-   * Stream kinds: the consuming delta since the previous read. Final-output
-   * kinds: empty while live, the terminal {@link JobOutcome.output} (or
-   * empty) once settled — idempotent, never consumed.
-   */
-  text: string
+  /** Ring chunks appended since the model cursor, in offset order; every channel included. */
+  chunks: readonly JobChunk[]
+  /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
+  /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */
+  result?: string
   /** The job's state at read time. */
-  snapshot: JobSnapshot
+  job: JobView
 }
 ```
 
+## Events
+
+The registry announces every commit through one filtered stream. Lifecycle events carry the projection after the commit they announce; `settled` names its cause so a completion reporter can skip a teardown; `output` carries only the id and the new total, so observers read from their own cursor and the registry never pushes payloads.
+
+```ts type-equiv
+/**
+ * One lifecycle or output event. Lifecycle events carry the job's projection
+ * after the commit they announce; `output` carries only the id and the new
+ * total, so an observer schedules a {@link JobRegistry.readAt} from its own
+ * cursor and the registry never pushes payloads.
+ */
+type JobEvent =
+  | {
+    /** Registration commit, progress line change, stopping transition, or removal from the visible set. */
+    readonly type: 'registered' | 'progress' | 'stopping' | 'removed'
+    readonly job: JobView
+  }
+  | {
+    readonly type: 'settled'
+    readonly job: JobView
+    readonly cause: JobSettleCause
+  }
+  | {
+    readonly type: 'output'
+    readonly id: JobId
+    /** Owning session, absent for an unowned job. */
+    readonly owner?: SessionId
+    /** The ring's total after the append (or at settlement, which ends the stream). */
+    readonly total: number
+  }
+```
+
+```ts type-equiv
+/**
+ * Who a subscription hears about. `{ owner }` delivers that session's jobs
+ * plus every unowned job (the set that session can see). `{ owners: 'scope' }`
+ * delivers the owners composed under the subscribing context — one registry
+ * serves every composition in the process, and a mount under one preset must
+ * not hear another preset's agents. `{ owners: 'all' }` delivers everything.
+ */
+type JobEventFilter =
+  | { readonly owner: SessionId }
+  | { readonly owners: 'all' | 'scope' }
+```
+
 ## Service behavior
 
-The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onJobDone` and `onJobsChanged` listeners, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer.
+The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `list`, `get`, consuming `read`, non-consuming `readAt`, `kill`, and bounded `wait`, the filtered `events` stream, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the live `Agent` registered under the owner session when the job starts. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity; `retainBytes` (default 262144) and `settledRetainBytes` (default 16384) bound each ring's live and settled retention, and `pumpPollMs` (default 150) is the pull cadence. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -164,18 +330,52 @@ The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Defi
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` 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="ctxjobcontroller--jobcontroller"></a>
+
+### `ctx.jobController` — `JobController`
+
+Host service backing the generated `ctx.remote.job` namespace.
+
+```ts cordis-catalog
+/**
+ * Stream the jobs one session can see — its own plus every unowned job —
+ * as whole-set frames: one on open, then one after each coalesced burst of
+ * lifecycle commits. The stream has no natural end; the carrier closes it.
+ * @param request - the session whose visible set to mirror.
+ * @param signal - cancellation owned by the Remote stream carrier.
+ * @returns the roster frames.
+ */
+@Remote({ mode: 'stream' }) list(request: JobListRequest, signal: AbortSignal): AsyncIterable<JobListFrame>
+
+/**
+ * Stream one job's retained output from an absolute byte offset, then its
+ * terminal projection once settled and drained. Non-consuming: the
+ * model-facing cursor and notice state never observe these reads. The
+ * request's session is the fenced read's caller; the registry rejects a
+ * job the session cannot see and an unknown job.
+ * @param request - target job, owning session, and optional resume offset.
+ * @param signal - cancellation owned by the Remote stream carrier.
+ * @returns anchor, coalesced output frames, and the terminal status.
+ */
+@Remote({ mode: 'stream' }) follow(request: JobFollowRequest, signal: AbortSignal): AsyncIterable<JobFollowFrame>
+```
+
+Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-controller/src/index.ts)
+
 <a id="ctxjobs--jobregistry-abstract-seam"></a>
 
 ### `ctx.jobs` — `JobRegistry` (abstract seam)
 
-Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
 Implementations must honor these semantics:
 
-- 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. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.
+- 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. Such settlements announce `cause: 'teardown'`, because a job whose owner is being destroyed has no reader left.
 - Owned-job 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, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.
-- start refuses work while no attached job 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.
+- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter, so a consumer that claims a settlement while waiting always claims before the event.
+- start refuses work while no attached job 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 event delivery under `{ owners: 'scope' }` — 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.
+- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model's consuming cursor and observers' absolute offsets read the same bytes and never disturb each other.
+- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle.
 
 ```ts cordis-catalog
 /**
@@ -183,96 +383,73 @@ Implementations must honor these semantics:
  * admission before starting and atomically registering work. Any preflight
  * rejection leaves no job id or execution resource. A throwing starter
  * leaves nothing registered; after it returns, registration cannot fail.
- * Settlement records the outcome, notifies listeners, and releases waiters.
- * @param spec - job identity, owner, and synchronous starter.
+ * @param spec - job identity, owner, output sources, and synchronous starter.
  * @returns the registry-issued `<kind>-N` id.
  */
-abstract start(spec: JobStart): JobId
+abstract start(spec: JobSpec): JobId
 
 /**
- * List caller-owned and unowned jobs in registration order without exposing
- * another session's labels.
- * @param caller - reading agent; a non-agent caller sees only unowned jobs.
- * @returns fresh snapshots.
+ * List caller-owned and unowned jobs in registration order.
+ * @param caller - reading session; omission sees only unowned jobs.
+ * @returns fresh projections.
  */
-abstract list(caller?: Agent): JobSnapshot[]
+abstract list(caller?: SessionId): JobView[]
 
 /**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign job.
- * @param id - job to look up.
- * @param caller - reading agent checked against the owner.
- * @returns a fresh snapshot.
- */
-abstract get(id: JobId, caller?: Agent): JobSnapshot
-
-/**
- * Read the next stream delta, or the idempotent final output after settlement.
- * A terminal read marks the job reported. Throws for an unknown or foreign
- * job.
- * @param id - job to read.
- * @param caller - reading agent checked against the owner.
- * @returns output text and the post-read snapshot.
- */
-abstract read(id: JobId, caller?: Agent): JobRead
-
-/**
- * Request cancellation, then mark the job stopping and reported. A producer
- * throw propagates without changing job state. Throws for an unknown or
+ * Project one job without changing its cursor. Throws for an unknown or
  * foreign job.
+ * @param id - job to look up.
+ * @param caller - reading session checked against the owner.
+ * @returns a fresh projection.
+ */
+abstract get(id: JobId, caller?: SessionId): JobView
+
+/**
+ * Consume the ring from the model cursor and advance it to the current
+ * total. After settlement the first read also carries the producer's
+ * result. Throws for an unknown or foreign job.
+ * @param id - job to read.
+ * @param caller - reading session checked against the owner.
+ * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection.
+ */
+abstract read(id: JobId, caller?: SessionId): JobRead
+
+/**
+ * Read retained ring output without moving the model cursor. Resume with
+ * a previous read's `next`; an offset inside a retained chunk returns the
+ * whole chunk (its `at` may precede `from`). Throws for a negative or
+ * non-integer offset, or an unknown or foreign job.
+ * @param id - job to read.
+ * @param from - absolute byte offset to read from (0 for the retained head).
+ * @param caller - reading session checked against the owner.
+ * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.
+ */
+abstract readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead
+
+/**
+ * Request cancellation, then mark the job stopping. A producer throw
+ * propagates without changing job state. A supplied reason is merged into
+ * terminal `detail` when the job settles `killed`. Throws for an unknown
+ * or foreign job.
  * @param id - job to cancel.
- * @param caller - killing agent checked against the owner.
- * @param reason - logged reason forwarded to the producer.
+ * @param caller - killing session checked against the owner.
+ * @param reason - cancellation reason forwarded verbatim to the producer.
  * @returns `requested` for live work, otherwise `already-finished`.
  */
-abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+abstract kill(id: JobId, caller?: SessionId, reason?: string): 'requested' | 'already-finished'
 
 /**
  * Wait for settlement or timeout without cancelling the job. Caller abort
  * rejects only while the job is live; after settlement the terminal
- * snapshot wins so a notice suppressed for this waiter is still delivered.
- * Throws for invalid, unknown, or foreign input.
+ * projection wins. Rejects for an invalid timeout or an unknown or foreign
+ * job.
  * @param id - job to wait for.
  * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
+ * @param caller - waiting session checked against the owner.
  * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
+ * @returns projection at settlement or timeout.
  */
-abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>
-
-/**
- * Register an effect-scoped completion listener. It receives the settlements
- * of the owners its registering context's scope covers; each listener is
- * contained; returned promises are observed but not awaited. No listener runs
- * after service disposal.
- * @param listener - receives each terminal snapshot and its exact owner.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobDone(listener: JobDoneListener): () => void
-
-/**
-/**
- * Register an effect-scoped observer of visible-set changes. It fires after
- * every commit that changes what {@link list} returns for that owner —
- * registration, every stopping transition (including the one teardown
- * performs before it awaits a slow producer), settlement, owner-disposal
- * removal, and the emptying that service disposal commits — so an observer
- * re-reads rather than accumulating deltas.
- *
- * Delivery is owner-relative on the same terms as {@link onJobDone}: an
- * observer registered from an unscoped context — a host composition's own
- * carrier — sees every owner, while one registered under an agent
- * composition's scope sees exactly the agents composed under it.
- *
- * This is not a superset of {@link onJobDone}: that one delivers the terminal
- * record under first-wins semantics a job 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
- *   `undefined` when an unowned job changed and every caller's set did.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobsChanged(listener: JobsChangedListener): () => void
+abstract wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView>
 
 /**
  * Attach an effect-scoped controller that can read and stop jobs. It serves the
@@ -284,7 +461,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void
 abstract attachController(name: string): () => void
 ```
 
-Types: [Agent](core.md)
+Types: [SessionId](core.md)
 
 Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/jobs.zh.md b/docs/subsystems/jobs.zh.md
index 9dc390eb30..3b0db7c654 100644
--- a/docs/subsystems/jobs.zh.md
+++ b/docs/subsystems/jobs.zh.md
@@ -2,7 +2,7 @@
 
 [English](jobs.md) | 中文
 
-长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md) 负责设计；本页记录 [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) 中的确切字段和变体。
+长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[seam 收敛 Agent Note](../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md) 负责当前设计，[运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md) 记录其起源；本页记录 [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) 与客户端安全叶子 [`view.ts`](../../packages/jobs/jobs/src/view.ts) 中的确切字段与变体。
 
 ## ID 与状态
 
@@ -19,45 +19,83 @@ interface JobKindMap {
 }
 ```
 
-`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实归入 `JobSnapshot.detail`。
+`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实在运行期间归入 `JobView.progress`，结算后归入 `JobView.detail`。
 
 ## 生产方约定
 
-`JobStart` 声明身份和启动器。运行时会在调用 `run()` 前完成预检，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问权限和生命周期状态。
+`JobSpec` 声明身份、拥有者会话、可选的拉取式 `output` 源与启动器。运行时会在完成预检后携带该 job 的 `JobHandle` 调用 `run()`，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问、生命周期状态与输出环。
 
 ```ts type-equiv
 /**
  * Producer declaration passed to {@link JobRegistry.start}. The runtime
  * preflights access and cleanup before invoking {@link run}; the producer owns
- * execution resources while the runtime owns identity and lifecycle state.
+ * execution resources while the runtime owns identity, lifecycle state, and
+ * the output ring.
  */
-interface JobStart {
+interface JobSpec {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
   kind: JobKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
+  /**
+   * Owning session. Access is fenced by it, and the owner's live Agent must be
+   * the one currently registered under that id: its disposal cancels and
+   * awaits the job. Omitting the owner creates an unowned job, open to any
+   * caller until service disposal.
+   */
+  owner?: SessionId
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including controller status metadata.
+   * output read, including controller status metadata. Independent of ring
+   * retention: it bounds the consuming model surface, never observers.
    */
   outputLimitBytes?: number
   /**
-   * Owning live agent. Access is fenced by its session id, and agent disposal
-   * cancels and awaits the job. The instance must be the one currently
-   * registered under its agent id. Omitting the owner creates an unowned job,
-   * open to any caller until service disposal.
+   * Pull sources the registry pumps into the ring at its own cadence.
+   * Producers that narrate their own progress use {@link JobHandle.append}
+   * instead; a job may use both.
    */
-  owner?: Agent
+  output?: readonly JobOutputSource[]
   /**
    * Start the work after preflight and synchronously return its hooks. Called
-   * once; a throw leaves nothing registered, and the producer must clean up any
-   * partially started resources.
+   * once with the job's producer face; a throw leaves nothing registered (the
+   * spent ordinal is skipped), and the producer must clean up any partially
+   * started resources.
+   * @param job - the issued id plus the ring append and progress writers.
    */
-  run(): JobHooks
+  run(job: JobHandle): JobHooks
 }
 ```
 
-`JobHooks.done` 会在生产方释放其资源后 resolve，而不是仅在工作完成时 resolve。可选的 `readOutput` 用来区分会消费输出的流式任务和仅有最终输出的任务。
+```ts type-equiv
+/**
+ * Producer face of one registered job, handed to {@link JobSpec.run} and
+ * valid for the job's whole life. All methods are synchronous. Writes staged
+ * inside the starter call are retained and become visible with the
+ * registration commit; after settlement — the producer's own outcome, a kill,
+ * or a registry-forced teardown end — writes log and drop instead of
+ * throwing, so a producer's trailing flush cannot break its own teardown path.
+ */
+interface JobHandle {
+  /** The registry-issued id (`<kind>-N`). */
+  readonly id: JobId
+  /**
+   * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8
+   * byte length; an empty chunk is dropped without waking observers.
+   * @param text - the chunk text, exactly as produced.
+   * @param options - stream label and gap marker.
+   */
+  append(text: string, options?: JobAppendOptions): void
+  /**
+   * Replace the live progress line (`3/10`, the current phase). Settlement
+   * clears it; the terminal reason travels in {@link JobOutcome.detail}.
+   * @param line - the new progress line.
+   */
+  updateProgress(line: string): void
+}
+```
+
+`JobHooks.done` 会在生产方释放其资源后 resolve，而不是仅在工作完成时 resolve。结果是一个值而非流的 job——subagent 的报告、workflow 渲染出的结果——把它作为 `JobOutcome.result` 返回；模型在结算后的第一次读取携带它一次。
 
 ```ts type-equiv
 /** Hooks through which the runtime controls and observes producer work. */
@@ -74,12 +112,6 @@ interface JobHooks {
    * registry record without claiming that the work stopped.
    */
   done: Promise<JobOutcome>
-  /**
-   * Consume output produced since the previous call. The producer formats
-   * truncation and spill notices. Absence marks a final-output-only job; each
-   * job has one consuming cursor.
-   */
-  readOutput?(): string
 }
 ```
 
@@ -88,73 +120,207 @@ interface JobHooks {
 interface JobOutcome {
   /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
   status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
+  /**
+   * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`).
+   * When the job settles `killed` after a {@link JobRegistry.kill} with a
+   * reason, the registry appends that reason.
+   */
   detail?: string
-  /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
-  output?: string
+  /**
+   * Return value for jobs whose result is a value rather than a stream (a
+   * workflow's rendered result, a subagent's report). The output ring carries
+   * the stream; this is handed out once by the model's next {@link JobRegistry.read}.
+   */
+  result?: string
+}
+```
+
+拉取源把一个非消耗的偏移读取器——子进程的 `readFrom` 家族——交给注册表。注册表按自己的节奏（`dsh-jobs-local` 的 `pumpPollMs`）泵送每个源，并在结算封环之前再排干一次，因此生产方不需要把任何东西折进 `done`。
+
+```ts type-equiv
+/**
+ * A pull source the registry pumps into the job's output ring — the subprocess
+ * `readFrom` family. The registry owns the cadence and drains every source one
+ * last time before settlement closes the ring, so a producer folds nothing
+ * into its `done`.
+ */
+interface JobOutputSource {
+  /** Stream label attached to every chunk this source yields. */
+  channel?: JobChannel
+  /**
+   * Read everything captured since `fromByte` without consuming it.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first).
+   * @returns the delta text, the next offset, the lossy flag, and the spill path the source currently keeps.
+   */
+  read(fromByte: number): JobSourceRead
+}
+```
+
+```ts type-equiv
+/** One incremental read from a {@link JobOutputSource}. */
+interface JobSourceRead {
+  /** Text captured since the requested offset (the whole retained tail when lossy). */
+  text: string
+  /** Whole-stream offset to resume from on the next read. */
+  nextOffset: number
+  /** True when the requested offset slid out of the source's retained window. */
+  lossy: boolean
+  /**
+   * Host path of a file holding the complete stream, when the source
+   * currently keeps an intact one. Reported on every read, so the registry
+   * tracks it as source metadata: a later read without it withdraws the file.
+   */
+  spillPath?: string
+}
+```
+
+## 输出环
+
+每个 job 拥有一个有界的环。拉取源被泵入其中，`JobHandle.append` 的推送整块落地；模型通过注册表保管的游标（`JobRegistry.read`）消耗该环，任意数量的观察者按绝对字节偏移读取它（`JobRegistry.readAt`），二者互不干扰。`JobChannel` 标记 `stdout`、`stderr` 与 `log`；`log` 是只到达观察者、从不进入模型消耗式读取的生产方叙述。结算即封流并把保留量裁剪到结算上限——环没有独立的生命周期。拉取源保留的 spill 文件是 job 元数据（`JobView.output.spillPaths`，每次泵读取都会刷新），不是逐块元数据，所以环淘汰了字节之后、甚至缺口 chunk 本身也被淘汰之后，模型的丢失输出提示仍能点名该文件。浏览器通过 [`dsh-api-job-controller`](../../packages/api/job-controller/README.zh.md) 的 Remote 流 `job.list` 与 `job.follow` 触达名册与环，其帧列于下文的 Cordis API 一节。
+
+```ts type-equiv
+/** One chunk of a job's output ring: absolute offset, text, channel, and loss marker. */
+interface JobChunk {
+  /** Absolute offset of the chunk's first byte; offsets never move once assigned. */
+  readonly at: number
+  /** Chunk text exactly as appended (possibly tail-trimmed by retention). */
+  readonly text: string
+  /** Stream label, when the producer supplied one. */
+  readonly channel?: JobChannel
+  /** Bytes immediately before this chunk were lost, at the producer or to retention. */
+  readonly gapBefore?: true
+}
+```
+
+```ts type-equiv
+/** Result of one non-consuming {@link JobRegistry.readAt}. */
+interface JobOutputRead {
+  /** Retained chunks overlapping `[from, total)`, in offset order. */
+  chunks: readonly JobChunk[]
+  /**
+   * Offset to resume from — the ring's current `total`. Always a chunk
+   * boundary: appends land whole and trimming only advances chunk starts, and
+   * consumers concatenate `chunks` under that assumption, so a provider
+   * serving partial chunks would silently duplicate text.
+   */
+  next: number
+  /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
 }
 ```
 
 ## 消费方视图
 
-快照是每次新建的只读投影。`ownerSession` 携带用于授权的共享 `SessionId`；完成监听器则会另行收到用于生命周期清理的确切拥有者对象。另一个接口已经交付终止状态或承诺交付时，`reported` 会抑制完成通知；排空 owner 或服务的 teardown 取消同样计入。
+`JobView` 是每个读者都消费的唯一投影：模型工具、浏览器名册与观测流。`owner` 携带划定访问边界的会话 id；注册表为生命周期清理解析其背后的活体 `Agent`，从不把该对象交出去。`progress` 是生产方的实时行，结算时清除；`detail` 是终态原因，合并了记录下来的 kill 原因。
 
 ```ts type-equiv
 /**
- * A read-only projection of one job, safe to hand to listeners and tools —
- * a fresh object per call, never live registry state.
+ * Read-only projection of one job — a fresh object per call, never live
+ * registry state. The model tools, the browser roster, and the observation
+ * stream all consume this one shape.
  */
-interface JobSnapshot {
+interface JobView {
   /** The registry-issued id (`<kind>-N`). */
-  id: JobId
-  /** The producer kind the job was registered with. */
-  kind: JobKind
+  readonly id: JobId
+  /**
+   * The producer kind the job was registered with: a Host-registered
+   * `JobKind`, carried as an open string because a browser bundle or a Remote
+   * codec sees only the `JobKindMap` merges its own program compiles.
+   */
+  readonly kind: string
   /** The producer-supplied one-line label. */
-  label: string
-  /** Producer-owned cap for complete model-facing notices and output reads. */
-  outputLimitBytes?: number
-  /**
-   * Owner session id used for authorization and correlation; absent for
-   * unowned jobs. Completion listeners receive the exact {@link Agent}
-   * separately through {@link JobDoneListener}.
-   */
-  ownerSession?: SessionId
+  readonly label: string
+  /** Owning session; absent for an unowned job, which every caller can see. */
+  readonly owner?: SessionId
+  /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */
+  readonly outputLimitBytes?: number
   /** Current lifecycle state. */
-  status: JobStatus
-  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
-  detail?: string
+  readonly status: JobStatus
+  /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */
+  readonly progress?: string
+  /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */
+  readonly detail?: string
   /** Epoch ms when the job was registered. */
-  startedAt: number
-  /** Epoch ms when the job settled; absent while `running`/`stopping`. */
-  finishedAt?: number
+  readonly startedAt: number
+  /** Epoch ms when the job settled; absent while live. */
+  readonly finishedAt?: number
   /**
-   * True when a kill, read, wait, or teardown cancel has reported or committed
-   * to report the terminal state. Completion reporters suppress redundant
-   * notices when set. Teardown claims it because the owner or service being
-   * destroyed leaves no reader: a reporter that opens a turn on notice would
-   * otherwise spend a model request per teardown layer.
+   * The output ring's absolute coordinates and the complete-stream files
+   * behind it. `total` is the offset the next chunk starts at (0 while
+   * nothing was written); `earliest` is the oldest retained byte, greater
+   * than zero exactly when retention dropped the head. `spillPaths` lists the
+   * spill files the job's pull sources currently keep, in source order and
+   * deduplicated, and is absent while no source keeps one: it outlives any
+   * chunk, so a reader below `earliest` can still name where the bytes went.
    */
-  reported: boolean
+  readonly output: { readonly total: number; readonly earliest: number; readonly spillPaths?: readonly string[] }
 }
 ```
 
+`JobRegistry` 的 `list`、`get`、`read`、`readAt`、`kill` 和 `wait` 各自接收调用方的 `SessionId`；省略调用方时仅可访问无主 job，传入会话时还可访问该会话拥有的 job。
+
 ```ts type-equiv
-/** Output and post-read state returned by {@link JobRegistry.read}. */
+/** Output and post-read state returned by the consuming {@link JobRegistry.read}. */
 interface JobRead {
-  /**
-   * Stream kinds: the consuming delta since the previous read. Final-output
-   * kinds: empty while live, the terminal {@link JobOutcome.output} (or
-   * empty) once settled — idempotent, never consumed.
-   */
-  text: string
+  /** Ring chunks appended since the model cursor, in offset order; every channel included. */
+  chunks: readonly JobChunk[]
+  /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
+  /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */
+  result?: string
   /** The job's state at read time. */
-  snapshot: JobSnapshot
+  job: JobView
 }
 ```
 
+## 事件
+
+注册表通过一条带过滤的流宣布每次提交。生命周期事件携带其所宣布的提交之后的投影；`settled` 标出原因，完成播报方据此跳过 teardown；`output` 只携带 id 与新的 total，观察者从自己的游标读取，注册表从不推送负载。
+
+```ts type-equiv
+/**
+ * One lifecycle or output event. Lifecycle events carry the job's projection
+ * after the commit they announce; `output` carries only the id and the new
+ * total, so an observer schedules a {@link JobRegistry.readAt} from its own
+ * cursor and the registry never pushes payloads.
+ */
+type JobEvent =
+  | {
+    /** Registration commit, progress line change, stopping transition, or removal from the visible set. */
+    readonly type: 'registered' | 'progress' | 'stopping' | 'removed'
+    readonly job: JobView
+  }
+  | {
+    readonly type: 'settled'
+    readonly job: JobView
+    readonly cause: JobSettleCause
+  }
+  | {
+    readonly type: 'output'
+    readonly id: JobId
+    /** Owning session, absent for an unowned job. */
+    readonly owner?: SessionId
+    /** The ring's total after the append (or at settlement, which ends the stream). */
+    readonly total: number
+  }
+```
+
+```ts type-equiv
+/**
+ * Who a subscription hears about. `{ owner }` delivers that session's jobs
+ * plus every unowned job (the set that session can see). `{ owners: 'scope' }`
+ * delivers the owners composed under the subscribing context — one registry
+ * serves every composition in the process, and a mount under one preset must
+ * not hear another preset's agents. `{ owners: 'all' }` delivers everything.
+ */
+type JobEventFilter =
+  | { readonly owner: SessionId }
+  | { readonly owners: 'all' | 'scope' }
+```
+
 ## 服务行为
 
-抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onJobDone` 与 `onJobsChanged` 监听器，以及 `attachController`；[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是其进程局部 Service Provider。授权会比较拥有者会话；拥有者清理与准入会使用确切的已注册 `Agent` 实例。本地 Service Provider 的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数，默认值为 `10`；它按确切 owner 统计 `running` 与 `stopping` 记录，所有无 owner 任务共享一个服务级桶，并在生产方终止结算后释放容量。Service Definition 约定见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md)，注册表生命周期与准入策略见 [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md)，面向模型的 Consumer 见 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md)。
+抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定了原子化的 `start`、各自接收调用方的 `list`、`get`、消耗式 `read`、非消耗的 `readAt`、`kill` 与有界的 `wait`、带过滤的 `events` 流，以及 `attachController`；[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是进程本地的 Service Provider。授权比较拥有者会话；拥有者清理与准入使用 job 启动时登记在该拥有者会话下的活体 `Agent`。本地提供方的正安全整数配置 `maxConcurrentJobsPerOwner` 默认为 `10`，按精确拥有者统计 `running` 加 `stopping` 记录，无主任务共享一个桶；生产方的终态结算释放容量；`retainBytes`（默认 262144）与 `settledRetainBytes`（默认 16384）约束每个环的运行期与结算后保留量，`pumpPollMs`（默认 150）是拉取节奏。参见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md) 了解 Service Definition 约定，[`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md) 了解注册表生命周期与准入策略，[`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md) 了解面向模型的 Consumer。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -164,18 +330,52 @@ interface JobRead {
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxjobcontroller--jobcontroller"></a>
+
+### `ctx.jobController` — `JobController`
+
+Host service backing the generated `ctx.remote.job` namespace.
+
+```ts cordis-catalog
+/**
+ * Stream the jobs one session can see — its own plus every unowned job —
+ * as whole-set frames: one on open, then one after each coalesced burst of
+ * lifecycle commits. The stream has no natural end; the carrier closes it.
+ * @param request - the session whose visible set to mirror.
+ * @param signal - cancellation owned by the Remote stream carrier.
+ * @returns the roster frames.
+ */
+@Remote({ mode: 'stream' }) list(request: JobListRequest, signal: AbortSignal): AsyncIterable<JobListFrame>
+
+/**
+ * Stream one job's retained output from an absolute byte offset, then its
+ * terminal projection once settled and drained. Non-consuming: the
+ * model-facing cursor and notice state never observe these reads. The
+ * request's session is the fenced read's caller; the registry rejects a
+ * job the session cannot see and an unknown job.
+ * @param request - target job, owning session, and optional resume offset.
+ * @param signal - cancellation owned by the Remote stream carrier.
+ * @returns anchor, coalesced output frames, and the terminal status.
+ */
+@Remote({ mode: 'stream' }) follow(request: JobFollowRequest, signal: AbortSignal): AsyncIterable<JobFollowFrame>
+```
+
+Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-controller/src/index.ts)
+
 <a id="ctxjobs--jobregistry-abstract-seam"></a>
 
 ### `ctx.jobs` — `JobRegistry` (abstract seam)
 
-Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
 Implementations must honor these semantics:
 
-- 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. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.
+- 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. Such settlements announce `cause: 'teardown'`, because a job whose owner is being destroyed has no reader left.
 - Owned-job 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, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.
-- start refuses work while no attached job 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.
+- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter, so a consumer that claims a settlement while waiting always claims before the event.
+- start refuses work while no attached job 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 event delivery under `{ owners: 'scope' }` — 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.
+- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model's consuming cursor and observers' absolute offsets read the same bytes and never disturb each other.
+- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle.
 
 ```ts cordis-catalog
 /**
@@ -183,96 +383,73 @@ Implementations must honor these semantics:
  * admission before starting and atomically registering work. Any preflight
  * rejection leaves no job id or execution resource. A throwing starter
  * leaves nothing registered; after it returns, registration cannot fail.
- * Settlement records the outcome, notifies listeners, and releases waiters.
- * @param spec - job identity, owner, and synchronous starter.
+ * @param spec - job identity, owner, output sources, and synchronous starter.
  * @returns the registry-issued `<kind>-N` id.
  */
-abstract start(spec: JobStart): JobId
+abstract start(spec: JobSpec): JobId
 
 /**
- * List caller-owned and unowned jobs in registration order without exposing
- * another session's labels.
- * @param caller - reading agent; a non-agent caller sees only unowned jobs.
- * @returns fresh snapshots.
+ * List caller-owned and unowned jobs in registration order.
+ * @param caller - reading session; omission sees only unowned jobs.
+ * @returns fresh projections.
  */
-abstract list(caller?: Agent): JobSnapshot[]
+abstract list(caller?: SessionId): JobView[]
 
 /**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign job.
- * @param id - job to look up.
- * @param caller - reading agent checked against the owner.
- * @returns a fresh snapshot.
- */
-abstract get(id: JobId, caller?: Agent): JobSnapshot
-
-/**
- * Read the next stream delta, or the idempotent final output after settlement.
- * A terminal read marks the job reported. Throws for an unknown or foreign
- * job.
- * @param id - job to read.
- * @param caller - reading agent checked against the owner.
- * @returns output text and the post-read snapshot.
- */
-abstract read(id: JobId, caller?: Agent): JobRead
-
-/**
- * Request cancellation, then mark the job stopping and reported. A producer
- * throw propagates without changing job state. Throws for an unknown or
+ * Project one job without changing its cursor. Throws for an unknown or
  * foreign job.
+ * @param id - job to look up.
+ * @param caller - reading session checked against the owner.
+ * @returns a fresh projection.
+ */
+abstract get(id: JobId, caller?: SessionId): JobView
+
+/**
+ * Consume the ring from the model cursor and advance it to the current
+ * total. After settlement the first read also carries the producer's
+ * result. Throws for an unknown or foreign job.
+ * @param id - job to read.
+ * @param caller - reading session checked against the owner.
+ * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection.
+ */
+abstract read(id: JobId, caller?: SessionId): JobRead
+
+/**
+ * Read retained ring output without moving the model cursor. Resume with
+ * a previous read's `next`; an offset inside a retained chunk returns the
+ * whole chunk (its `at` may precede `from`). Throws for a negative or
+ * non-integer offset, or an unknown or foreign job.
+ * @param id - job to read.
+ * @param from - absolute byte offset to read from (0 for the retained head).
+ * @param caller - reading session checked against the owner.
+ * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.
+ */
+abstract readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead
+
+/**
+ * Request cancellation, then mark the job stopping. A producer throw
+ * propagates without changing job state. A supplied reason is merged into
+ * terminal `detail` when the job settles `killed`. Throws for an unknown
+ * or foreign job.
  * @param id - job to cancel.
- * @param caller - killing agent checked against the owner.
- * @param reason - logged reason forwarded to the producer.
+ * @param caller - killing session checked against the owner.
+ * @param reason - cancellation reason forwarded verbatim to the producer.
  * @returns `requested` for live work, otherwise `already-finished`.
  */
-abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+abstract kill(id: JobId, caller?: SessionId, reason?: string): 'requested' | 'already-finished'
 
 /**
  * Wait for settlement or timeout without cancelling the job. Caller abort
  * rejects only while the job is live; after settlement the terminal
- * snapshot wins so a notice suppressed for this waiter is still delivered.
- * Throws for invalid, unknown, or foreign input.
+ * projection wins. Rejects for an invalid timeout or an unknown or foreign
+ * job.
  * @param id - job to wait for.
  * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
+ * @param caller - waiting session checked against the owner.
  * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
+ * @returns projection at settlement or timeout.
  */
-abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>
-
-/**
- * Register an effect-scoped completion listener. It receives the settlements
- * of the owners its registering context's scope covers; each listener is
- * contained; returned promises are observed but not awaited. No listener runs
- * after service disposal.
- * @param listener - receives each terminal snapshot and its exact owner.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobDone(listener: JobDoneListener): () => void
-
-/**
-/**
- * Register an effect-scoped observer of visible-set changes. It fires after
- * every commit that changes what {@link list} returns for that owner —
- * registration, every stopping transition (including the one teardown
- * performs before it awaits a slow producer), settlement, owner-disposal
- * removal, and the emptying that service disposal commits — so an observer
- * re-reads rather than accumulating deltas.
- *
- * Delivery is owner-relative on the same terms as {@link onJobDone}: an
- * observer registered from an unscoped context — a host composition's own
- * carrier — sees every owner, while one registered under an agent
- * composition's scope sees exactly the agents composed under it.
- *
- * This is not a superset of {@link onJobDone}: that one delivers the terminal
- * record under first-wins semantics a job 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
- *   `undefined` when an unowned job changed and every caller's set did.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobsChanged(listener: JobsChangedListener): () => void
+abstract wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView>
 
 /**
  * Attach an effect-scoped controller that can read and stop jobs. It serves the
@@ -284,7 +461,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void
 abstract attachController(name: string): () => void
 ```
 
-Types: [Agent](core.zh.md)
+Types: [SessionId](core.zh.md)
 
 Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts)
 <!-- END GENERATED cordis-surface -->
diff --git a/docs/subsystems/office-to-pdf.i18n.yaml b/docs/subsystems/office-to-pdf.i18n.yaml
index 7f4afe0589..200c1c670b 100644
--- a/docs/subsystems/office-to-pdf.i18n.yaml
+++ b/docs/subsystems/office-to-pdf.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/office-to-pdf.md
-office-to-pdf.md: 65f46ded856e81f9bcd7890c11c82f0a22f769c4
-office-to-pdf.zh.md: df46af01d78241bbc88f6b85a83c47551faf4bfe
+office-to-pdf.md: dd0f6392f264775f12c0f7612656f1c07366567d
+office-to-pdf.zh.md: 5c99f87681dd8d98da3717a311a7f858d4b52b32
diff --git a/docs/subsystems/office-to-pdf.md b/docs/subsystems/office-to-pdf.md
index 65f46ded85..dd0f6392f2 100644
--- a/docs/subsystems/office-to-pdf.md
+++ b/docs/subsystems/office-to-pdf.md
@@ -29,7 +29,7 @@ The provider admits the deferred read before allocating source bytes, shares con
 
 ## Preview reads
 
-`RenderedDocumentBytes` extends the workspace byte response with `missingFonts` and `generation`; the original source identity accompanies the converted PDF.
+`RenderedDocumentBytes` carries workspace file metadata, base64 PDF `data`, `missingFonts`, and `generation`; the original source identity accompanies the converted PDF.
 
 The `officeToPdf.render` Remote method checks source authorization and versions through the Session's [Workspace Files](../../packages/api/workspace-files/README.md) service. After conversion admission, `fs.readBytes` supplies raw input within the reserved byte capacity; Office input limits govern this read. The response carries base64 PDF bytes with the source absolute path and freshness version. Source access failures pass through; size and engine failures expose a classified reason without diagnostics. Conversion does not activate an Agent or append events.
 
diff --git a/docs/subsystems/office-to-pdf.zh.md b/docs/subsystems/office-to-pdf.zh.md
index df46af01d7..5c99f87681 100644
--- a/docs/subsystems/office-to-pdf.zh.md
+++ b/docs/subsystems/office-to-pdf.zh.md
@@ -29,7 +29,7 @@
 
 ## 预览读取
 
-`RenderedDocumentBytes` 在工作区字节响应上增加 `missingFonts` 和 `generation`；转换后的 PDF 附带原始源文件身份。
+`RenderedDocumentBytes` 携带工作区文件元数据、base64 PDF `data`、`missingFonts` 和 `generation`；转换后的 PDF 附带原始源文件身份。
 
 `officeToPdf.render` Remote 方法通过 Session 的[工作区文件](../../packages/api/workspace-files/README.zh.md)服务检查源文件授权与版本。取得转换容量后，`fs.readBytes` 在预留字节容量内提供原始输入；该读取受 Office 输入上限约束。响应携带 base64 PDF 字节、源文件绝对路径与新鲜度版本。源访问失败直接传递；大小和引擎失败只暴露分类原因，不含诊断信息。转换不激活 Agent 或追加事件。
 
diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml
index 83eecfd1c7..878b270089 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: 62f7785d4d1db9c30706a8b967e6f4073b810149
-session.zh.md: 7cd3c38162df209d245d3f1085ab1edce002531a
+session.md: be48d4833bacbac31f3765e0b4d9cdcf6da9f4d7
+session.zh.md: 093fc6d570e93dc5be42d8779fc4d5965085b7e0
diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md
index 62f7785d4d..be48d4833b 100644
--- a/docs/subsystems/session.md
+++ b/docs/subsystems/session.md
@@ -758,6 +758,8 @@ The backends that consume this contract are on [persistence.md](persistence.md).
 
 `SessionOpenWorkspacePathRequest` carries an absolute or workspace-resolved `path`; optional `action: "reveal"` selects file-manager navigation instead of default-application opening. `SessionOpenWorkspacePathValue` confirms that the Host accepted the native handoff. A Session-aware Client resolves relative paths against its current Session cwd when known; the controller hands the path to the opener unchanged and reports invalid requests, cancellation, and opener failures through the Session Remote error vocabulary.
 
+The optional `application` selects a registered file handler without changing the system default; `workspacePathApplications({ path })` returns current handlers, names, icons, and default selection after Host path verification.
+
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -845,6 +847,15 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' |
  */
 @Remote('openWorkspacePath') async openWorkspacePath( request: SessionOpenWorkspacePathRequest, signal: AbortSignal, ): Promise<SessionOpenWorkspacePathValue>
 
+/**
+ * Query current file handlers on the serving desktop without activating an Agent.
+ * @param request - file path in Host filesystem syntax.
+ * @param signal - caller lifetime, propagated to filesystem and desktop queries.
+ * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+ * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+ */
+@Remote('workspacePathApplications') async workspacePathApplications( request: { readonly path: string }, signal: AbortSignal, ): Promise<readonly SessionWorkspacePathApplication[]>
+
 /**
  * Rename one Session after explicitly resuming it.
  * @param request - Session identity and proposed title.
diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md
index 7cd3c38162..093fc6d570 100644
--- a/docs/subsystems/session.zh.md
+++ b/docs/subsystems/session.zh.md
@@ -762,6 +762,8 @@ interface TurnEndReasonMap {
 
 `SessionOpenWorkspacePathRequest` 携带绝对路径或已按 workspace 解析的 `path`。`SessionOpenWorkspacePathValue` 确认 Host 已接受原生交接。Session-aware Client 会在已知当前 Session cwd 时据此解析相对路径；controller 将路径原样交给打开器，并通过 Session Remote 错误词汇表报告无效请求、取消与打开器失败。 可选的 `action: "reveal"` 选择文件管理器导航；省略时使用默认应用打开。
 
+可选的 `application` 指定文件关联应用，不修改系统默认值；`workspacePathApplications({ path })` 在校验 Host 路径后返回当前关联应用、名称、图标和默认项。
+
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -849,6 +851,15 @@ workspaceDesktop(): { name: string; available: boolean; fileManager: 'finder' |
  */
 @Remote('openWorkspacePath') async openWorkspacePath( request: SessionOpenWorkspacePathRequest, signal: AbortSignal, ): Promise<SessionOpenWorkspacePathValue>
 
+/**
+ * Query current file handlers on the serving desktop without activating an Agent.
+ * @param request - file path in Host filesystem syntax.
+ * @param signal - caller lifetime, propagated to filesystem and desktop queries.
+ * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+ * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+ */
+@Remote('workspacePathApplications') async workspacePathApplications( request: { readonly path: string }, signal: AbortSignal, ): Promise<readonly SessionWorkspacePathApplication[]>
+
 /**
  * Rename one Session after explicitly resuming it.
  * @param request - Session identity and proposed title.
diff --git a/docs/subsystems/shell.i18n.yaml b/docs/subsystems/shell.i18n.yaml
index be9a099f49..9c6c29422c 100644
--- a/docs/subsystems/shell.i18n.yaml
+++ b/docs/subsystems/shell.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/shell.md
-shell.md: de04083093a1e53aedd310f388f778638d858ce7
-shell.zh.md: d68b1b2cfba3214a23e9120f19fc9a029a181a18
+shell.md: 734b9e7c72948be23d2c6a2c82c6af27c1e2812b
+shell.zh.md: bfe455c2e5f680f743188e8accb70008a95ab8f9
diff --git a/docs/subsystems/shell.md b/docs/subsystems/shell.md
index de04083093..734b9e7c72 100644
--- a/docs/subsystems/shell.md
+++ b/docs/subsystems/shell.md
@@ -195,6 +195,13 @@ interface ShellProcess {
    * full-stream spill files when available.
    */
   readOutput(): ShellProcessRead
+  /**
+   * Non-consuming offset readers over the same captured streams the consuming
+   * {@link readOutput} cursor drains, including the provider-failure note a
+   * rejected spawn leaves on stderr. Independent observers read here at their
+   * own offsets without stealing bytes from `readOutput`.
+   */
+  observed: ShellObservedStreams
   /**
    * Terminate the provider-managed range. Returns false when it had already finished
    * (no-op); idempotent.
diff --git a/docs/subsystems/shell.zh.md b/docs/subsystems/shell.zh.md
index d68b1b2cfb..bfe455c2e5 100644
--- a/docs/subsystems/shell.zh.md
+++ b/docs/subsystems/shell.zh.md
@@ -195,6 +195,13 @@ interface ShellProcess {
    * full-stream spill files when available.
    */
   readOutput(): ShellProcessRead
+  /**
+   * Non-consuming offset readers over the same captured streams the consuming
+   * {@link readOutput} cursor drains, including the provider-failure note a
+   * rejected spawn leaves on stderr. Independent observers read here at their
+   * own offsets without stealing bytes from `readOutput`.
+   */
+  observed: ShellObservedStreams
   /**
    * Terminate the provider-managed range. Returns false when it had already finished
    * (no-op); idempotent.
diff --git a/docs/subsystems/sidebar-right.i18n.yaml b/docs/subsystems/sidebar-right.i18n.yaml
index a1164e5891..b4d97350d4 100644
--- a/docs/subsystems/sidebar-right.i18n.yaml
+++ b/docs/subsystems/sidebar-right.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/sidebar-right.md
-sidebar-right.md: 9ad6bd63ed63c5c59dbe29cd1229a6412ad22de2
-sidebar-right.zh.md: d0a967f400ea80ab696e24e1b4f46d7d8664eff8
+sidebar-right.md: bade9a958a62368b84ddfae8b5dbe869dfe11e4a
+sidebar-right.zh.md: 93a6f1f25171b19fef5876e353e4b8be46aef78d
diff --git a/docs/subsystems/sidebar-right.md b/docs/subsystems/sidebar-right.md
index 9ad6bd63ed..bade9a958a 100644
--- a/docs/subsystems/sidebar-right.md
+++ b/docs/subsystems/sidebar-right.md
@@ -8,7 +8,7 @@ This page is the reference for the subsystem's contracts: addresses, tab-type re
 
 ## Position and ownership
 
-One docking surface exists per Session, held in a session-scoped slot store and drawn by `rightbar.session`. The root-scoped `rightbar` controller mounts that seat only while Conversation is selected; a reload returns every session to the collapsed default, and switching sessions keeps each surface where it was ([state](../../packages/client/ui-sidebar-right/README.md#state)). The surface's every change is one recorded history entry computed by the kit's pure planners; a docked pane never stays empty, and an empty root pane receives the default page selected from registered guide entries.
+One docking surface exists per Session, held in a session-scoped slot store and drawn by `rightbar.session`. The root-scoped `rightbar` controller retains separate seats for the selected Session and background Sessions with initialized `keepMounted` bodies; only the foreground Conversation is visible. Reload restores saved layouts ([state](../../packages/client/ui-sidebar-right/README.md#state)). The surface's every change is one recorded history entry computed by the kit's pure planners; a docked pane never stays empty, and an empty root pane receives the default page selected from registered guide entries.
 
 A tab type is two registrations that share the definition's `id`: a static definition in `ctx.sidebarRightTabs` saying which addresses its `kind` opens, and a keyed slot registration supplying its body. The framework injects `useTabInfo()` for live Sidebar, pane and tab information; each type keeps its own state in its slot store. Packages import each other's declarations only as types.
 
@@ -43,6 +43,7 @@ Tab identity is the pair `(kind, address)`: the registry's claim uses the addres
 | `priority` | One of three literal bands: `extension` (the default and the highest: a type from outside the product outranks every shipped viewer), `builtin` (types shipped with the product), `fallback` (plain-content viewers anything more specific should beat). |
 | `canOpen(address)` | Optional synchronous veto of a glob match; it runs on every routing decision. |
 | `title(address)` | The chip's text, captured into the layout record when the tab opens and never rewritten. |
+| `keepMounted` | Optional lazy retention of visited bodies across hiding, Session switches and docking; the owning View holds the Session reference. |
 | `guide` | Optional entry boxes for the guide page: `{ order, title(), description?(), icon? }`. Picking a box opens the contributing type as a page; omit to stay off the page. |
 
 Routing is a ranked claim. `candidates(address)` ranks the types whose patterns match and whose `canOpen` does not veto: by band, then by the length of the longest matched pattern, then by registration order. `claim(address, kind?)` picks the first candidate, or the named `kind` outright — its globs are skipped, its `canOpen` still applies — and returns `{ kind, contentId: address, title }`. An address no type claims throws: it is a wiring mistake, not a user error.
@@ -101,7 +102,7 @@ The Sidebar declares four extension slots; its document tab declares the additio
 | `sidebar.right.tab.menu.item` | list, Session scope | Content-level actions appended after the kit's own layout actions. An item that acts must call the owner's `dismiss()`. |
 | `sidebar.right.tab.document` | keyed by the document implementation's `id`, Session scope | The selected file renderer inside the document tab; the parent owns shared loading and toolbar controls. |
 
-A body, title and guide replacement receive the framework-injected `useTabInfo()`. It returns `{ sidebar, panel, tab }`: `sidebar` holds `expanded` and `fullscreen`, `panel.id` names the containing pane, and `tab` contains its record fields plus `visible`, `navigation`, `signal`, and `actions`. Docked bodies are visible only while expanded and active; docked titles need only expansion; floats stay visible. `signal` aborts when the record disappears or the plugin unloads, not on hiding or Session switching. `tab.actions` provides `openResource`, `openTab`, and `close`, bound to the tab's own Session. Open placement defaults to its current pane; `revealIfOpened` defaults to `true`, and `replaceTab: true` replaces this record in the same history entry. Menu entries retain plain `tab` and `dismiss` owner parameters.
+A body, title and guide replacement receive the framework-injected `useTabInfo()`. It returns `{ sidebar, panel, tab }`: `sidebar` holds `expanded` and `fullscreen`, `panel.id` names the containing pane, and `tab` contains its record fields plus `visible`, `navigation`, `signal`, and `actions`. All tabs require a foreground Session. Docked bodies also require expansion and selection; docked titles require expansion; foreground floats survive collapse. `signal` aborts when the record disappears or the plugin unloads, not on hiding or Session switching. `tab.actions` provides `openResource`, `openTab`, and `close`, bound to the tab's own Session. Open placement defaults to its current pane; `revealIfOpened` defaults to `true`, and `replaceTab: true` replaces this record in the same history entry. Menu entries retain plain `tab` and `dismiss` owner parameters.
 
 `navigation.revision` increments on every navigation to the tab whether or not `params` changed, so a body can act on "navigated again" alone; it is `1` for a tab opened by address and `0` for a record nobody opened by address — a seeded guide, or a tab restored by undo. The Tab domain holds one occurrence per open record: a record that appears is pinned in the resource model, so switching tabs unmounts a body without dropping its content; a record that vanishes is aborted and dropped; a record restored by undo is a new occurrence ([Tab domain](../../packages/client/ui-sidebar-right/README.md#the-tab-domain)).
 
@@ -111,7 +112,7 @@ The `text` tab is the shared Document Preview owner. Its [root registration](../
 
 The [registry](../../packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts) records unique `id`, `extensions`, localized `title()`, `loading`, optional `priority`, and optional `wrap`. Case-insensitive suffix matching ranks `extension` (the default) before `builtin`, then longer suffixes before shorter ones, then registration order. Unlike tab-kind replacement, the registry keeps all implementations available; the toolbar lists matching alternatives and remembers the selection per tab. Unknown extensions use plain text. Suffixes declared in `binaryExtensions` suppress the plain-text alternative, as described in the [package README](../../packages/client/ui-sidebar-documentpreview/README.md#what-it-registers). `loading` is `text-pages`, `bytes-complete`, or `renderer`; `wrap` advertises support for the shared source-wrap control.
 
-[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) derives from `PropsRuntime<'sidebar.right.tab.document'>`. The owner supplies the original `resourceAddress`, `content`, current `wrap`, and `addResource` / `setResources` dependency callbacks: text content is `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`, with cumulative `text`; complete bytes are `{ kind: 'bytes', data }`, with `Uint8Array<ArrayBuffer>` data. These transient buffers are borrowed read-only and must not enter durable layout or Session JSON. PDF copies the bytes before Worker transfer, preserving the owner's buffer. The child receives the same framework-bound `useTabInfo` and the global metadata-only `useResource`. The parent reads through ordinary inject callbacks to `remote.workspaceFiles.read`/`readAll` and owns page appends, per-tab refresh, and loading status. HTML's own inject callback uses `readRelated`; Host code resolves paths. Markdown and code retain one incremental renderer across appends and settle at EOF; HTML and PDF receive complete bytes.
+[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) derives from `PropsRuntime<'sidebar.right.tab.document'>`. The owner supplies the original `resourceAddress`, `content`, current `wrap`, and `addResource` / `setResources` dependency callbacks: text content is `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`, with cumulative `text`; complete bytes are `{ kind: 'bytes', data }`, with `Uint8Array<ArrayBuffer>` data. These transient buffers are borrowed read-only and must not enter durable layout or Session JSON. PDF copies the bytes before Worker transfer, preserving the owner's buffer. The child receives the same framework-bound `useTabInfo` and the global metadata-only `useResource`. The parent reads text through `remote.workspaceFiles.read` and bytes through `remote.workspaceFiles.readBytes`, and owns page appends, per-tab refresh, and loading status. HTML passes `baseFile` to the same byte reader; Host code resolves paths. Markdown and code retain one incremental renderer across appends and settle at EOF; HTML and PDF receive complete bytes.
 
 Preview records its loaded version and the version observed when a read starts. Automatic refresh defaults to enabled; initial member metadata establishes a baseline, and later changes reload the tab. Refresh rereads only that tab, without changing shared metadata or another tab's content. Reads are non-transactional; versions are opaque equality tokens, not ordered timestamps ([resource observation and Preview RPC](../../.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md)).
 
@@ -127,16 +128,16 @@ A resource stays open while it has a holder — a subscribed `useResource` or a
 
 ## Workspace Files
 
-The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote namespace read files allowed by the Session filesystem backend: `stat(path)` returns `{ absolutePath, version, bytes? }`; `read(path, { offset?, limit? })` returns one page of lines (`offset` 1-based, `limit` capped by the configured page size) as `{ …stat, offset, text, eof }`; `readBytes(path, { offset?, length? })` returns one raw byte window (`offset` 0-based, `length` capped by the configured byte limit) as base64 `{ …stat, offset, data, eof }` with no text decoding. `list(path)` remains inside the workspace root and returns a directory's direct children (`name`, `type: 'file' | 'directory' | 'other'`, `size?`) cut to the configured cap with `truncated` set. `changes(path)` watches one target; the Host determines its type and confines directories to the workspace. It yields `{ kind: 'ready' }` once subscribed, then `{ kind: 'change', change }` frames whose payload is `{ absolutePath, version }` or `{ absolutePath, absent: true }` ([README](../../packages/api/workspace-files/README.md#use-this-package)). File reads reject final symlinks and enforce transfer caps; `read` additionally requires UTF-8 text. Failures use `workspace-file/*` codes ([failures](../../packages/api/workspace-files/README.md)).
+The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote namespace read files allowed by the Session filesystem backend: `stat(path)` returns `{ absolutePath, version, bytes? }`; `read(path, { offset?, limit? })` returns one page of lines (`offset` 1-based, `limit` capped by the configured page size) as `{ …stat, offset, text, eof }`; `readBytes(path, { range?, baseFile? })` returns a complete file under `maxFileBytes` or a byte window under `maxBytes` as `{ …stat, offset, data, eof }` with native `Uint8Array` data. Its optional `range` uses 0-based `offset` and a byte `length`; `baseFile` resolves the relative target from another file’s directory. `list(path)` remains inside the workspace root and returns a directory's direct children (`name`, `type: 'file' | 'directory' | 'other'`, `size?`) cut to the configured cap with `truncated` set. `changes(path)` watches one target; the Host determines its type and confines directories to the workspace. It yields `{ kind: 'ready' }` once subscribed, then `{ kind: 'change', change }` frames whose payload is `{ absolutePath, version }` or `{ absolutePath, absent: true }` ([README](../../packages/api/workspace-files/README.md#use-this-package)). File reads reject final symlinks and enforce transfer caps; `read` additionally requires UTF-8 text. Failures use `workspace-file/*` codes ([failures](../../packages/api/workspace-files/README.md)).
 
-[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) registers the `file` provider, with `ResourceProtocolMap.file` directly naming `WorkspaceFileStat`. A Session address carries the authorizing Session and a relative or absolute path, passed unchanged to the Host for resolution. The provider waits for Host `ready` before stat and filters changes by `stat.absolutePath`. Bare `absolute` addresses have no authorizing Session and fail with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Any UI, including Global components, shares the observation for the same complete address. Preview's ordinary Remote callbacks use the Session in that address; Host `readAll` and `readRelated` remain, and Preview's `rpc.ts` decodes byte results.
+[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) registers the `file` provider, with `ResourceProtocolMap.file` directly naming `WorkspaceFileStat`. A Session address carries the authorizing Session and a relative or absolute path, passed unchanged to the Host for resolution. The provider waits for Host `ready` before stat and filters changes by `stat.absolutePath`. Bare `absolute` addresses have no authorizing Session and fail with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Any UI, including Global components, shares the observation for the same complete address. Preview's Remote callbacks use the Session in that address; `remote.workspaceFiles.readBytes` returns native bytes through Connection's binary RPC transport.
 
 ## Shipped types
 
 - **`guide`** — `builtin`, opened as `openTab('guide')`. A muted compass sits above one capsule per contributed `guide` entry, in `order`; short lists show registered descriptions, and every missing icon uses the shipped placeholder. Picking a capsule opens the contributing type as a page in the guide tab's place. A pane holds at most one guide tab, and the strip's add control appears only while its pane has none. A new pane receives the registered default page: the sole guide entry directly, or the guide when the entry count is not one ([guide](../../packages/client/ui-sidebar-right/README.md#the-guide)).
 - **`text`** — `fallback`, `dsh-resource://file/**`, claiming Session addresses only. Document Preview observes metadata through `useResource<'file'>`, loads content through Remote callbacks, and owns renderer selection, the toolbar, per-tab refresh, scroll, and source navigation; unknown extensions render as plain text ([README](../../packages/client/ui-sidebar-documentpreview/README.md)).
 - **`files`** — `builtin`, opened as `openTab('files')`. The workspace directory tree, listed lazily through `list` and watched by expanded directory, opening a file with `tab.actions.openResource(fileAddressFor(sessionId, root, path))` into its own pane ([README](../../packages/client/ui-sidebar-files/README.md)).
-- **`browser`** — multi-instance `builtin`, opened as `openTab('browser', { params: { url? } })`. Assistant Markdown delegates HTTP(S) links to this page type. It accepts public and loopback HTTP(S) targets under the default sandbox, rejects local files in favor of Document Preview, and uses application-known iframe history ([README](../../packages/client/ui-sidebar-browser/README.md)).
+- **`browser`** — multi-instance `builtin`, opened as `openTab('browser', { params: { url? } })`. Chat's [link preference](../../packages/client/ui-chat/README.md) controls whether Assistant Markdown opens HTTP(S) links here. It accepts public and loopback HTTP(S) targets under the default sandbox, rejects local files in favor of Document Preview, and uses application-known iframe history ([README](../../packages/client/ui-sidebar-browser/README.md)).
 - **`subagentchat`** — `builtin`, `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>`. An explicitly addressed subagent Conversation retained by the resource provider and rendered through the shared Conversation Factory ([README](../../packages/client/ui-subagent/README.md)).
 
 <a id="not-built"></a>
diff --git a/docs/subsystems/sidebar-right.zh.md b/docs/subsystems/sidebar-right.zh.md
index d0a967f400..93a6f1f251 100644
--- a/docs/subsystems/sidebar-right.zh.md
+++ b/docs/subsystems/sidebar-right.zh.md
@@ -8,7 +8,7 @@
 
 ## 定位与归属
 
-每个会话恰有一个停靠面，保存在会话作用域的 slot store 里、由 `rightbar.session` 绘制。root 作用域的 `rightbar` 控制器仅在选中 Conversation 时挂载该席位；刷新页面后每个会话回到折叠的默认态，切换会话时各自的面保持原状（[状态](../../packages/client/ui-sidebar-right/README.zh.md#state)）。面的每一次变化都是 kit 纯规划器算出的一条历史记录；停靠的 pane 从不空着，根 pane 为空时会加入根据已注册引导入口选出的默认页。
+每个会话恰有一个停靠面，保存在会话作用域的 slot store 里、由 `rightbar.session` 绘制。root 作用域的 `rightbar` 控制器为选中 Session 和拥有已初始化 `keepMounted` 正文的后台 Session 保留独立席位；只有前台 Conversation 可见。刷新会恢复已保存的布局（[状态](../../packages/client/ui-sidebar-right/README.zh.md#state)）。面的每一次变化都是 kit 纯规划器算出的一条历史记录；停靠的 pane 从不空着，根 pane 为空时会加入根据已注册引导入口选出的默认页。
 
 一个 tab 类型是共用定义 `id` 的两次注册：在 `ctx.sidebarRightTabs` 里的静态定义说明其 `kind` 打开哪些地址，一次 keyed slot 注册提供它的正文。框架注入 `useTabInfo()` 以读取 Sidebar、窗格和标签的实时信息；各类型把自身状态放在 slot store 里。各包之间只以类型形式引用彼此的声明。
 
@@ -43,6 +43,7 @@ tab 身份是 `(kind, address)` 二元组：注册表的认领把地址原文用
 | `priority` | 三档字面量之一：`extension`（缺省且最高：产品之外的类型压过所有内置查看器）、`builtin`（随产品发布的类型）、`fallback`（任何更具体的类型都应压过的纯内容查看器）。 |
 | `canOpen(address)` | 可选的同步否决，对 glob 命中生效；每次路由决策都会调用。 |
 | `title(address)` | chip 文本，在 tab 打开时捕获进布局记录，之后不再改写。 |
+| `keepMounted` | 可选的懒保活：已访问正文跨隐藏、Session 切换与停靠切换保留，由所属 View 持有 Session reference。 |
 | `guide` | 可选的引导页入口框：`{ order, title(), description?(), icon? }`。点一框即把贡献它的类型作为页面打开；省略即不上引导页。 |
 
 路由是一次排序认领。`candidates(address)` 对模式命中且未被 `canOpen` 否决的类型排序：先按档，再按最长命中模式的长度，最后按注册顺序。`claim(address, kind?)` 取第一个候选，或直接用点名的 `kind`——跳过它的 glob，但 `canOpen` 仍生效——返回 `{ kind, contentId: address, title }`。没有任何类型认领的地址会抛错：这是接线错误，不是用户错误。
@@ -101,7 +102,7 @@ Sidebar 声明四个扩展 slot；其文档 tab 另行声明下表中的 keyed 
 | `sidebar.right.tab.menu.item` | list，会话作用域 | 追加在 kit 自身布局动作之后的内容级动作。执行了动作的条目必须调用 owner 的 `dismiss()`。 |
 | `sidebar.right.tab.document` | 按文档实现的 `id` keyed，会话作用域 | 文档 tab 内选中的文件渲染器；父组件拥有共享加载与工具栏控件。 |
 
-正文、标题与引导页替换项接收框架注入的 `useTabInfo()`。它返回 `{ sidebar, panel, tab }`：`sidebar` 包含 `expanded` 与 `fullscreen`，`panel.id` 标识所属窗格，`tab` 包含记录字段以及 `visible`、`navigation`、`signal` 和 `actions`。停靠正文仅在展开且活跃时可见；停靠标题只要求展开；浮窗保持可见。`signal` 在记录消失或插件卸载时中止，不因隐藏或切换 Session 而中止。`tab.actions` 提供绑定到标签所属 Session 的 `openResource`、`openTab` 与 `close`。打开位置缺省为当前所属窗格；`revealIfOpened` 缺省为 `true`，`replaceTab: true` 在同一历史项中替换本记录。菜单项保留普通的 `tab` 与 `dismiss` owner 参数。
+正文、标题与引导页替换项接收框架注入的 `useTabInfo()`。它返回 `{ sidebar, panel, tab }`：`sidebar` 包含 `expanded` 与 `fullscreen`，`panel.id` 标识所属窗格，`tab` 包含记录字段以及 `visible`、`navigation`、`signal` 和 `actions`。所有 tab 都要求 Session 位于前台。停靠正文还要求展开且选中；停靠标题要求展开；前台浮窗不随整栏收起。`signal` 在记录消失或插件卸载时中止，不因隐藏或切换 Session 而中止。`tab.actions` 提供绑定到标签所属 Session 的 `openResource`、`openTab` 与 `close`。打开位置缺省为当前所属窗格；`revealIfOpened` 缺省为 `true`，`replaceTab: true` 在同一历史项中替换本记录。菜单项保留普通的 `tab` 与 `dismiss` owner 参数。
 
 `navigation.revision` 在每次导航到该 tab 时递增，`params` 不变也递增，正文可仅凭「又被导航了」行动；按地址打开的 tab 为 `1`，没有人按地址打开的记录——种入的引导、撤销恢复的 tab——为 `0`。Tab 域为每条打开的记录保有一个 occurrence：记录出现即在资源模型里钉住，因此切换 tab 卸载正文也不丢内容；记录消失即中止并丢弃；撤销恢复的记录是新的 occurrence（[Tab 域](../../packages/client/ui-sidebar-right/README.zh.md#the-tab-domain)）。
 
@@ -111,7 +112,7 @@ Sidebar 声明四个扩展 slot；其文档 tab 另行声明下表中的 keyed 
 
 [注册表](../../packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts)记录唯一的 `id`、`extensions`、本地化 `title()`、`loading`，以及可选的 `priority` 和 `wrap`。后缀匹配不区分大小写，先排 `extension`（缺省值）、再排 `builtin`，随后比较后缀长度（长者优先）与注册顺序。与 tab kind 替换不同，注册表保留所有实现；工具栏列出匹配的候选，按 tab 记住选择。未知扩展名使用纯文本。`binaryExtensions` 声明的后缀不提供纯文本备选，见[包 README](../../packages/client/ui-sidebar-documentpreview/README.zh.md#what-it-registers)。`loading` 为 `text-pages`、`bytes-complete` 或 `renderer`；`wrap` 声明是否支持共享的源码换行控件。
 
-[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) 派生自 `PropsRuntime<'sidebar.right.tab.document'>`。owner 提供原始 `resourceAddress`、`content`、当前 `wrap`，以及声明依赖的 `addResource` / `setResources` 回调：文本内容为 `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`，其中 `text` 为累积文本；完整字节为 `{ kind: 'bytes', data }`，其中 `data` 为 `Uint8Array<ArrayBuffer>`。这些瞬时缓冲区按只读方式借用，不得进入持久布局或 Session JSON。PDF 在转移到 Worker 前复制字节，以保留 owner 的缓冲区。子组件收到同一个框架绑定的 `useTabInfo`，以及全局共享、仅提供元数据的 `useResource`。父组件通过普通 inject 回调调用 `remote.workspaceFiles.read`/`readAll`，拥有追加分页、逐 tab 刷新与加载状态。HTML 自己的 inject 回调使用 `readRelated`；路径由 Host 代码解析。Markdown 和代码在追加期间保留同一个增量渲染器，到 EOF 完成最终解析；HTML 和 PDF 接收完整字节。
+[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) 派生自 `PropsRuntime<'sidebar.right.tab.document'>`。owner 提供原始 `resourceAddress`、`content`、当前 `wrap`，以及声明依赖的 `addResource` / `setResources` 回调：文本内容为 `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`，其中 `text` 为累积文本；完整字节为 `{ kind: 'bytes', data }`，其中 `data` 为 `Uint8Array<ArrayBuffer>`。这些瞬时缓冲区按只读方式借用，不得进入持久布局或 Session JSON。PDF 在转移到 Worker 前复制字节，以保留 owner 的缓冲区。子组件收到同一个框架绑定的 `useTabInfo`，以及全局共享、仅提供元数据的 `useResource`。父组件通过 `remote.workspaceFiles.read` 读取文本，通过 `remote.workspaceFiles.readBytes` 读取字节，拥有追加分页、逐 tab 刷新与加载状态。HTML 向同一个字节读取方法传入 `baseFile`；路径由 Host 代码解析。Markdown 和代码在追加期间保留同一个增量渲染器，到 EOF 完成最终解析；HTML 和 PDF 接收完整字节。
 
 Preview 记录已载入版本和读取开始时的观察版本。自动刷新默认开启；成员首次元数据只建立基线，后续变化才重新加载 tab。刷新只重读当前 tab，不改变共享元数据或其他 tab 的内容。读取不具备事务性；版本是不透明的相等性令牌，不是可排序的时间戳（[资源观察与 Preview RPC](../../.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md)）。
 
@@ -127,16 +128,16 @@ Preview 记录已载入版本和读取开始时的观察版本。自动刷新默
 
 ## Workspace Files
 
-Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名空间读取 Session 文件系统后端允许的文件：`stat(path)` 返回 `{ absolutePath, version, bytes? }`；`read(path, { offset?, limit? })` 返回一页行（`offset` 1 起，`limit` 受配置页长限制），形如 `{ …stat, offset, text, eof }`；`readBytes(path, { offset?, length? })` 返回一个原始字节窗口（`offset` 0 起，`length` 受配置字节上限限制），形如 base64 的 `{ …stat, offset, data, eof }`、不做文本解码。`list(path)` 仍限定在工作区根内，返回目录的直接子项（`name`、`type: 'file' | 'directory' | 'other'`、`size?`），按配置上限截断并置 `truncated`。`changes(path)` 监听一个目标，由 Host 判断目标类型并将目录限制在工作区内；订阅就绪后产出 `{ kind: 'ready' }`，随后产出 `{ kind: 'change', change }` 帧，其载荷为 `{ absolutePath, version }` 或 `{ absolutePath, absent: true }`（[README](../../packages/api/workspace-files/README.zh.md#use-this-package)）。文件读取拒绝末端符号链接并执行传输上限；`read` 还要求 UTF-8 文本。失败使用 `workspace-file/*` 错误码（[失败](../../packages/api/workspace-files/README.zh.md)）。
+Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名空间读取 Session 文件系统后端允许的文件：`stat(path)` 返回 `{ absolutePath, version, bytes? }`；`read(path, { offset?, limit? })` 返回一页行（`offset` 1 起，`limit` 受配置页长限制），形如 `{ …stat, offset, text, eof }`；`readBytes(path, { range?, baseFile? })` 在 `maxFileBytes` 上限内返回完整文件，或在 `maxBytes` 上限内返回字节窗口，形如 `{ …stat, offset, data, eof }`，其中 `data` 为原生 `Uint8Array`。可选 `range` 使用 0 起算的 `offset` 与字节数 `length`；`baseFile` 从另一文件所在目录解析相对目标。`list(path)` 仍限定在工作区根内，返回目录的直接子项（`name`、`type: 'file' | 'directory' | 'other'`、`size?`），按配置上限截断并置 `truncated`。`changes(path)` 监听一个目标，由 Host 判断目标类型并将目录限制在工作区。订阅就绪后产出 `{ kind: 'ready' }`，随后产出 `{ kind: 'change', change }` 帧，其载荷为 `{ absolutePath, version }` 或 `{ absolutePath, absent: true }`（[README](../../packages/api/workspace-files/README.zh.md#use-this-package)）。文件读取拒绝末端符号链接并执行传输上限；`read` 还要求 UTF-8 文本。失败使用 `workspace-file/*` 错误码（[失败](../../packages/api/workspace-files/README.zh.md)）。
 
-[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 注册 `file` 提供方，`ResourceProtocolMap.file` 直接是 `WorkspaceFileStat`。Session 地址携带授权 Session 与相对或绝对路径，Host 原样接收并解析。提供方在 stat 前等待 Host 的 `ready` 帧，并按 `stat.absolutePath` 过滤变更。裸 `absolute` 地址没有授权 Session，以 `workspace-file/unknown-workspace` 失败，不借用当前或 Tab Session。任何 UI（包括 Global）访问同一完整地址都共享观察。Preview 的普通 Remote 回调使用地址中的 Session；Host `readAll` 和 `readRelated` 保留，字节结果由 Preview 的 `rpc.ts` 解码。
+[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 注册 `file` 提供方，`ResourceProtocolMap.file` 直接是 `WorkspaceFileStat`。Session 地址携带授权 Session 与相对或绝对路径，Host 原样接收并解析。提供方在 stat 前等待 Host 的 `ready` 帧，并按 `stat.absolutePath` 过滤变更。裸 `absolute` 地址没有授权 Session，以 `workspace-file/unknown-workspace` 失败，不借用当前或 Tab Session。任何 UI（包括 Global）访问同一完整地址都共享观察。Preview 的 Remote 回调使用地址中的 Session；`remote.workspaceFiles.readBytes` 通过 Connection 的二进制 RPC 传输返回原生字节。
 
 ## 内置类型
 
 - **`guide`**——`builtin`，以 `openTab('guide')` 打开。一枚弱化的罗盘位于各类型按 `order` 贡献的入口胶囊上方；入口较少时显示已注册的描述，未提供图标的入口统一使用内置占位符。点选胶囊即在引导 tab 的位置把贡献它的类型作为页面打开。每个 pane 最多一个引导 tab，tab 条的新增控件只在本 pane 没有引导时出现。新 pane 使用已注册的默认页：只有一个引导入口时直接使用该入口，否则使用引导页（[引导](../../packages/client/ui-sidebar-right/README.zh.md#the-guide)）。
 - **`text`**——`fallback`，`dsh-resource://file/**`，只认领 Session 地址。Document Preview 通过 `useResource<'file'>` 观察元数据，经 Remote 回调加载内容，并拥有渲染器选择、工具栏、逐 tab 刷新、滚动与源码定位；未知扩展名按纯文本渲染（[README](../../packages/client/ui-sidebar-documentpreview/README.zh.md)）。
 - **`files`**——`builtin`，以 `openTab('files')` 打开。工作区目录树，经 `list` 懒加载，按展开目录建立监听，用 `tab.actions.openResource(fileAddressFor(sessionId, root, path))` 在自己所在 pane 打开文件（[README](../../packages/client/ui-sidebar-files/README.zh.md)）。
-- **`browser`**——可多开的 `builtin`，以 `openTab('browser', { params: { url? } })` 打开。Assistant Markdown 会把 HTTP(S) 链接委托给该页面类型。它在默认 sandbox 下接受公共与 loopback HTTP(S) 目标，本地文件改用 Document Preview，并使用应用已知的 iframe history（[README](../../packages/client/ui-sidebar-browser/README.zh.md)）。
+- **`browser`**——可多开的 `builtin`，以 `openTab('browser', { params: { url? } })` 打开。Chat 的[链接偏好](../../packages/client/ui-chat/README.zh.md)决定 Assistant Markdown 是否在此打开 HTTP(S) 链接。它在默认 sandbox 下接受公共与 loopback HTTP(S) 目标，本地文件改用 Document Preview，并使用应用已知的 iframe history（[README](../../packages/client/ui-sidebar-browser/README.zh.md)）。
 - **`subagentchat`**——`builtin`，`dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>`。资源提供方保留一个显式寻址的 subagent Conversation，并通过共享 Conversation Factory 渲染（[README](../../packages/client/ui-subagent/README.zh.md)）。
 
 <a id="not-built"></a>
diff --git a/docs/subsystems/slots.i18n.yaml b/docs/subsystems/slots.i18n.yaml
index 50d7a12706..152904f4d3 100644
--- a/docs/subsystems/slots.i18n.yaml
+++ b/docs/subsystems/slots.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/slots.md
-slots.md: 1e820fd880163d565a72733372fa4f2cc70a62b5
-slots.zh.md: c5bec8e752b9d9e1922f608449ca3249d0477062
+slots.md: 3a2eb7d0ff7297f6c80fa083134144cbb7a6864e
+slots.zh.md: 16a529aa46837af0aaa675271e765bd88f29e623
diff --git a/docs/subsystems/slots.md b/docs/subsystems/slots.md
index 1e820fd880..3a2eb7d0ff 100644
--- a/docs/subsystems/slots.md
+++ b/docs/subsystems/slots.md
@@ -6,6 +6,8 @@ Slots are the Web Client's typed React composition system. [`dsh-client-ui-slots
 
 This page documents slot ownership, component inputs, extension APIs, and the shipped hierarchy. The surrounding boot, Remote, Client model, and Conversation paths are in [Web Client architecture](web-client.md).
 
+`plugins.bundle.config` supplies bundle detail configuration, keyed by npm package name. `plugins.bundle.activation` renders optional guidance after user-requested enablement, with owner callbacks to dismiss or open that bundle’s details. `conversation.input.activity` supplies one action between the model selector and Send, with toolbar expansion released on unmount.
+
 ## Declaration and lifecycle
 
 `SlotMap` is the compile-time registry. A package declaration-merges the key, cardinality, scope, owner props, keyed props, and optional slot-level inject face. The runtime declaration is the matching `children` entry on the component that owns the render location.
diff --git a/docs/subsystems/slots.zh.md b/docs/subsystems/slots.zh.md
index c5bec8e752..16a529aa46 100644
--- a/docs/subsystems/slots.zh.md
+++ b/docs/subsystems/slots.zh.md
@@ -6,6 +6,8 @@ Slots 是 Web Client 的类型化 React 组合系统。[`dsh-client-ui-slots`](.
 
 本文记录 slot 的所有权、组件输入、扩展 API 与当前层级。外围的启动、Remote、Client model 与 Conversation 数据通路见 [Web Client 架构](web-client.zh.md)。
 
+`plugins.bundle.config` 以 npm 包名为 key，提供 Bundle 详情配置。`plugins.bundle.activation` 在用户显式启用后渲染可选引导，由拥有者提供关闭引导和打开该 Bundle 详情的回调。`conversation.input.activity` 提供模型选择器与发送按钮之间的单个活动控件，可展开工具栏并在卸载时释放展开状态。
+
 ## 声明与生命周期
 
 `SlotMap` 是编译期注册表。包通过声明合并写入 key、cardinality（基数）、scope、owner props、keyed props 与可选的 slot 级 inject face。运行时声明则是拥有该渲染位置的组件在 `children` 中给出的对应条目。
diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml
index 034d835426..805d66f003 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: d642fe1658926b17cb29f280803f12e61228be60
-subagent.zh.md: ff153c7861b4ac46bb058efd00a2f5a50181b6f2
+subagent.md: 67f9bc31b46617ea2f7b1ec81bf8c52fd62720cb
+subagent.zh.md: a69e032ed96a24a980badaf9e14d924311e1d175
diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md
index d642fe1658..67f9bc31b4 100644
--- a/docs/subsystems/subagent.md
+++ b/docs/subsystems/subagent.md
@@ -8,7 +8,7 @@ Service Definition: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subag
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
-The `subagentCatalog` projection exposes `SubagentCatalogEntry[]` in parent event order through Session observations and client snapshots. Each entry contains the child id, creation time, mode, and mode-dependent label; fork-inherited catalog facts are excluded. [The subagent package](../../packages/subagent/subagent/README.md) owns catalog creation and persistence semantics.
+The `subagentCatalog` projection exposes `SubagentCatalogEntry[]` in parent event order through Session observations and client snapshots. Each entry contains the child id, creation time, mode, and mode-dependent label; fork-inherited catalog facts are excluded. [The subagent package](../../packages/subagent/subagent/README.md) owns catalog creation and persistence semantics. Historical children with unavailable descriptors have `mode: 'unknown'`; their header identity remains discoverable without granting continuation capabilities.
 
 ## Two kinds of capability, discovered two ways
 
@@ -465,7 +465,7 @@ The spawn and fork backends create an ordinary one-shot agent through `parent.ct
 - **Delegation depth** is durable `SessionHeader.delegationDepth` plus the merge-extensible runtime field `AgentOptions.subagentDepth`; absence means top-level depth zero, and the greater present value is authoritative. The seam owns both fields — the loop neither sets nor reads them — so an in-process child persists parent depth + 1, cold resume cannot lower it, and every start rejects a derived depth outside the safe-integer domain or above a defined absolute `request.maxDepth` cap.
 - **Fork seeding** uses [`CreateAgentOptions.seed`](core.md#creation-and-ownership) (a `SessionEvent[]` prefix threaded through `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })`, the same primitive `ctx.agents.resume()` uses). The fork backend passes a *balanced completed-turn prefix* of the parent's log — the parent's events up to and including its last `turn/end` — so the seed is contiguous-from-0 and the [invariants](../../packages/runtime-diagnostics/invariants) replay accepts it (the in-flight, unbalanced turn is excluded).
 
-`SubagentCatalogEntry` describes one successful direct-child creation fact; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to complete-descendant listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
+`SubagentCatalogEntry` describes a direct child with complete or unknown-mode discovery information; `SubagentCatalogState` is the host-only projection state. `listChildren()` owns a live-preferred parent observation without opening child logs. Browser consumers read `subagentCatalog` through the shared Session projection store and combine membership with Session-list activity. `SubagentCatalogRow` belongs to complete-descendant listing. [The parent-catalog decision](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns the persistent facts and read semantics.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md
index ff153c7861..a69e032ed9 100644
--- a/docs/subsystems/subagent.zh.md
+++ b/docs/subsystems/subagent.zh.md
@@ -8,7 +8,7 @@ Service Definition：[dsh-subagent](../../packages/subagent/subagent)（`ctx.sub
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
-`subagentCatalog` projection 通过 Session 观察和客户端快照暴露按父会话事件排序的 `SubagentCatalogEntry[]`。每个条目包含子级 id、创建时间、模式和依模式确定的标签；fork 继承的目录事实不在其中。[subagent 包](../../packages/subagent/subagent/README.zh.md) 定义目录创建和持久化语义。
+`subagentCatalog` projection 通过 Session 观察和客户端快照暴露按父会话事件排序的 `SubagentCatalogEntry[]`。每个条目包含子级 id、创建时间、模式和依模式确定的标签；fork 继承的目录事实不在其中。[subagent 包](../../packages/subagent/subagent/README.zh.md) 定义目录创建和持久化语义。历史子会话的 descriptor 不可用时使用 `mode: 'unknown'`，保留 header 身份供发现，但不授予继续执行能力。
 
 ## 两类能力，两种发现方式
 
@@ -469,7 +469,7 @@ spawn 和 fork 后端通过 `parent.ctx` 创建一个普通的单次 agent，将
 - **委派深度**由持久 `SessionHeader.delegationDepth` 与可合并扩展的运行时字段 `AgentOptions.subagentDepth` 共同表示；缺失表示顶层深度为零，存在的较大值具有权威性。两个字段都归该 seam 所有——循环既不设置也不读取它们——因此进程内子 agent 会持久保存 parent 深度 + 1，冷恢复无法降低深度，而且每次 start 都会拒绝超出安全整数域、或高于已定义绝对 `request.maxDepth` 上限的派生深度。
 - **Fork 种子注入**使用 [`CreateAgentOptions.seed`](core.zh.md#creation-and-ownership)（一个 `SessionEvent[]` 前缀，经由 `AgentLoop.createAgent` → `ctx.sessions.prepare({ seed })` 传递，与 `ctx.agents.resume()` 使用的原语相同）。fork 后端传入父级日志的一段*平衡的已完成轮次前缀*——父级事件直到并包括其最后一个 `turn/end`——因此种子从 0 连续，[invariants](../../packages/runtime-diagnostics/invariants) 回放可以接受它（进行中的、未平衡的轮次被排除在外）。
 
-`SubagentCatalogEntry` 描述一条成功创建直接子级的事实；`SubagentCatalogState` 是仅 host 使用的 projection state。`listChildren()` 拥有一次 live-preferred 父 Session observation，不打开子级日志。浏览器消费者通过共享 Session projection store 读取 `subagentCatalog`，并将成员关系与 Session 列表活动状态组合。`SubagentCatalogRow` 属于完整后代列表。[父目录决策](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 规定持久事实与读取语义。
+`SubagentCatalogEntry` 描述一条完整或未知模式的直接子级目录记录；`SubagentCatalogState` 是仅 host 使用的 projection state。`listChildren()` 拥有一次 live-preferred 父 Session observation，不打开子级日志。浏览器消费者通过共享 Session projection store 读取 `subagentCatalog`，并将成员关系与 Session 列表活动状态组合。`SubagentCatalogRow` 属于完整后代列表。[父目录决策](../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 规定持久事实与读取语义。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml
index fb6146eda0..e63a0fe9d5 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: 954c3dfb7e66b100132c6d4604c28f06fba04916
-typert.zh.md: dd2becdc43871ddbecdfb45909e076435ab5a447
+typert.md: db8b48945e2301e14d866b8a2e3df59c4ae408c9
+typert.zh.md: cdaee66201d0f27a5a18aa99cb1888438051e018
diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md
index 954c3dfb7e..db8b48945e 100644
--- a/docs/subsystems/typert.md
+++ b/docs/subsystems/typert.md
@@ -38,7 +38,7 @@ interface TypertLookupDefinition {
 
 ## Invocation descriptors
 
-An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schema factories, while SRC codecs enforce JSON-safe values without structural type recovery. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`.
+An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schema factories, while SRC codecs enforce JSON-safe inputs without structural type recovery. Unary result codecs can supply `encode()` for byte-containing subtrees and `decode()` for recursive native-byte validation; Client declarations narrow every `Uint8Array` to `ArrayBuffer` backing. Pure JSON results need neither byte detection nor Client decoding. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`.
 
 ```ts type-equiv
 /** Codec attached to one invocation parameter or result. */
@@ -48,6 +48,19 @@ type TypertCodec =
     readonly typeSymbol: string
     /** Materialize and return the process-realm schema on first boundary use. */
     readonly create: () => TypertSchema
+    /**
+     * Decode a unary result whose fields require type-specific handling.
+     * @param value - result reconstructed by the RPC carrier.
+     * @returns the validated result, retaining native byte views.
+     */
+    readonly decode?: (value: unknown) => unknown
+    /**
+     * Project typed binary fields into RPC result attachments.
+     * @param value - native unary result.
+     * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
+     * @returns JSON metadata with untouched JSON subtrees retained.
+     */
+    readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown
   }
   | {
     readonly mode: 'src-json'
@@ -85,7 +98,7 @@ interface InvocationDescriptor {
   readonly method: string
   /** Service member invoked when the exported method name is an alias. */
   readonly implementation?: string
-  /** Absent for unary calls; stream calls validate and deliver every yielded item. */
+  /** Absent for unary calls; stream calls deliver every yielded item as the Host produced it. */
   readonly mode?: 'stream'
   /** Receiver selection mode. */
   readonly invocation:
@@ -105,6 +118,16 @@ interface InvocationDescriptor {
   }
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[]
+  /**
+   * Client-to-Host items of the same logical stream, generated from the `In`
+   * type argument of the method's `RemoteStream<Out, In>` return type; absent
+   * when `In` is `never`. The method reads the items through
+   * `RemoteInvocation.uplink()`, so nothing enters the parameter list.
+   */
+  readonly uplink?: {
+    /** Codec validating every uplink item before `uplink()` delivers it. */
+    readonly codec: TypertCodec
+  }
   /** Transport cancellation injected after business parameters instead of entering wire args. */
   readonly cancellation?: {
     /** Reserved final Host method parameter. */
@@ -117,6 +140,106 @@ interface InvocationDescriptor {
 }
 ```
 
+The Host alias `RemoteStream<Out, In>` names both directions of one stream, and the receiving method reads its call context as `this.ctx.invocation`:
+
+```ts type-equiv
+/**
+ * One Remote stream as a Host method returns it: the items it yields to the
+ * Client, iterated as a plain `AsyncIterable<Out>`. `In` is the type of the
+ * items the Client may send back on the same logical stream, read through
+ * `RemoteInvocation.uplink()`; it is carried only as a type-level marker. The
+ * default `never` declares a method that reads none, and its descriptor
+ * carries no uplink codec. A generated Client stream method returns the same
+ * stream as a `RemoteStreamHandle<Out, In>`.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+```
+
+```ts type-equiv
+/**
+ * One open Remote stream as the Client holds it: the downlink items as an
+ * `AsyncIterable`, plus the uplink and cancellation of the same logical
+ * stream. A generated Client stream method returns it, and calling that
+ * method opens the stream: a holder that neither iterates nor disposes the
+ * handle keeps the Host stream alive. A handle stands for one generation:
+ * when the carrier is lost, iteration fails with the carrier error and the
+ * handle is finished.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+  /**
+   * Send one uplink item. Items sent before the stream has opened are queued
+   * and sent once the `open` frame is on the wire. A top-level `undefined`
+   * travels as an `item` frame without `value`.
+   * @param item - item the Host validates against the method's uplink codec.
+   * @throws {Error} when the item is not a lossless JSON value, when `end()`
+   * was called, or once the stream has terminated.
+   */
+  send(item: In): void
+  /** Half-close the uplink: the Host's `uplink()` iteration ends. Idempotent; ignored after termination. */
+  end(): void
+  /**
+   * Cancel the logical stream: send `cancel` unless a terminal frame has
+   * arrived, and end the downlink iterator quietly. Breaking out of
+   * `for await` early does the same.
+   */
+  dispose(): void
+}
+```
+
+```ts type-equiv
+/**
+ * One Peer's session on this Host. Connection owns it: `ctx` is the Cordis
+ * scope that owns connection-lifetime registrations and is disposed with the
+ * Peer. Who the Peer is and what it may do are not recorded here.
+ */
+interface PeerScope {
+  readonly id: PeerId
+  readonly ctx: Context
+  /**
+   * Tear down every registration made through `ctx`.
+   * @returns settles once the scope has quiesced; racing calls share one completion.
+   */
+  dispose(): Promise<void>
+}
+```
+
+```ts type-equiv
+/**
+ * The context of one Remote call, reachable inside the receiving method as
+ * `this.ctx.invocation`. The Gateway derives the receiver from a Context that
+ * carries it, so no parameter is injected and nothing crosses the wire.
+ */
+interface RemoteInvocation {
+  readonly request: {
+    readonly namespace: string
+    readonly method: string
+    readonly args: Readonly<Record<string, unknown>>
+  }
+  /** Cordis service key of the receiving Service. */
+  readonly service: string
+  /** Peer the call speaks for; an in-process carrier speaks for the operator. */
+  readonly peer: PeerScope
+  /** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
+  readonly signal: AbortSignal
+  /**
+   * The Client's uplink items for this call. Available once; a second call
+   * throws. With an uplink codec on the descriptor every item is decoded to
+   * `In`; without one items arrive as `unknown` after a JSON-safety check.
+   * Iteration ends when the Client ends its uplink; when the method finishes
+   * its downlink the Gateway calls the iterator's `return()` and unread items
+   * are dropped. `In` is the caller's assertion: the runtime decodes by the
+   * descriptor and does not cross-check it.
+   * @template In - item type the caller reads; the descriptor codec decides what arrives.
+   * @returns the single-consumer uplink iterable.
+   */
+  uplink<In = unknown>(): AsyncIterable<In>
+}
+```
+
 ## Typert registry
 
 `ctx.typert` separates current-environment descriptors, explicitly selected Remote contributions, lookup providers, and scoped Context providers. A lookup provider owns the stable wire declaration and default resolver; Host composition can configure an effect-scoped synchronous or asynchronous resolver for the same key, and unloading that configuration restores the default policy. Registrations are Cordis-owned effects and return awaitable disposers.
@@ -151,6 +274,13 @@ interface InvokeRemoteRequest {
   readonly method: string
   /** Named wire values; fields must exactly match the descriptor. */
   readonly args: Readonly<Record<string, unknown>>
+  /**
+   * Client uplink items of this logical stream, delivered to the method through
+   * `invocation.uplink()`; absent means an immediately ended iterable.
+   */
+  readonly uplink?: AsyncIterable<unknown>
+  /** Peer the call speaks for; absent means an in-process carrier, answered as the operator. */
+  readonly peer?: PeerScope
   /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
   readonly signal?: AbortSignal
 }
@@ -172,10 +302,12 @@ type TypertGatewayErrorCode =
   | 'gateway/lookup-not-found'
   | 'gateway/lookup-unavailable'
   | 'gateway/method-unavailable'
+  | 'gateway/protocol'
   | 'gateway/provider-mismatch'
   | 'gateway/result-invalid'
   | 'gateway/service-unavailable'
   | 'gateway/signature-invalid'
+  | 'gateway/uplink-overflow'
 ```
 
 ```ts type-equiv
@@ -202,7 +334,7 @@ interface TypertGateway {
   invoke(request: InvokeRemoteRequest): Promise<unknown>
   /**
    * Open one live stream Remote method without assuming a physical carrier.
-   * @param request - decoded endpoint and named wire arguments.
+   * @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
    * @returns a cancellation-aware iterable over the business results.
    */
   stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
@@ -334,7 +466,7 @@ async invoke(request: InvokeRemoteRequest): Promise<unknown>
 
 /**
  * Open one live stream Remote method without assuming a physical carrier.
- * @param request - decoded endpoint and named wire arguments.
+ * @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
  * @returns a cancellation-aware iterable over the business results.
  */
 async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md
index dd2becdc43..cdaee66201 100644
--- a/docs/subsystems/typert.zh.md
+++ b/docs/subsystems/typert.zh.md
@@ -38,7 +38,7 @@ interface TypertLookupDefinition {
 
 ## 调用 descriptor
 
-`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema factory，SRC codec 则在不恢复结构类型的前提下强制要求 JSON 安全值。取消通过带外 carrier signal 表达：它在业务参数之后注入，绝不进入 `args`。
+`InvocationDescriptor` 是本地反射信息，不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor；请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema factory，SRC codec 则在不恢复结构类型的前提下强制要求输入为 JSON 安全值。一元结果 codec 可提供 `encode()` 处理含字节的子树，并通过 `decode()` 递归校验原生字节；Client 声明将每个 `Uint8Array` 限定为以 `ArrayBuffer` 为底层缓冲区。纯 JSON 结果无需字节识别或 Client 解码。取消通过带外 carrier signal 表达：它在业务参数之后注入，绝不进入 `args`。
 
 ```ts type-equiv
 /** Codec attached to one invocation parameter or result. */
@@ -48,6 +48,19 @@ type TypertCodec =
     readonly typeSymbol: string
     /** Materialize and return the process-realm schema on first boundary use. */
     readonly create: () => TypertSchema
+    /**
+     * Decode a unary result whose fields require type-specific handling.
+     * @param value - result reconstructed by the RPC carrier.
+     * @returns the validated result, retaining native byte views.
+     */
+    readonly decode?: (value: unknown) => unknown
+    /**
+     * Project typed binary fields into RPC result attachments.
+     * @param value - native unary result.
+     * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
+     * @returns JSON metadata with untouched JSON subtrees retained.
+     */
+    readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown
   }
   | {
     readonly mode: 'src-json'
@@ -85,7 +98,7 @@ interface InvocationDescriptor {
   readonly method: string
   /** Service member invoked when the exported method name is an alias. */
   readonly implementation?: string
-  /** Absent for unary calls; stream calls validate and deliver every yielded item. */
+  /** Absent for unary calls; stream calls deliver every yielded item as the Host produced it. */
   readonly mode?: 'stream'
   /** Receiver selection mode. */
   readonly invocation:
@@ -105,6 +118,16 @@ interface InvocationDescriptor {
   }
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[]
+  /**
+   * Client-to-Host items of the same logical stream, generated from the `In`
+   * type argument of the method's `RemoteStream<Out, In>` return type; absent
+   * when `In` is `never`. The method reads the items through
+   * `RemoteInvocation.uplink()`, so nothing enters the parameter list.
+   */
+  readonly uplink?: {
+    /** Codec validating every uplink item before `uplink()` delivers it. */
+    readonly codec: TypertCodec
+  }
   /** Transport cancellation injected after business parameters instead of entering wire args. */
   readonly cancellation?: {
     /** Reserved final Host method parameter. */
@@ -117,6 +140,106 @@ interface InvocationDescriptor {
 }
 ```
 
+Host 别名 `RemoteStream<Out, In>` 同时命名一条流的两个方向，接收方法通过 `this.ctx.invocation` 读取本次调用的上下文：
+
+```ts type-equiv
+/**
+ * One Remote stream as a Host method returns it: the items it yields to the
+ * Client, iterated as a plain `AsyncIterable<Out>`. `In` is the type of the
+ * items the Client may send back on the same logical stream, read through
+ * `RemoteInvocation.uplink()`; it is carried only as a type-level marker. The
+ * default `never` declares a method that reads none, and its descriptor
+ * carries no uplink codec. A generated Client stream method returns the same
+ * stream as a `RemoteStreamHandle<Out, In>`.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+```
+
+```ts type-equiv
+/**
+ * One open Remote stream as the Client holds it: the downlink items as an
+ * `AsyncIterable`, plus the uplink and cancellation of the same logical
+ * stream. A generated Client stream method returns it, and calling that
+ * method opens the stream: a holder that neither iterates nor disposes the
+ * handle keeps the Host stream alive. A handle stands for one generation:
+ * when the carrier is lost, iteration fails with the carrier error and the
+ * handle is finished.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+  /**
+   * Send one uplink item. Items sent before the stream has opened are queued
+   * and sent once the `open` frame is on the wire. A top-level `undefined`
+   * travels as an `item` frame without `value`.
+   * @param item - item the Host validates against the method's uplink codec.
+   * @throws {Error} when the item is not a lossless JSON value, when `end()`
+   * was called, or once the stream has terminated.
+   */
+  send(item: In): void
+  /** Half-close the uplink: the Host's `uplink()` iteration ends. Idempotent; ignored after termination. */
+  end(): void
+  /**
+   * Cancel the logical stream: send `cancel` unless a terminal frame has
+   * arrived, and end the downlink iterator quietly. Breaking out of
+   * `for await` early does the same.
+   */
+  dispose(): void
+}
+```
+
+```ts type-equiv
+/**
+ * One Peer's session on this Host. Connection owns it: `ctx` is the Cordis
+ * scope that owns connection-lifetime registrations and is disposed with the
+ * Peer. Who the Peer is and what it may do are not recorded here.
+ */
+interface PeerScope {
+  readonly id: PeerId
+  readonly ctx: Context
+  /**
+   * Tear down every registration made through `ctx`.
+   * @returns settles once the scope has quiesced; racing calls share one completion.
+   */
+  dispose(): Promise<void>
+}
+```
+
+```ts type-equiv
+/**
+ * The context of one Remote call, reachable inside the receiving method as
+ * `this.ctx.invocation`. The Gateway derives the receiver from a Context that
+ * carries it, so no parameter is injected and nothing crosses the wire.
+ */
+interface RemoteInvocation {
+  readonly request: {
+    readonly namespace: string
+    readonly method: string
+    readonly args: Readonly<Record<string, unknown>>
+  }
+  /** Cordis service key of the receiving Service. */
+  readonly service: string
+  /** Peer the call speaks for; an in-process carrier speaks for the operator. */
+  readonly peer: PeerScope
+  /** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
+  readonly signal: AbortSignal
+  /**
+   * The Client's uplink items for this call. Available once; a second call
+   * throws. With an uplink codec on the descriptor every item is decoded to
+   * `In`; without one items arrive as `unknown` after a JSON-safety check.
+   * Iteration ends when the Client ends its uplink; when the method finishes
+   * its downlink the Gateway calls the iterator's `return()` and unread items
+   * are dropped. `In` is the caller's assertion: the runtime decodes by the
+   * descriptor and does not cross-check it.
+   * @template In - item type the caller reads; the descriptor codec decides what arrives.
+   * @returns the single-consumer uplink iterable.
+   */
+  uplink<In = unknown>(): AsyncIterable<In>
+}
+```
+
 ## Typert 注册表
 
 `ctx.typert` 分开保存当前环境的 descriptor、显式选择的 Remote contribution、lookup 提供方与作用域上下文提供方。lookup 提供方拥有稳定 wire 声明和默认 resolver；Host 组合可以为同一个 key 配置 effect-scoped 同步或异步 resolver，配置卸载后恢复默认策略。各项注册都是由 Cordis 持有的 effect，并返回可等待的 disposer。
@@ -151,6 +274,13 @@ interface InvokeRemoteRequest {
   readonly method: string
   /** Named wire values; fields must exactly match the descriptor. */
   readonly args: Readonly<Record<string, unknown>>
+  /**
+   * Client uplink items of this logical stream, delivered to the method through
+   * `invocation.uplink()`; absent means an immediately ended iterable.
+   */
+  readonly uplink?: AsyncIterable<unknown>
+  /** Peer the call speaks for; absent means an in-process carrier, answered as the operator. */
+  readonly peer?: PeerScope
   /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
   readonly signal?: AbortSignal
 }
@@ -172,10 +302,12 @@ type TypertGatewayErrorCode =
   | 'gateway/lookup-not-found'
   | 'gateway/lookup-unavailable'
   | 'gateway/method-unavailable'
+  | 'gateway/protocol'
   | 'gateway/provider-mismatch'
   | 'gateway/result-invalid'
   | 'gateway/service-unavailable'
   | 'gateway/signature-invalid'
+  | 'gateway/uplink-overflow'
 ```
 
 ```ts type-equiv
@@ -202,7 +334,7 @@ interface TypertGateway {
   invoke(request: InvokeRemoteRequest): Promise<unknown>
   /**
    * Open one live stream Remote method without assuming a physical carrier.
-   * @param request - decoded endpoint and named wire arguments.
+   * @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
    * @returns a cancellation-aware iterable over the business results.
    */
   stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
@@ -334,7 +466,7 @@ async invoke(request: InvokeRemoteRequest): Promise<unknown>
 
 /**
  * Open one live stream Remote method without assuming a physical carrier.
- * @param request - decoded endpoint and named wire arguments.
+ * @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
  * @returns a cancellation-aware iterable over the business results.
  */
 async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
diff --git a/docs/subsystems/web-client.i18n.yaml b/docs/subsystems/web-client.i18n.yaml
index 0dfc4fa69c..f89b3c13dc 100644
--- a/docs/subsystems/web-client.i18n.yaml
+++ b/docs/subsystems/web-client.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-client.md
-web-client.md: 6bcf9bf84ed0b049b801c38d2426074d784e8de6
-web-client.zh.md: 9c697964a0f92bc646f5ca305fc3372bebcdc902
+web-client.md: 80d233b634f57bb150d8eb6604428557e1e16033
+web-client.zh.md: f14cdbe9b1d5605b90bd595a384ef7ac9c0d7286
diff --git a/docs/subsystems/web-client.md b/docs/subsystems/web-client.md
index 6bcf9bf84e..80d233b634 100644
--- a/docs/subsystems/web-client.md
+++ b/docs/subsystems/web-client.md
@@ -27,7 +27,7 @@ The Web boot kernel creates the module system, prefetches `immediately` entries,
 
 Host business services annotate callable methods with Typert Remote decorators. Host generation emits strict descriptors, runtime codecs, declaration merges, and source maps. The Client-side `api-remotes` assembly selects those generated contributions and mounts concrete methods under `ctx.remote.<namespace>` and Session-scoped `agentCtx.remote.<namespace>`. Feature packages depend on the generated service face, not the Gateway implementation or a Host package's runtime entry.
 
-The Connection owns request correlation, the `/api` carrier, trust checks, exact Fetch routes, and connection generations. API Gateway owns Remote dispatch, cancellation, logical streams, and selected Host event forwarding. Controller operations belong on generated Remote methods or explicit Remote streams; feature-owned downloads register exact Fetch routes. The [API Gateway reference](../api-gateway.md) defines generation and invocation, while the [Connection README](../../packages/client/connection/README.md) defines the physical carrier and trust policy.
+The Connection owns request URL resolution, correlation, the `/api` carrier, trust checks, exact Fetch routes, and connection generations. API Gateway owns Remote dispatch, cancellation, logical streams, and selected Host event forwarding. Controller operations belong on generated Remote methods or explicit Remote streams; feature-owned downloads register exact Fetch routes. The [API Gateway reference](../api-gateway.md) defines generation and invocation, while the [Connection README](../../packages/client/connection/README.md) defines the physical carrier and trust policy.
 
 The internal `$events` logical stream is the Connection generation source. Its opening `ready` frame carries the Host home used for path display and establishes the generation after Host listeners are attached, before any controller begins a baseline read. `ctx.remote.$on()` delivers allowlisted ordinary events to the root Client Context and scoped waterfall events to the resolved Session Context; a waterfall listener returns a result, calls `next()`, or rejects.
 
@@ -40,10 +40,10 @@ Each API controller package owns a paired Host and Client face. The Host side ow
 [`api/session-controller`](../../packages/api/session-controller/README.md) exposes Host commands for list, search, creation, prompt, queue, cancellation, pagination, and follow/control streams. Its Client side is organized as `ClientSessions → SessionManager → Session`:
 
 - `ClientSessions` provides `ctx.sessions`, owns references, source counts, Session scopes, and stable `SessionBinding` objects, and projects catalog state without selecting a global current Session.
-- `SessionManager` owns the list baseline, live list/control updates, lazy Session instances, queues, projection stores, subagent catalogs, and conflict ordering between pulls and later updates.
+- `SessionManager` owns the list baseline, live list/control updates, lazy Session instances, projection stores, subagent catalogs, and conflict ordering between pulls and later updates.
 - Each `Session` owns one contiguous logical-event window represented by `SessionEventLikeEntry` values, paging, follow, prompt/control state, and the observable snapshot consumed by adapters.
 
-The durable event path opens `follow()`, whose first frame contains the current header, tail page, cursor, and complete projection baseline. History records have an explicit `event` or `chunks` discriminator and an aligned inner `event`; the journal validates each inclusive logical sequence range before the Client retains the records as `SessionEventLikeEntry` values without per-record conversion. Each physical generation atomically replaces the retained window from that snapshot; standard live events then append by sequence. `page()` is reserved for older history and gap repair. The transient control stream starts every generation with a complete baseline and then applies queue, job, and projection updates.
+The durable event path opens `follow()`, whose first frame contains the current header, tail page, cursor, and complete projection baseline. History records have an explicit `event` or `chunks` discriminator and an aligned inner `event`; the journal validates each inclusive logical sequence range before the Client retains the records as `SessionEventLikeEntry` values without per-record conversion. Each physical generation atomically replaces the retained window from that snapshot; standard live events then append by sequence. `page()` is reserved for older history and gap repair. The transient control stream starts every generation with a complete baseline and then applies projection updates.
 
 ### Workspaces
 
@@ -66,7 +66,8 @@ Web and desktop share the [developer-tool preference](../../packages/client/ui-s
 | Path | Sequence |
 |---|---|
 | durable Session display | Host Session log → packed Remote `follow`/`page` history → Client `SessionEventLikeEntry` window → Conversation Contexts → target snapshot (`chat`, `trajectory`, or another registered target) → Slot view → React |
-| transient Session control | Host control baseline → Remote snapshot stream → `SessionManager` queue/job/projection stores → Session and list snapshots → standard hooks → components |
+| transient Session control | Host control baseline → Remote snapshot stream → `SessionManager` projection stores → Session and list snapshots → standard hooks → components |
+| Background jobs | Host job registry → `job.list` / `job.follow` → [`ClientJobs`](../../packages/api/job-controller/README.md) roster and output views → job list and panels |
 | Workspace state | Host Workspace baseline and increments → `ClientWorkspaceModel` → `ctx.workspaces.list` → `useWorkspaces` → sidebar, hero, and navigation entries |
 | scoped interaction | Host Cordis waterfall → API Remotes `$events` → `ctx.remote.$on()` on the Session Context → owning UI package → result or `next()` |
 | user command | component callback → registration inject face or Slot owner → `ctx.sessions`, `ctx.workspaces`, or generated scoped Remote → Host Controller → authoritative update → stream or event projection back to the Client |
diff --git a/docs/subsystems/web-client.zh.md b/docs/subsystems/web-client.zh.md
index 9c697964a0..f14cdbe9b1 100644
--- a/docs/subsystems/web-client.zh.md
+++ b/docs/subsystems/web-client.zh.md
@@ -27,7 +27,7 @@ Web boot kernel 创建模块系统、预取 `immediately` entry、挂载 vendore
 
 Host 业务 service 使用 Typert Remote decorator 标记可调用 method。Host generation 产出严格 descriptor、runtime codec、declaration merge 与 source map。Client 侧 `api-remotes` assembly 选择这些生成贡献，并把具体 method 挂到 `ctx.remote.<namespace>` 与 Session scope 的 `agentCtx.remote.<namespace>`。功能包依赖生成的 service face，而不依赖 Gateway 实现或 Host 包的运行时 entry。
 
-Connection 拥有 request correlation、`/api` carrier、trust check、精确 Fetch 路由与 connection generation。API Gateway 拥有 Remote dispatch、取消、logical stream 与选定 Host event 的转发。Controller 操作应进入生成的 Remote method 或显式 Remote stream；功能自有的下载则注册精确 Fetch 路由。[API Gateway 参考](../api-gateway.zh.md)定义 generation 与调用，[Connection README](../../packages/client/connection/README.zh.md)定义物理 carrier 与信任策略。
+Connection 拥有请求 URL 解析、request correlation、`/api` carrier、trust check、精确 Fetch 路由与 connection generation。API Gateway 拥有 Remote dispatch、取消、logical stream 与选定 Host event 的转发。Controller 操作应进入生成的 Remote method 或显式 Remote stream；功能自有的下载则注册精确 Fetch 路由。[API Gateway 参考](../api-gateway.zh.md)定义 generation 与调用，[Connection README](../../packages/client/connection/README.zh.md)定义物理 carrier 与信任策略。
 
 内部 `$events` logical stream 是 Connection generation source。它的 opening `ready` frame 携带用于路径显示的 Host home，并在 Host listener 已挂载、任何 controller 开始 baseline read 之前建立 generation。`ctx.remote.$on()` 把 allowlist 内的普通 event 交付给 root Client Context，并把 scoped waterfall event 交付给已解析的 Session Context；waterfall listener 可以返回结果、调用 `next()` 或拒绝。
 
@@ -40,10 +40,10 @@ Connection 拥有 request correlation、`/api` carrier、trust check、精确 Fe
 [`api/session-controller`](../../packages/api/session-controller/README.zh.md)公开 Session list、search、creation、prompt、queue、cancellation、pagination 及 follow/control stream 等 Host command。其 Client 侧按 `ClientSessions → SessionManager → Session` 组织：
 
 - `ClientSessions` 提供 `ctx.sessions`，拥有 reference、source count、Session scope 与稳定的 `SessionBinding` object，并投影不含全局 current Session 选择的 catalog state。
-- `SessionManager` 拥有 list baseline、实时 list/control update、惰性 Session instance、queue、projection store、subagent catalog，以及 pull 与后到 update 之间的冲突顺序。
+- `SessionManager` 拥有 list baseline、实时 list/control update、惰性 Session instance、projection store、subagent catalog，以及 pull 与后到 update 之间的冲突顺序。
 - 每个 `Session` 拥有一段由 `SessionEventLikeEntry` value 表示的连续逻辑 event window、pagination、follow、prompt/control state 与供 adapter 消费的 observable snapshot。
 
-持久 event 路径打开 `follow()`，其首帧包含当前 header、tail page、cursor 与完整 projection baseline。历史 record 带有显式 `event` 或 `chunks` 判别字段和字段对齐的内部 `event`；journal 先校验每条 record 的逻辑 seq 闭区间，Client 再直接把这些 record 保留为 `SessionEventLikeEntry`，无需逐 record 转换。每个物理 generation 都根据该 snapshot 原子替换保留窗口，随后按 seq append 标准实时 event。`page()` 只用于更早历史与 gap repair。瞬态 control stream 每代以完整 baseline 开始，随后应用 queue、job 与 projection update。
+持久 event 路径打开 `follow()`，其首帧包含当前 header、tail page、cursor 与完整 projection baseline。历史 record 带有显式 `event` 或 `chunks` 判别字段和字段对齐的内部 `event`；journal 先校验每条 record 的逻辑 seq 闭区间，Client 再直接把这些 record 保留为 `SessionEventLikeEntry`，无需逐 record 转换。每个物理 generation 都根据该 snapshot 原子替换保留窗口，随后按 seq append 标准实时 event。`page()` 只用于更早历史与 gap repair。瞬态 control stream 每代以完整 baseline 开始，随后应用 projection update。
 
 ### Workspaces
 
@@ -66,7 +66,8 @@ Web 和桌面端共享[开发者工具偏好](../../packages/client/ui-settings/
 | 路径 | 顺序 |
 |---|---|
 | 持久 Session 展示 | Host Session log → packed Remote `follow`/`page` 历史 → Client `SessionEventLikeEntry` window → Conversation Context → target snapshot（`chat`、`trajectory` 或其他已注册 target）→ Slot view → React |
-| 瞬态 Session control | Host control baseline → Remote snapshot stream → `SessionManager` queue/job/projection store → Session 与 list snapshot → 标准 hook → component |
+| 瞬态 Session control | Host control baseline → Remote snapshot stream → `SessionManager` projection store → Session 与 list snapshot → 标准 hook → component |
+| 后台任务 | Host job 注册表 → `job.list` / `job.follow` → [`ClientJobs`](../../packages/api/job-controller/README.zh.md) 名册与输出视图 → 任务列表和面板 |
 | Workspace 状态 | Host Workspace baseline 与 increment → `ClientWorkspaceModel` → `ctx.workspaces.list` → `useWorkspaces` → sidebar、hero 与 navigation entry |
 | scoped interaction | Host Cordis waterfall → API Remotes `$events` → Session Context 上的 `ctx.remote.$on()` → 所属 UI 包 → result 或 `next()` |
 | 用户 command | component callback → 注册项 inject face 或 Slot owner → `ctx.sessions`、`ctx.workspaces` 或生成的 scoped Remote → Host Controller → 权威 update → stream 或 event projection 回到 Client |
diff --git a/docs/subsystems/web-server.i18n.yaml b/docs/subsystems/web-server.i18n.yaml
index 558b700088..0024bc7600 100644
--- a/docs/subsystems/web-server.i18n.yaml
+++ b/docs/subsystems/web-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/web-server.md
-web-server.md: e74d51da21682c0271c42b0a4584558e41b52b26
-web-server.zh.md: da89262e7055dbf4d6ee044def4cb5a08ce4dfe4
+web-server.md: 7b4d3a17a66ce4c3736b6d5d3eadf887622057c0
+web-server.zh.md: 5a95bbaff4aae20c6df05529f4154e42ccefaa3d
diff --git a/docs/subsystems/web-server.md b/docs/subsystems/web-server.md
index e74d51da21..7b4d3a17a6 100644
--- a/docs/subsystems/web-server.md
+++ b/docs/subsystems/web-server.md
@@ -64,7 +64,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.connection` — `HostConnectionHandle`
 
-Host `ctx.connection` shape consumed by transport-independent adapters.
+Host `ctx.connection` members consumed by transport-independent adapters.
 
 ```ts cordis-catalog
 /**
@@ -82,6 +82,14 @@ createSharedFetchHandler(channel: '/api'): ConnectionFetchHandler
  */
 requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection
 
+/**
+ * Admit one request: it passes {@link requestRejection} and speaks for the
+ * operator, or it is refused with that status.
+ * @param request - request headers from the HTTP or upgrade request.
+ * @returns the operator Peer, or the rejection status.
+ */
+admit(request: ConnectionTrustRequest): PeerAdmission
+
 /**
  * Authenticate one frontend index request, owning a token redirect or 401.
  * @param request - root or configured-index HTTP request.
diff --git a/docs/subsystems/web-server.zh.md b/docs/subsystems/web-server.zh.md
index da89262e70..5a95bbaff4 100644
--- a/docs/subsystems/web-server.zh.md
+++ b/docs/subsystems/web-server.zh.md
@@ -64,7 +64,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.connection` — `HostConnectionHandle`
 
-Host `ctx.connection` shape consumed by transport-independent adapters.
+Host `ctx.connection` members consumed by transport-independent adapters.
 
 ```ts cordis-catalog
 /**
@@ -82,6 +82,14 @@ createSharedFetchHandler(channel: '/api'): ConnectionFetchHandler
  */
 requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection
 
+/**
+ * Admit one request: it passes {@link requestRejection} and speaks for the
+ * operator, or it is refused with that status.
+ * @param request - request headers from the HTTP or upgrade request.
+ * @returns the operator Peer, or the rejection status.
+ */
+admit(request: ConnectionTrustRequest): PeerAdmission
+
 /**
  * Authenticate one frontend index request, owning a token redirect or 401.
  * @param request - root or configured-index HTTP request.
diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml
index db7bb548ef..b03f962bef 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: 9fe5f2bf4c62ba7d4f878b7b2f34490f43ca0b81
-workspace.zh.md: 63681e1a459c81a327654cfafa1f5cb2f231d6c8
+workspace.md: 8a3369778f0eac10d5fe077686d336eb47f6b41e
+workspace.zh.md: f1e7e96f1fb5e983de30bd8e2f9fe08ed0635beb
diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md
index 9fe5f2bf4c..8a3369778f 100644
--- a/docs/subsystems/workspace.md
+++ b/docs/subsystems/workspace.md
@@ -121,6 +121,10 @@ Ownership truth is the record's ordered `sessionIds`, never derived from session
 
 Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
 
+## Default Workspace initialization
+
+The controller's [transport types](../../packages/api/workspace-controller/src/types.ts) define `WorkspaceInitializeDefaultRequest`: a Client-resolved `directoryName` and initial `title`. The Host resolves the Documents location and asks the registry to initialize once. Locale selection belongs to the Client; the registry accepts a directory resolver and commits the registration with its durable identity. [First-use behavior and configuration](../../packages/api/workspace-controller/README.md#first-use-workspace) describe reuse and failure handling.
+
 ## Session pinning
 
 The controller's [transport types](../../packages/api/workspace-controller/src/types.ts) define `WorkspacePinSessionRequest` and `WorkspaceUnpinSessionRequest`, each carrying one `sessionId`. Both operations return `WorkspacePinValue`: the complete `pinnedSessionIds` array of Session ids, most recently pinned first. Pinning requires a known, unarchived Session; unpinning an id that is not pinned succeeds without changing the set. Archiving removes the Session's pin in the same durable write, and unarchiving does not restore it.
@@ -301,6 +305,14 @@ Host service backing the generated `ctx.remote.workspace` namespace.
  */
 @Remote('create') create(request: WorkspaceCreateRequest): Promise<WorkspaceCreateValue>
 
+/**
+ * Initialize or reuse the default Workspace during first-use startup.
+ * @param request - initial directory name and title; never rename an existing default.
+ * @param signal - caller lifetime; cancels native directory lookup.
+ * @returns the durable Workspace, or undefined when first-use initialization is ineligible; creates no Session or message.
+ */
+@Remote('initializeDefault') async initializeDefault(request: WorkspaceInitializeDefaultRequest, signal: AbortSignal): Promise<WorkspaceValue | undefined>
+
 /**
  * Rename one Workspace to a unique non-blank title.
  * @param request - Workspace identity and proposed title.
@@ -385,34 +397,14 @@ Host Remote file reads and workspace directory observations over the composed fi
 @Remote async read( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal, ): Promise<WorkspaceFileText>
 
 /**
- * Read one byte window of a regular file readable by the filesystem backend: raw
- * bytes, no text decoding and no binary rejection.
+ * Read a complete regular file or one byte range without text decoding.
  * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
- * @param path - absolute path or path relative to the workspace root; files outside it are allowed.
- * @param range - the byte window; omitted fields take the window defaults.
+ * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided.
+ * @param options - optional base file and range; without a range the complete-file cap applies.
  * @param signal - caller cancellation.
- * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+ * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
  */
-@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
-
-/**
- * Read a complete regular file as bytes, subject to the configured full-file cap.
- * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
- * @param path - absolute or workspace-relative file path.
- * @param signal - caller cancellation.
- * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large.
- */
-@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes>
-
-/**
- * Read a complete file relative to another file's directory, including outside the workspace.
- * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
- * @param path - base file, absolute or workspace-relative.
- * @param relativePath - relative filesystem path, not a URL or absolute path.
- * @param signal - caller cancellation.
- * @returns the complete related file using the ordinary file-size and access checks.
- */
-@Remote async readRelated( workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
+@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
 
 /**
  * Report one regular file's identity, version, and size without its content.
@@ -466,6 +458,18 @@ Durable workspace registry. Startup waits for `sessionPersistence`, builds one c
  */
 async create(path: string, title?: string): Promise<Workspace>
 
+/**
+ * Initialize the default Workspace only while both the registry and Session
+ * history are empty. Repeated requests reuse its durable identity; deleting
+ * that registration permanently disables automatic creation.
+ * @param resolveDirectory - resolve the absolute directory and initial title;
+ * called only for eligible creation, inside the registry mutation queue.
+ * Missing directories are created recursively before registration.
+ * After resolution, caller cancellation does not roll back creation or registration.
+ * @returns the initialized Workspace, or undefined when automatic creation is ineligible.
+ */
+initializeDefault(resolveDirectory: () => Promise<{ path: string; title: string }>): Promise<Workspace | undefined>
+
 /**
  * Look up a workspace by id.
  * @param id - Workspace id.
diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md
index 63681e1a45..f1e7e96f1f 100644
--- a/docs/subsystems/workspace.zh.md
+++ b/docs/subsystems/workspace.zh.md
@@ -121,6 +121,10 @@ interface Workspace {
 
 会话的 cwd 在创建时由创建者赋予，而不是由本注册表赋予——API 网关从所选工作区的 `path` 解析新会话的 cwd（回退到显式或默认 cwd），先创建会话使 cwd 落入其不可变的 [`SessionHeader`](persistence.zh.md#sessionheader--metadata-beside-the-log)，再调用 `attachSession`，后者会把已存储的 header cwd 与工作区路径重新校验一遍。首次成功启动时，注册表仅凭已持久化的 header（`id`、`cwd`、`createdAt`——绝不读事件正文）引导历史：把规范 cwd 有效的会话按目录分组为工作区，最新的排在最前；「已初始化」标记最后写入，因此被中断的引导可以安全续跑。引导只发生这一次：没有 cwd 的历史遗留会话保持 Ungrouped，此后创建的会话只能通过 `attachSession` 加入工作区。
 
+## 默认工作区初始化
+
+控制器的[传输类型](../../packages/api/workspace-controller/src/types.ts)定义了 `WorkspaceInitializeDefaultRequest`，包含 Client 解析出的 `directoryName` 和初始 `title`。Host 解析 Documents 位置，并请求注册表执行一次初始化。语言选择由 Client 负责；注册表接收目录解析器，并将登记与持久化身份一起提交。[首次使用行为与配置](../../packages/api/workspace-controller/README.zh.md#first-use-workspace)说明复用和失败处理。
+
 ## 会话置顶
 
 控制器的[传输类型](../../packages/api/workspace-controller/src/types.ts)定义了 `WorkspacePinSessionRequest` 和 `WorkspaceUnpinSessionRequest`，两者都携带一个 `sessionId`。两个操作都返回 `WorkspacePinValue`：完整的会话 id 数组 `pinnedSessionIds`，最近置顶的会话排在前面。置顶要求会话已知且未归档；对未置顶的 id 取消置顶会成功，且不改变集合。归档在同一次持久化写入中移除该会话的置顶，取消归档不会恢复置顶。
@@ -301,6 +305,14 @@ Host service backing the generated `ctx.remote.workspace` namespace.
  */
 @Remote('create') create(request: WorkspaceCreateRequest): Promise<WorkspaceCreateValue>
 
+/**
+ * Initialize or reuse the default Workspace during first-use startup.
+ * @param request - initial directory name and title; never rename an existing default.
+ * @param signal - caller lifetime; cancels native directory lookup.
+ * @returns the durable Workspace, or undefined when first-use initialization is ineligible; creates no Session or message.
+ */
+@Remote('initializeDefault') async initializeDefault(request: WorkspaceInitializeDefaultRequest, signal: AbortSignal): Promise<WorkspaceValue | undefined>
+
 /**
  * Rename one Workspace to a unique non-blank title.
  * @param request - Workspace identity and proposed title.
@@ -385,34 +397,14 @@ Host Remote file reads and workspace directory observations over the composed fi
 @Remote async read( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal, ): Promise<WorkspaceFileText>
 
 /**
- * Read one byte window of a regular file readable by the filesystem backend: raw
- * bytes, no text decoding and no binary rejection.
+ * Read a complete regular file or one byte range without text decoding.
  * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
- * @param path - absolute path or path relative to the workspace root; files outside it are allowed.
- * @param range - the byte window; omitted fields take the window defaults.
+ * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided.
+ * @param options - optional base file and range; without a range the complete-file cap applies.
  * @param signal - caller cancellation.
- * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+ * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
  */
-@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
-
-/**
- * Read a complete regular file as bytes, subject to the configured full-file cap.
- * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
- * @param path - absolute or workspace-relative file path.
- * @param signal - caller cancellation.
- * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large.
- */
-@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes>
-
-/**
- * Read a complete file relative to another file's directory, including outside the workspace.
- * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
- * @param path - base file, absolute or workspace-relative.
- * @param relativePath - relative filesystem path, not a URL or absolute path.
- * @param signal - caller cancellation.
- * @returns the complete related file using the ordinary file-size and access checks.
- */
-@Remote async readRelated( workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
+@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise<WorkspaceFileBytes>
 
 /**
  * Report one regular file's identity, version, and size without its content.
@@ -466,6 +458,18 @@ Durable workspace registry. Startup waits for `sessionPersistence`, builds one c
  */
 async create(path: string, title?: string): Promise<Workspace>
 
+/**
+ * Initialize the default Workspace only while both the registry and Session
+ * history are empty. Repeated requests reuse its durable identity; deleting
+ * that registration permanently disables automatic creation.
+ * @param resolveDirectory - resolve the absolute directory and initial title;
+ * called only for eligible creation, inside the registry mutation queue.
+ * Missing directories are created recursively before registration.
+ * After resolution, caller cancellation does not roll back creation or registration.
+ * @returns the initialized Workspace, or undefined when automatic creation is ineligible.
+ */
+initializeDefault(resolveDirectory: () => Promise<{ path: string; title: string }>): Promise<Workspace | undefined>
+
 /**
  * Look up a workspace by id.
  * @param id - Workspace id.
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 04a2230cee..8cdff8b24e 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: 2f5746fc63e73b1caf2692a05ff942c13399e6bc
-tool-catalog.zh.md: 6fb80b689ca569834e8f585c765547d23cec50df
+tool-catalog.md: c60d3979e65f3c5a2bc363fd082a3f63a446e8b5
+tool-catalog.zh.md: dc061b51681cc73f9d10059276bcdfa5b3268cff
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 2f5746fc63..c60d3979e6 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -43,6 +43,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-experimental-tool-agent-team` | `interrupt_agent`, `list_agents`, `send_message`, `spawn_teammate`, `team_task_create`, `team_task_get`, `team_task_list`, `team_task_update`, `wait_agent` | `ctx.tools`, `ctx.systemPrompt`, `ctx.agentTeams`, `an exact live Team member Agent` | `tool/call`, `team/member`, `team/message/queued`, `team/message/delivered`, `team/task`, `tool/result` | - | All nine tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names. |
 | `@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.workflowEngine`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - |
+| `@deepseek-ai/dsh-tool-workspace-dependencies` | `load_workspace_dependencies` | `ctx.tools` | `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. |
 
 <a id="deepseek-aidsh-plugin-manager"></a>
@@ -731,7 +732,7 @@ Source: [`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/
 
 ### `cordis_inspect_query`
 
-Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant.
+Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime.
 
 ```json
 {
@@ -2442,6 +2443,23 @@ Constraints: concurrency and total-agent caps apply; no filesystem, network, tim
 
 Source: [`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts)
 
+<a id="deepseek-aidsh-tool-workspace-dependencies"></a>
+
+## `@deepseek-ai/dsh-tool-workspace-dependencies`
+
+### `load_workspace_dependencies`
+
+Get absolute paths to bundled Python and library directories, plus bundled Python distribution versions. Node.js and pnpm paths are included when the payload provides them. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. When Node.js and pnpm paths are returned, run pnpm with that Node executable and pnpm script path. This does not change PATH or package-manager settings.
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+Source: [`packages/skill/tool-workspace-dependencies/src/index.ts`](../packages/skill/tool-workspace-dependencies/src/index.ts)
+
 <a id="deepseek-aidsh-tool-web"></a>
 
 ## `@deepseek-ai/dsh-tool-web`
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index 6fb80b689c..dc061b5168 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -47,6 +47,7 @@
 | `@deepseek-ai/dsh-experimental-tool-agent-team` | `interrupt_agent`、`list_agents`、`send_message`、`spawn_teammate`、`team_task_create`、`team_task_get`、`team_task_list`、`team_task_update`、`wait_agent` | `ctx.tools`、`ctx.systemPrompt`、`ctx.agentTeams`、`an exact live Team member Agent` | `tool/call`、`team/member`、`team/message/queued`、`team/message/delivered`、`team/task`、`tool/result` | - | 这 9 个工具限定于隐式 Team Lead 与持久 teammate 作用域。随产品发布的 dsh-base bundle 默认禁用该包；文档中的 Agent Teams profile patch 会启用它，并禁用旧 continuable child 的同名控制工具。 |
 | `@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.workflowEngine`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - |
+| `@deepseek-ai/dsh-tool-workspace-dependencies` | `load_workspace_dependencies` | `ctx.tools` | `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 在更换后端时保持稳定。 |
 
 <a id="deepseek-aidsh-plugin-manager"></a>
@@ -735,7 +736,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费
 
 ### `cordis_inspect_query`
 
-执行 Inspect Provider 明确声明的只读查询。platform、provider 和 method 必须来自 cordis_inspect_list，input 必须符合该方法的 schema。编写插件代码前，用本工具读取准确的 Service 方法、Event 模式、Builtin 签名、Tool schema、主题 token，或实时 Slot 树与 props。Host 查询在本地运行。Client 查询等待页面首个有效响应，直到页面回应或工具取消。本工具不能调用业务 Service 方法或修改运行时。对于 Service.listService 和 Event.listEvents，不传 input 可浏览精简签名目录，再查询准确服务或事件以获得完整约定及引用类型。对于 Slots.listSubTree，不传 root 可浏览精简树；查询准确的 Slot root 可获得完整注册约定和 props，而查询准确的 Factory root 只返回 identity、scope 与 registrant。
+执行 Inspect Provider 声明的只读查询。platform、provider 和 method 必须来自 cordis_inspect_list，input 必须符合该方法的 schema。编写插件代码前，用本工具读取准确的 Service 方法、Event 模式、Builtin 签名、Tool schema、主题 token，或实时 Slot 树与 props。Host 查询在本地运行。Client 查询等待页面首个有效响应，直到页面回应或工具取消。本工具不能调用业务 Service 方法或修改运行时。
 
 ```json
 {
@@ -2450,6 +2451,23 @@ todo_write 是会话所有的状态；UI 将最新的 todo/write 事件渲染为
 
 来源：[`packages/workflow/tool-workflow/src/index.ts`](../packages/workflow/tool-workflow/src/index.ts)
 
+<a id="deepseek-aidsh-tool-workspace-dependencies"></a>
+
+## `@deepseek-ai/dsh-tool-workspace-dependencies`
+
+### `load_workspace_dependencies`
+
+获取随包附带的 Python 和库目录的绝对路径，以及随包 Python 发行版的版本。payload 提供 Node.js 和 pnpm 时才返回对应路径。Python 含 numpy、pandas、python-docx、python-pptx、openpyxl、Pillow、lxml 与 XlsxWriter。除非用户或工作区指令选择了别的环境，Office 文件请使用这些库。返回 Node.js 和 pnpm 路径时，用该 Node 可执行文件和 pnpm 脚本路径运行 pnpm。本工具不改 PATH，也不改包管理器设置。
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+来源：[`packages/skill/tool-workspace-dependencies/src/index.ts`](../packages/skill/tool-workspace-dependencies/src/index.ts)
+
 <a id="deepseek-aidsh-tool-web"></a>
 
 ## `@deepseek-ai/dsh-tool-web`
diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml
index b3f4cd607a..88df3856da 100644
--- a/docs/user/develop/basic/publish.i18n.yaml
+++ b/docs/user/develop/basic/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 docs/user/develop/basic/publish.md
-publish.md: 17b0cb80f9cf385773ae9e1f4d7061ec1df9c1a2
-publish.zh.md: 3cc65af58d34028a6bff03455451153e2c7f439b
+publish.md: b317943954972e63d0e4b741fb16d2fc19091f58
+publish.zh.md: b7864f7e7596681f48fc87590772841294d2a039
diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md
index 17b0cb80f9..b317943954 100644
--- a/docs/user/develop/basic/publish.md
+++ b/docs/user/develop/basic/publish.md
@@ -61,7 +61,7 @@ Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--pa
       name: dsh-hello-plugin
 ```
 
-A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable.
+`patch` also accepts an ordered list of files, for example `["./base.patch.yml", "./web.patch.yml"]`; the launcher applies them in that order as one layer, and each file's relative plugin paths resolve beside that file. A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable.
 
 ### The profile manifest
 
@@ -100,6 +100,12 @@ The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first
 }
 ```
 
+A linked checkout keeps its own `node_modules`. Declare dsh packages whose instances the plugin must share with the host under both `peerDependencies` and `devDependencies`, as the harness packages do. At that manifest's lookup position, peers present in the running dsh's runtime resolution use the installation's copy; the devDependency copy serves your type checker and standalone tests. Keep independently versioned third-party dependencies and stateless dsh utilities under `dependencies`.
+
+Ordinary linked imports follow Node's ancestor order and check each directory's current peer declarations. A nearer physical package wins before a higher peer declaration. A link target can lack `package.json`; ancestor peers still apply, even without a physical `node_modules` beside that manifest. Explicit `require.resolve(..., { paths })` is always native, including paths inside a profile. These rules are shared by npm, Desktop, and source launches; they do not invalidate loaded modules or validate peer version ranges. See the [resolution rules](../../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md) for scope and file-query behavior.
+
+Linking a broad checkout does not apply peer interception to the running installation's own package directories. Links whose targets stay inside the profile, including its pnpm store, remain profile-owned installation content rather than external linked roots. Overlapping external links do not change lookup order: each request still starts from its importer's directory.
+
 Verify the layer without booting, then boot:
 
 ```sh
diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md
index 3cc65af58d..b7864f7e75 100644
--- a/docs/user/develop/basic/publish.zh.md
+++ b/docs/user/develop/basic/publish.zh.md
@@ -61,7 +61,7 @@ export function apply() {
       name: dsh-hello-plugin
 ```
 
-没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
+`patch` 也接受一个有序的文件列表，例如 `["./base.patch.yml", "./web.patch.yml"]`；launcher 按该顺序把它们作为同一层应用，每个文件中的相对插件路径相对于该文件解析。没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
 
 ### profile manifest
 
@@ -100,6 +100,12 @@ dsh plugin --profile demo add ./hello-plugin
 }
 ```
 
+通过链接安装的 checkout 保留自己的 `node_modules`。与 harness 自身的包一样，需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies` 中。在该 manifest 的查询位置，运行中 dsh 的 runtime resolution 已包含的 peer 使用安装中的副本；devDependency 副本供类型检查和独立测试使用。需要独立版本的第三方依赖和无状态 dsh 工具包放在 `dependencies` 中。
+
+普通 linked import 遵循 Node 的祖先顺序，检查每个目录当前的 peer 声明。更近的物理包先于更高的 peer 声明。link 目标可以没有 `package.json`，祖先 peer 仍可生效，即使该 manifest 旁没有物理 `node_modules`。显式 `require.resolve(..., { paths })` 始终是原生查询，包括指向 profile 内的路径。npm、Desktop 与源码启动共用这些规则；规则不会使已加载模块失效，也不校验 peer 版本范围。作用域和文件查询行为见[解析规则](../../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)。
+
+链接整个 checkout 不会对运行中安装自身的包目录应用 peer 拦截。目标仍位于 profile 内的链接（包括它的 pnpm store）属于 profile 自己安装的内容，不算外部 linked root。外部链接互相重叠也不改变查找顺序，每个请求仍从其 importer 所在目录开始。
+
 先不启动、只验证该层，再启动：
 
 ```sh
diff --git a/docs/user/develop/practice/llm-adapter.i18n.yaml b/docs/user/develop/practice/llm-adapter.i18n.yaml
index 452a429302..a77a7ed049 100644
--- a/docs/user/develop/practice/llm-adapter.i18n.yaml
+++ b/docs/user/develop/practice/llm-adapter.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/llm-adapter.md
-llm-adapter.md: 7e30847cdf265bca8f55aac40f73686101ec185d
-llm-adapter.zh.md: 22a3c54f45088a41362c1a8e903d2441ed4fc93b
+llm-adapter.md: 32e412b10ade376e88d23be4de8cb2de976706f0
+llm-adapter.zh.md: bfa9842ce583f0486aff6269ad78c1f465f43671
diff --git a/docs/user/develop/practice/llm-adapter.md b/docs/user/develop/practice/llm-adapter.md
index 7e30847cdf..32e412b10a 100644
--- a/docs/user/develop/practice/llm-adapter.md
+++ b/docs/user/develop/practice/llm-adapter.md
@@ -146,7 +146,7 @@ The first argument lists provider routes handled by the adapter. `GenerateOption
 
 The repository contains complete implementations:
 
-- `packages/llm/llm-deepseek/` — DeepSeek API adapter using the OpenAI-compatible format
+- `packages/llm/llm-deepseek/` — DeepSeek adapter using the Messages API
 - `packages/llm/llm-pi-ai/` — Pi AI adapter using a different API format
 
 Compare the two shipped adapters to see the same harness contract implemented over different provider SDKs.
diff --git a/docs/user/develop/practice/llm-adapter.zh.md b/docs/user/develop/practice/llm-adapter.zh.md
index 22a3c54f45..bfa9842ce5 100644
--- a/docs/user/develop/practice/llm-adapter.zh.md
+++ b/docs/user/develop/practice/llm-adapter.zh.md
@@ -146,7 +146,7 @@ ctx.llm.registerAdapter(['my-provider'], adapter)
 
 仓库中包含以下两个完整实现：
 
-- `packages/llm/llm-deepseek/` — DeepSeek API 适配器（OpenAI 兼容格式）
+- `packages/llm/llm-deepseek/` — 使用 Messages API 的 DeepSeek 适配器
 - `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式）
 
 对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。
diff --git a/docs/user/guide/providers-custom-form.png b/docs/user/guide/providers-custom-form.png
index bbbedde794..82ca074212 100644
Binary files a/docs/user/guide/providers-custom-form.png and b/docs/user/guide/providers-custom-form.png differ
diff --git a/docs/user/guide/providers-custom-form.zh.png b/docs/user/guide/providers-custom-form.zh.png
index 2c48120331..9a2b7661ca 100644
Binary files a/docs/user/guide/providers-custom-form.zh.png and b/docs/user/guide/providers-custom-form.zh.png differ
diff --git a/docs/user/guide/providers-models-page.png b/docs/user/guide/providers-models-page.png
index f3ffe6e90f..fb87367d54 100644
Binary files a/docs/user/guide/providers-models-page.png and b/docs/user/guide/providers-models-page.png differ
diff --git a/docs/user/guide/providers-models-page.zh.png b/docs/user/guide/providers-models-page.zh.png
index b5d1f4597c..694f1b6f16 100644
Binary files a/docs/user/guide/providers-models-page.zh.png and b/docs/user/guide/providers-models-page.zh.png differ
diff --git a/docs/user/guide/providers.i18n.yaml b/docs/user/guide/providers.i18n.yaml
index 3097c5ae9e..f0043c374d 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: e578ff96a373c96ebe646126d6c60d7bcc62bbc1
-providers.zh.md: fd0859f0b235efb5fe8ecc3c248a2ac2bbaeb495
+providers.md: ef016ef39d5e34f3ce3dd2feb6213b9597668592
+providers.zh.md: 15fd229ce222a020e897f08c15afcd843791a3bb
diff --git a/docs/user/guide/providers.md b/docs/user/guide/providers.md
index e578ff96a3..ef016ef39d 100644
--- a/docs/user/guide/providers.md
+++ b/docs/user/guide/providers.md
@@ -8,21 +8,21 @@ This guide assumes you started the Web UI through the [root README](../../../REA
 
 Open **Settings → Models**. The DeepSeek card exposes one API-key field; enter the key and save it.
 
-![The Models page: the DeepSeek card, with Add provider and Add a custom provider below it](providers-models-page.png)
+![The Models page: the DeepSeek card, with Add model provider below it](providers-models-page.png)
 
 Keys are write-only. The page receives a redacted descriptor after saving, never the literal secret. The key is stored in `$DSH_HOME/.credentials.yaml`, while settings retain only its credential reference.
 
-## Add a built-in provider
+## Add a third-party provider
 
-Choose **Add provider** and pick a provider dsh ships with; the list shows provider ids such as `anthropic`, `openai`, `moonshotai` for Kimi, or `zai` for GLM. Enter its API key and save. The installed catalog supplies the endpoint, protocol, and model list.
+Choose **Add model provider**. The card opens on **Third-party model provider**: pick a provider dsh ships with — the list shows provider ids such as `anthropic`, `openai`, `moonshotai` for Kimi, or `zai` for GLM — enter its API key, and save. The installed catalog supplies the endpoint, protocol, and model list.
 
 Providers that sign in with OAuth, such as Codex, are not supported here yet.
 
-## Add a custom provider
+## Add a custom model API
 
-Choose **Add a custom provider** for a company gateway, self-hosted server, or provider absent from the installed catalog. Supply a lowercase Provider ID, base URL, API protocol, credential, and at least one model. The **API protocol** must be the one your gateway speaks, and the form offers three: `openai-completions` for OpenAI Chat Completions, `openai-responses` for the OpenAI Responses API, and `anthropic-messages` for the Anthropic Messages API. A provider speaks one protocol, so a gateway that serves two needs two providers.
+Switch the card to **Custom model API** for a relay, a company gateway, a self-hosted server, or any provider absent from the installed catalog. Supply a lowercase Provider ID, base URL, API protocol, credential, and at least one model. The **API protocol** must be the one your gateway speaks, and the picker offers three: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages, stored in `settings.yaml` as `openai-completions`, `openai-responses`, and `anthropic-messages`. A provider speaks one protocol, so a gateway that serves two needs two providers.
 
-![The custom provider form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
+![The custom model API form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
 
 The Provider ID is permanent because requests, saved sessions, model defaults, and credential references use it. To rename a provider, add a new provider and delete the old one. The display name, base URL, protocol, credential, and models remain editable.
 
diff --git a/docs/user/guide/providers.zh.md b/docs/user/guide/providers.zh.md
index fd0859f0b2..15fd229ce2 100644
--- a/docs/user/guide/providers.zh.md
+++ b/docs/user/guide/providers.zh.md
@@ -8,39 +8,39 @@
 
 打开**设置 → 模型**。DeepSeek 卡片提供一个 API 密钥字段；输入密钥并保存。
 
-![模型页：DeepSeek 卡片，以及添加提供方与添加自定义提供方两个入口](providers-models-page.zh.png)
+![模型页：DeepSeek 卡片，及其下方的添加模型提供商入口](providers-models-page.zh.png)
 
 密钥是只写的。保存后，页面只会收到脱敏描述符，永远不会收到明文密钥。密钥存储在 `$DSH_HOME/.credentials.yaml` 中，settings 只保留它的凭据引用。
 
-## 添加内置提供方
+## 添加第三方提供商
 
-选择**添加提供方**，选取 dsh 自带的提供方；列表显示的是提供方 id，例如 `anthropic`、`openai`、Kimi 对应的 `moonshotai`、GLM 对应的 `zai`。输入其 API 密钥并保存。已安装目录会提供端点、协议和模型列表。
+选择**添加模型提供商**。卡片默认打开在**第三方模型提供商**：选取 dsh 自带的提供商——列表显示的是提供商 id，例如 `anthropic`、`openai`、Kimi 对应的 `moonshotai`、GLM 对应的 `zai`——输入其 API 密钥并保存。已安装目录会提供端点、协议和模型列表。
 
-通过 OAuth 登录的提供方（例如 Codex）暂不支持。
+通过 OAuth 登录的提供商（例如 Codex）暂不支持。
 
-## 添加自定义提供方
+## 添加自定义模型 API
 
-对于公司网关、自建服务器或已安装目录中不存在的提供方，选择**添加自定义提供方**。提供小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。**API 协议**必须选网关实际使用的那一种，表单提供三种：`openai-completions` 对应 OpenAI Chat Completions，`openai-responses` 对应 OpenAI Responses API，`anthropic-messages` 对应 Anthropic Messages API。一个提供方只使用一种协议，网关同时提供两种时需要建两个提供方。
+对于中转站、公司网关、自建服务器或已安装目录中不存在的提供商，把卡片切换到**自定义模型 API**。提供小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。**API 协议**必须选网关实际使用的那一种，选择框提供三种：OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages，在 `settings.yaml` 中分别存为 `openai-completions`、`openai-responses` 和 `anthropic-messages`。一个提供商只使用一种协议，网关同时提供两种时需要建两个提供商。
 
-![自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](providers-custom-form.zh.png)
+![自定义模型 API 表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](providers-custom-form.zh.png)
 
-Provider ID 是永久的，因为请求、已保存会话、模型默认值和凭据引用都会使用它。如需重命名提供方，请添加新提供方并删除旧提供方。显示名称、基础 URL、协议、凭据和模型仍可编辑。
+Provider ID 是永久的，因为请求、已保存会话、模型默认值和凭据引用都会使用它。如需重命名提供商，请添加新提供商并删除旧提供商。显示名称、基础 URL、协议、凭据和模型仍可编辑。
 
 ### 探测模型
 
-在**模型目录**中选择**获取可用模型**，即可询问端点它提供哪些模型。请求使用表单当前的 API 地址、协议和密钥，已保存的提供方则用已存储的密钥；响应会打开一个可搜索的选择框，搜索、勾选想要的模型，再点**添加所选**。保存或创建提供方之前不会存储任何内容。
+在**模型目录**中选择**获取可用模型**，即可询问端点它提供哪些模型。请求使用表单当前的 API 地址、协议和密钥，已保存的提供商则用已存储的密钥；响应会打开一个可搜索的选择框，搜索、勾选想要的模型，再点**添加所选**。保存或创建提供商之前不会存储任何内容。
 
-探测读取的是常见网关公开的列表格式，但并非每个端点都用这些格式作答，所以它只是便利手段而非保证：探测失败或列表为空时，手动添加模型 ID 即可，效果完全一样。内置提供方一律由已安装目录作答，即使其 API 地址指向网关也是如此，要查看网关实际提供的模型，请通过自定义提供方探测。
+探测读取的是常见网关公开的列表格式，但并非每个端点都用这些格式作答，所以它只是便利手段而非保证：探测失败或列表为空时，手动添加模型 ID 即可，效果完全一样。内置提供商一律由已安装目录作答，即使其 API 地址指向网关也是如此，要查看网关实际提供的模型，请通过自定义提供商探测。
 
 ## 选择模型
 
-已配置的提供方会出现在模型选择器中。选择模型也会将其设为新会话的默认值。已发送过请求的会话会保留自身日志中记录的模型。
+已配置的提供商会出现在模型选择器中。选择模型也会将其设为新会话的默认值。已发送过请求的会话会保留自身日志中记录的模型。
 
-如果已保存默认值指向已删除的提供方，输入框会显示**选择模型**，并在选择其他模型前阻止输入。
+如果已保存默认值指向已删除的提供商，输入框会显示**选择模型**，并在选择其他模型前阻止输入。
 
 ## 进阶配置
 
-自动生成的[插件配置目录](../../config-catalog.zh.md)列出每个插件的所有受支持字段与默认值；[`dsh-llm-pi-ai`](../../config-catalog.zh.md#deepseek-aidsh-llm-pi-ai) 就是本页所配置的那个提供方段落。[`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.zh.md) 和 [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.zh.md) 参考文档负责直接 `settings.yaml` 配置、目录解析、推理控制、凭据与适配器错误。
+自动生成的[插件配置目录](../../config-catalog.zh.md)列出每个插件的所有受支持字段与默认值；[`dsh-llm-pi-ai`](../../config-catalog.zh.md#deepseek-aidsh-llm-pi-ai) 就是本页所配置的那个提供商段落。[`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.zh.md) 和 [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.zh.md) 参考文档负责直接 `settings.yaml` 配置、目录解析、推理控制、凭据与适配器错误。
 
 ::: tip 其他设置
 模型页提供 API 密钥、显示名称、API 地址、API 协议，以及每个模型的 ID、显示名称、上下文窗口、最大输出 token 数和输入类型。推理等级、请求兼容性开关、请求头、超时和重试策略在 `$DSH_HOME/settings.yaml` 中设置，也就是模型页写入的同一份文档。可以直接编辑它；浏览器与服务器在同一台机器时，也可以点击设置页顶部的**打开配置文件**打开它。适配器会在下一次请求时重新读取，无需重启任何东西。下面各小节介绍多数网关会用到的字段。
@@ -48,9 +48,9 @@ Provider ID 是永久的，因为请求、已保存会话、模型默认值和
 
 ### 图片输入
 
-在**设置 → 模型**中编辑提供方，打开**自定义设置**并展开该模型的**模型选项**。**输入类型**独占容量字段下方的一行。对于支持图片的模型，勾选**图片**并保存。没有继承图片能力的新自定义模型默认勾选**文本**。至少保留一种输入类型；仅图片模型需先勾选图片，再取消文本。
+在**设置 → 模型**中编辑提供商，打开**自定义设置**并展开该模型的**模型选项**。**输入类型**独占容量字段下方的一行。对于支持图片的模型，勾选**图片**并保存。没有继承图片能力的新自定义模型默认勾选**文本**。至少保留一种输入类型；仅图片模型需先勾选图片，再取消文本。
 
-复选框将 pi-ai 模型的选择保存为 `input`，将直连 DeepSeek 适配器的选择保存为 `inputModalities`。也可以在 `$DSH_HOME/settings.yaml` 中编辑模型；例如，以下自定义 pi-ai 提供方声明了一个纯文本模型和一个视觉模型：
+复选框将 pi-ai 模型的选择保存为 `input`，将直连 DeepSeek 适配器的选择保存为 `inputModalities`。也可以在 `$DSH_HOME/settings.yaml` 中编辑模型；例如，以下自定义 pi-ai 提供商声明了一个纯文本模型和一个视觉模型：
 
 ```yaml
 llm-pi-ai:
@@ -86,7 +86,7 @@ llm-pi-ai:
         - id: second-model
 ```
 
-`defaultInput` 是回退值而不是覆盖值，默认为 `[text]`：在内置提供方上，它只为其目录未描述的模型作答，因此绝不会把目录中本就具备图片能力的模型的该能力去掉。要收窄这类模型，请用它自己的 `input`。内置提供方没有显式 `models` 列表时，写在 `modelOverrides` 下，以模型 id 为键：
+`defaultInput` 是回退值而不是覆盖值，默认为 `[text]`：在内置提供商上，它只为其目录未描述的模型作答，因此绝不会把目录中本就具备图片能力的模型的该能力去掉。要收窄这类模型，请用它自己的 `input`。内置提供商没有显式 `models` 列表时，写在 `modelOverrides` 下，以模型 id 为键：
 
 ```yaml
 llm-pi-ai:
@@ -99,11 +99,11 @@ llm-pi-ai:
 
 在 pi-ai 配置中，除模型自身的 `input` 外，每个列表都至少要写一项模态；模型自身的空列表与省略它同义。未知模态在任何位置写入都会被拒绝。
 
-这两个字段都是对你端点的断言，而不是对它的检查。声明了端点并不提供的图片能力的模型不会在这里被拦下，改由提供方拒绝该请求。
+这两个字段都是对你端点的断言，而不是对它的检查。声明了端点并不提供的图片能力的模型不会在这里被拦下，改由提供商拒绝该请求。
 
 ### 推理等级
 
-对于声明了推理等级的模型，模型选择器会提供**推理等级**菜单。内置提供方的模型从已安装目录继承其等级。手动录入的模型不声明任何等级，因此模型菜单里不会出现推理等级项，由端点自身的默认值决定模型是否思考。请在 `$DSH_HOME/settings.yaml` 中用 `reasoningEfforts` 声明等级：
+对于声明了推理等级的模型，模型选择器会提供**推理等级**菜单。内置提供商的模型从已安装目录继承其等级。手动录入的模型不声明任何等级，因此模型菜单里不会出现推理等级项，由端点自身的默认值决定模型是否思考。请在 `$DSH_HOME/settings.yaml` 中用 `reasoningEfforts` 声明等级：
 
 ```yaml
 llm-pi-ai:
@@ -136,7 +136,7 @@ llm-pi-ai:
             max: max
 ```
 
-网关并不提供推理能力的内置提供方模型，可在 `modelOverrides` 下用 `reasoningEfforts: false` 去掉其等级；之后再为它选择等级会被拒绝并报 `UNSUPPORTED_REASONING_EFFORT`。DeepSeek 自身的路由不需要以上任何配置：其模型已经提供 `off`、`low`、`high` 和 `max`，`llm-deepseek.reasoningEffort` 设置选择器的起始默认值：
+网关并不提供推理能力的内置提供商模型，可在 `modelOverrides` 下用 `reasoningEfforts: false` 去掉其等级；之后再为它选择等级会被拒绝并报 `UNSUPPORTED_REASONING_EFFORT`。DeepSeek 自身的路由不需要以上任何配置：其模型已经提供 `off`、`low`、`high` 和 `max`，`llm-deepseek.reasoningEffort` 设置选择器的起始默认值：
 
 ```yaml
 llm-deepseek:
@@ -181,8 +181,8 @@ llm-pi-ai:
 
 ## 排错
 
-- **`MISSING_CREDENTIAL`**：通过模型页存储提供方密钥，或提供被引用的环境变量。
-- **`UNKNOWN_MODEL`**：选择已配置的模型，或向自定义提供方添加缺失的模型。
+- **`MISSING_CREDENTIAL`**：通过模型页存储提供商密钥，或提供被引用的环境变量。
+- **`UNKNOWN_MODEL`**：选择已配置的模型，或向自定义提供商添加缺失的模型。
 - **获取可用模型返回 401**：检查密钥。模型发现会调用 OpenAI 兼容的 `GET /models` 端点；对于不提供该端点的服务，请手动输入模型。
 - **获取可用模型提示既没有 `data` 数组也没有 `models` 对象**：端点返回的列表格式不在探测的读取范围内。请手动输入模型。
 - **密钥与地址都正确，网关却拒绝每一个请求**：它的请求形状与 OpenAI 不同。先在路由上设 `compat.supportsDeveloperRole: false` 与 `compat.maxTokensField: max_tokens`。
@@ -190,5 +190,5 @@ llm-pi-ai:
 - **手动录入的模型没有推理等级菜单**：该模型没有声明任何等级。在 `settings.yaml` 中给该模型加上 `reasoningEfforts`。
 - **`off` 无法让 DeepSeek 模型停止思考**：留空的 `off` 不发送任何推理字段，默认思考的端点就继续思考。请在模型或路由上设置 `compat.thinkingFormat: deepseek`。
 - **某个 compat 开关因没有值而被拒绝**：冒号后什么都没写。给它一个值，或删掉该键以沿用已安装 catalog 的值。
-- **图片在发送前被拒绝**：该模型未声明图片模态。请给自定义提供方的模型加上 `input: [text, image]`；在 DeepSeek 自身的路由上，请从配置的目录中选择支持图片的条目（默认为 `deepseek-flash`），并确认网关提供该模型且支持图片输入。
-- **提供方拒绝了带图片的请求**：该模型声明了其端点实际并不提供的图片能力。请从授予它图片能力的那个列表中移除 `image`——可能是模型的 `input`，也可能是路由的 `defaultInput`——然后开启新会话：附加的图片会留在会话日志里，因此在会话离开它之前，同一个请求会不断重复。
+- **图片在发送前被拒绝**：该模型未声明图片模态。请给自定义提供商的模型加上 `input: [text, image]`；在 DeepSeek 自身的路由上，请从配置的目录中选择支持图片的条目（默认为 `deepseek-flash`），并确认网关提供该模型且支持图片输入。
+- **提供商拒绝了带图片的请求**：该模型声明了其端点实际并不提供的图片能力。请从授予它图片能力的那个列表中移除 `image`——可能是模型的 `input`，也可能是路由的 `defaultInput`——然后开启新会话：附加的图片会留在会话日志里，因此在会话离开它之前，同一个请求会不断重复。
diff --git a/lefthook.yml b/lefthook.yml
index 04106e1fd1..1d5c8898c6 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -28,7 +28,7 @@ pre-commit:
     # lefthook only inspects files present on disk — so that one case still
     # falls through to the freshness assertion in the test lane.
     - name: third-party notices (staged)
-      glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,*/*/*/*/package.json,pnpm-workspace.yaml,*/*/pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml,apps/desktop/scripts/primary-runtime-lock.json,scripts/gen-third-party-notices.ts,scripts/browser-bundled-externals.ts,scripts/build-exe-for-python-sdk.ts,tsconfig.base*.json,packages/*/*/src/**/*,packages/*/*/tsdown.config.ts,packages/client/tsdown.client.ts,apps/*/src/**/*,apps/*/vite.config.ts}'
+      glob: '{package.json,*/package.json,*/*/package.json,*/*/*/package.json,*/*/*/*/package.json,pnpm-workspace.yaml,*/*/pnpm-workspace.yaml,pnpm-lock.yaml,vendor/README.md,python/*/pyproject.toml,scripts/primary-runtime/lock.json,scripts/gen-third-party-notices.ts,scripts/browser-bundled-externals.ts,scripts/build-exe-for-python-sdk.ts,tsconfig.base*.json,packages/*/*/src/**/*,packages/*/*/tsdown.config.ts,packages/client/tsdown.client.ts,apps/*/src/**/*,apps/*/vite.config.ts}'
       run: node_modules/.bin/tsx scripts/gen-third-party-notices.ts && git add THIRD_PARTY_NOTICES.md
 
     - name: whitespace (staged)
diff --git a/package.json b/package.json
index 4d36479376..827b4000dd 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,7 @@
     "website"
   ],
   "scripts": {
+    "prepare:primary-runtime": "tsx scripts/primary-runtime/prepare.ts",
     "build": "tsx scripts/build.ts",
     "build:bench": "npm run build:native-system && npm run build:lib && tsdown --config benchmarks/tsdown.config.ts",
     "build:official": "tsx scripts/build.ts --profile official",
@@ -196,6 +197,7 @@
     "demo:ptc": "node scripts/demo-ptc.mjs",
     "demo:inspector": "node --import tsx/esm apps/cli/src/bin.ts web --patch ./packages/experimental/inspector/cordis.source.patch.yml",
     "mock:llm": "node --import tsx packages/test-support/llm-mock-server/src/bin.ts",
+    "start:web": "node --import tsx/esm apps/cli/src/bin.ts web",
     "dev:web": "tsx scripts/dev-web.ts --poll",
     "postinstall": "node scripts/install-lefthook.mjs"
   },
@@ -225,7 +227,9 @@
     "@yarnpkg/cli-dist": "4.17.1",
     "eslint-plugin-sonarjs": "^4.1.0",
     "execa": "^10.0.0",
+    "extract-zip": "^2.0.1",
     "fast-check": "^4.8.0",
+    "fflate": "^0.8.2",
     "istanbul-lib-report": "^3.0.1",
     "js-yaml": "^4.2.0",
     "jscpd": "^5.0.12",
@@ -238,14 +242,17 @@
     "micromark-extension-gfm": "^3.0.0",
     "oxlint": "1.76.0",
     "oxlint-tsgolint": "7.0.2001",
+    "pnpm": "11.7.0",
     "publint": "^0.3.21",
     "smol-toml": "^1.7.1",
     "spdx-expression-parse": "^5.0.0",
+    "tar": "^7.5.0",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.8",
-    "@deepseek-ai/dsh-skill-office": "workspace:^"
+    "@deepseek-ai/dsh-skill-office": "workspace:^",
+    "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:^"
   }
 }
diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml
index 86d8d25086..f2447b3546 100644
--- a/packages/api/README.i18n.yaml
+++ b/packages/api/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/README.md
-README.md: f1aefa7d4564539f94202e869bacb85857f939d5
-README.zh.md: 870bbd32552166fdbb06221baaf54b9a130c6069
+README.md: 691a56856d0fceb62d3b32c3d5af90dd0323983a
+README.zh.md: 9303fbaae7b0f9a10880c18a7af79f1dffb3bdeb
diff --git a/packages/api/README.md b/packages/api/README.md
index f1aefa7d45..691a56856d 100644
--- a/packages/api/README.md
+++ b/packages/api/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-The `api/` group provides the application's Remote layer: a Client environment can call the business capabilities running on the Host — manage goals, run commands, list the plugin inventory, discover file and session references — as typed method calls, and receive the results or forwarded Host events. `remotes` decides which capabilities are exposed and how each call reaches the right session's agent; `gateway` carries the calls and their results between Client and Host. The stack runs over the application's shared Connection; streaming session data is deliberately outside it.
+The `api/` group provides the application's Remote layer: a Client environment can call the business capabilities running on the Host — manage goals, run commands, list the plugin inventory, discover file and session references — as typed method calls, receive results or streams, send uplink items on an open stream, and observe forwarded Host events. `remotes` decides which capabilities are exposed and how each call reaches the right session's agent; `gateway` carries the calls and their results between Client and Host. The stack runs over the application's shared Connection; streaming session data is deliberately outside it.
 
 ## Table of Contents
 
@@ -27,14 +27,15 @@ The packages below provide the Remote layer; the package READMEs own the exhaust
 | Package | Role | ctx key |
 |---|---|---|
 | [`remotes/`](remotes/README.md) | Chooses which Host capabilities and events the Client can consume. | — |
-| [`gateway/`](gateway/README.md) | Carries typed unary calls, multiplexed streams, and forwarded Host events. | `ctx.typertGateway` / `ctx.remote` |
+| [`gateway/`](gateway/README.md) | Carries typed unary calls, multiplexed streams with their Client uplinks, and forwarded Host events. | `ctx.typertGateway` / `ctx.remote` |
+| [`job-controller/`](job-controller/README.md) | Streams one background job's observation record to the Client. | `ctx.jobController` / `ctx.remote.job` |
 | [`session-controller/`](session-controller/README.md) | Owns Session commands, history streams, live control state, and Agent/Session identity policy. | `ctx.sessionController` / `ctx.remote.session` |
 | [`settings-controller/`](settings-controller/README.md) | Owns the configuration-surface reads and writes over the settings-domain seams. | `ctx.settingsController`, `ctx.credentialsController` / `ctx.remote.settings`, `ctx.remote.credentials` |
 | [`workspace-controller/`](workspace-controller/README.md) | Owns Workspace mutations and the complete Client Workspace projection. | `ctx.workspaceController` / `ctx.remote.workspace` |
 | [`terminal-controller/`](terminal-controller/README.md) | Session-owned interactive shells, screen recovery and browser terminal control. | `ctx.terminalController` / `ctx.remote.terminal` |
 | [`workspace-files/`](workspace-files/README.md) | Owns bounded workspace file access — `stat`, paged `read`, `list`, and the instrumented-operation `changes` feed — and the Client `file` resource provider over it. | `ctx.workspaceFiles` / `ctx.remote.workspaceFiles` |
 
-Remote calls run Client → Host over the application's shared Connection. API Gateway owns Remote transport, while the controller packages own Session, configuration-surface, and Workspace behavior. Feature packages register exact Connection Fetch routes for responses that do not fit Remote invocation, such as streamed downloads.
+Remote calls run Client → Host over the application's shared Connection; stream items flow Host → Client on the Gateway mux, and a stream's uplink items flow Client → Host on the same logical stream. API Gateway owns Remote transport, while the controller packages own Session, configuration-surface, and Workspace behavior. Feature packages register exact Connection Fetch routes for responses that do not fit Remote invocation, such as streamed downloads.
 
 -----
 
diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md
index 870bbd3255..9303fbaae7 100644
--- a/packages/api/README.zh.md
+++ b/packages/api/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-group"
 
 ## 概述
 
-`api/` 组提供应用的 Remote 层：Client 环境可以调用运行在 Host 上的业务能力——管理目标、运行命令、查看插件清单、发现文件与会话引用——调用方式是类型化方法，并接收结果或转发的 Host 事件。`remotes` 决定暴露哪些能力、以及每次调用如何到达正确会话的 agent；`gateway` 在 Client 与 Host 之间承载调用及其结果。技术栈运行在应用共享的 Connection 之上；流式会话数据刻意不在其中。
+`api/` 组提供应用的 Remote 层：Client 环境可以调用运行在 Host 上的业务能力——管理目标、运行命令、查看插件清单、发现文件与会话引用——调用方式是类型化方法，可接收结果或流、在已打开的流上发送上行项，并观察转发的 Host 事件。`remotes` 决定暴露哪些能力、以及每次调用如何到达正确会话的 agent；`gateway` 在 Client 与 Host 之间承载调用及其结果。技术栈运行在应用共享的 Connection 之上；流式会话数据刻意不在其中。
 
 ## 目录
 
@@ -27,14 +27,15 @@ kind: "package-group"
 | 包 | 职责 | ctx key |
 |---|---|---|
 | [`remotes/`](remotes/README.zh.md) | 决定 Client 可以消费哪些 Host 能力与事件。 | — |
-| [`gateway/`](gateway/README.zh.md) | 承载类型化一元调用、多路复用流与转发的 Host 事件。 | `ctx.typertGateway` / `ctx.remote` |
+| [`gateway/`](gateway/README.zh.md) | 承载类型化一元调用、带 Client 上行的多路复用流，以及转发的 Host 事件。 | `ctx.typertGateway` / `ctx.remote` |
+| [`job-controller/`](job-controller/README.zh.md) | 把一个后台任务的观测 record 流式送到 Client。 | `ctx.jobController` / `ctx.remote.job` |
 | [`session-controller/`](session-controller/README.zh.md) | 拥有会话命令、历史记录流、实时控制状态与 Agent/Session 身份策略。 | `ctx.sessionController` / `ctx.remote.session` |
 | [`settings-controller/`](settings-controller/README.zh.md) | 拥有 settings 域各 seam 之上的配置界面读写。 | `ctx.settingsController`、`ctx.credentialsController` / `ctx.remote.settings`、`ctx.remote.credentials` |
 | [`workspace-controller/`](workspace-controller/README.zh.md) | 拥有 Workspace 变更与完整 Client Workspace 投影。 | `ctx.workspaceController` / `ctx.remote.workspace` |
 | [`terminal-controller/`](terminal-controller/README.zh.md) | Session 拥有的交互式 shell、屏幕恢复和浏览器终端控制。 | `ctx.terminalController` / `ctx.remote.terminal` |
 | [`workspace-files/`](workspace-files/README.zh.md) | 拥有有界的工作区文件访问——`stat`、分页 `read`、`list` 与已埋点操作的 `changes` 流——以及其上的 Client `file` 资源提供方。 | `ctx.workspaceFiles` / `ctx.remote.workspaceFiles` |
 
-Remote 调用沿 Client → Host 方向运行在应用共享的 Connection 之上。API Gateway 拥有 Remote 传输，各控制器包分别拥有 Session、配置界面与 Workspace 行为。流式下载等不适合 Remote 调用的响应由功能包注册精确的 Connection Fetch 路由。
+Remote 调用沿 Client → Host 方向运行在应用共享的 Connection 之上；流项沿 Host → Client 方向经 Gateway mux 传输，流的上行项则沿 Client → Host 方向走同一条逻辑流。API Gateway 拥有 Remote 传输，各控制器包分别拥有 Session、配置界面与 Workspace 行为。流式下载等不适合 Remote 调用的响应由功能包注册精确的 Connection Fetch 路由。
 
 -----
 
diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml
index 366e9297fe..832baf5fd0 100644
--- a/packages/api/gateway/README.i18n.yaml
+++ b/packages/api/gateway/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/api/gateway/README.md
-README.md: 1460f5a27062ffcac09c68358dc7b186241a1baa
-README.zh.md: 79ed379faad8498cfdf249a0accb437f6d5f98e3
+README.md: 71171ef65c9113315cbd401a6b59eefb5a9a45a1
+README.zh.md: f9f2068eb593acc25f1fd384d08979d5c48c7743
diff --git a/packages/api/gateway/README.md b/packages/api/gateway/README.md
index 1460f5a270..71171ef65c 100644
--- a/packages/api/gateway/README.md
+++ b/packages/api/gateway/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Two-sided Typert RPC endpoint for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-api-gateway/client` provides `ctx.remote`; both consume the same generated `InvocationDescriptor` contract and leave business selection to API Remotes. Connection carries unary request correlation, trust, and response envelopes, while Gateway owns multiplexed Remote streams.
+Two-sided Typert RPC endpoint for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-api-gateway/client` provides `ctx.remote`; both consume the same generated `InvocationDescriptor` contract and leave business selection to API Remotes. Connection carries unary request correlation, trust, and response envelopes, while Gateway owns multiplexed Remote streams, each carrying a Client-to-Host uplink on the same logical stream.
 
 ## Table of Contents
 
@@ -26,14 +26,16 @@ Two-sided Typert RPC endpoint for Host and Client Cordis environments. The Host
 
 `ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, and invokes the public business method. Business Services extend `TypertRemoteService` and mark methods with `@Remote` or `@RemoteScope` from [`dsh-typert-protocol`](../../typert/protocol/README.md); `bindTypertRemote()` remains available when another base class owns inheritance.
 
-Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteScope` resolves its receiver through a registered Host Context adapter. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
+Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteScope` resolves its receiver through a registered Host Context adapter. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation. For unary results, Gateway executes the generated codec's `encode()` when present and otherwise keeps strict JSON values unchanged; SRC recursively detects runtime byte values. Both paths return JSON-compatible metadata and result-relative byte attachments to Connection for transport framing.
 
-The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and returns 404 for unclaimed requests unless an exact Fetch route owns them. Direct `invoke()` calls preserve business errors; `TypertGatewayError` is a `RemoteError` subclass whose `gateway/*` codes name the failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs. A resolver that refuses on policy grounds — a cold-resume failure or an ownership fence — throws its own `RemoteError`, and the code it chose reaches the caller unchanged.
+The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and returns 404 for unclaimed requests unless an exact Fetch route owns them. Direct `invoke()` calls preserve business errors; `TypertGatewayError` is a `RemoteError` subclass whose `gateway/*` codes name the failures owned by dispatch, binding, providers, lookup, Context, arguments, codecs, and the uplink: `gateway/uplink-overflow` for an uplink whose buffered frames exceed `streamInboxBytes`, `gateway/protocol` for an uplink item after `end`, and the codec code `gateway/input-invalid` for a rejected uplink item. A resolver that refuses on policy grounds — a cold-resume failure or an ownership fence — throws its own `RemoteError`, and the code it chose reaches the caller unchanged.
 
 A cancellation-aware Remote method declares `signal: AbortSignal` as its final Host parameter. The signal is descriptor metadata rather than a wire argument: Connection supplies it to the Gateway, and the Gateway injects it after decoded business parameters. SRC recognizes the reserved final name, while strict generation additionally requires the global `AbortSignal` type.
 
 A stream Remote uses `@Remote({ mode: 'stream' })` and returns an `Iterable` or `AsyncIterable`. `ctx.typertGateway.stream()` applies the same endpoint, argument, lookup, and cancellation checks as unary invocation, then returns a cancellation-aware iterable over the business items. The Client opens the Gateway-owned `/api/remote.mux` WebSocket when its plugin activates and keeps it connected while idle. Connection owns the retry schedule; before each retry it asks the mux to cancel any candidate or active socket and make exactly one fresh physical attempt. The Host sends Ping control frames at the configured `websocketHeartbeatIntervalMs` interval (two seconds by default), and the browser answers Pong at the WebSocket protocol layer, so idle network intermediaries see traffic without any Remote stream frame. A socket that has not answered the previous Ping is terminated at the next interval. Independently cancellable logical streams share that socket; an in-process Connection carrier provides equivalent streams directly without opening it.
 
+Every stream also carries a Client-to-Host uplink on the same logical stream. A method declares the uplink item type as the second type argument of its return type, `RemoteStream<Out, In>` from [`dsh-typert-protocol`](../../typert/protocol/README.md); `In` defaults to `never`, and a method that returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out>` declares that it reads none. The running method reads its call as `this.ctx.invocation`: the Gateway derives the receiver from a Context carrying that `RemoteInvocation` — `request`, `service`, `peer`, `signal`, and `uplink()` — so nothing enters the parameter list, and `ctx.invocation` is `undefined` on a Context no Remote call derived. `uplink()` is available once per call. With a descriptor codec it decodes every item before delivery; without one — an SRC method, or a method whose `In` is `never` — it delivers JSON-safe `unknown` values. The Client sends each item as an `item` frame on the open logical stream, a top-level `undefined` item as an `item` frame without `value`, and its half-close as an `end` frame; the method observes the half-close as the end of the `uplink()` iteration and cancellation through `signal`. A rejected item fails the whole stream with `gateway/input-invalid` (field `uplink`). Uplink items are validated one by one at the Host because they arrive from the browser; downlink items are values the Host method produced and pass through unchecked. When the method finishes its downlink the Gateway returns the uplink iterator and drops unread items; items sent to a method that never takes its uplink wait in the inbox until then. Each logical stream buffers at most `streamInboxBytes` (262144 by default) of uplink frame bytes; overflow fails the stream with `gateway/uplink-overflow`, and an item after `end` fails it with `gateway/protocol`, in both cases without closing the socket. `item`, `end`, and `cancel` frames for a stream id the Host has already finished are dropped; only a duplicate `open` closes the socket. Gateway-owned streams such as `$events` return their uplink as soon as they open, so their `item` frames are dropped instead of buffered. A unary method may also call `uplink()`; its items are readable only while the method runs. Every stream speaks for the operator Peer: a WebSocket's streams for the Peer Connection admitted at upgrade, whose scope disposal closes the socket, and an in-process carrier's for the operator directly.
+
 Host composition can register one application event source through `registerRemoteEvents()`. Gateway reserves the internal `$events` logical endpoint for that source, accepts only empty `args`, and aborts streams opened by the registration when the source is withdrawn. API Remotes owns the event selection, argument validation, per-Client queues, and the Host home sent in the opening `{ type: 'ready', clientId, host: { home } }` frame. Its source factory attaches incremental listeners synchronously, so the Client publishes the generation and starts baseline reads only after incremental delivery is ready.
 
 <a id="client-service-clientremote-ctx-key-remote"></a>
@@ -43,7 +45,7 @@ The browser carrier accepts the shell-owned stream origin described by [Connecti
 
 `ctx.remote.$mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Each namespace is a traced `remote.<namespace>` child Service and unloads after its last method is withdrawn. Duplicate endpoints, namespace collisions, and Client-supplied fields without strict generated codecs fail before methods become callable.
 
-Each unary call checks positional arity, constructs the descriptor's exact named `args`, and sends the typed values through `ctx.connection.rpc.call('/api', endpoint, ...)` without executing Client-side schemas; the Host validates the received wire fields before business invocation. A generated stream method returns an `AsyncIterable` and opens one logical stream through an in-process Connection carrier when available, otherwise through the shared Gateway WebSocket. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before invoking the carrier. Successful unary results and stream items pass through without Client-side type parsing. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls and streams, and makes retained method handles reject.
+Each unary call checks positional arity, constructs the descriptor's exact named `args`, and sends the typed values through `ctx.connection.rpc.call('/api', endpoint, ...)` without executing Client-side schemas; the Host validates the received wire fields before business invocation. A generated stream method returns a `RemoteStreamHandle<Out, In>` from `dsh-typert-protocol` and opens one logical stream when it is called, through an in-process Connection carrier when available, otherwise through the shared Gateway WebSocket. The handle iterates the downlink once. `send(item)` queues an uplink item, sent after the `open` frame; `end()` half-closes the uplink; `dispose()` sends `cancel` unless a terminal frame has arrived and ends the iteration quietly. Breaking out of the iteration early disposes the handle; after the downlink terminates `send` throws and `end` is ignored. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before invoking the carrier. The Client delegates unary result conversion to the codec's optional `decode()`. Generated decoders validate nested metadata and native byte types without iterating, copying, or freezing byte payloads. JSON unary results and stream items pass through without Client-side type parsing. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls and streams, and makes retained method handles reject.
 
 Every unary call resolves to `RemoteResult<T>` — `{ ok: true, value }` or `{ ok: false, error }` — and never rejects for a carrier problem: this face folds an offline carrier into the error branch and answers `gateway/cancelled` when the caller's signal aborts, so no consumer wraps a call to recover one. Only an assembly fault still rejects: wrong arity, an unmounted method, a withdrawn contribution, a missing Context adapter. `error` is a live `RemoteError` instance, so `throw result.error` keeps throw semantics, and `isRemoteFailure(value)` is the one predicate a consumer needs — a caught value it accepts carries a Host code, and anything it rejects is a local fault the caller should let crash. `carrierFailure(endpoint, error)` and `cancelledFailure(endpoint, cause)` build those two folded results, so a test stand-in for this face folds identically.
 
@@ -79,6 +81,7 @@ No direct effect; invoked business Services own any model-visible result.
 - Lookup resolvers are configured per key; an individual Remote parameter or endpoint cannot currently select a live-only policy under the same `agent`/`session` key.
 - Forwarded events reach `$on` without business-payload projection or redaction. Ordinary notifications are not replayed after reconnect; Agent-scoped waterfalls project only the top-level Agent identity needed to select the Client Context and carry their own pending lifetime.
 - `websocketHeartbeatIntervalMs` is both the Ping cadence and the Pong deadline. The Host terminates a peer that does not answer before the next interval, so a deployment whose event loop or network can stall longer than this interval must raise it.
+- Uplinks have no flow control beyond the bounded Host inbox: a Client that sends faster than the method reads, or that sends to a method never taking its uplink, fails its stream with `gateway/uplink-overflow`, and no uplink item is replayed across carrier generations; a domain that must resume an uplink carries its own acknowledgement cursor in the reopened request.
 
 
 <a id="dev-note"></a>
diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md
index 79ed379faa..f9f2068eb5 100644
--- a/packages/api/gateway/README.zh.md
+++ b/packages/api/gateway/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-为 Host 与 Client 两侧的 Cordis 环境提供 Typert RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 约定，并将业务选择交给 API Remotes。Connection 承载一元调用的请求关联、信任和响应 envelope，Gateway 则拥有多路复用的 Remote 流。
+为 Host 与 Client 两侧的 Cordis 环境提供 Typert RPC endpoint。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-api-gateway/client` 则提供 `ctx.remote`；两者使用同一份生成的 `InvocationDescriptor` 约定，并将业务选择交给 API Remotes。Connection 承载一元调用的请求关联、信任和响应 envelope，Gateway 则拥有多路复用的 Remote 流，每条流都在同一条逻辑流上携带从 Client 到 Host 的上行（uplink）。
 
 ## 目录
 
@@ -26,14 +26,16 @@ kind: "package-reference"
 
 每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，并调用公开的业务方法。业务服务继承 [`dsh-typert-protocol`](../../typert/protocol/README.zh.md) 的 `TypertRemoteService`，并用 `@Remote` 或 `@RemoteScope` 标记方法；已有其他基类时仍可改用 `bindTypertRemote()`。
 
-严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的解析器：业务包注册稳定声明与默认策略，Host 组合可用 effect-scoped `configure()` 覆盖解析行为；`@RemoteScope` 则通过已注册的 Host Context 适配器解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
+严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的解析器：业务包注册稳定声明与默认策略，Host 组合可用 effect-scoped `configure()` 覆盖解析行为；`@RemoteScope` 则通过已注册的 Host Context 适配器解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。对于一元结果，Gateway 在生成 codec 提供 `encode()` 时执行它，否则保持 strict JSON 值不变；SRC 则递归识别运行时字节值。两条路径都向 Connection 返回 JSON 兼容元数据及相对于结果的字节附件，由 Connection 完成传输帧封装。
 
-Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领且没有精确 Fetch 路由负责的请求返回 404。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 是 `RemoteError` 的子类，其 `gateway/*` 码命名了分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。因策略而拒绝的解析器——冷恢复失败或 ownership fence——抛出自己的 `RemoteError`，它选定的码原样到达调用方。
+Connection 可用时，Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge；handler 将已认领 endpoint 分发给 Gateway，未认领且没有精确 Fetch 路由负责的请求返回 404。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 是 `RemoteError` 的子类，其 `gateway/*` 码命名了分发、绑定、提供方、查找、Context、参数、编解码器以及上行各自负责的故障：缓冲帧超过 `streamInboxBytes` 的上行报 `gateway/uplink-overflow`，`end` 之后的上行项报 `gateway/protocol`，被 codec 拒绝的上行项报编解码码 `gateway/input-invalid`。因策略而拒绝的解析器——冷恢复失败或 ownership fence——抛出自己的 `RemoteError`，它选定的码原样到达调用方。
 
 支持取消的 Remote 方法会把 `signal: AbortSignal` 声明为最后一个 Host 参数。signal 是 descriptor 元数据，而不是 wire 参数：Connection 将它提供给 Gateway，Gateway 则在已解码的业务参数之后注入它。SRC 识别这个保留的末位参数名，严格生成还要求它具有全局 `AbortSignal` 类型。
 
 流式 Remote 使用 `@Remote({ mode: 'stream' })` 并返回 `Iterable` 或 `AsyncIterable`。`ctx.typertGateway.stream()` 执行与一元调用相同的 endpoint、参数、lookup 和取消校验，再返回可取消的业务项 iterable。Client 插件激活时打开 Gateway 自有的 `/api/remote.mux` WebSocket，并让它在空闲时保持连接。Connection 拥有重试调度；每次 retry 前，它要求 mux 取消候选或活动 socket，并且只做一次全新的物理连接尝试。Host 按配置的 `websocketHeartbeatIntervalMs` 间隔（默认 2 秒）发送 Ping 控制帧，浏览器在 WebSocket 协议层自动回复 Pong，使空闲网络中间层持续看到流量，而不新增 Remote 流帧。若 socket 尚未回复上一次 Ping，Host 会在下一间隔终止它。可独立取消的逻辑流共享这条连接；进程内 Connection 载体直接提供等价的流，不打开该 WebSocket。
 
+每条流还在同一条逻辑流上携带从 Client 到 Host 的上行。方法把上行项类型声明为返回类型的第二个类型参数——来自 [`dsh-typert-protocol`](../../typert/protocol/README.zh.md) 的 `RemoteStream<Out, In>`；`In` 缺省为 `never`，返回 `Iterable`、`AsyncIterable` 或 `RemoteStream<Out>` 的方法即声明自己不读上行。运行中的方法通过 `this.ctx.invocation` 读取本次调用：Gateway 从携带该 `RemoteInvocation`（`request`、`service`、`peer`、`signal` 与 `uplink()`）的 Context 派生接收者，因此没有任何东西进入参数列表，而非 Remote 调用派生的 Context 上 `ctx.invocation` 为 `undefined`。`uplink()` 每次调用只能取一次。描述符带 codec 时它在交付前逐项解码；不带时——SRC 方法，或 `In` 为 `never` 的方法——它交付经 JSON 安全校验的 `unknown` 值。Client 在已打开的逻辑流上把每一项作为 `item` 帧发送（顶层 `undefined` 项是不带 `value` 的 `item` 帧），以 `end` 帧表示半关闭；方法通过 `uplink()` 迭代结束感知半关闭，通过 `signal` 感知取消。被拒绝的项使整条流以 `gateway/input-invalid`（字段 `uplink`）失败。上行项在 Host 逐项校验，因为它们来自浏览器；下行项是 Host 方法产出的值，不经校验原样透传。方法结束下行时 Gateway 调用 uplink 迭代器的 return 并丢弃未读的项；发给从未取用 uplink 的方法的项在 inbox 里等到那时为止。每条逻辑流最多缓冲 `streamInboxBytes`（默认 262144）字节的上行帧；超限使流以 `gateway/uplink-overflow` 失败，`end` 之后的项使流以 `gateway/protocol` 失败，两种情况都不关闭 socket。发给 Host 已结束的流 id 的 `item`、`end` 与 `cancel` 帧被丢弃；只有重复的 `open` 会关闭 socket。`$events` 这类 Gateway 自有的流在打开时立即 return 其 uplink，因此它们的 `item` 帧被丢弃而不缓冲。一元方法也可以调用 `uplink()`；其项只在方法运行期间可读。每条流都代表操作者 Peer：WebSocket 上的流代表 Connection 在升级时接纳的 Peer，该 scope 释放时 socket 关闭；进程内载体的流直接代表操作者。
+
 Host 组合可通过 `registerRemoteEvents()` 注册唯一的应用事件 source。Gateway 为它保留内部 `$events` logical endpoint，只接受空 `args`，并在 source 撤回时中止该注册打开的流。事件名单、参数校验、每个 Client 的队列及 opening `{ type: 'ready', clientId, host: { home } }` frame 中的 Host home 由 API Remotes 拥有。source factory 在返回 iterable 前同步挂好增量 listener，因此 Client 只在增量投递就绪后发布 generation 并开始 baseline 读取。
 
 <a id="client-service-clientremote-ctx-key-remote"></a>
@@ -43,7 +45,7 @@ Host 组合可通过 `registerRemoteEvents()` 注册唯一的应用事件 source
 
 `ctx.remote.$mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。每个 namespace 都是可追踪的 `remote.<namespace>` 子 Service，并在最后一个方法撤回后卸载。重复端点、命名空间冲突，以及缺少生成的严格 codec 的 Client 供值字段，都会在方法可调用前报错。
 
-每次一元调用都会检查位置参数数量，构造与描述符完全匹配的具名 `args`，再把带类型的值原样交给 `ctx.connection.rpc.call('/api', endpoint, ...)`，而不执行 Client 侧 schema；Host 会在业务调用前校验收到的 wire 字段。生成的流方法返回 `AsyncIterable`，并在进程内 Connection 载体可用时通过它打开逻辑流，否则通过共享的 Gateway WebSocket 打开。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用载体前将它与贡献项的挂载生命周期合并。成功的一元结果与流项不经 Client 侧类型解析直接传递。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用与流，并使外部仍持有的方法句柄在调用时返回拒绝。
+每次一元调用都会检查位置参数数量，构造与描述符完全匹配的具名 `args`，再把带类型的值原样交给 `ctx.connection.rpc.call('/api', endpoint, ...)`，而不执行 Client 侧 schema；Host 会在业务调用前校验收到的 wire 字段。生成的流方法返回 `dsh-typert-protocol` 的 `RemoteStreamHandle<Out, In>`，并在被调用时就打开一条逻辑流，进程内 Connection 载体可用时通过它打开，否则通过共享的 Gateway WebSocket 打开。句柄只迭代下行一次。`send(item)` 把一个上行项入队，在 `open` 帧之后发出；`end()` 半关闭上行；`dispose()` 在未收到终止帧时发送 `cancel`，并让迭代安静结束。提前跳出迭代等价于 dispose 句柄；下行终止后 `send` 抛错，`end` 被忽略。生成的支持取消的方法接受最后一个可选 `AbortSignal`；Client 会在调用载体前将它与贡献项的挂载生命周期合并。Client 将一元结果转换交给 codec 的可选 `decode()`。生成的解码器校验嵌套元数据与原生字节类型，不逐字节遍历、复制或冻结字节载荷。JSON 一元结果与流项不经 Client 侧类型解析直接传递。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用与流，并使外部仍持有的方法句柄在调用时返回拒绝。
 
 每次一元调用都解析为 `RemoteResult<T>`——`{ ok: true, value }` 或 `{ ok: false, error }`——且绝不因载体问题 reject：本面把断线载体折入错误分支，调用方 signal 中止时答以 `gateway/cancelled`，因此没有消费方需要包一层来兜载体失败。只有装配故障仍会 reject：参数个数不符、方法未挂载、贡献已撤下、缺少 Context 适配器。`error` 是活的 `RemoteError` 实例，所以 `throw result.error` 保持 throw 语义；而 `isRemoteFailure(value)` 是消费方唯一需要的谓词——它认下的捕获值带着 Host 码，它拒绝的一律是本地故障，调用方应当让其崩掉。`carrierFailure(endpoint, error)` 与 `cancelledFailure(endpoint, cause)` 构造这两种折叠结果，测试里的替代实现据此采用相同的折叠方式。
 
@@ -79,6 +81,7 @@ Client waterfall 的 Context 解析保持同步。解析器可以返回借用的
 - lookup 解析器按 key 配置；当前无法让单个 Remote 参数或 endpoint 在同一 `agent`/`session` key 下选择 live-only 策略。
 - 被转发的事件到达 `$on` 时不做业务载荷投影或脱敏。普通通知在重连后不重放；Agent-scoped waterfall 只投影选择 Client Context 所需的顶层 Agent 身份，并自行携带 pending 生命周期。
 - `websocketHeartbeatIntervalMs` 同时是 Ping 周期和 Pong 截止时间。对端未在下一周期前回复时，Host 会终止连接；如果部署的事件循环或网络可能停顿超过该间隔，必须调大此配置。
+- 上行除了有界的 Host inbox 之外没有流控：Client 发送快于方法读取，或发给从未取用 uplink 的方法时，其流以 `gateway/uplink-overflow` 失败；上行项不会跨载体代际重放，需要恢复上行的领域在重开的请求里自带确认游标。
 
 
 <a id="dev-note"></a>
diff --git a/packages/api/gateway/package.json b/packages/api/gateway/package.json
index 4680b06f39..e2359db6be 100644
--- a/packages/api/gateway/package.json
+++ b/packages/api/gateway/package.json
@@ -58,7 +58,8 @@
     "@deepseek-ai/dsh-typert-protocol": "workspace:^"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts
index 01784c9d68..9a6cb07d16 100644
--- a/packages/api/gateway/src/client/index.ts
+++ b/packages/api/gateway/src/client/index.ts
@@ -5,7 +5,7 @@
  */
 
 import { Service } from '@deepseek-ai/cordis'
-import { RemoteError, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
+import { RemoteError, isRemoteUplinkItem, remoteErrorOf } from '@deepseek-ai/dsh-typert-protocol'
 export type { TypertGatewayFaultDetails } from '../remote-error-codes.ts'
 import type { Context } from '@deepseek-ai/cordis'
 import type {
@@ -17,12 +17,14 @@ import type {
   TypertClientRemote,
   RemoteFailure,
   RemoteResult,
+  RemoteStreamHandle,
   TypertCodec,
   TypertDisposer,
   TypertRemoteContribution,
   TypertRemoteEvent,
 } from '@deepseek-ai/dsh-typert-protocol'
 import {
+  ClientUplinkQueue,
   RemoteStreamCarrierError,
   RemoteStreamMuxClient,
 } from './stream-client.ts'
@@ -219,13 +221,14 @@ class ClientRemoteService extends Service implements ClientRemote {
     endpoint: string,
     payload: unknown,
     signal: AbortSignal,
+    uplink?: AsyncIterable<unknown>,
     noConnection = `client api: ${endpoint} has no active Connection`,
   ): AsyncIterable<unknown> {
     const connection = this.ownerCtx.get('connection') as ConnectionHandle | undefined
     if (connection === undefined) throw new Error(noConnection)
-    const local = connection.rpc.open?.('/api', endpoint, payload, signal)
+    const local = connection.rpc.open?.('/api', endpoint, payload, signal, uplink)
     return local === undefined
-      ? this.streams.open(endpoint, payload, signal)
+      ? this.streams.open(endpoint, payload, signal, uplink)
       : normalizeConnectionStream(local)
   }
 
@@ -387,7 +390,7 @@ class ClientRemoteService extends Service implements ClientRemote {
     scoped: ScopedMethod | undefined,
     callerCtx: Context,
     values: readonly unknown[],
-  ): Promise<RemoteResult<unknown>> | AsyncIterable<unknown> {
+  ): Promise<RemoteResult<unknown>> | RemoteStreamHandle<unknown, unknown> {
     if (scoped !== undefined) {
       const adapter = this.ownerCtx.typert.contexts.getClient(scoped.projection.context)
       const identity = adapter?.identity(callerCtx)
@@ -418,8 +421,8 @@ class ClientRemoteService extends Service implements ClientRemote {
     callerCtx: Context,
     values: readonly unknown[],
     boundIdentity?: BoundContextIdentity,
-  ): Promise<RemoteResult<unknown>> | AsyncIterable<unknown> {
-    if (descriptor.mode === 'stream') {
+  ): Promise<RemoteResult<unknown>> | RemoteStreamHandle<unknown, unknown> {
+    if (descriptor.mode !== undefined) {
       return this.invokeStream(descriptor, projection, token, callerCtx, values, boundIdentity)
     }
     return this.invoke(descriptor, projection, token, callerCtx, values, boundIdentity)
@@ -441,8 +444,12 @@ class ClientRemoteService extends Service implements ClientRemote {
     try {
       const result = await connection.rpc.call('/api', endpoint, { args: prepared.args }, prepared.signal)
       if (!mountActive(token)) return withdrawn(endpoint)
+      prepared.signal.throwIfAborted()
       if (!result.ok) return { ok: false, error: rebuiltFailure(result.error) }
-      return { ok: true, value: result.value }
+      const value = descriptor.result.mode === 'strict' && descriptor.result.decode !== undefined
+        ? descriptor.result.decode(result.value)
+        : result.value
+      return { ok: true, value }
     } catch (error) {
       // Carrier throws (offline or abort) are outcomes of the call, not assembly
       // faults, so they join the same error branch. A caller-aborted call is a
@@ -453,22 +460,27 @@ class ClientRemoteService extends Service implements ClientRemote {
     }
   }
 
-  private async *invokeStream(
+  /** Open the logical stream now and hand back its handle; `send()` before the first read queues behind the `open` frame. */
+  private invokeStream(
     descriptor: InvocationDescriptor,
     projection: ScopedProjection | undefined,
     token: MountToken,
     callerCtx: Context,
     values: readonly unknown[],
     boundIdentity?: BoundContextIdentity,
-  ): AsyncGenerator {
+  ): RemoteStreamHandle<unknown, unknown> {
     const endpoint = endpointOf(descriptor)
     if (!token.active) throw new Error(withdrawn(endpoint).error.message)
     const prepared = this.prepareInvocation(descriptor, projection, token, callerCtx, values, boundIdentity)
-    const stream = this.openRemoteStream(endpoint, { args: prepared.args }, prepared.signal)
-    for await (const value of stream) {
-      if (!mountActive(token)) throw new Error(withdrawn(endpoint).error.message)
-      yield value
-    }
+    const generation = new AbortController()
+    const uplink = new ClientUplinkQueue(endpoint)
+    const downlink = this.openRemoteStream(
+      endpoint,
+      { args: prepared.args },
+      AbortSignal.any([prepared.signal, generation.signal]),
+      uplink,
+    )
+    return new ClientStreamHandle(endpoint, downlink, uplink, generation, token)
   }
 
   private prepareInvocation(
@@ -521,12 +533,94 @@ class ClientRemoteService extends Service implements ClientRemote {
   }
 }
 
+/**
+ * The handle a generated stream method returns: one generation of one logical
+ * stream. The downlink is iterated once; `send`/`end` feed the uplink queue the
+ * carrier pump drains; `dispose` aborts the generation and returns the carrier
+ * iterator, which sends `cancel` unless a terminal frame arrived, drops what was
+ * buffered, and ends the iteration quietly.
+ */
+class ClientStreamHandle implements RemoteStreamHandle<unknown, unknown> {
+  private readonly downlink: AsyncIterator<unknown>
+  private primed: Promise<IteratorResult<unknown>> | undefined
+  private consumed = false
+  private disposed = false
+
+  constructor(
+    private readonly endpoint: string,
+    downlink: AsyncIterable<unknown>,
+    private readonly uplink: ClientUplinkQueue,
+    private readonly generation: AbortController,
+    private readonly token: MountToken,
+  ) {
+    this.downlink = downlink[Symbol.asyncIterator]()
+    // The carrier opens the logical stream on the first pull; pulling now puts
+    // the `open` frame on the wire before any `send()`. The first read is kept
+    // for the consumer, and a failure waits for it instead of surfacing here;
+    // it also terminates the stream, so the queue closes and `send()` throws.
+    this.primed = this.downlink.next()
+    void this.primed.catch(() => { this.uplink.close() })
+  }
+
+  send(item: unknown): void {
+    if (!isRemoteUplinkItem(item)) throw new Error(`client api: ${this.endpoint} uplink item is not a lossless JSON value`)
+    this.uplink.push(item)
+  }
+
+  end(): void {
+    this.uplink.end()
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.uplink.close()
+    this.generation.abort(new Error(`client api: ${this.endpoint} stream disposed`))
+    // Returning the carrier iterator reaches its `finally` even while nobody
+    // reads the downlink, so `cancel` goes out now and the pump stops.
+    void Promise.resolve(this.downlink.return?.()).catch(() => undefined)
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    if (this.consumed) throw new Error(`client api: ${this.endpoint} stream has one consumer`)
+    this.consumed = true
+    const iteration = this.iterate()
+    return {
+      next: () => iteration.next(),
+      // A return before the first read ends a generator that never started, so its `finally` would not dispose.
+      return: (value?: unknown) => {
+        this.dispose()
+        return iteration.return(value)
+      },
+    }
+  }
+
+  private async *iterate(): AsyncGenerator {
+    try {
+      while (true) {
+        const next = await (this.primed ?? this.downlink.next())
+        this.primed = undefined
+        if (this.disposed || next.done === true) return
+        if (!mountActive(this.token)) throw new Error(withdrawn(this.endpoint).error.message)
+        yield next.value
+      }
+    } catch (error) {
+      if (this.disposed) return
+      throw error
+    } finally {
+      // Ending early is a dispose; a terminated stream accepts no more uplink.
+      this.dispose()
+      await this.downlink.return?.()
+    }
+  }
+}
+
 type InvokeRemote = (
   direct: DirectMethod | undefined,
   scoped: ScopedMethod | undefined,
   callerCtx: Context,
   args: readonly unknown[],
-) => Promise<RemoteResult<unknown>> | AsyncIterable<unknown>
+) => Promise<RemoteResult<unknown>> | RemoteStreamHandle<unknown, unknown>
 
 class RemoteNamespaceService extends Service {
   private readonly methods = new Map<string, RemoteMethodRecord>()
@@ -698,6 +792,7 @@ function requireStrictInputs(descriptor: InvocationDescriptor): void {
   for (const parameter of descriptor.parameters) {
     requireStrictCodec(parameter.codec, endpoint, parameter.wire)
   }
+  if (descriptor.uplink !== undefined) requireStrictCodec(descriptor.uplink.codec, endpoint, 'uplink')
   if (descriptor.invocation.kind === 'context') {
     requireStrictCodec(descriptor.invocation.codec, endpoint, descriptor.invocation.wire)
   }
diff --git a/packages/api/gateway/src/client/remote-events.ts b/packages/api/gateway/src/client/remote-events.ts
index d799648b98..eabda54e37 100644
--- a/packages/api/gateway/src/client/remote-events.ts
+++ b/packages/api/gateway/src/client/remote-events.ts
@@ -11,7 +11,7 @@ import type {
   TypertOwnedValue,
   TypertRemoteEvent,
 } from '@deepseek-ai/dsh-typert-protocol'
-import { isTypertOwnedValue } from '@deepseek-ai/dsh-typert-protocol'
+import { isRemoteJsonValue, isTypertOwnedValue } from '@deepseek-ai/dsh-typert-protocol'
 import { randomUUID } from '@deepseek-ai/dsh-util-crypto'
 import {
   REMOTE_EVENT_RESULT_ENDPOINT,
@@ -20,7 +20,6 @@ import {
   isRemoteEventAgentId,
   isRemoteEventClientId,
   isRemoteEventId,
-  isRemoteJsonValue,
   projectRemoteEventRejection,
   type RemoteEventClientId,
   type RemoteEventDownlinkFrame,
diff --git a/packages/api/gateway/src/client/stream-client.ts b/packages/api/gateway/src/client/stream-client.ts
index 13e107ade8..7a580c5fac 100644
--- a/packages/api/gateway/src/client/stream-client.ts
+++ b/packages/api/gateway/src/client/stream-client.ts
@@ -28,6 +28,21 @@ interface SocketWaiter {
   reject(error: unknown): void
 }
 
+interface UplinkPump {
+  /** Settles once the pump has stopped sending. */
+  readonly done: Promise<void>
+  /** Interrupt the pump, including a read blocked on the caller's iterator, and release the iterator. */
+  stop(): void
+}
+
+/** One open logical stream: its downlink frames and, once the `open` frame is out, its uplink pump. */
+interface LogicalStream {
+  readonly inbox: StreamInbox
+  pump: UplinkPump | undefined
+}
+
+const UPLINK_DONE: IteratorReturnResult<undefined> = { value: undefined, done: true }
+
 /**
  * Keep one physical WebSocket and share it among independently cancellable
  * Remote streams. A carrier that supplies an in-process stream opener never
@@ -38,7 +53,7 @@ export class RemoteStreamMuxClient {
   private cancelCandidate: ((error: Error) => void) | undefined
   private keepAlive: Promise<void> | undefined
   private revision = 0
-  private readonly streams = new Map<string, StreamInbox>()
+  private readonly streams = new Map<string, LogicalStream>()
   private readonly waiters = new Set<SocketWaiter>()
   private running = false
   private disposed = false
@@ -77,16 +92,20 @@ export class RemoteStreamMuxClient {
    * @param endpoint - Typert Remote stream endpoint.
    * @param payload - endpoint request encoded on the wire.
    * @param signal - cancellation for this logical stream.
+   * @param uplink - the Client's items: each is sent as an `item` frame, its end as `end`; its `return()`
+   * runs when the stream finishes, and its failure cancels the stream and fails the downlink.
    * @returns Host items until completion, cancellation, or failure.
    */
   async *open(
     endpoint: string,
     payload: unknown,
     signal: AbortSignal,
+    uplink?: AsyncIterable<unknown>,
   ): AsyncGenerator {
     signal.throwIfAborted()
     const streamId = randomUUID()
     const inbox = new StreamInbox()
+    const stream: LogicalStream = { inbox, pump: undefined }
     let carrier: WebSocket | undefined
     let opened = false
     let terminal = false
@@ -96,9 +115,10 @@ export class RemoteStreamMuxClient {
       const socket = await this.waitForSocket(signal)
       signal.throwIfAborted()
       carrier = socket
-      this.streams.set(streamId, inbox)
+      this.streams.set(streamId, stream)
       this.send(socket, { type: 'open', streamId, endpoint, payload })
       opened = true
+      if (uplink !== undefined) stream.pump = this.pumpUplink(socket, streamId, uplink, signal, inbox)
       while (true) {
         const frame = await inbox.next()
         signal.throwIfAborted()
@@ -115,9 +135,65 @@ export class RemoteStreamMuxClient {
     } finally {
       signal.removeEventListener('abort', abort)
       this.streams.delete(streamId)
+      stream.pump?.stop()
       if (opened && !terminal && carrier?.readyState === WebSocket.OPEN) {
         this.send(carrier, { type: 'cancel', streamId })
       }
+      // The old generation's pump has stopped before a supervisor reopens the next one.
+      if (stream.pump !== undefined) await stream.pump.done
+    }
+  }
+
+  /**
+   * Send the caller's uplink items on this generation's socket. `stop()`
+   * interrupts a pump blocked on `uplink.next()` and releases the iterator: a
+   * handle's queue closes at once, so `send()` throws from then on, and any
+   * other iterator's `return()` is invoked without being awaited because a
+   * generator blocked in `next()` only completes it once it yields.
+   */
+  private pumpUplink(
+    socket: WebSocket,
+    streamId: string,
+    uplink: AsyncIterable<unknown>,
+    signal: AbortSignal,
+    inbox: StreamInbox,
+  ): UplinkPump {
+    const stopped = Promise.withResolvers<IteratorReturnResult<undefined>>()
+    const interruption: IteratorReturnResult<undefined> = { value: undefined, done: true }
+    const uplinkIterator = uplink[Symbol.asyncIterator]()
+    const state = { stopping: false, exhausted: false, released: false }
+    const release = (): void => {
+      if (state.released || state.exhausted) return
+      state.released = true
+      if (uplink instanceof ClientUplinkQueue) uplink.close()
+      void Promise.resolve().then(() => uplinkIterator.return?.()).catch(() => undefined)
+    }
+    const done = (async (): Promise<void> => {
+      try {
+        while (true) {
+          const next = await Promise.race([uplinkIterator.next(), stopped.promise])
+          if (state.stopping || next === interruption || signal.aborted || this.socket !== socket) return
+          if (next.done === true) {
+            state.exhausted = true
+            break
+          }
+          this.send(socket, { type: 'item', streamId, value: next.value })
+        }
+        this.send(socket, { type: 'end', streamId })
+      } catch (error) {
+        inbox.fail(error)
+      } finally {
+        release()
+      }
+    })()
+    return {
+      done,
+      stop: () => {
+        if (state.stopping) return
+        state.stopping = true
+        stopped.resolve(interruption)
+        release()
+      },
     }
   }
 
@@ -226,7 +302,11 @@ export class RemoteStreamMuxClient {
     try {
       if (typeof data !== 'string') throw new Error('api gateway: Remote stream WebSocket requires text messages')
       const frame = parseRemoteStreamServerMessage(data)
-      this.streams.get(frame.streamId)?.push(frame)
+      const stream = this.streams.get(frame.streamId)
+      if (stream === undefined) return
+      stream.inbox.push(frame)
+      // A terminal frame ends the uplink now, not on the consumer's next read.
+      if (frame.type !== 'item') stream.pump?.stop()
     } catch (error) {
       const failure = new RemoteStreamCarrierError('api gateway: invalid Remote stream frame', { cause: error })
       this.failAll(failure)
@@ -266,7 +346,10 @@ export class RemoteStreamMuxClient {
   }
 
   private failAll(error: unknown): void {
-    for (const stream of this.streams.values()) stream.fail(error)
+    for (const stream of this.streams.values()) {
+      stream.inbox.fail(error)
+      stream.pump?.stop()
+    }
   }
 
   private send(socket: WebSocket, message: RemoteStreamClientMessage): void {
@@ -303,6 +386,83 @@ class StreamInbox {
   }
 }
 
+/**
+ * Uplink items a stream handle queues for its carrier: the mux pump or the
+ * in-process Host decoder iterates it as the stream's uplink. `end()` is the
+ * Client half-close; `close()` marks the stream terminated, after which
+ * `push()` throws. One consumer reads it, one read at a time.
+ */
+export class ClientUplinkQueue implements AsyncIterable<unknown>, AsyncIterator<unknown> {
+  private readonly items = new Deque<unknown>()
+  private ended = false
+  private closed = false
+  private wake: (() => void) | undefined
+
+  /** @param endpoint - canonical Remote endpoint named by failures. */
+  constructor(private readonly endpoint: string) {}
+
+  /**
+   * Queue one item for the carrier.
+   * @param item - item the Host validates against the method's uplink codec.
+   * @throws {Error} after `end()` or once the stream has terminated.
+   */
+  push(item: unknown): void {
+    if (this.closed) throw new Error(`client api: ${this.endpoint} stream has terminated`)
+    if (this.ended) throw new Error(`client api: ${this.endpoint} uplink was ended`)
+    this.items.pushBack(item)
+    this.signal()
+  }
+
+  /** Half-close: the carrier reads the queued items, then `end`. Idempotent; ignored after termination. */
+  end(): void {
+    if (this.ended || this.closed) return
+    this.ended = true
+    this.signal()
+  }
+
+  /** The carrier stopped reading: the logical stream terminated or was disposed. Idempotent. */
+  close(): void {
+    if (this.closed) return
+    this.closed = true
+    this.items.clear()
+    this.signal()
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return this
+  }
+
+  /**
+   * Take the next queued item, waiting for one; ends after `end()` or `close()`.
+   * @returns the next item, or the end of the uplink.
+   * @throws {Error} when a read is already pending.
+   */
+  async next(): Promise<IteratorResult<unknown>> {
+    while (true) {
+      if (this.closed) return UPLINK_DONE
+      if (this.items.size > 0) return { value: this.items.popFront(), done: false }
+      if (this.ended) return UPLINK_DONE
+      if (this.wake !== undefined) throw new Error(`client api: ${this.endpoint} uplink has one pending read`)
+      await new Promise<void>((resolve) => { this.wake = resolve })
+    }
+  }
+
+  /**
+   * The carrier is done with the uplink: close it.
+   * @returns the end of the uplink.
+   */
+  return(): Promise<IteratorResult<unknown>> {
+    this.close()
+    return Promise.resolve(UPLINK_DONE)
+  }
+
+  private signal(): void {
+    const wake = this.wake
+    this.wake = undefined
+    wake?.()
+  }
+}
+
 function remoteStreamUrl(): string {
   // The mux route is registered absolute; a page resolves its document-relative
   // form against its own document base. A shell-owned Host on another origin
diff --git a/packages/api/gateway/src/index.ts b/packages/api/gateway/src/index.ts
index 1fe2438876..d9bc91d52a 100644
--- a/packages/api/gateway/src/index.ts
+++ b/packages/api/gateway/src/index.ts
@@ -7,7 +7,11 @@
 
 import { randomUUID } from 'node:crypto'
 import { Context, Service, symbols } from '@deepseek-ai/cordis'
-import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection'
+import {
+  OperatorPeer,
+  type ConnectionRpcAttachment,
+  type ConnectionRpcHandler,
+} from '@deepseek-ai/dsh-client-connection'
 import { Deque } from '@deepseek-ai/dsh-deque'
 import type { WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
@@ -15,10 +19,13 @@ import z from '@deepseek-ai/schemastery'
 export type { TypertGatewayFaultDetails } from './remote-error-codes.ts'
 import {
   RemoteError,
+  isRemoteJsonValue,
   remoteErrorOf,
   remoteMethods,
   type InvocationDescriptor,
   type InvocationParameterDescriptor,
+  type PeerScope,
+  type RemoteInvocation,
   type TypertCodec,
   type TypertGatewayBinding,
 } from '@deepseek-ai/dsh-typert-protocol'
@@ -43,7 +50,6 @@ import {
   REMOTE_EVENT_RESULT_ENDPOINT,
   REMOTE_STREAM_MUX_PATH,
   isRemoteEventAgentId,
-  isRemoteJsonValue,
   parseRemoteEventResult,
   projectRemoteEventRequest,
   restoreRemoteEventRejection,
@@ -84,9 +90,22 @@ interface ResolvedBinding {
 interface PreparedInvocation {
   readonly endpoint: string
   readonly descriptor: InvocationDescriptor
+  /** Service view bound to a Context carrying `invocation`, so the method reads it as `this.ctx.invocation`. */
   readonly receiver: object
   readonly args: readonly unknown[]
   readonly method: (...args: never[]) => unknown
+  readonly invocation: GatewayInvocation
+}
+
+/** Carrier inputs `GatewayInvocation.uplink()` decodes on first use. */
+interface UplinkSource {
+  /** Carrier items; an immediately ended iterable when the carrier has none. */
+  readonly source: AsyncIterable<unknown>
+  /** Descriptor codec, or the JSON-safety codec when the descriptor declares no uplink. */
+  readonly codec: TypertCodec
+  readonly endpoint: string
+  /** Fail the logical stream with a Remote failure as the reason. */
+  readonly abort: (reason: unknown) => void
 }
 
 interface RegisteredRemoteEventSource {
@@ -114,15 +133,24 @@ type ConnectionRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>
 type ConnectionRpcError = Extract<ConnectionRpcResult, { readonly ok: false }>['error']
 const NEVER_ABORTED_SIGNAL = new AbortController().signal
 const DEFAULT_WEBSOCKET_HEARTBEAT_INTERVAL_MS = 2_000
+const DEFAULT_STREAM_INBOX_BYTES = 262_144
+const EMPTY_ASYNC_ITERABLE: AsyncIterable<never> = {
+  [Symbol.asyncIterator]: () => ({ next: () => Promise.resolve({ value: undefined, done: true }) }),
+}
+const UPLINK_DONE: IteratorReturnResult<undefined> = { value: undefined, done: true }
+const SRC_JSON_CODEC: TypertCodec = { mode: 'src-json' }
 
 /** Gateway transport configuration. */
 export interface Config {
   /** WebSocket Ping interval from 1 through 2,147,483,647 milliseconds. @default 2000 */
   readonly websocketHeartbeatIntervalMs?: number
+  /** Buffered uplink frame bytes one logical stream may hold before it fails with `gateway/uplink-overflow`. @default 262144 */
+  readonly streamInboxBytes?: number
 }
 
 interface ResolvedConfig extends Config {
   readonly websocketHeartbeatIntervalMs: number
+  readonly streamInboxBytes: number
 }
 
 /**
@@ -171,15 +199,18 @@ export class TypertGatewayService extends Service implements TypertGateway {
   static Config: z<Config> = z.object({
     websocketHeartbeatIntervalMs: z.number().step(1).min(1).max(MAX_TIMER_DELAY_MS)
       .default(DEFAULT_WEBSOCKET_HEARTBEAT_INTERVAL_MS),
+    streamInboxBytes: z.number().step(1).min(1).default(DEFAULT_STREAM_INBOX_BYTES),
   })
 
   /** Carrier adapter shared by the WebSocket mux and local Host transports. */
   readonly wireStream: TypertGatewayWireStream = {
-    open: (endpoint, payload, signal) => this.openWireStream(endpoint, payload, signal),
+    open: (endpoint, payload, uplink, peer, signal) =>
+      this.openWireStream(endpoint, payload, uplink, peer, signal, new AbortController()),
     failure: error => rpcError(error),
   }
 
   private srcClaims: ReadonlySet<string> | undefined
+  private inProcessOperator: PeerScope | undefined
   private remoteEvents: RegisteredRemoteEventSource | undefined
   private readonly remoteEventClients = new Map<RemoteEventClientId, RemoteEventClient>()
   private readonly pendingRemoteEvents = new Map<RemoteEventId, PendingRemoteEvent>()
@@ -199,25 +230,27 @@ export class TypertGatewayService extends Service implements TypertGateway {
       connectionCtx.connection.rpc.intercept(
         '/api',
         endpoint => this.claimsEndpoint(endpoint),
-        (endpoint, payload, signal) => this.dispatchRpc(endpoint, payload, signal),
+        (endpoint, payload, signal, peer) => this.dispatchRpc(endpoint, payload, signal, peer),
       )
     })
     ctx.inject(['connection', 'webServer'], (webCtx) => {
       const mux = new RemoteStreamMuxServer(
-        (endpoint, payload, signal) => this.openWireStream(endpoint, payload, signal),
+        (endpoint, payload, uplink, peer, control) =>
+          this.openWireStream(endpoint, payload, uplink, peer, control.signal, control),
         this.wireStream.failure,
         resolved.websocketHeartbeatIntervalMs,
+        resolved.streamInboxBytes,
       )
       webCtx.effect(() => {
         const route: WebUpgradeRoute = {
           path: REMOTE_STREAM_MUX_PATH,
           handler: (req, socket, head) => {
-            const rejection = webCtx.connection.requestRejection(req)
-            if (rejection !== undefined) {
-              rejectRemoteStreamUpgrade(socket, rejection)
+            const admission = webCtx.connection.admit(req)
+            if ('rejection' in admission) {
+              rejectRemoteStreamUpgrade(socket, admission.rejection)
               return
             }
-            mux.handleUpgrade(req, socket, head)
+            mux.handleUpgrade(req, socket, head, admission.peer)
           },
         }
         const unregister = webCtx.webServer.registerUpgrade(route)
@@ -296,8 +329,11 @@ export class TypertGatewayService extends Service implements TypertGateway {
    * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity.
    */
   async invoke(request: InvokeRemoteRequest): Promise<unknown> {
-    const prepared = await this.prepareInvocation(request)
-    if (prepared.descriptor.mode === 'stream') {
+    return this.invokePrepared(await this.prepareInvocation(request, new AbortController()))
+  }
+
+  private async invokePrepared(prepared: PreparedInvocation): Promise<unknown> {
+    if (prepared.descriptor.mode !== undefined) {
       throw new TypertGatewayError(
         'gateway/signature-invalid',
         prepared.endpoint,
@@ -308,19 +344,31 @@ export class TypertGatewayService extends Service implements TypertGateway {
     try {
       return await Reflect.apply(prepared.method, prepared.receiver, prepared.args) as unknown
     } catch (error) {
-      if (request.signal?.aborted === true) throw remoteCancelled(prepared.endpoint, error)
+      if (prepared.invocation.signal.aborted) throw remoteCancelled(prepared.endpoint, error)
       throw error
+    } finally {
+      // A unary call's uplink is readable only while the method runs.
+      await prepared.invocation.close()
     }
   }
 
   /**
    * Open one live stream Remote method without assuming a physical carrier.
-   * @param request - decoded endpoint and named wire arguments.
+   * @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
    * @returns a cancellation-aware iterable over the business results.
    */
   async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>> {
-    const prepared = await this.prepareInvocation(request)
-    if (prepared.descriptor.mode !== 'stream') {
+    return this.openStream(request, new AbortController())
+  }
+
+  /**
+   * `control` belongs to the logical stream: a rejected uplink item aborts it
+   * with the Remote failure as the reason so the carrier delivers that failure.
+   */
+  private async openStream(request: InvokeRemoteRequest, control: AbortController): Promise<AsyncIterable<unknown>> {
+    const prepared = await this.prepareInvocation(request, control)
+    if (prepared.descriptor.mode === undefined) {
+      await prepared.invocation.close()
       throw new TypertGatewayError(
         'gateway/signature-invalid',
         prepared.endpoint,
@@ -331,10 +379,12 @@ export class TypertGatewayService extends Service implements TypertGateway {
     try {
       source = Reflect.apply(prepared.method, prepared.receiver, prepared.args) as unknown
     } catch (error) {
-      if (request.signal?.aborted === true) throw remoteCancelled(prepared.endpoint, error)
+      await prepared.invocation.close()
+      if (prepared.invocation.signal.aborted) throw remoteCancelled(prepared.endpoint, error)
       throw error
     }
     if (!isIterable(source)) {
+      await prepared.invocation.close()
       throw new TypertGatewayError(
         'gateway/result-invalid',
         prepared.endpoint,
@@ -342,17 +392,14 @@ export class TypertGatewayService extends Service implements TypertGateway {
         { field: 'result' },
       )
     }
-    return cancellableStream(
-      source,
-      prepared.endpoint,
-      request.signal ?? NEVER_ABORTED_SIGNAL,
-    )
+    return cancellableStream(source, prepared.endpoint, prepared.invocation)
   }
 
   private async dispatchRpc(
     endpoint: string,
     payload: unknown,
     signal: AbortSignal,
+    peer: PeerScope,
   ): Promise<ConnectionRpcResult> {
     if (endpoint === REMOTE_EVENT_RESULT_ENDPOINT) {
       try {
@@ -367,18 +414,36 @@ export class TypertGatewayService extends Service implements TypertGateway {
         return rpcFailure(error)
       }
     }
-    return this.invokeRpc(endpoint, payload, signal)
+    return this.invokeRpc(endpoint, payload, signal, peer)
   }
 
   private async openWireStream(
     endpoint: string,
     payload: unknown,
+    uplink: AsyncIterable<unknown>,
+    peer: PeerScope | undefined,
     signal: AbortSignal,
+    control: AbortController,
   ): Promise<AsyncIterable<unknown>> {
     if (endpoint === REMOTE_EVENT_STREAM_ENDPOINT) {
+      // A Gateway-owned stream reads no uplink: releasing it now keeps its items out of the bounded inbox.
+      releaseUplink(uplink)
       return this.openRemoteEvents(payload, signal)
     }
-    return this.stream(remoteRequest(endpoint, payload, signal))
+    return this.openStream({ ...remoteRequest(endpoint, payload, signal, peer), uplink }, control)
+  }
+
+  /**
+   * The Peer an in-process carrier speaks for when it names none: the
+   * operator's Peer when Connection is mounted, otherwise an operator scope the
+   * Gateway owns for its own lifetime.
+   * @returns the operator Peer.
+   */
+  private operatorPeer(): PeerScope {
+    const connection = this.ctx.get('connection')
+    if (connection !== undefined) return connection.operator
+    this.inProcessOperator ??= new OperatorPeer(this.ctx)
+    return this.inProcessOperator
   }
 
   private async *openRemoteEvents(
@@ -582,19 +647,32 @@ export class TypertGatewayService extends Service implements TypertGateway {
     for (const client of [...this.remoteEventClients.values()]) client.queue.end()
   }
 
-  private async invokeRpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<ConnectionRpcResult> {
+  private async invokeRpc(
+    endpoint: string,
+    payload: unknown,
+    signal: AbortSignal,
+    peer: PeerScope,
+  ): Promise<ConnectionRpcResult> {
     try {
-      const value = await this.invoke(remoteRequest(endpoint, payload, signal))
+      const prepared = await this.prepareInvocation(
+        remoteRequest(endpoint, payload, signal, peer),
+        new AbortController(),
+      )
+      const value = await this.invokePrepared(prepared)
       // A void or explicitly absent business result carries no `value` field;
       // JSON has no `undefined`, and the envelope's optional slot is the one
       // representation of absence that both args and results already use.
-      return { ok: true, value }
+      return encodeRpcResult(value, prepared.descriptor.result)
     } catch (error) {
       return rpcFailure(error)
     }
   }
 
-  private async prepareInvocation(request: InvokeRemoteRequest): Promise<PreparedInvocation> {
+  /** `control` fails the logical stream when an uplink item is rejected; unary calls hand over an inert one. */
+  private async prepareInvocation(
+    request: InvokeRemoteRequest,
+    control: AbortController,
+  ): Promise<PreparedInvocation> {
     const endpoint = endpointOf(request.namespace, request.method)
     const descriptor = this.resolveDescriptor(request.namespace, request.method, endpoint)
     assertExactArguments(request.args, descriptor, endpoint)
@@ -610,9 +688,27 @@ export class TypertGatewayService extends Service implements TypertGateway {
     validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)
     const args = await Promise.all(descriptor.parameters.map(parameter =>
       this.resolveParameter(parameter, request.args, endpoint)))
-    if (descriptor.cancellation !== undefined) args.push(request.signal ?? NEVER_ABORTED_SIGNAL)
+    const signal = methodSignal(request, control)
+    const invocation = new GatewayInvocation(
+      { namespace: request.namespace, method: request.method, args: request.args },
+      descriptor.service,
+      request.peer ?? this.operatorPeer(),
+      signal,
+      {
+        source: request.uplink ?? EMPTY_ASYNC_ITERABLE,
+        codec: descriptor.uplink?.codec ?? SRC_JSON_CODEC,
+        endpoint,
+        abort: (reason) => { control.abort(reason) },
+      },
+    )
+    if (descriptor.cancellation !== undefined) args.push(signal)
+    // The method runs on a Service view bound to a Context carrying this call:
+    // Cordis rebinds `this.ctx` to the accessing Context, so `this.ctx.invocation`
+    // is this call and nothing travels through the parameter list. The view
+    // resolves the Service the plain read above already found.
+    const callReceiver = receiverContext.extend({ invocation }).get(descriptor.service) as object
     const implementation = descriptor.implementation ?? descriptor.method
-    const method: unknown = Reflect.get(receiver, implementation)
+    const method: unknown = Reflect.get(callReceiver, implementation)
     if (typeof method !== 'function') {
       throw new TypertGatewayError(
         'gateway/method-unavailable',
@@ -620,7 +716,14 @@ export class TypertGatewayService extends Service implements TypertGateway {
         `active Service ${JSON.stringify(descriptor.service)} has no callable method ${JSON.stringify(implementation)}`,
       )
     }
-    return { endpoint, descriptor, receiver, args, method: method as (...args: never[]) => unknown }
+    return {
+      endpoint,
+      descriptor,
+      receiver: callReceiver,
+      args,
+      method: method as (...args: never[]) => unknown,
+      invocation,
+    }
   }
 
   private resolveDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
@@ -871,6 +974,67 @@ export class TypertGatewayService extends Service implements TypertGateway {
   }
 }
 
+function encodeRpcResult(value: unknown, codec: TypertCodec): ConnectionRpcResult {
+  const attachments: ConnectionRpcAttachment[] = []
+  const writeBytes = (bytes: Uint8Array, path: readonly (string | number)[]): null => {
+    attachments.push({ path: [...path], bytes })
+    return null
+  }
+  const encoded = codec.mode === 'strict'
+    ? codec.encode?.(value, writeBytes) ?? value
+    : encodeRuntimeResult(value, writeBytes)
+  return { ok: true, value: encoded, ...(attachments.length === 0 ? {} : { attachments }) }
+}
+
+function encodeRuntimeResult(
+  input: unknown,
+  writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null,
+): unknown {
+  const path: (string | number)[] = []
+  const ancestors = new Set<object>()
+  const extract = (input: unknown, key: string): unknown => {
+    // Capture accessors and toJSON once, before materializing the JSON metadata.
+    let value = input
+    if (input !== null && typeof input === 'object' && !(input instanceof Uint8Array)) {
+      const toJSON: unknown = Reflect.get(input, 'toJSON')
+      if (typeof toJSON === 'function') value = Reflect.apply(toJSON, input, [key])
+    }
+    if (value instanceof Uint8Array) return writeBytes(value, path)
+    if (typeof value !== 'object' || value === null) return value
+    if (value instanceof Number || value instanceof String || value instanceof Boolean) return value.valueOf()
+    if (ancestors.has(value)) throw new TypeError('gateway: circular RPC result')
+    ancestors.add(value)
+    let copy: object
+    if (Array.isArray(value)) {
+      const items: unknown[] = []
+      // JSON arrays include every index, even holes and non-enumerable elements.
+      for (let index = 0, length = value.length; index < length; index++) items.push(child(value[index], index))
+      copy = items
+    } else {
+      const fields: Record<string, unknown> = {}
+      for (const key of Object.keys(value)) {
+        const item: unknown = Reflect.get(value, key)
+        // A toJSON method on the projected object must not run a second time.
+        if (key === 'toJSON' && typeof item === 'function') continue
+        const extracted = child(item, key)
+        if (key === '__proto__') Object.defineProperty(fields, key, { value: extracted, enumerable: true })
+        else fields[key] = extracted
+      }
+      copy = fields
+    }
+    ancestors.delete(value)
+    return copy
+  }
+  const child = (value: unknown, key: string | number): unknown => {
+    if (typeof value !== 'object' || value === null) return value
+    path.push(key)
+    const extracted = extract(value, String(key))
+    path.pop()
+    return extracted
+  }
+  return extract(input, 'value')
+}
+
 type RemoteEventWireFrame =
   | RemoteEventEmitFrame
   | RemoteEventInvocationFrame
@@ -933,7 +1097,12 @@ function parseRemoteEventResultPayload(payload: unknown): ReturnType<typeof pars
   return parseRemoteEventResult(payload.args)
 }
 
-function remoteRequest(endpoint: string, payload: unknown, signal: AbortSignal): InvokeRemoteRequest {
+function remoteRequest(
+  endpoint: string,
+  payload: unknown,
+  signal: AbortSignal,
+  peer?: PeerScope,
+): InvokeRemoteRequest {
   const segments = endpoint.split('/')
   if (segments.length !== 2 || segments[0] === '' || segments[1] === '') {
     throw new Error(`invalid Remote endpoint ${JSON.stringify(endpoint)}`)
@@ -947,7 +1116,20 @@ function remoteRequest(endpoint: string, payload: unknown, signal: AbortSignal):
     || !isPlainObject(payload.args)) {
     throw new Error('Remote payload must contain exactly one plain-object args field')
   }
-  return { namespace, method, args: payload.args, signal }
+  return { namespace, method, args: payload.args, signal, ...(peer === undefined ? {} : { peer }) }
+}
+
+/**
+ * The signal a method observes. A carrier that supplies an uplink fails the
+ * stream through `control` when an item is rejected, so that invocation joins
+ * `control` with the carrier signal; every other invocation keeps the carrier
+ * signal's identity.
+ */
+function methodSignal(request: InvokeRemoteRequest, control: AbortController): AbortSignal {
+  const carrier = request.signal
+  if (request.uplink === undefined) return carrier ?? NEVER_ABORTED_SIGNAL
+  if (carrier === undefined || carrier === control.signal) return control.signal
+  return AbortSignal.any([carrier, control.signal])
 }
 
 function isIterable(value: unknown): value is Iterable<unknown> | AsyncIterable<unknown> {
@@ -959,8 +1141,9 @@ function isIterable(value: unknown): value is Iterable<unknown> | AsyncIterable<
 async function *cancellableStream(
   source: Iterable<unknown> | AsyncIterable<unknown>,
   endpoint: string,
-  signal: AbortSignal,
+  invocation: GatewayInvocation,
 ): AsyncGenerator {
+  const { signal } = invocation
   const asyncFactory: unknown = Reflect.get(source, Symbol.asyncIterator)
   const syncFactory: unknown = Reflect.get(source, Symbol.iterator)
   const iterator = typeof asyncFactory === 'function'
@@ -969,11 +1152,11 @@ async function *cancellableStream(
   let rejectAbort: ((error: unknown) => void) | undefined
   const aborted = new Promise<never>((_resolve, reject) => { rejectAbort = reject })
   const onAbort = (): void => {
-    rejectAbort?.(remoteCancelled(endpoint, signal.reason))
+    rejectAbort?.(streamAbortFailure(endpoint, signal.reason))
   }
   signal.addEventListener('abort', onAbort, { once: true })
   try {
-    if (signal.aborted) throw remoteCancelled(endpoint, signal.reason)
+    if (signal.aborted) throw streamAbortFailure(endpoint, signal.reason)
     while (true) {
       const next = await Promise.race([Promise.resolve(iterator.next()), aborted])
       if (next.done === true) return
@@ -981,15 +1164,163 @@ async function *cancellableStream(
     }
   } finally {
     signal.removeEventListener('abort', onAbort)
+    // The uplink closes first so a method blocked on `uplink.next()` unwinds
+    // before its iterator is asked to return.
+    await invocation.close()
     await iterator.return?.()
   }
 }
 
+/**
+ * The failure a stream surfaces for its abort: a Remote failure used as the
+ * reason is the Gateway or carrier failing the stream itself (a rejected,
+ * overflowing, or misplaced uplink item); any other abort is a cancellation.
+ */
+function streamAbortFailure(endpoint: string, reason: unknown): unknown {
+  return remoteErrorOf(reason) === undefined ? remoteCancelled(endpoint, reason) : reason
+}
+
 /** Carrier-signal cancellation as the shared failure vocabulary expresses it. */
 function remoteCancelled(endpoint: string, cause: unknown): RemoteError<'gateway/cancelled'> {
   return new RemoteError('gateway/cancelled', `Remote invocation "${endpoint}" was aborted`, {}, { cause })
 }
 
+/**
+ * The iterable `invocation.uplink()` returns. Each uplink item passes the
+ * descriptor codec, or the JSON-safety check when the descriptor declares no
+ * uplink, before delivery; a rejected item fails the whole logical stream.
+ * Iteration ends when the Client half-closes or the downlink finishes, and
+ * fails when the stream is cancelled, so a method blocked on the uplink always
+ * wakes.
+ */
+class UplinkDecoder implements AsyncIterable<unknown>, AsyncIterator<unknown> {
+  private readonly source: AsyncIterator<unknown>
+  private readonly interrupted = Promise.withResolvers<IteratorResult<unknown>>()
+  private readonly onAbort = (): void => {
+    this.interrupted.reject(streamAbortFailure(this.endpoint, this.signal.reason))
+  }
+  private closed = false
+
+  constructor(
+    uplink: AsyncIterable<unknown>,
+    private readonly codec: TypertCodec,
+    private readonly endpoint: string,
+    private readonly signal: AbortSignal,
+    private readonly abort: (reason: unknown) => void,
+  ) {
+    this.source = uplink[Symbol.asyncIterator]()
+    // The rejection settles the race inside next(); an abort with no read in
+    // flight must not surface as an unhandled rejection.
+    void this.interrupted.promise.catch(() => undefined)
+    signal.addEventListener('abort', this.onAbort, { once: true })
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return this
+  }
+
+  async next(): Promise<IteratorResult<unknown>> {
+    // A cancelled stream reports the cancellation on every read, closed or not.
+    if (this.signal.aborted) throw streamAbortFailure(this.endpoint, this.signal.reason)
+    if (this.closed) return UPLINK_DONE
+    const next = await Promise.race([this.source.next(), this.interrupted.promise])
+    if (next.done === true) {
+      this.finish()
+      return UPLINK_DONE
+    }
+    let value: unknown
+    try {
+      // A top-level `undefined` is the absent `value` of its frame: without a codec it is the item itself.
+      value = next.value === undefined && this.codec.mode === 'src-json'
+        ? undefined
+        : decode(this.codec, next.value, this.endpoint, 'uplink')
+    } catch (failure) {
+      // The codec failure (`gateway/input-invalid`, field `uplink`) fails the whole logical stream.
+      this.abort(failure)
+      throw failure
+    }
+    return { value, done: false }
+  }
+
+  /** Downlink finished or the method stopped reading: unread uplink items are dropped. */
+  return(): Promise<IteratorResult<unknown>> {
+    if (!this.closed) {
+      this.finish()
+      // The carrier owns the source iterator; a generator blocked in next()
+      // completes this return once it yields, so it is not awaited here.
+      void Promise.resolve().then(() => this.source.return?.()).catch(() => undefined)
+    }
+    return Promise.resolve(UPLINK_DONE)
+  }
+
+  private finish(): void {
+    this.closed = true
+    this.signal.removeEventListener('abort', this.onAbort)
+    this.interrupted.resolve(UPLINK_DONE)
+  }
+}
+
+/**
+ * The context of one Remote call as the receiving method reads it through
+ * `this.ctx.invocation`. The uplink is decoded on first use and released when
+ * the call's downlink finishes.
+ */
+class GatewayInvocation implements RemoteInvocation {
+  private decoder: UplinkDecoder | undefined
+  private taken = false
+
+  /**
+   * @param request - decoded endpoint and wire arguments.
+   * @param service - Cordis service key of the receiver.
+   * @param peer - Peer the call speaks for.
+   * @param signal - the signal the method observes.
+   * @param uplink - carrier items and the codec that decodes them.
+   */
+  constructor(
+    readonly request: RemoteInvocation['request'],
+    readonly service: string,
+    readonly peer: PeerScope,
+    readonly signal: AbortSignal,
+    private readonly uplink_: UplinkSource,
+  ) {}
+
+  uplink<In = unknown>(): AsyncIterable<In> {
+    if (this.taken) {
+      throw new Error(`typert gateway: ${this.uplink_.endpoint}: invocation.uplink() is available once per call`)
+    }
+    this.taken = true
+    const { source, codec, endpoint, abort } = this.uplink_
+    this.decoder = new UplinkDecoder(source, codec, endpoint, this.signal, abort)
+    // The descriptor codec decides what arrives; `In` is the caller's assertion.
+    return this.decoder as AsyncIterable<In>
+  }
+
+  /**
+   * The downlink finished: release the uplink. Unread items are dropped, and a
+   * carrier iterable the method never took is returned so it stops producing;
+   * a later `uplink()` throws like a second one would.
+   * @returns settles once a taken uplink has closed.
+   */
+  async close(): Promise<void> {
+    if (this.decoder !== undefined) {
+      await this.decoder.return()
+      return
+    }
+    this.taken = true
+    releaseUplink(this.uplink_.source)
+  }
+}
+
+/**
+ * Return a carrier uplink nobody will read, so it drops later items instead of
+ * buffering them. The carrier owns the iterator and `return()` is not awaited:
+ * a generator blocked in `next()` completes it only once it yields.
+ * @param source - the carrier's uplink iterable.
+ */
+function releaseUplink(source: AsyncIterable<unknown>): void {
+  void Promise.resolve().then(() => source[Symbol.asyncIterator]().return?.()).catch(() => undefined)
+}
+
 function rpcFailure(error: unknown): ConnectionRpcResult {
   const remote = remoteErrorOf(error)
   if (remote !== undefined) {
diff --git a/packages/api/gateway/src/remote-error-codes.ts b/packages/api/gateway/src/remote-error-codes.ts
index 22f94749f5..5e560557cc 100644
--- a/packages/api/gateway/src/remote-error-codes.ts
+++ b/packages/api/gateway/src/remote-error-codes.ts
@@ -27,9 +27,11 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
     'gateway/lookup-not-found': TypertGatewayFaultDetails
     'gateway/lookup-unavailable': TypertGatewayFaultDetails
     'gateway/method-unavailable': TypertGatewayFaultDetails
+    'gateway/protocol': TypertGatewayFaultDetails
     'gateway/provider-mismatch': TypertGatewayFaultDetails
     'gateway/result-invalid': TypertGatewayFaultDetails
     'gateway/service-unavailable': TypertGatewayFaultDetails
     'gateway/signature-invalid': TypertGatewayFaultDetails
+    'gateway/uplink-overflow': TypertGatewayFaultDetails
   }
 }
diff --git a/packages/api/gateway/src/stream-protocol.ts b/packages/api/gateway/src/stream-protocol.ts
index 5b77944a50..610fc07780 100644
--- a/packages/api/gateway/src/stream-protocol.ts
+++ b/packages/api/gateway/src/stream-protocol.ts
@@ -1,6 +1,7 @@
 /** Wire messages for Gateway-owned Remote streams and event-result RPCs. */
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
+import { isRemoteJsonValue } from '@deepseek-ai/dsh-typert-protocol'
 
 /** Exact WebSocket route carrying every Typert Remote stream. */
 export const REMOTE_STREAM_MUX_PATH = '/api/remote.mux'
@@ -203,15 +204,6 @@ export function restoreRemoteEventRejection(rejection: RemoteEventRejection): Er
   return error
 }
 
-/**
- * Test whether a value crosses JSON transport without coercion or omission.
- * @param value - candidate boundary value.
- * @returns whether the value is losslessly JSON-compatible.
- */
-export function isRemoteJsonValue(value: unknown): boolean {
-  return visitJsonValue(value, new Set<object>())
-}
-
 /**
  * Recognize a non-empty Remote Event correlation id at a wire boundary.
  * @param value - untrusted wire value.
@@ -239,7 +231,7 @@ export function isRemoteEventAgentId(value: unknown): value is RemoteEventAgentI
   return typeof value === 'string' && value.length > 0
 }
 
-/** One logical stream request sent from the browser. */
+/** One logical stream request sent from the browser: open, one uplink item, uplink half-close, or cancel. */
 export type RemoteStreamClientMessage =
   | {
     readonly type: 'open'
@@ -247,6 +239,8 @@ export type RemoteStreamClientMessage =
     readonly endpoint: string
     readonly payload: unknown
   }
+  | { readonly type: 'item'; readonly streamId: string; readonly value?: unknown }
+  | { readonly type: 'end'; readonly streamId: string }
   | { readonly type: 'cancel'; readonly streamId: string }
 
 /** Carrier-safe failure delivered by the Host. */
@@ -269,7 +263,15 @@ export type RemoteStreamServerMessage =
  */
 export function parseRemoteStreamClientMessage(text: string): RemoteStreamClientMessage {
   return parseMessage(text, (value) => {
-    if (value.type === 'cancel' && exactKeys(value, ['type', 'streamId']) && validId(value.streamId)) {
+    if ((value.type === 'cancel' || value.type === 'end')
+      && exactKeys(value, ['type', 'streamId'])
+      && validId(value.streamId)) {
+      return value as RemoteStreamClientMessage
+    }
+    if (value.type === 'item'
+      && (exactKeys(value, ['type', 'streamId']) || exactKeys(value, ['type', 'streamId', 'value']))
+      && validId(value.streamId)
+      && (!Object.hasOwn(value, 'value') || isRemoteJsonValue(value.value))) {
       return value as RemoteStreamClientMessage
     }
     if (value.type === 'open'
@@ -377,31 +379,3 @@ function stringProperty(value: object | undefined, key: string): string | undefi
   const candidate: unknown = Reflect.get(value, key)
   return typeof candidate === 'string' ? candidate : undefined
 }
-
-function visitJsonValue(value: unknown, ancestors: Set<object>): boolean {
-  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
-  if (typeof value === 'number') return Number.isFinite(value) && !Object.is(value, -0)
-  if (typeof value !== 'object') return false
-  if (ancestors.has(value)) return false
-  ancestors.add(value)
-  try {
-    if (Array.isArray(value)) {
-      if (Object.getPrototypeOf(value) !== Array.prototype
-        || Reflect.ownKeys(value).length !== value.length + 1) return false
-      for (let index = 0; index < value.length; index++) {
-        if (!Object.hasOwn(value, index) || !visitJsonValue(value[index], ancestors)) return false
-      }
-      return true
-    }
-    const prototype: unknown = Object.getPrototypeOf(value)
-    if (prototype !== Object.prototype && prototype !== null) return false
-    for (const key of Reflect.ownKeys(value)) {
-      if (typeof key !== 'string') return false
-      const descriptor = Object.getOwnPropertyDescriptor(value, key)
-      if (descriptor?.enumerable !== true || !visitJsonValue(Reflect.get(value, key), ancestors)) return false
-    }
-    return true
-  } finally {
-    ancestors.delete(value)
-  }
-}
diff --git a/packages/api/gateway/src/stream-server.ts b/packages/api/gateway/src/stream-server.ts
index 3a36e97ecd..9454f03f2d 100644
--- a/packages/api/gateway/src/stream-server.ts
+++ b/packages/api/gateway/src/stream-server.ts
@@ -2,18 +2,36 @@
 
 import type { IncomingMessage } from 'node:http'
 import type { Duplex } from 'node:stream'
+import { Deque } from '@deepseek-ai/dsh-deque'
+import { RemoteError, remoteErrorOf, type PeerScope } from '@deepseek-ai/dsh-typert-protocol'
 import WebSocket, { WebSocketServer, type RawData } from 'ws'
 import {
   parseRemoteStreamClientMessage,
+  type RemoteStreamClientMessage,
   type RemoteStreamFailure,
   type RemoteStreamServerMessage,
 } from './stream-protocol.ts'
 
-/** Open one validated Remote stream for a decoded wire request. */
+/**
+ * Open one validated Remote stream for a decoded wire request on behalf of one
+ * Peer. `uplink` carries the Client's items; `control` cancels the logical
+ * stream, and aborting it with a Remote failure as the reason delivers that
+ * failure to the Client.
+ */
 export type RemoteStreamOpener = (
   endpoint: string,
   payload: unknown,
-  signal: AbortSignal,
+  uplink: AsyncIterable<unknown>,
+  peer: PeerScope,
+  control: AbortController,
+) => Promise<AsyncIterable<unknown>>
+
+/** The opener one socket uses: its Peer is fixed at upgrade time. */
+type BoundStreamOpener = (
+  endpoint: string,
+  payload: unknown,
+  uplink: AsyncIterable<unknown>,
+  control: AbortController,
 ) => Promise<AsyncIterable<unknown>>
 
 /** Convert an invocation or carrier failure to a stable wire value. */
@@ -32,28 +50,40 @@ export class RemoteStreamMuxServer {
    * @param open - Gateway stream dispatcher.
    * @param failure - Gateway error-to-wire mapper.
    * @param heartbeatIntervalMs - interval between WebSocket Ping control frames.
+   * @param streamInboxBytes - buffered uplink frame bytes one logical stream may hold before it fails.
    */
   constructor(
     private readonly open: RemoteStreamOpener,
     private readonly failure: RemoteStreamFailureMapper,
     private readonly heartbeatIntervalMs: number,
+    private readonly streamInboxBytes: number,
   ) {}
 
   /**
-   * Upgrade one trusted request and begin serving its logical streams.
+   * Upgrade one admitted request and begin serving its logical streams. Every
+   * stream the socket opens speaks for the Peer admitted at upgrade, and the
+   * socket closes when that Peer's scope is disposed.
    * @param req - authenticated HTTP upgrade request.
    * @param socket - carrier socket transferred to the WebSocket server.
    * @param head - bytes already read after the HTTP upgrade headers.
+   * @param peer - Peer the upgrade was admitted as.
    */
-  handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
+  handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, peer: PeerScope): void {
     this.server.handleUpgrade(req, socket, head, (websocket) => {
+      const release = bindPeer(websocket, peer)
+      if (release === undefined) return
       this.missedHeartbeats.set(websocket, 0)
       websocket.on('pong', () => { this.missedHeartbeats.set(websocket, 0) })
       this.startHeartbeat()
-      const connection = new RemoteStreamMuxConnection(websocket, this.open, this.failure)
+      const bound: BoundStreamOpener = (endpoint, payload, uplink, control) =>
+        this.open(endpoint, payload, uplink, peer, control)
+      const connection = new RemoteStreamMuxConnection(websocket, bound, this.failure, this.streamInboxBytes)
       const done = connection.run()
       this.connections.add(done)
-      void done.then(() => { this.connections.delete(done) })
+      void done.then(() => {
+        this.connections.delete(done)
+        void release()
+      })
     })
   }
 
@@ -96,6 +126,9 @@ export class RemoteStreamMuxServer {
 
 interface ActiveStream {
   readonly abort: AbortController
+  readonly inbox: UplinkInbox
+  /** Cancel the logical stream and end any Host read still waiting on its uplink. */
+  readonly stop: (reason: Error) => void
   done: Promise<void>
 }
 
@@ -105,8 +138,9 @@ class RemoteStreamMuxConnection {
 
   constructor(
     private readonly socket: WebSocket,
-    private readonly open: RemoteStreamOpener,
+    private readonly open: BoundStreamOpener,
     private readonly failure: RemoteStreamFailureMapper,
+    private readonly streamInboxBytes: number,
   ) {}
 
   async run(): Promise<void> {
@@ -127,22 +161,58 @@ class RemoteStreamMuxConnection {
     })
     await closed
     const active = [...this.streams.values()]
-    for (const stream of active) stream.abort.abort(new Error('Remote stream socket closed'))
+    for (const stream of active) stream.stop(new Error('Remote stream socket closed'))
     await Promise.all(active.map(stream => stream.done))
   }
 
+  /**
+   * Dispatch one frame. `item`, `end`, and `cancel` for a stream this connection
+   * no longer owns are dropped: a finished stream leaves the table while the
+   * Client's in-flight frames are still arriving. A duplicate `open` is the one
+   * protocol violation that closes the socket.
+   */
   private receive(text: string): void {
     const message = parseRemoteStreamClientMessage(text)
-    if (message.type === 'cancel') {
-      this.streams.get(message.streamId)?.abort.abort(new Error('Remote stream cancelled'))
-      return
+    switch (message.type) {
+      case 'open': {
+        this.openStream(message)
+        return
+      }
+      case 'item': {
+        this.streams.get(message.streamId)?.inbox.push(message.value, Buffer.byteLength(text, 'utf8'))
+        return
+      }
+      case 'end': {
+        this.streams.get(message.streamId)?.inbox.end()
+        return
+      }
+      case 'cancel': {
+        this.streams.get(message.streamId)?.stop(new Error('Remote stream cancelled'))
+        return
+      }
+      /* v8 ignore next 4 -- parseRemoteStreamClientMessage admits only the four frame types above. */
+      default: {
+        const unknown: never = message
+        throw new Error(`api gateway: unknown Remote stream client message ${JSON.stringify(unknown)}`)
+      }
     }
+  }
+
+  private openStream(message: Extract<RemoteStreamClientMessage, { readonly type: 'open' }>): void {
     if (this.streams.has(message.streamId)) {
       throw new Error(`api gateway: duplicate Remote stream id ${JSON.stringify(message.streamId)}`)
     }
     const abort = new AbortController()
+    // Created before the opener resolves so items the Client sends right
+    // after `open` wait in the inbox instead of being lost.
+    const inbox = new UplinkInbox(this.streamInboxBytes, message.endpoint, (error) => { abort.abort(error) })
     const active: ActiveStream = {
       abort,
+      inbox,
+      stop: (reason) => {
+        abort.abort(reason)
+        inbox.fail(reason)
+      },
       done: Promise.resolve(),
     }
     this.streams.set(message.streamId, active)
@@ -158,22 +228,46 @@ class RemoteStreamMuxConnection {
     payload: unknown,
     active: ActiveStream,
   ): Promise<void> {
+    let outcome: { readonly failed: false } | { readonly failed: true; readonly error: unknown }
     try {
-      const source = await this.open(endpoint, payload, active.abort.signal)
+      const source = await this.open(endpoint, payload, active.inbox, active.abort)
       for await (const value of source) {
         await this.send({ type: 'item', streamId, value })
       }
-      if (!active.abort.signal.aborted) await this.send({ type: 'end', streamId })
+      outcome = { failed: false }
     } catch (error) {
-      if (!active.abort.signal.aborted && this.socket.readyState === WebSocket.OPEN) {
-        try {
-          await this.send({ type: 'error', streamId, error: this.failure(error) })
-        } catch {
-          // A terminal frame that cannot be encoded or written leaves the
-          // logical stream ambiguous, so fail the physical generation.
-          this.socket.close(1011, 'Remote stream failure could not be delivered')
-        }
-      }
+      outcome = { failed: true, error }
+    }
+    // The downlink has settled; later uplink frames cannot change the outcome.
+    active.inbox.fail(new Error('Remote stream ended'))
+    if (active.abort.signal.aborted) {
+      // A Remote failure as the abort reason is the Gateway or this mux failing
+      // the stream (a rejected or overflowing uplink item, or an item after
+      // end); the Client is still waiting for that terminal frame. Any other
+      // abort is a cancellation.
+      const reason: unknown = active.abort.signal.reason
+      if (remoteErrorOf(reason) !== undefined) await this.sendFailure(streamId, reason)
+      return
+    }
+    if (outcome.failed) {
+      await this.sendFailure(streamId, outcome.error)
+      return
+    }
+    try {
+      await this.send({ type: 'end', streamId })
+    } catch (error) {
+      await this.sendFailure(streamId, error)
+    }
+  }
+
+  private async sendFailure(streamId: string, error: unknown): Promise<void> {
+    if (this.socket.readyState !== WebSocket.OPEN) return
+    try {
+      await this.send({ type: 'error', streamId, error: this.failure(error) })
+    } catch {
+      // A terminal frame that cannot be encoded or written leaves the
+      // logical stream ambiguous, so fail the physical generation.
+      this.socket.close(1011, 'Remote stream failure could not be delivered')
     }
   }
 
@@ -199,6 +293,132 @@ class RemoteStreamMuxConnection {
   }
 }
 
+interface UplinkEntry {
+  readonly value: unknown
+  readonly bytes: number
+}
+
+const UPLINK_DONE: IteratorReturnResult<undefined> = { value: undefined, done: true }
+
+/**
+ * Bounded single-consumer uplink queue of one logical stream, the source the
+ * Host method reads through `invocation.uplink()`. Buffered frame bytes are
+ * capped: overflow, and an item after the Client's `end`, fail the queue and
+ * report a Remote failure that the connection uses to fail the logical stream.
+ */
+class UplinkInbox implements AsyncIterable<unknown>, AsyncIterator<unknown> {
+  private readonly queue = new Deque<UplinkEntry>()
+  private bytes = 0
+  private ended = false
+  private closed = false
+  private taken = false
+  private failure: Error | undefined
+  private wake: (() => void) | undefined
+
+  constructor(
+    private readonly maxBytes: number,
+    private readonly endpoint: string,
+    private readonly onViolation: (error: RemoteError<'gateway/protocol' | 'gateway/uplink-overflow'>) => void,
+  ) {}
+
+  push(value: unknown, frameBytes: number): void {
+    if (this.failure !== undefined || this.closed) return
+    if (this.ended) {
+      this.violate(new RemoteError(
+        'gateway/protocol',
+        'api gateway: Remote stream uplink item after end',
+        { endpoint: this.endpoint },
+      ))
+      return
+    }
+    if (this.bytes + frameBytes > this.maxBytes) {
+      this.violate(new RemoteError(
+        'gateway/uplink-overflow',
+        `api gateway: Remote stream uplink exceeded ${String(this.maxBytes)} buffered bytes`,
+        { endpoint: this.endpoint },
+      ))
+      return
+    }
+    this.queue.pushBack({ value, bytes: frameBytes })
+    this.bytes += frameBytes
+    this.signal()
+  }
+
+  /** Client half-close; idempotent. */
+  end(): void {
+    if (this.ended) return
+    this.ended = true
+    this.signal()
+  }
+
+  /** End the consumer's next read with `error`; idempotent, drops buffered items. */
+  fail(error: Error): void {
+    if (this.failure !== undefined) return
+    this.failure = error
+    this.queue.clear()
+    this.bytes = 0
+    this.signal()
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    if (this.taken) throw new Error('api gateway: Remote stream uplink inbox already has a consumer')
+    this.taken = true
+    return this
+  }
+
+  async next(): Promise<IteratorResult<unknown>> {
+    while (true) {
+      if (this.closed) return UPLINK_DONE
+      const entry = this.queue.popFront()
+      if (entry !== undefined) {
+        this.bytes -= entry.bytes
+        return { value: entry.value, done: false }
+      }
+      if (this.failure !== undefined) throw this.failure
+      if (this.ended) return UPLINK_DONE
+      if (this.wake !== undefined) throw new Error('api gateway: Remote stream uplink inbox has one pending read')
+      await new Promise<void>((resolve) => { this.wake = resolve })
+    }
+  }
+
+  /** Consumer stopped reading: later items are dropped, a pending read ends. */
+  return(): Promise<IteratorResult<unknown>> {
+    this.closed = true
+    this.queue.clear()
+    this.bytes = 0
+    this.signal()
+    return Promise.resolve(UPLINK_DONE)
+  }
+
+  private violate(error: RemoteError<'gateway/protocol' | 'gateway/uplink-overflow'>): void {
+    this.fail(error)
+    this.onViolation(error)
+  }
+
+  private signal(): void {
+    const wake = this.wake
+    this.wake = undefined
+    wake?.()
+  }
+}
+
+/**
+ * Close the socket when the Peer's scope is disposed. A scope that is already
+ * disposed leaves no Peer for the socket to speak for, so the socket closes now.
+ * @returns the registration's disposer, or `undefined` when the socket was closed.
+ */
+function bindPeer(websocket: WebSocket, peer: PeerScope): (() => unknown) | undefined {
+  try {
+    return peer.ctx.effect(
+      () => () => { websocket.close(1001, 'peer left') },
+      'api-gateway: Remote stream socket bound to its Peer',
+    )
+  } catch {
+    websocket.close(1001, 'peer left')
+    return undefined
+  }
+}
+
 function rawText(data: RawData): string {
   if (Array.isArray(data)) return Buffer.concat(data).toString('utf8')
   if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8')
diff --git a/packages/api/gateway/src/types.ts b/packages/api/gateway/src/types.ts
index f325d46e1a..cae8c9dcaf 100644
--- a/packages/api/gateway/src/types.ts
+++ b/packages/api/gateway/src/types.ts
@@ -4,6 +4,7 @@
  */
 
 import type { Context } from '@deepseek-ai/cordis'
+import type { PeerScope } from '@deepseek-ai/dsh-typert-protocol'
 import type { RemoteEventHostInfo } from './stream-protocol.ts'
 
 /** One Remote method request after a carrier has decoded its envelope. */
@@ -14,6 +15,13 @@ export interface InvokeRemoteRequest {
   readonly method: string
   /** Named wire values; fields must exactly match the descriptor. */
   readonly args: Readonly<Record<string, unknown>>
+  /**
+   * Client uplink items of this logical stream, delivered to the method through
+   * `invocation.uplink()`; absent means an immediately ended iterable.
+   */
+  readonly uplink?: AsyncIterable<unknown>
+  /** Peer the call speaks for; absent means an in-process carrier, answered as the operator. */
+  readonly peer?: PeerScope
   /** Carrier or direct-caller cancellation injected only into cancellation-aware methods. */
   readonly signal?: AbortSignal
 }
@@ -78,12 +86,17 @@ export interface TypertGatewayWireStream {
    * Open one logical stream from its wire endpoint and payload.
    * @param endpoint - canonical Remote endpoint or Gateway-owned stream name.
    * @param payload - decoded carrier payload.
+   * @param uplink - Client-to-Host items of the logical stream; a Gateway-owned endpoint returns its iterator
+   * as soon as it opens, so the carrier drops those items instead of buffering them.
+   * @param peer - Peer the stream speaks for; `undefined` means the operator's in-process carrier.
    * @param signal - logical-stream cancellation.
    * @returns validated stream values.
    */
   readonly open: (
     endpoint: string,
     payload: unknown,
+    uplink: AsyncIterable<unknown>,
+    peer: PeerScope | undefined,
     signal: AbortSignal,
   ) => Promise<AsyncIterable<unknown>>
 
@@ -114,10 +127,12 @@ export type TypertGatewayErrorCode =
   | 'gateway/lookup-not-found'
   | 'gateway/lookup-unavailable'
   | 'gateway/method-unavailable'
+  | 'gateway/protocol'
   | 'gateway/provider-mismatch'
   | 'gateway/result-invalid'
   | 'gateway/service-unavailable'
   | 'gateway/signature-invalid'
+  | 'gateway/uplink-overflow'
 
 /** Host dispatcher consumed by Connection adapters. */
 export interface TypertGateway {
@@ -145,7 +160,7 @@ export interface TypertGateway {
 
   /**
    * Open one live stream Remote method without assuming a physical carrier.
-   * @param request - decoded endpoint and named wire arguments.
+   * @param request - decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.
    * @returns a cancellation-aware iterable over the business results.
    */
   stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>
diff --git a/packages/api/gateway/tests/browser-credentials.ts b/packages/api/gateway/tests/browser-credentials.ts
index 8661983ea8..9bced52acc 100644
--- a/packages/api/gateway/tests/browser-credentials.ts
+++ b/packages/api/gateway/tests/browser-credentials.ts
@@ -1,5 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 
+const browserCookies = new WeakMap<Context, string>()
+
 /** Provide an in-memory credential-record owner for a mounted Connection plugin. */
 export function provideBrowserCredentials(ctx: Context): void {
   const records = new Map<unknown, unknown>()
@@ -15,3 +17,28 @@ export function provideBrowserCredentials(ctx: Context): void {
     },
   } as never)
 }
+
+/**
+ * Exchange a test Host's process token for its WebSocket/HTTP Cookie header.
+ * @param ctx - Host root with the Web server and Connection mounted.
+ * @returns the `cookie` header value, cached per root.
+ */
+export function browserCookie(ctx: Context): string {
+  const existing = browserCookies.get(ctx)
+  if (existing !== undefined) return existing
+  const origin = `http://127.0.0.1:${String(ctx.webServer.port)}`
+  const target = new URL(ctx.connection.authenticatedUrl(origin))
+  let setCookie: string | undefined
+  ctx.connection.authorizeIndex({
+    method: 'GET',
+    url: `${target.pathname}${target.search}`,
+    headers: { host: target.host },
+  }, {
+    writeHead(_status, headers) { setCookie = headers?.['set-cookie'] },
+    end() {},
+  })
+  if (setCookie === undefined) throw new Error('gateway fixture did not receive a browser cookie')
+  const cookie = setCookie.split(';', 1)[0]!
+  browserCookies.set(ctx, cookie)
+  return cookie
+}
diff --git a/packages/api/gateway/tests/echo-stream.host.spec.ts b/packages/api/gateway/tests/echo-stream.host.spec.ts
new file mode 100644
index 0000000000..d56b529002
--- /dev/null
+++ b/packages/api/gateway/tests/echo-stream.host.spec.ts
@@ -0,0 +1,96 @@
+import { once } from 'node:events'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import WebSocket, { type RawData } from 'ws'
+import { Context } from '@deepseek-ai/cordis'
+import { apply as applyConnection, inject as connectionInject } from '@deepseek-ai/dsh-client-connection'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { Remote, TypertRemoteService, type RemoteStream } from '@deepseek-ai/dsh-typert-protocol'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import TypertGatewayService from '@deepseek-ai/dsh-api-gateway'
+import { browserCookie, provideBrowserCredentials } from './browser-credentials.ts'
+
+/** The smallest Remote stream that reads its uplink: every carrier has to serve it alike. */
+class EchoService extends TypertRemoteService {
+  constructor(ctx: Context) {
+    super(ctx, 'echo', { namespace: 'echo' })
+  }
+
+  @Remote({ mode: 'stream' })
+  async *echo(prefix: string, signal: AbortSignal): RemoteStream<string, string> {
+    const invocation = this.ctx.invocation
+    if (invocation === undefined) throw new Error('echo ran outside a Remote call')
+    for await (const item of invocation.uplink<string>()) {
+      signal.throwIfAborted()
+      yield `${prefix}${item}`
+    }
+  }
+}
+
+const roots: Context[] = []
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map(ctx => ctx.fiber.dispose()))
+})
+
+describe('the echo stream on each carrier', () => {
+  it('echoes uplink items through the in-process carrier', async () => {
+    const ctx = await setup(false)
+    const replies = await ctx.typertGateway.stream({
+      namespace: 'echo', method: 'echo', args: { prefix: '> ' }, uplink: items(['a', 'b']),
+    })
+    await expect(collect(replies)).resolves.toEqual(['> a', '> b'])
+  })
+
+  it('echoes uplink frames through the WebSocket carrier', async () => {
+    const ctx = await setup(true)
+    const socket = new WebSocket(`ws://127.0.0.1:${String(ctx.webServer.port)}/api/remote.mux`, {
+      headers: { cookie: browserCookie(ctx) },
+    })
+    await once(socket, 'open')
+    const frames: unknown[] = []
+    socket.on('message', (data) => { frames.push(JSON.parse(rawText(data))) })
+    socket.send(JSON.stringify({ type: 'open', streamId: 'echo', endpoint: 'echo/echo', payload: { args: { prefix: '> ' } } }))
+    socket.send(JSON.stringify({ type: 'item', streamId: 'echo', value: 'a' }))
+    socket.send(JSON.stringify({ type: 'item', streamId: 'echo', value: 'b' }))
+    socket.send(JSON.stringify({ type: 'end', streamId: 'echo' }))
+    await vi.waitFor(() => {
+      expect(frames).toEqual([
+        { type: 'item', streamId: 'echo', value: '> a' },
+        { type: 'item', streamId: 'echo', value: '> b' },
+        { type: 'end', streamId: 'echo' },
+      ])
+    })
+    socket.close()
+    await once(socket, 'close')
+  })
+})
+
+async function setup(transport: boolean): Promise<Context> {
+  const ctx = new Context()
+  roots.push(ctx)
+  if (transport) {
+    await ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 })
+    provideBrowserCredentials(ctx)
+  }
+  await ctx.plugin(TypertRegistry)
+  await ctx.plugin(TypertGatewayService, {})
+  if (transport) await ctx.plugin({ inject: [...connectionInject], apply: applyConnection })
+  await ctx.plugin(EchoService)
+  return ctx
+}
+
+async function *items<T>(values: readonly T[]): AsyncIterable<T> {
+  for (const value of values) yield value
+}
+
+async function collect(source: AsyncIterable<unknown>): Promise<unknown[]> {
+  const values: unknown[] = []
+  for await (const value of source) values.push(value)
+  return values
+}
+
+function rawText(data: RawData): string {
+  if (Array.isArray(data)) return Buffer.concat(data).toString('utf8')
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8')
+  return Buffer.from(data).toString('utf8')
+}
diff --git a/packages/api/gateway/tests/gateway-stream.host.spec.ts b/packages/api/gateway/tests/gateway-stream.host.spec.ts
index 904dfb84a9..7ed908f620 100644
--- a/packages/api/gateway/tests/gateway-stream.host.spec.ts
+++ b/packages/api/gateway/tests/gateway-stream.host.spec.ts
@@ -2,14 +2,18 @@ import { randomUUID } from 'node:crypto'
 import { once } from 'node:events'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import WebSocket, { type RawData } from 'ws'
-import { Context, Service, symbols } from '@deepseek-ai/cordis'
+import { Context, symbols } from '@deepseek-ai/cordis'
 import { apply as applyConnection, inject as connectionInject } from '@deepseek-ai/dsh-client-connection'
 import WebServer from '@deepseek-ai/dsh-host-webserver'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import {
-  bindTypertRemote,
   Remote,
+  remoteErrorOf,
+  TypertRemoteService,
   type InvocationDescriptor,
+  type PeerScope,
+  type RemoteInvocation,
+  type RemoteStream,
   type TypertContextMap,
   type TypertContextWire,
   RemoteError,
@@ -22,7 +26,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
     'fixture/broken': { readonly count: bigint }
   }
 }
-import { provideBrowserCredentials } from './browser-credentials.ts'
+import { browserCookie, provideBrowserCredentials } from './browser-credentials.ts'
 import TypertGatewayService, {
   TypertGatewayError,
   type Config as GatewayConfig,
@@ -42,35 +46,15 @@ vi.mock('node:crypto', async (importOriginal) => {
 })
 
 const randomUuid = vi.mocked(randomUUID)
-const browserCookies = new WeakMap<Context, string>()
 const REMOTE_HOST = { home: '/home/fixture' } as const
 type AgentWireId = TypertContextWire<TypertContextMap['agent']>
 const agentId = (value: string): AgentWireId => value as AgentWireId
 
-/** Exchange this test Host's process token for its WebSocket/HTTP Cookie header. */
-function browserCookie(ctx: Context): string {
-  const existing = browserCookies.get(ctx)
-  if (existing !== undefined) return existing
-  const origin = `http://127.0.0.1:${String(ctx.webServer.port)}`
-  const target = new URL(ctx.connection.authenticatedUrl(origin))
-  let setCookie: string | undefined
-  ctx.connection.authorizeIndex({
-    method: 'GET',
-    url: `${target.pathname}${target.search}`,
-    headers: { host: target.host },
-  }, {
-    writeHead(_status, headers) { setCookie = headers?.['set-cookie'] },
-    end() {},
-  })
-  if (setCookie === undefined) throw new Error('gateway stream fixture did not receive a browser cookie')
-  const cookie = setCookie.split(';', 1)[0]!
-  browserCookies.set(ctx, cookie)
-  return cookie
-}
-
-class FeedService extends Service {
-  readonly typertRemote = bindTypertRemote(this, 'feed')
+class FeedService extends TypertRemoteService {
   readonly signals: AbortSignal[] = []
+  readonly peeked: unknown[] = []
+  readonly peers: PeerScope[] = []
+  leftover: AsyncIterator<string> | undefined
   returns = 0
 
   constructor(ctx: Context) {
@@ -133,9 +117,114 @@ class FeedService extends Service {
     throw new RemoteError('fixture/broken', 'fixture emitted invalid details', { count: 1n })
   }
 
+  @Remote({ mode: 'stream' })
+  async *echo(prefix: string, signal: AbortSignal): RemoteStream<string, string> {
+    this.signals.push(signal)
+    const invocation = this.invocation()
+    this.peers.push(invocation.peer)
+    try {
+      for await (const item of invocation.uplink<string>()) yield `${prefix}${item}`
+    } finally {
+      this.returns += 1
+    }
+  }
+
+  /** Hides the uplink failure so the test proves the Gateway still fails the stream. */
+  @Remote({ mode: 'stream' })
+  async *swallow(signal: AbortSignal): RemoteStream<string, string> {
+    try {
+      for await (const item of this.invocation().uplink<string>()) yield item
+    } catch {
+      // The fixture keeps yielding after the rejected item on purpose.
+    }
+    yield 'swallowed'
+    await abortOf(signal)
+  }
+
+  /** Never takes its uplink. */
+  @Remote({ mode: 'stream' })
+  async *ignore(prefix: string): RemoteStream<string, string> {
+    yield `${prefix}:one`
+    yield `${prefix}:two`
+  }
+
+  /** Keeps the downlink open without reading, and retains the uplink iterator for post-stream reads. */
+  @Remote({ mode: 'stream' })
+  async *hold(signal: AbortSignal): RemoteStream<string, string> {
+    this.leftover = this.invocation().uplink<string>()[Symbol.asyncIterator]()
+    yield 'held'
+    await abortOf(signal)
+  }
+
+  /** Reads before yielding so cancellation races the pending read, then reads once more after the abort. */
+  @Remote({ mode: 'stream' })
+  async *peek(signal: AbortSignal): RemoteStream<string, string> {
+    const iterator = this.invocation().uplink<string>()[Symbol.asyncIterator]()
+    const pending = iterator.next().then(result => result, (error: unknown) => error)
+    yield 'ready'
+    await abortOf(signal)
+    this.peeked.push(await pending, await iterator.next().then(result => result, (error: unknown) => error))
+  }
+
+  /** Yields once, then blocks on the uplink until the Gateway closes it. */
+  @Remote({ mode: 'stream' })
+  async *drain(): RemoteStream<string, string> {
+    yield 'ready'
+    for await (const item of this.invocation().uplink<string>()) yield item
+  }
+
+  /** Reads the uplink to its end and then again: an ended uplink reports done on every later read. */
+  @Remote({ mode: 'stream' })
+  async *rereads(): RemoteStream<string, string> {
+    const uplink = this.invocation().uplink<string>()
+    for await (const item of uplink) yield item
+    for await (const item of uplink) yield `again:${item}`
+    yield 'done'
+  }
+
+  /** Reports the call context; its descriptor declares no uplink codec, so items arrive as `unknown`. */
+  @Remote({ mode: 'stream' })
+  async *context(label: string): RemoteStream<string> {
+    const invocation = this.invocation()
+    this.peers.push(invocation.peer)
+    const { namespace, method, args } = invocation.request
+    yield `${namespace}/${method}:${invocation.service}:${JSON.stringify(args)}:${label}`
+    for await (const item of invocation.uplink()) yield `raw:${JSON.stringify(item)}`
+    try {
+      invocation.uplink()
+    } catch (error) {
+      yield error instanceof Error ? error.message : String(error)
+    }
+  }
+
+  /** SRC-discovered: no descriptor, so uplink items arrive as `unknown`. */
+  @Remote({ mode: 'stream' })
+  async *srcEcho(prefix: string, signal: AbortSignal): RemoteStream<string, string> {
+    void signal
+    for await (const item of this.invocation().uplink()) yield `${prefix}${String(item)}`
+  }
+
   unary(label: string): string {
     return label
   }
+
+  /** Reads the uplink inside a unary call: items arrive only while the method runs. */
+  async unaryUplink(): Promise<string[]> {
+    const items: string[] = []
+    for await (const item of this.invocation().uplink<string>()) items.push(item)
+    return items
+  }
+
+  /** What `ctx.invocation` reads on the Service's own Context, outside any Remote call. */
+  invocationOutsideCall(): RemoteInvocation | undefined {
+    return this.ctx.invocation
+  }
+
+  private invocation(): RemoteInvocation {
+    const invocation = this.ctx.invocation
+    if (invocation === undefined) throw new Error('fixture method ran outside a Remote call')
+    return invocation
+  }
 }
 
 const roots: Context[] = []
@@ -218,13 +307,16 @@ afterEach(async () => {
 })
 
 describe('Typert Remote streams', () => {
-  it('validates the WebSocket heartbeat timer range', () => {
-    expect(TypertGatewayService.Config({})).toEqual({ websocketHeartbeatIntervalMs: 2_000 })
-    expect(TypertGatewayService.Config({ websocketHeartbeatIntervalMs: MAX_TIMER_DELAY_MS }))
-      .toEqual({ websocketHeartbeatIntervalMs: MAX_TIMER_DELAY_MS })
+  it('validates the WebSocket heartbeat timer range and the stream inbox bound', () => {
+    expect(TypertGatewayService.Config({})).toEqual({ websocketHeartbeatIntervalMs: 2_000, streamInboxBytes: 262_144 })
+    expect(TypertGatewayService.Config({ websocketHeartbeatIntervalMs: MAX_TIMER_DELAY_MS, streamInboxBytes: 1 }))
+      .toEqual({ websocketHeartbeatIntervalMs: MAX_TIMER_DELAY_MS, streamInboxBytes: 1 })
     for (const websocketHeartbeatIntervalMs of [0, 1.5, MAX_TIMER_DELAY_MS + 1]) {
       expect(() => TypertGatewayService.Config({ websocketHeartbeatIntervalMs })).toThrow()
     }
+    for (const streamInboxBytes of [0, 1.5]) {
+      expect(() => TypertGatewayService.Config({ streamInboxBytes })).toThrow()
+    }
   })
 
   it('opens decoded carrier payloads through the in-process wire adapter', async () => {
@@ -232,10 +324,294 @@ describe('Typert Remote streams', () => {
     const source = await ctx.typertGateway.wireStream.open(
       'feed/sync',
       { args: { label: 'wire' } },
+      toAsync([]),
+      undefined,
       new AbortController().signal,
     )
-
     await expect(collect(source)).resolves.toEqual(['wire:one', 'wire:two'])
+
+    const echoed = await ctx.typertGateway.wireStream.open(
+      'feed/echo',
+      { args: { prefix: 'wire:' } },
+      toAsync(['a', 'b']),
+      undefined,
+      new AbortController().signal,
+    )
+    await expect(collect(echoed)).resolves.toEqual(['wire:a', 'wire:b'])
+  })
+
+  it('delivers uplink items through the in-process carrier and ends on half-close', async () => {
+    const { ctx, service } = await setup(false)
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'echo', args: { prefix: '> ' }, uplink: toAsync(['a', 'b']),
+    }))).resolves.toEqual(['> a', '> b'])
+    expect(service.returns).toBe(1)
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'echo', args: { prefix: 'x' },
+    }))).resolves.toEqual([])
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'feed', method: 'echo', args: { prefix: 'x' },
+    })).rejects.toMatchObject({
+      code: 'gateway/signature-invalid',
+      message: 'typert gateway: feed/echo: stream Remote methods must be opened through the stream carrier',
+    })
+
+    // The caller's iterator is released even when its own return() rejects.
+    const returned = vi.fn(async (): Promise<IteratorResult<string>> => {
+      throw new Error('fixture release failure')
+    })
+    const unread: AsyncIterable<string> = {
+      [Symbol.asyncIterator]: () => ({
+        next: () => new Promise<IteratorResult<string>>(() => {}),
+        return: returned,
+      }),
+    }
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'ignore', args: { prefix: 'i' }, uplink: unread,
+    }))).resolves.toEqual(['i:one', 'i:two'])
+    await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() })
+  })
+
+  it('fails a stream whose uplink item fails its codec, even when the method swallows the failure', async () => {
+    const { ctx, service } = await setup(false)
+    const rejected = await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'echo', args: { prefix: '' }, uplink: toAsync<unknown>(['ok', 1]),
+    })
+    const iterator = rejected[Symbol.asyncIterator]()
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: 'ok' })
+    await expect(iterator.next()).rejects.toMatchObject({
+      code: 'gateway/input-invalid',
+      details: { endpoint: 'feed/echo', field: 'uplink' },
+    })
+    const signal = service.signals.at(-1)
+    expect(signal?.aborted).toBe(true)
+    expect(remoteErrorOf(signal?.reason)?.code).toBe('gateway/input-invalid')
+    expect(service.returns).toBe(1)
+
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'swallow', args: {}, uplink: toAsync<unknown>([1]),
+    }))).rejects.toMatchObject({ code: 'gateway/input-invalid' })
+  })
+
+  it('ends a pending uplink read on cancellation and reports later reads as cancelled', async () => {
+    const { ctx, service } = await setup(false)
+    const abort = new AbortController()
+    const source = await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'peek', args: {}, uplink: neverYielding(), signal: abort.signal,
+    })
+    const iterator = source[Symbol.asyncIterator]()
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: 'ready' })
+    const pending = iterator.next()
+    abort.abort(new Error('fixture cancellation'))
+    await expect(pending).rejects.toThrow('Remote invocation "feed/peek" was aborted')
+    await vi.waitFor(() => { expect(service.peeked).toHaveLength(2) })
+    expect(service.peeked.map(outcome => remoteErrorOf(outcome)?.code))
+      .toEqual(['gateway/cancelled', 'gateway/cancelled'])
+  })
+
+  it('drops unread uplink items once the method finishes', async () => {
+    const { ctx, service } = await setup(false)
+    const abort = new AbortController()
+    const source = await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'hold', args: {}, uplink: toAsync(['unread']), signal: abort.signal,
+    })
+    const iterator = source[Symbol.asyncIterator]()
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: 'held' })
+    const pending = iterator.next()
+    abort.abort(new Error('fixture cancellation'))
+    await expect(pending).rejects.toThrow('Remote invocation "feed/hold" was aborted')
+    const leftover = service.leftover
+    if (leftover === undefined) throw new Error('fixture did not retain its uplink iterator')
+    // The unread item is gone; a cancelled stream reports the cancellation on every later read.
+    await expect(leftover.next()).rejects.toMatchObject({ code: 'gateway/cancelled' })
+    await expect(leftover.return?.()).resolves.toEqual({ done: true, value: undefined })
+  })
+
+  it('exposes the call as ctx.invocation, delivers codec-less uplink items as unknown, and hands the uplink out once', async () => {
+    const { ctx, service } = await setup(false)
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'context', args: { label: 'ctx' }, uplink: toAsync<unknown>([1, { nested: true }]),
+    }))).resolves.toEqual([
+      'feed/context:feed:{"label":"ctx"}:ctx',
+      'raw:1',
+      'raw:{"nested":true}',
+      'typert gateway: feed/context: invocation.uplink() is available once per call',
+    ])
+    expect(service.peers.at(-1)?.id).toMatch(/^[0-9a-f-]{36}$/)
+    expect(service.invocationOutsideCall()).toBeUndefined()
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'context', args: { label: 'again' },
+    }))).resolves.toHaveLength(2)
+    expect(service.peers.at(-1)).toBe(service.peers.at(-2))
+    await expect(service.peers.at(-1)?.dispose()).resolves.toBeUndefined()
+
+    // Items sent to a method that never takes its uplink wait in the carrier and are dropped when the downlink ends.
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'sync', args: { label: 'closed' }, uplink: toAsync(['unread']),
+    }))).resolves.toEqual(['closed:one', 'closed:two'])
+
+    // Without a codec an item still has to be a JSON-safe value.
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'context', args: { label: 'bad' }, uplink: toAsync<unknown>([1n]),
+    }))).rejects.toMatchObject({
+      code: 'gateway/input-invalid',
+      details: { endpoint: 'feed/context', field: 'uplink' },
+    })
+  })
+
+  it('releases a taken uplink source even when its return() rejects', async () => {
+    const { ctx } = await setup(false)
+    const abort = new AbortController()
+    const returned = vi.fn(async (): Promise<IteratorResult<string>> => {
+      throw new Error('fixture release failure')
+    })
+    const stuck: AsyncIterable<string> = {
+      [Symbol.asyncIterator]: () => ({
+        next: () => new Promise<IteratorResult<string>>(() => {}),
+        return: returned,
+      }),
+    }
+    const source = await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'hold', args: {}, uplink: stuck, signal: abort.signal,
+    })
+    const iterator = source[Symbol.asyncIterator]()
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: 'held' })
+    const pending = iterator.next()
+    abort.abort(new Error('fixture cancellation'))
+    await expect(pending).rejects.toThrow('Remote invocation "feed/hold" was aborted')
+    await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() })
+  })
+
+  it('closes the uplink before returning a method blocked on it', async () => {
+    const { ctx } = await setup(false)
+    const source = await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'drain', args: {}, uplink: neverYielding(),
+    })
+    const iterator = source[Symbol.asyncIterator]()
+    await expect(iterator.next()).resolves.toEqual({ done: false, value: 'ready' })
+    await expect(iterator.return?.()).resolves.toEqual({ done: true, value: undefined })
+  })
+
+  it('reports done on every read after the uplink ended', async () => {
+    const { ctx } = await setup(false)
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'rereads', args: {}, uplink: toAsync(['a', 'b']),
+    }))).resolves.toEqual(['a', 'b', 'done'])
+  })
+
+  it('accepts a top-level undefined uplink item where no codec applies and rejects it where one does', async () => {
+    const { ctx } = await setup(false)
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'context', args: { label: 'absent' }, uplink: toAsync<unknown>([undefined, 'x']),
+    }))).resolves.toEqual([
+      'feed/context:feed:{"label":"absent"}:absent',
+      'raw:undefined',
+      'raw:"x"',
+      'typert gateway: feed/context: invocation.uplink() is available once per call',
+    ])
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'echo', args: { prefix: '' }, uplink: toAsync<unknown>([undefined]),
+    }))).rejects.toMatchObject({ code: 'gateway/input-invalid', details: { endpoint: 'feed/echo', field: 'uplink' } })
+  })
+
+  it('releases the uplink when a unary method is opened through the stream carrier', async () => {
+    const { ctx } = await setup(false)
+    const returned = vi.fn(async (): Promise<IteratorResult<string>> => ({ value: undefined, done: true }))
+    const unread: AsyncIterable<string> = {
+      [Symbol.asyncIterator]: () => ({ next: () => new Promise<IteratorResult<string>>(() => {}), return: returned }),
+    }
+    await expect(ctx.typertGateway.stream({
+      namespace: 'feed', method: 'unary', args: { label: 'a' }, uplink: unread,
+    })).rejects.toMatchObject({ code: 'gateway/signature-invalid' })
+    await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() })
+  })
+
+  it('lets a unary method read uplink items while it runs', async () => {
+    const { ctx } = await setup(false)
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'feed', method: 'unaryUplink', args: {}, uplink: toAsync(['a', 'b']),
+    })).resolves.toEqual(['a', 'b'])
+  })
+
+  it('derives SRC descriptors whose uplink arrives without a codec', async () => {
+    const { ctx } = await setup(false)
+    await expect(collect(await ctx.typertGateway.stream({
+      namespace: 'feed', method: 'srcEcho', args: { prefix: 's:' }, uplink: toAsync<unknown>(['a', 2]),
+    }))).resolves.toEqual(['s:a', 's:2'])
+  })
+
+  it('echoes uplink frames over the WebSocket carrier and fails misused uplinks per stream', async () => {
+    const { ctx, service } = await setup(true)
+    const socket = new WebSocket(`ws://127.0.0.1:${String(ctx.webServer.port)}/api/remote.mux`, {
+      headers: { cookie: browserCookie(ctx) },
+    })
+    await once(socket, 'open')
+    const frames: Record<string, unknown>[] = []
+    socket.on('message', (data) => { frames.push(JSON.parse(rawText(data)) as Record<string, unknown>) })
+
+    sendOpen(socket, 'echo', 'feed/echo', { prefix: '> ' })
+    socket.send(JSON.stringify({ type: 'item', streamId: 'echo', value: 'a' }))
+    socket.send(JSON.stringify({ type: 'item', streamId: 'echo', value: 'b' }))
+    socket.send(JSON.stringify({ type: 'end', streamId: 'echo' }))
+    await vi.waitFor(() => {
+      expect(frames.filter(frame => frame.streamId === 'echo')).toEqual([
+        { type: 'item', streamId: 'echo', value: '> a' },
+        { type: 'item', streamId: 'echo', value: '> b' },
+        { type: 'end', streamId: 'echo' },
+      ])
+    })
+    expect(service.returns).toBe(1)
+    expect(service.peers.at(-1)).toBe(ctx.connection.operator)
+
+    sendOpen(socket, 'rejected', 'feed/echo', { prefix: '' })
+    socket.send(JSON.stringify({ type: 'item', streamId: 'rejected', value: 1 }))
+    await vi.waitFor(() => {
+      expect(frames.find(frame => frame.streamId === 'rejected')).toMatchObject({
+        type: 'error',
+        error: { code: 'gateway/input-invalid', details: { endpoint: 'feed/echo', field: 'uplink' } },
+      })
+    })
+
+    // An item frame without value is a top-level undefined item.
+    sendOpen(socket, 'absent', 'feed/context', { label: 'w' })
+    socket.send(JSON.stringify({ type: 'item', streamId: 'absent' }))
+    await vi.waitFor(() => {
+      expect(frames).toContainEqual({ type: 'item', streamId: 'absent', value: 'raw:undefined' })
+    })
+
+    sendOpen(socket, 'late', 'feed/hold', {})
+    await vi.waitFor(() => { expect(frames).toContainEqual({ type: 'item', streamId: 'late', value: 'held' }) })
+    socket.send(JSON.stringify({ type: 'end', streamId: 'late' }))
+    socket.send(JSON.stringify({ type: 'item', streamId: 'late', value: 'after end' }))
+    await vi.waitFor(() => {
+      expect(frames.find(frame => frame.streamId === 'late' && frame.type === 'error')).toMatchObject({
+        error: { code: 'gateway/protocol', details: { endpoint: 'feed/hold' } },
+      })
+    })
+    expect(socket.readyState).toBe(WebSocket.OPEN)
+    socket.close()
+    await once(socket, 'close')
+  })
+
+  it('fails a stream whose buffered uplink exceeds the configured inbox bytes', async () => {
+    const { ctx } = await setup(true, { streamInboxBytes: 64 })
+    const socket = new WebSocket(`ws://127.0.0.1:${String(ctx.webServer.port)}/api/remote.mux`, {
+      headers: { cookie: browserCookie(ctx) },
+    })
+    await once(socket, 'open')
+    const frames: Record<string, unknown>[] = []
+    socket.on('message', (data) => { frames.push(JSON.parse(rawText(data)) as Record<string, unknown>) })
+
+    sendOpen(socket, 'big', 'feed/hold', {})
+    await vi.waitFor(() => { expect(frames).toContainEqual({ type: 'item', streamId: 'big', value: 'held' }) })
+    socket.send(JSON.stringify({ type: 'item', streamId: 'big', value: 'x'.repeat(128) }))
+    await vi.waitFor(() => {
+      expect(frames.find(frame => frame.streamId === 'big' && frame.type === 'error')).toMatchObject({
+        error: { code: 'gateway/uplink-overflow', details: { endpoint: 'feed/hold' } },
+      })
+    })
+    socket.close()
+    await once(socket, 'close')
   })
 
   it('passes Iterable and AsyncIterable items through and returns the iterator on cancellation', async () => {
@@ -371,6 +747,44 @@ describe('Typert Remote streams', () => {
     expect(service.signals[1]?.aborted).toBe(true)
   })
 
+  it('keeps uplink frames to a Gateway-owned stream out of the bounded inbox', async () => {
+    const { ctx } = await setup(true, { streamInboxBytes: 64 })
+    const source = (signal: AbortSignal): AsyncIterable<{ event: string; args: readonly unknown[] }> => (async function *() {
+      await new Promise<void>((resolve) => {
+        if (signal.aborted) resolve()
+        else signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    })()
+    ctx.typertGateway.registerRemoteEvents(source, REMOTE_HOST)
+
+    // An in-process carrier's uplink is returned as soon as the Gateway-owned stream opens.
+    const returned = vi.fn(async (): Promise<IteratorResult<unknown>> => ({ value: undefined, done: true }))
+    const idle: AsyncIterable<unknown> = {
+      [Symbol.asyncIterator]: () => ({ next: () => new Promise<IteratorResult<unknown>>(() => {}), return: returned }),
+    }
+    const events = await ctx.typertGateway.wireStream.open('$events', { args: {} }, idle, undefined, new AbortController().signal)
+    await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() })
+    await events[Symbol.asyncIterator]().return?.()
+
+    const socket = new WebSocket(`ws://127.0.0.1:${String(ctx.webServer.port)}/api/remote.mux`, {
+      headers: { cookie: browserCookie(ctx) },
+    })
+    await once(socket, 'open')
+    const frames: Record<string, unknown>[] = []
+    socket.on('message', (data) => { frames.push(JSON.parse(rawText(data)) as Record<string, unknown>) })
+    sendOpen(socket, 'events', '$events', {})
+    await vi.waitFor(() => { expect(frames.filter(frame => frame.streamId === 'events')).toHaveLength(1) })
+    for (let index = 0; index < 4; index += 1) {
+      socket.send(JSON.stringify({ type: 'item', streamId: 'events', value: 'x'.repeat(40) }))
+    }
+    // A Remote stream opened afterwards on the same socket shows the flood was processed and harmed nothing.
+    sendOpen(socket, 'after', 'feed/sync', { label: 'after' })
+    await vi.waitFor(() => { expect(frames).toContainEqual({ type: 'end', streamId: 'after' }) })
+    expect(frames.filter(frame => frame.streamId === 'events').map(frame => frame.type)).toEqual(['item'])
+    socket.close()
+    await once(socket, 'close')
+  })
+
   it('carries the registered Remote event source and withdraws its active stream', async () => {
     const { ctx } = await setup(true)
     let sourceSignal: AbortSignal | undefined
@@ -603,6 +1017,8 @@ describe('Typert Remote streams', () => {
 
   it('retries a colliding Remote event Client id before opening the second generation', async () => {
     const { ctx } = await setup(true)
+    // Connection minted the operator Peer id above; only the event Client ids are counted below.
+    randomUuid.mockClear()
     const source = new RemoteEventSourceProbe()
     const unregister = ctx.typertGateway.registerRemoteEvents(source.source, REMOTE_HOST)
     const firstId = '00000000-0000-4000-8000-000000000011' as ReturnType<typeof randomUUID>
@@ -956,6 +1372,7 @@ function descriptors(): InvocationDescriptor[] {
     source: 'json' as const,
     codec: { mode: 'strict' as const, typeSymbol: '@fixture/feed#Label', create: () => z.string() },
   }
+  const prefix = { ...label, name: 'prefix', wire: 'prefix' }
   const stream = (method: string, parameters: InvocationDescriptor['parameters'], schema: z.ZodType): InvocationDescriptor => ({
     id: `@fixture/feed#feed/${method}`,
     service: 'feed',
@@ -966,7 +1383,20 @@ function descriptors(): InvocationDescriptor[] {
     parameters,
     result: { mode: 'strict', typeSymbol: '@fixture/feed#Item', create: () => schema },
   })
+  const withUplink = (method: string, parameters: InvocationDescriptor['parameters'], cancellable = true): InvocationDescriptor => ({
+    ...stream(method, parameters, z.string()),
+    uplink: { codec: { mode: 'strict', typeSymbol: '@fixture/feed#Item', create: () => z.string() } },
+    ...(cancellable ? { cancellation: { parameter: 'signal' } } : {}),
+  })
   return [
+    withUplink('echo', [prefix]),
+    withUplink('swallow', []),
+    withUplink('ignore', [prefix], false),
+    withUplink('hold', []),
+    withUplink('peek', []),
+    withUplink('drain', [], false),
+    withUplink('rereads', [], false),
+    stream('context', [label], z.string()),
     { ...stream('follow', [label], z.string()), cancellation: { parameter: 'signal' } },
     stream('sync', [label], z.string()),
     stream('invalid', [], z.string()),
@@ -984,6 +1414,15 @@ function descriptors(): InvocationDescriptor[] {
       parameters: [label],
       result: { mode: 'strict', typeSymbol: '@fixture/feed#Item', create: () => z.string() },
     },
+    {
+      id: '@fixture/feed#feed/unaryUplink',
+      service: 'feed',
+      namespace: 'feed',
+      method: 'unaryUplink',
+      invocation: { kind: 'direct' },
+      parameters: [],
+      result: { mode: 'strict', typeSymbol: '@fixture/feed#Items', create: () => z.array(z.string()) },
+    },
   ]
 }
 
@@ -1089,3 +1528,18 @@ async function collect(source: AsyncIterable<unknown>): Promise<unknown[]> {
   for await (const value of source) values.push(value)
   return values
 }
+
+async function *toAsync<T>(values: readonly T[]): AsyncIterable<T> {
+  for (const value of values) yield value
+}
+
+function neverYielding(): AsyncIterable<string> {
+  return { [Symbol.asyncIterator]: () => ({ next: () => new Promise<IteratorResult<string>>(() => {}) }) }
+}
+
+function abortOf(signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) resolve()
+    else signal.addEventListener('abort', () => { resolve() }, { once: true })
+  })
+}
diff --git a/packages/api/gateway/tests/gateway.client.spec.ts b/packages/api/gateway/tests/gateway.client.spec.ts
index 1a1102e5b5..aeec14ecf1 100644
--- a/packages/api/gateway/tests/gateway.client.spec.ts
+++ b/packages/api/gateway/tests/gateway.client.spec.ts
@@ -14,6 +14,7 @@ import {
 import type {
   InvocationDescriptor,
   RemoteResult,
+  RemoteStreamHandle,
   TypertContextMap,
   TypertContextWire,
   TypertContext,
@@ -23,11 +24,13 @@ import type {
 } from '@deepseek-ai/dsh-typert-protocol'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import type { ClientRemote } from '../src/client/index.ts'
-import { apply, inject, RemoteStream } from '../src/client/index.ts'
+import { apply, inject, isRemoteFailure, RemoteStream } from '../src/client/index.ts'
 import {
+  ClientUplinkQueue,
   RemoteStreamCarrierError,
   RemoteStreamMuxClient,
 } from '../src/client/stream-client.ts'
+import { parseRemoteStreamClientMessage } from '../src/stream-protocol.ts'
 
 type FixtureApprovalOutcome = 'allowed' | 'unavailable'
 const fixtureContextTag = Symbol('fixture-context-tag')
@@ -92,7 +95,9 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
       signal?: AbortSignal,
     ) => Promise<RemoteResult<{ readonly ref: string }>>
     'probe/maybe': (value: string | null | undefined) => Promise<RemoteResult<string | null | undefined>>
+    'probe/bytes': (signal?: AbortSignal) => Promise<RemoteResult<{ readonly data: Uint8Array<ArrayBuffer>; readonly offset: number }>>
     'probe/watch': (topic: string, signal?: AbortSignal) => AsyncIterable<string>
+    'probe/attach': (topic: string, signal?: AbortSignal) => RemoteStreamHandle<string, string>
   }
 
   interface TypertRemoteScopeMap {
@@ -224,6 +229,28 @@ function streamDescriptor(): InvocationDescriptor {
   }
 }
 
+function attachDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/probe#probe/attach',
+    service: 'probe',
+    namespace: 'probe',
+    method: 'attach',
+    mode: 'stream',
+    invocation: { kind: 'direct' },
+    parameters: [{
+      name: 'topic',
+      wire: 'topic',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#Topic', create: () => z.string().min(1) },
+    }],
+    uplink: {
+      codec: { mode: 'strict', typeSymbol: '@fixture#AttachInput', create: () => z.string() },
+    },
+    cancellation: { parameter: 'signal' },
+    result: { mode: 'strict', typeSymbol: '@fixture#AttachItem', create: () => z.string().min(1) },
+  }
+}
+
 type WebSocketGlobal = { WebSocket?: typeof WebSocket }
 
 class FakeWebSocket extends EventTarget {
@@ -2226,20 +2253,6 @@ describe('Client Typert API', () => {
   it('guards stream iteration across mount and Connection withdrawal', async () => {
     const call = vi.fn<ConnectionHandle['rpc']['call']>()
     const ctx = await bench(call)
-    const firstDispose = await ctx.remote.$mount({
-      package: '@fixture/stream-first', descriptors: [streamDescriptor()],
-    })
-    const withdrawn = ctx.remote.probe.watch('withdrawn')[Symbol.asyncIterator]()
-    await firstDispose()
-    await expect(withdrawn.next()).rejects.toThrow('Remote method probe/watch is no longer mounted')
-
-    const secondDispose = await ctx.remote.$mount({
-      package: '@fixture/stream-second', descriptors: [streamDescriptor()],
-    })
-    ctx.set('connection', undefined)
-    await expect(ctx.remote.probe.watch('offline')[Symbol.asyncIterator]().next())
-      .rejects.toThrow('probe/watch has no active Connection')
-
     let release!: () => void
     const released = new Promise<void>((resolve) => { release = resolve })
     let markStarted!: () => void
@@ -2252,12 +2265,26 @@ describe('Client Typert API', () => {
     ctx.set('connection', {
       rpc: { call, open: () => source() },
     } as unknown as ConnectionHandle)
+    const firstDispose = await ctx.remote.$mount({
+      package: '@fixture/stream-first', descriptors: [streamDescriptor()],
+    })
+    // The handle opens its stream when the method is called; the mount is withdrawn before the first item arrives.
     const active = ctx.remote.probe.watch('active')[Symbol.asyncIterator]()
     const pending = active.next()
     await started
-    await secondDispose()
+    await firstDispose()
     release()
     await expect(pending).rejects.toThrow('Remote method probe/watch is no longer mounted')
+
+    const secondDispose = await ctx.remote.$mount({
+      package: '@fixture/stream-second', descriptors: [streamDescriptor()],
+    })
+    ctx.set('connection', undefined)
+    expect(() => ctx.remote.probe.watch('offline')).toThrow('probe/watch has no active Connection')
+    // A method function read before the withdrawal keeps its mount token and refuses afterwards.
+    const retained = ctx.remote.probe.watch
+    await secondDispose()
+    expect(() => retained('withdrawn')).toThrow('Remote method probe/watch is no longer mounted')
   })
 
   it('publishes a namespace only after every contributed method is installed', async () => {
@@ -2416,6 +2443,364 @@ describe('Client Typert API', () => {
       else Object.defineProperty(globalThis, 'document', documentDescriptor)
     }
   })
+
+  it('hands the handle uplink to the in-process carrier and echoes it through remote-mock', async () => {
+    const mock = RemoteMock.create().stream('probe/attach', async (args, stream) => {
+      const [{ topic }] = args as [{ readonly topic: string }]
+      for await (const item of stream.uplink) stream.push(`${topic}:${String(item)}`)
+      stream.end()
+    })
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+    const { ctx, client } = await benchFiber(call, 'in-process', mock.rpc.open)
+    await expect(ctx.remote.$mount({
+      package: '@fixture/weak-uplink',
+      descriptors: [{ ...attachDescriptor(), uplink: { codec: { mode: 'src-json' } } }],
+    })).rejects.toThrow('client api: generated Remote probe/attach field "uplink" has no strict codec')
+    const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+    try {
+      const alpha = ctx.remote.probe.attach('alpha')
+      alpha.send('a')
+      alpha.send('b')
+      alpha.end()
+      alpha.end()
+      await expect(drainStream(alpha)).resolves.toEqual(['alpha:a', 'alpha:b'])
+      expect(() => { alpha.send('late') }).toThrow('client api: probe/attach stream has terminated')
+      const beta = ctx.remote.probe.attach('beta', new AbortController().signal)
+      beta.send('c')
+      expect(() => { beta.end(); beta.send('d') }).toThrow('client api: probe/attach uplink was ended')
+      await expect(drainStream(beta)).resolves.toEqual(['beta:c'])
+      expect(mock.log.streams('probe/attach').map(open => open.args)).toEqual([[{ topic: 'alpha' }], [{ topic: 'beta' }]])
+
+      // Arity is a runtime contract, so the topic is deliberately omitted through Reflect.
+      expect(() => { Reflect.apply(ctx.remote.probe.attach, ctx.remote.probe, []) }).toThrow(
+        'client api: probe/attach expected 1 business argument(s) plus an optional AbortSignal, got 0',
+      )
+      expect(call).not.toHaveBeenCalled()
+    } finally {
+      await dispose()
+      await client.dispose()
+    }
+  })
+
+  it('sends handle uplink items as wire frames, queued until the open frame, and half-closes on end', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle = ctx.remote.probe.attach('alpha')
+        handle.send('a')
+        handle.send('b')
+        handle.end()
+        const stream = handle[Symbol.asyncIterator]()
+        const first = stream.next()
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(4) })
+        const frames = socket.sent.map(text => parseRemoteStreamClientMessage(text))
+        const opened = frames[0]
+        if (opened?.type !== 'open') throw new Error('fixture expected the open frame first')
+        expect(opened).toMatchObject({ endpoint: 'probe/attach', payload: { args: { topic: 'alpha' } } })
+        expect(frames.slice(1)).toEqual([
+          { type: 'item', streamId: opened.streamId, value: 'a' },
+          { type: 'item', streamId: opened.streamId, value: 'b' },
+          { type: 'end', streamId: opened.streamId },
+        ])
+
+        socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:a' })
+        await expect(first).resolves.toEqual({ done: false, value: 'alpha:a' })
+        const ended = stream.next()
+        socket.receive({ type: 'end', streamId: opened.streamId })
+        await expect(ended).resolves.toEqual({ done: true, value: undefined })
+        expect(socket.sent).toHaveLength(4)
+        expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated')
+        handle.end()
+        expect(socket.sent).toHaveLength(4)
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('terminates the handle uplink when the downlink ends first', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle = ctx.remote.probe.attach('alpha')
+        const stream = handle[Symbol.asyncIterator]()
+        const pending = stream.next()
+        handle.send('first')
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) })
+        const opened = JSON.parse(socket.sent[0]!) as { streamId: string }
+        socket.receive({ type: 'end', streamId: opened.streamId })
+        await expect(pending).resolves.toEqual({ done: true, value: undefined })
+        expect(() => { handle.send('second') }).toThrow('client api: probe/attach stream has terminated')
+        expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item'])
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('sends cancel and ends the downlink quietly when the handle is disposed', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle = ctx.remote.probe.attach('alpha')
+        const pending = handle[Symbol.asyncIterator]().next()
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) })
+        handle.dispose()
+        handle.dispose()
+        await expect(pending).resolves.toEqual({ done: true, value: undefined })
+        expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel'])
+        expect(() => { handle.send('after dispose') }).toThrow('client api: probe/attach stream has terminated')
+
+        // Breaking out of the iteration early is the same as dispose().
+        const second = ctx.remote.probe.attach('beta')
+        const iterator = second[Symbol.asyncIterator]()
+        const opened = iterator.next()
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(3) })
+        const betaId = (JSON.parse(socket.sent[2]!) as { streamId: string }).streamId
+        socket.receive({ type: 'item', streamId: betaId, value: 'beta:1' })
+        await expect(opened).resolves.toEqual({ done: false, value: 'beta:1' })
+        await expect(iterator.return?.()).resolves.toEqual({ done: true, value: undefined })
+        expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type))
+          .toEqual(['open', 'cancel', 'open', 'cancel'])
+        expect(() => { second.send('late') }).toThrow('client api: probe/attach stream has terminated')
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('sends cancel on dispose while nobody reads, and drops what was buffered', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle = ctx.remote.probe.attach('alpha')
+        const iterator = handle[Symbol.asyncIterator]()
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) })
+        const opened = JSON.parse(socket.sent[0]!) as { streamId: string }
+        socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:1' })
+        await expect(iterator.next()).resolves.toEqual({ done: false, value: 'alpha:1' })
+        // No read is pending: the cancel still goes out on dispose, and the buffered item is dropped.
+        socket.receive({ type: 'item', streamId: opened.streamId, value: 'alpha:2' })
+        handle.dispose()
+        await vi.waitFor(() => {
+          expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel'])
+        })
+        await expect(iterator.next()).resolves.toEqual({ done: true, value: undefined })
+        expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated')
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('ends the uplink the moment a terminal frame arrives, before the consumer reads it', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle = ctx.remote.probe.attach('alpha')
+        handle.send('a')
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) })
+        const opened = JSON.parse(socket.sent[0]!) as { streamId: string }
+        socket.receive({ type: 'end', streamId: opened.streamId })
+        expect(() => { handle.send('after end') }).toThrow('client api: probe/attach stream has terminated')
+        handle.end()
+        await expect(drainStream(handle)).resolves.toEqual([])
+        expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item'])
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('ignores server frames for a stream it no longer tracks', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const alpha = ctx.remote.probe.attach('alpha')
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) })
+        const alphaId = (JSON.parse(socket.sent[0]!) as { streamId: string }).streamId
+        const beta = ctx.remote.probe.attach('beta')
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) })
+        const betaId = (JSON.parse(socket.sent[1]!) as { streamId: string }).streamId
+        alpha.dispose()
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(3) })
+        // The Host's end for alpha crosses the cancel on the wire, so no stream owns that id any more; a
+        // never-opened id is just as unknown. Neither frame disturbs beta or the socket.
+        socket.receive({ type: 'end', streamId: alphaId })
+        socket.receive({ type: 'item', streamId: 'never-opened', value: 'stray' })
+        socket.receive({ type: 'item', streamId: betaId, value: 'beta:1' })
+        socket.receive({ type: 'end', streamId: betaId })
+        await expect(drainStream(beta)).resolves.toEqual(['beta:1'])
+        expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'open', 'cancel'])
+        expect(socket.closedWith).toEqual([])
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('swallows a carrier iterator whose return() rejects on dispose', async () => {
+    // One item, then silence: dispose reaches the carrier's return() while the stream is suspended at that item.
+    const next = vi.fn<() => Promise<IteratorResult<unknown>>>()
+      .mockResolvedValueOnce({ value: 'alpha:1', done: false })
+      .mockReturnValue(new Promise<IteratorResult<unknown>>(() => {}))
+    const returned = vi.fn<() => Promise<IteratorResult<unknown>>>()
+      .mockRejectedValueOnce(new Error('carrier return failed'))
+      .mockResolvedValue({ value: undefined, done: true })
+    const open: NonNullable<ConnectionHandle['rpc']['open']> = () => ({
+      [Symbol.asyncIterator]: () => ({ next, return: returned }),
+    })
+    const { ctx, client } = await benchFiber(vi.fn<ConnectionHandle['rpc']['call']>(), 'in-process', open)
+    const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+    try {
+      const handle = ctx.remote.probe.attach('alpha')
+      const iterator = handle[Symbol.asyncIterator]()
+      await expect(iterator.next()).resolves.toEqual({ done: false, value: 'alpha:1' })
+      handle.dispose()
+      await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() })
+      // The rejection is swallowed (an unhandled rejection would fail this test) and the iteration ends quietly.
+      await expect(iterator.next()).resolves.toEqual({ done: true, value: undefined })
+    } finally {
+      await dispose()
+      await client.dispose()
+    }
+  })
+
+  it('sends a top-level undefined item as an item frame without value', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle: RemoteStreamHandle<string, unknown> = ctx.remote.probe.attach('alpha')
+        handle.send(undefined)
+        expect(() => { handle.send({ nested: undefined }) }).toThrow('is not a lossless JSON value')
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(2) })
+        const opened = JSON.parse(socket.sent[0]!) as { streamId: string }
+        const item = JSON.parse(socket.sent[1]!) as Record<string, unknown>
+        expect(item).toEqual({ type: 'item', streamId: opened.streamId })
+        expect(Object.keys(item)).toEqual(['type', 'streamId'])
+        handle.dispose()
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('disposes on an iterator return that precedes the first read', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const handle = ctx.remote.probe.attach('alpha')
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) })
+        await expect(handle[Symbol.asyncIterator]().return?.()).resolves.toEqual({ done: true, value: undefined })
+        await vi.waitFor(() => {
+          expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel'])
+        })
+        expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated')
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
+
+  it('closes the uplink when the stream fails to open and keeps the failure for the reader', async () => {
+    const open: NonNullable<ConnectionHandle['rpc']['open']> = () => ({
+      [Symbol.asyncIterator]: () => ({ next: () => Promise.reject(new Error('handshake failed')) }),
+    })
+    const { ctx, client } = await benchFiber(vi.fn<ConnectionHandle['rpc']['call']>(), 'in-process', open)
+    const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+    try {
+      const handle = ctx.remote.probe.attach('alpha')
+      await vi.waitFor(() => {
+        expect(() => { handle.send('late') }).toThrow('client api: probe/attach stream has terminated')
+      })
+      await expect(drainStream(handle)).rejects.toThrow('handshake failed')
+    } finally {
+      await dispose()
+      await client.dispose()
+    }
+  })
+
+  it('refuses an uplink item that is not a lossless JSON value', async () => {
+    const mock = RemoteMock.create().stream('probe/attach', async (args, stream) => {
+      const [{ topic }] = args as [{ readonly topic: string }]
+      for await (const item of stream.uplink) stream.push(`${topic}:${String(item)}`)
+      stream.end()
+    })
+    const { ctx, client } = await benchFiber(vi.fn<ConnectionHandle['rpc']['call']>(), 'in-process', mock.rpc.open)
+    const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+    try {
+      // Widened to the loosest caller `send` accepts: the check is on the value, not on the generated type.
+      const handle: RemoteStreamHandle<string, unknown> = ctx.remote.probe.attach('alpha')
+      expect(() => { handle.send(1n) }).toThrow('client api: probe/attach uplink item is not a lossless JSON value')
+      expect(() => { handle.send(Number.NaN) }).toThrow('is not a lossless JSON value')
+      handle.send('ok')
+      handle.end()
+      await expect(drainStream(handle)).resolves.toEqual(['alpha:ok'])
+    } finally {
+      await dispose()
+      await client.dispose()
+    }
+  })
+
+  it('lets one uplink read wait at a time', async () => {
+    const queue = new ClientUplinkQueue('probe/attach')
+    const first = queue.next()
+    await expect(queue.next()).rejects.toThrow('client api: probe/attach uplink has one pending read')
+    queue.push('x')
+    await expect(first).resolves.toEqual({ value: 'x', done: false })
+    queue.end()
+    await expect(queue.next()).resolves.toEqual({ value: undefined, done: true })
+    expect(() => { queue.push('late') }).toThrow('client api: probe/attach uplink was ended')
+    await expect(queue.return()).resolves.toEqual({ value: undefined, done: true })
+    expect(() => { queue.push('closed') }).toThrow('client api: probe/attach stream has terminated')
+  })
+
+  it('sends cancel and fails the downlink when the caller signal aborts', async () => {
+    await withFakeWebSocket('https://harness.example/', async () => {
+      const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>(), 'web')
+      const dispose = await ctx.remote.$mount({ package: '@fixture/attach', descriptors: [attachDescriptor()] })
+      try {
+        const abort = new AbortController()
+        const handle = ctx.remote.probe.attach('alpha', abort.signal)
+        const pending = handle[Symbol.asyncIterator]().next()
+        const socket = FakeWebSocket.sockets[0]!
+        await vi.waitFor(() => { expect(socket.sent).toHaveLength(1) })
+        const reason = new Error('caller left')
+        abort.abort(reason)
+        await expect(pending).rejects.toBe(reason)
+        expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'cancel'])
+        expect(() => { handle.send('after abort') }).toThrow('client api: probe/attach stream has terminated')
+        expect(() => handle[Symbol.asyncIterator]().next()).toThrow('client api: probe/attach stream has one consumer')
+      } finally {
+        await dispose()
+        await ctx.fiber.dispose()
+      }
+    })
+  })
 })
 
 describe('Remote stream client carrier lifecycle', () => {
@@ -2433,6 +2818,40 @@ describe('Remote stream client carrier lifecycle', () => {
     })
   })
 
+  it('fails the downlink and cancels when an uplink iterable throws, and swallows a rejecting uplink return()', async () => {
+    await withFakeWebSocket('https://harness.example', async () => {
+      const client = new RemoteStreamMuxClient()
+      client.start()
+      const socket = FakeWebSocket.sockets[0]!
+      const exploding = (async function* (): AsyncGenerator<string> {
+        yield 'a'
+        throw new Error('uplink exploded')
+      })()
+      const pending = client.open('probe/attach', {}, new AbortController().signal, exploding)[Symbol.asyncIterator]().next()
+      await expect(pending).rejects.toThrow('uplink exploded')
+      expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item', 'cancel'])
+
+      const returned = vi.fn(async (): Promise<IteratorResult<string>> => {
+        throw new Error('fixture release failure')
+      })
+      const stuck: AsyncIterable<string> = {
+        [Symbol.asyncIterator]: () => ({
+          next: () => new Promise<IteratorResult<string>>(() => {}),
+          return: returned,
+        }),
+      }
+      const abort = new AbortController()
+      const second = client.open('probe/attach', {}, abort.signal, stuck)[Symbol.asyncIterator]().next()
+      await vi.waitFor(() => { expect(socket.sent).toHaveLength(4) })
+      const reason = new Error('caller left')
+      abort.abort(reason)
+      await expect(second).rejects.toBe(reason)
+      await vi.waitFor(() => { expect(returned).toHaveBeenCalledOnce() })
+      expect(socket.sent.map(text => (JSON.parse(text) as { type: string }).type)).toEqual(['open', 'item', 'cancel', 'open', 'cancel'])
+      await client.close()
+    })
+  })
+
   it('requires the transport owner to start the physical carrier', async () => {
     const client = new RemoteStreamMuxClient()
     await expect(client.open('feed/follow', {}, new AbortController().signal)
@@ -2737,3 +3156,99 @@ async function withFakeWebSocket(
     else Object.defineProperty(globalThis, 'location', locationDescriptor)
   }
 }
+
+describe('Remote result decoders', () => {
+  const schema = z.object({ data: z.instanceof(Uint8Array), offset: z.number() })
+  const descriptor: InvocationDescriptor = {
+    id: '@fixture/probe#probe/bytes',
+    service: 'probe', namespace: 'probe', method: 'bytes',
+    invocation: { kind: 'direct' }, parameters: [],
+    cancellation: { parameter: 'signal' },
+    result: {
+      mode: 'strict', typeSymbol: '@fixture#Bytes',
+      create: () => schema,
+      decode: value => schema.parse(value),
+    },
+  }
+
+  it('validates metadata without copying or freezing native data on a logical RPC carrier', async () => {
+    const data = new Uint8Array([0, 128, 255])
+    const call = vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: true, value: { data, offset: 2 } })
+    const { ctx, client } = await benchFiber(call)
+    try {
+      await ctx.remote.$mount({ package: '@fixture/binary', descriptors: [descriptor] })
+      const result = await ctx.remote.probe.bytes()
+      expect(result).toEqual({ ok: true, value: { data, offset: 2 } })
+      if (result.ok) expect(result.value.data).toBe(data)
+      expect(Object.isFrozen(data)).toBe(false)
+      for (const value of [{ data: 'base64', offset: 2 }, { data: [0, 128], offset: 2 }, { data, offset: '2' }]) {
+        call.mockResolvedValueOnce({ ok: true, value })
+        const failure = await ctx.remote.probe.bytes()
+        expect(failure).toMatchObject({ ok: false, error: { code: 'gateway/internal' } })
+        if (!failure.ok) expect(isRemoteFailure(failure.error)).toBe(true)
+      }
+    } finally {
+      await client.dispose()
+    }
+  })
+
+  it('delegates nested fields to the result decoder and leaves JSON results untouched', async () => {
+    const data = new Uint8Array([0, 128, 255])
+    const value = { files: [{ content: data }], thumbnail: data }
+    const call = vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: true, value })
+    const decode = vi.fn((input: unknown) => z.object({
+      files: z.array(z.object({ content: z.instanceof(Uint8Array) })),
+      thumbnail: z.instanceof(Uint8Array),
+    }).parse(input))
+    const { ctx, client } = await benchFiber(call)
+    try {
+      const dispose = await ctx.remote.$mount({
+        package: '@fixture/binary', descriptors: [{
+          ...descriptor, result: { mode: 'strict', typeSymbol: '@fixture#Files', create: () => schema, decode },
+        }],
+      })
+      expect(await ctx.remote.probe.bytes()).toEqual({ ok: true, value })
+      expect(decode).toHaveBeenCalledWith(value)
+      expect((decode.mock.results[0]?.value as ReturnType<typeof decode>).files[0]?.content).toBe(data)
+      expect(Object.isFrozen(data)).toBe(false)
+      await dispose()
+      const json = { base64: 'AP8=', items: [1, 2] }
+      call.mockResolvedValue({ ok: true, value: json })
+      const create = vi.fn(() => schema)
+      await ctx.remote.$mount({ package: '@fixture/json', descriptors: [{
+        ...descriptor, result: { mode: 'strict', typeSymbol: '@fixture#Json', create },
+      }] })
+      const result = await ctx.remote.probe.bytes()
+      if (result.ok) expect(result.value).toBe(json)
+      expect(create).not.toHaveBeenCalled()
+    } finally {
+      await client.dispose()
+    }
+  })
+
+  it.each(['cancel', 'withdraw'] as const)('discards late binary results after %s', async (action) => {
+    const response = Promise.withResolvers<Awaited<ReturnType<ConnectionHandle['rpc']['call']>>>()
+    const call = vi.fn<ConnectionHandle['rpc']['call']>().mockReturnValue(response.promise)
+    const { ctx, client } = await benchFiber(call)
+    try {
+      const dispose = await ctx.remote.$mount({ package: '@fixture/binary', descriptors: [descriptor] })
+      const abort = new AbortController()
+      const pending = ctx.remote.probe.bytes(abort.signal)
+      expect(call).toHaveBeenCalledOnce()
+      if (action === 'cancel') abort.abort()
+      else await dispose()
+      response.resolve({ ok: true, value: { data: new Uint8Array([7]), offset: 0 } })
+      expect(await pending).toMatchObject({
+        ok: false, error: { code: action === 'cancel' ? 'gateway/cancelled' : 'gateway/internal' },
+      })
+    } finally {
+      await client.dispose()
+    }
+  })
+})
+
+async function drainStream(source: AsyncIterable<unknown>): Promise<unknown[]> {
+  const values: unknown[] = []
+  for await (const value of source) values.push(value)
+  return values
+}
diff --git a/packages/api/gateway/tests/gateway.host.spec.ts b/packages/api/gateway/tests/gateway.host.spec.ts
index d88de09fc3..24522ce846 100644
--- a/packages/api/gateway/tests/gateway.host.spec.ts
+++ b/packages/api/gateway/tests/gateway.host.spec.ts
@@ -4,7 +4,12 @@ import { describe, expect, it } from 'vitest'
 import { Context, Service, symbols } from '@deepseek-ai/cordis'
 import { z } from 'zod'
 import { apply as applyConnection, inject as connectionInject } from '@deepseek-ai/dsh-client-connection'
-import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection'
+import type {
+  ConnectionRpcHandler,
+  HostConnectionHandle,
+  PeerId,
+  PeerScope,
+} from '@deepseek-ai/dsh-client-connection'
 import type { WebServer, WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import {
   bindTypertRemote,
@@ -53,6 +58,7 @@ class GoalService extends Service {
   readonly typertRemote = bindTypertRemote(this, 'goals')
   readonly calls: string[] = []
   lastSignal: AbortSignal | undefined
+  lastPeer: PeerScope | undefined
   nextResult: unknown = undefined
   businessError: Error | undefined
 
@@ -64,6 +70,7 @@ class GoalService extends Service {
   create(agent: FixtureAgent, request: { readonly title: string }, signal: AbortSignal): unknown {
     this.calls.push('create')
     this.lastSignal = signal
+    this.lastPeer = this.ctx.invocation?.peer
     return {
       agentId: agent.id,
       title: request.title,
@@ -102,19 +109,19 @@ class GoalService extends Service {
   }
 }
 
-type FakeRpcResult =
-  | { readonly ok: true; readonly value: unknown }
-  | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly details: object } }
-
+type FakeRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>
 type FakeRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<FakeRpcResult>
 
 class FakeConnectionService extends Service {
   channel: string | undefined
   matches: ((endpoint: string) => boolean) | undefined
   handler: FakeRpcHandler | undefined
+  /** The operator Peer every call this fake dispatches speaks for. */
+  readonly operator: PeerScope
 
   constructor(ctx: Context) {
     super(ctx, 'connection')
+    this.operator = { id: 'fake-operator' as PeerId, ctx, dispose: () => Promise.resolve() }
   }
 
   get rpc() {
@@ -123,12 +130,12 @@ class FakeConnectionService extends Service {
       intercept: (
         channel: string,
         matches: (endpoint: string) => boolean,
-        handler: FakeRpcHandler,
+        handler: ConnectionRpcHandler,
       ) =>
         owner.effect(() => {
           this.channel = channel
           this.matches = matches
-          this.handler = handler
+          this.handler = (endpoint, payload, signal) => handler(endpoint, payload, signal, this.operator)
           return () => {
             this.channel = undefined
             this.matches = undefined
@@ -993,16 +1000,25 @@ describe('TypertGatewayService', () => {
     const signal = abort.signal
     const handler = connection.handler
     if (handler === undefined) throw new Error('fixture Connection did not retain the /api interceptor')
-    await expect(handler('goals/create', {
+    const success = await handler('goals/create', {
       args: { agentId: 'agent-1', request: { title: 'ship' } },
-    }, signal)).resolves.toEqual({
+    }, signal)
+    expect(success).toMatchObject({
       ok: true,
       value: { agentId: 'agent-1', title: 'ship', scope: 'rpc-caller' },
     })
+    if (!success.ok) throw new Error('fixture Remote failed')
+    expect(success.attachments).toBeUndefined()
     const service = rawGoalService(ctx)
     expect(service.lastSignal).toBe(signal)
     abort.abort(new Error('client disconnected'))
     expect(service.lastSignal?.aborted).toBe(true)
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'direct' } },
+    })).resolves.toMatchObject({ title: 'direct' })
+    expect(service.lastPeer).toBe(connection.operator)
     const invalid = await handler('goals/create', { invalid: true }, signal)
     expect(invalid).toMatchObject({
       ok: false,
@@ -1011,11 +1027,11 @@ describe('TypertGatewayService', () => {
     if (invalid.ok) throw new Error('invalid Remote payload unexpectedly succeeded')
     expect(invalid.error.message).toMatch(/exactly one plain-object args field/)
 
-    await expect(handler('goals/maybe', { args: {} }, signal)).resolves.toEqual({
+    await expect(handler('goals/maybe', { args: {} }, signal)).resolves.toMatchObject({
       ok: true,
       value: undefined,
     })
-    await expect(handler('goals/maybe', { args: { value: null } }, signal)).resolves.toEqual({
+    await expect(handler('goals/maybe', { args: { value: null } }, signal)).resolves.toMatchObject({
       ok: true,
       value: null,
     })
@@ -1065,6 +1081,112 @@ describe('TypertGatewayService', () => {
     expect(connection.handler).toBeUndefined()
   })
 
+  it('projects strict and SRC result bytes before returning to Connection', async () => {
+    const { ctx } = await setup()
+    const fiber = ctx.plugin(FakeConnectionService)
+    await fiber
+    try {
+      const value = { content: new Uint8Array([0, 128, 255]) }
+      rawGoalService(ctx).nextResult = value
+      const handler = rawConnection(ctx).handler!
+      const source = await handler('goals/passthrough', { args: { value: null } }, new AbortController().signal)
+      expect(source).toEqual({
+        ok: true,
+        value: { content: null },
+        attachments: [{ path: ['content'], bytes: value.content }],
+      })
+      const descriptor = passthroughDescriptor()
+      const codec = {
+        mode: 'strict' as const,
+        typeSymbol: '@fixture/gateway#Bytes',
+        create: () => z.object({ content: z.instanceof(Uint8Array) }),
+        encode: (input: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => {
+          const result = input as { readonly content: Uint8Array }
+          return { content: writeBytes(result.content, ['content']) }
+        },
+      }
+      const remove = registerStrict(ctx, [{ ...descriptor, result: codec }])
+      const strict = await handler('goals/passthrough', { args: { value: null } }, new AbortController().signal)
+      expect(strict).toEqual({
+        ok: true,
+        value: { content: null },
+        attachments: [{ path: ['content'], bytes: value.content }],
+      })
+      await remove()
+    } finally {
+      await fiber.dispose()
+    }
+  })
+
+  it('owns runtime result projection for SRC methods', async () => {
+    const { ctx, service } = await setup()
+    const fiber = ctx.plugin(FakeConnectionService)
+    await fiber
+    try {
+      const handler = rawConnection(ctx).handler!
+      const call = () => handler('goals/passthrough', { args: { value: null } }, new AbortController().signal)
+      let reads = 0
+      const bytes = new Uint8Array([1, 2])
+      service.nextResult = { get content() { reads++; return bytes }, get count() { return ++reads } }
+      await expect(call()).resolves.toEqual({
+        ok: true,
+        value: { content: null, count: 2 },
+        attachments: [{ path: ['content'], bytes }],
+      })
+      expect(reads).toBe(2)
+
+      const array: Uint8Array[] = []
+      Object.defineProperty(array, 0, { value: bytes })
+      service.nextResult = array
+      await expect(call()).resolves.toEqual({
+        ok: true,
+        value: [null],
+        attachments: [{ path: [0], bytes }],
+      })
+
+      service.nextResult = Object.assign(new Date('2026-01-01T00:00:00Z'), { content: bytes })
+      await expect(call()).resolves.toEqual({ ok: true, value: '2026-01-01T00:00:00.000Z' })
+      const json = { self: {} as object, toJSON: () => ({ selected: true }) }
+      json.self = json
+      service.nextResult = json
+      await expect(call()).resolves.toEqual({ ok: true, value: { selected: true } })
+      let conversions = 0
+      service.nextResult = { toJSON(key: string) { conversions++; expect(key).toBe('value'); return this }, count: 5 }
+      await expect(call()).resolves.toEqual({ ok: true, value: { count: 5 } })
+      expect(conversions).toBe(1)
+      for (const primitive of [1, 'text', true]) {
+        service.nextResult = Object(primitive) as object
+        await expect(call()).resolves.toEqual({ ok: true, value: primitive })
+      }
+      service.nextResult = { toJSON: 'ordinary' }
+      await expect(call()).resolves.toEqual({ ok: true, value: service.nextResult })
+
+      const protectedName = JSON.parse('{"__proto__":null}') as Record<string, unknown>
+      Object.defineProperty(protectedName, '__proto__', { value: bytes, enumerable: true })
+      service.nextResult = protectedName
+      const protectedResult = await call()
+      expect(protectedResult).toMatchObject({
+        ok: true,
+        attachments: [{ path: ['__proto__'], bytes }],
+      })
+      if (!protectedResult.ok || typeof protectedResult.value !== 'object' || protectedResult.value === null) {
+        throw new Error('SRC protected-name result was not projected')
+      }
+      expect(Object.hasOwn(protectedResult.value, '__proto__')).toBe(true)
+      expect(Reflect.get(protectedResult.value, '__proto__')).toBeNull()
+
+      const circular: { next?: object } = {}
+      circular.next = circular
+      service.nextResult = circular
+      await expect(call()).resolves.toMatchObject({
+        ok: false,
+        error: { code: 'gateway/internal', message: 'gateway: circular RPC result' },
+      })
+    } finally {
+      await fiber.dispose()
+    }
+  })
+
   it('claims and validates in-process Remote event results for the active Client generation', async () => {
     const ctx = new Context()
     await ctx.plugin(TypertRegistry)
diff --git a/packages/api/gateway/tests/remote-event-protocol.host.spec.ts b/packages/api/gateway/tests/remote-event-protocol.host.spec.ts
index 09259ea43f..87dac480ce 100644
--- a/packages/api/gateway/tests/remote-event-protocol.host.spec.ts
+++ b/packages/api/gateway/tests/remote-event-protocol.host.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
+import { isRemoteJsonValue } from '@deepseek-ai/dsh-typert-protocol'
 import {
-  isRemoteJsonValue,
   parseRemoteEventResult,
   parseRemoteStreamClientMessage,
   projectRemoteEventRequest,
diff --git a/packages/api/gateway/tests/stream-protocol.host.spec.ts b/packages/api/gateway/tests/stream-protocol.host.spec.ts
index f353dce901..c5803e8dd3 100644
--- a/packages/api/gateway/tests/stream-protocol.host.spec.ts
+++ b/packages/api/gateway/tests/stream-protocol.host.spec.ts
@@ -14,6 +14,15 @@ describe('Remote stream wire protocol', () => {
     expect(parseRemoteStreamClientMessage(JSON.stringify({
       type: 'cancel', streamId: 'stream-1',
     }))).toEqual({ type: 'cancel', streamId: 'stream-1' })
+    expect(parseRemoteStreamClientMessage(JSON.stringify({
+      type: 'item', streamId: 'stream-1', value: { line: 'ls\n' },
+    }))).toEqual({ type: 'item', streamId: 'stream-1', value: { line: 'ls\n' } })
+    expect(parseRemoteStreamClientMessage(JSON.stringify({
+      type: 'item', streamId: 'stream-1',
+    }))).toEqual({ type: 'item', streamId: 'stream-1' })
+    expect(parseRemoteStreamClientMessage(JSON.stringify({
+      type: 'end', streamId: 'stream-1',
+    }))).toEqual({ type: 'end', streamId: 'stream-1' })
   })
 
   it.each([
@@ -21,12 +30,22 @@ describe('Remote stream wire protocol', () => {
     { type: 'open', streamId: 'stream-1', endpoint: '', payload: {} },
     { type: 'open', streamId: 'stream-1', endpoint: 'feed/follow' },
     { type: 'cancel', streamId: 'stream-1', extra: true },
+    { type: 'item', streamId: '', value: 'line' },
+    { type: 'item', streamId: 'stream-1', value: 'line', extra: true },
+    { type: 'item', streamId: 'stream-1', endpoint: 'feed/follow' },
+    { type: 'end', streamId: '' },
+    { type: 'end', streamId: 'stream-1', value: 'line' },
     { type: 'unknown', streamId: 'stream-1' },
   ])('rejects an invalid client message: %j', (message) => {
     expect(() => parseRemoteStreamClientMessage(JSON.stringify(message)))
       .toThrow('api gateway: invalid Remote stream client message')
   })
 
+  it('rejects an uplink item whose value is not lossless JSON', () => {
+    expect(() => parseRemoteStreamClientMessage('{"type":"item","streamId":"stream-1","value":-0}'))
+      .toThrow('api gateway: invalid Remote stream client message')
+  })
+
   it('accepts every server message variant', () => {
     expect(parseRemoteStreamServerMessage(JSON.stringify({
       type: 'item', streamId: 'stream-1', value: null,
diff --git a/packages/api/gateway/tests/stream-server.host.spec.ts b/packages/api/gateway/tests/stream-server.host.spec.ts
index bd631619a2..469aa25b0c 100644
--- a/packages/api/gateway/tests/stream-server.host.spec.ts
+++ b/packages/api/gateway/tests/stream-server.host.spec.ts
@@ -1,5 +1,7 @@
 import { once } from 'node:events'
 import { createServer, type Server } from 'node:http'
+import { Context } from '@deepseek-ai/cordis'
+import { remoteErrorOf, type PeerId, type PeerScope } from '@deepseek-ai/dsh-typert-protocol'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import WebSocket from 'ws'
 import {
@@ -26,7 +28,7 @@ afterEach(async () => {
 
 describe('Remote stream mux server carrier lifecycle', () => {
   it('sends WebSocket Ping control frames without application messages', async () => {
-    const entry = await startMux(async (_endpoint, _payload, signal) => waitForAbort(signal), 20)
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => waitForAbort(control.signal), 20)
     const client = await connect(entry.url)
     const serverSocket = acceptedSocket(entry.mux)
     const messages = vi.fn()
@@ -51,7 +53,7 @@ describe('Remote stream mux server carrier lifecycle', () => {
   })
 
   it('requires two missed heartbeats before terminating an unresponsive socket', async () => {
-    const entry = await startMux(async (_endpoint, _payload, signal) => waitForAbort(signal), 20)
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => waitForAbort(control.signal), 20)
     const client = await connect(entry.url)
     const serverSocket = acceptedSocket(entry.mux)
     serverSocket.removeAllListeners('pong')
@@ -66,7 +68,7 @@ describe('Remote stream mux server carrier lifecycle', () => {
   })
 
   it('keeps the socket when a delayed Pong arrives before the final check', async () => {
-    const entry = await startMux(async (_endpoint, _payload, signal) => waitForAbort(signal), 20)
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => waitForAbort(control.signal), 20)
     const client = await connect(entry.url, false)
     const serverSocket = acceptedSocket(entry.mux)
     const terminated = vi.spyOn(serverSocket, 'terminate')
@@ -92,7 +94,7 @@ describe('Remote stream mux server carrier lifecycle', () => {
   })
 
   it('rejects binary, malformed, and duplicate logical-stream messages', async () => {
-    const entry = await startMux(async (_endpoint, _payload, signal) => waitForAbort(signal))
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => waitForAbort(control.signal))
 
     const binary = await connect(entry.url)
     const binaryClosed = once(binary, 'close')
@@ -115,16 +117,16 @@ describe('Remote stream mux server carrier lifecycle', () => {
     expect(duplicateEvent[0]).toBe(1008)
     expect(String(duplicateEvent[1])).toBe('invalid Remote stream request')
 
-    const noInput = await connect(entry.url)
-    noInput.send(openFrame('no-input'))
-    noInput.send(JSON.stringify({ type: 'input', streamId: 'no-input', value: 'unexpected' }))
-    const noInputEvent = await once(noInput, 'close')
-    expect(noInputEvent[0]).toBe(1008)
-    expect(String(noInputEvent[1])).toBe('invalid Remote stream request')
+    const unknownType = await connect(entry.url)
+    unknownType.send(openFrame('unknown-type'))
+    unknownType.send(JSON.stringify({ type: 'input', streamId: 'unknown-type', value: 'unexpected' }))
+    const unknownTypeEvent = await once(unknownType, 'close')
+    expect(unknownTypeEvent[0]).toBe(1008)
+    expect(String(unknownTypeEvent[1])).toBe('invalid Remote stream request')
   })
 
   it('accepts all ws text representations and terminates a carrier error', async () => {
-    const entry = await startMux(async (_endpoint, _payload, signal) => waitForAbort(signal))
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => waitForAbort(control.signal))
     const client = await connect(entry.url)
     const serverSocket = acceptedSocket(entry.mux)
     const cancel = JSON.stringify({ type: 'cancel', streamId: 'absent' })
@@ -142,16 +144,12 @@ describe('Remote stream mux server carrier lifecycle', () => {
     const didOpen = new Promise<void>((resolve) => { opened = resolve })
     let returned!: () => void
     const didReturn = new Promise<void>((resolve) => { returned = resolve })
-    const entry = await startMux(async (_endpoint, _payload, signal) => {
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => {
       opened()
-      return cleanlyCancelled(signal, returned)
+      return cleanlyCancelled(control.signal, returned)
     })
     const client = await connect(entry.url)
-    const frames: unknown[] = []
-    client.on('message', (data) => {
-      if (!Buffer.isBuffer(data)) throw new TypeError('fixture expected a Buffer frame')
-      frames.push(JSON.parse(data.toString('utf8')) as unknown)
-    })
+    const frames = collectFrames(client)
     client.send(openFrame('cancelled'))
     await didOpen
     client.send(JSON.stringify({ type: 'cancel', streamId: 'cancelled' }))
@@ -171,13 +169,7 @@ describe('Remote stream mux server carrier lifecycle', () => {
     const client = await connect(entry.url)
     client.send(openFrame('write-failure'))
     await didOpen
-    const serverSocket = acceptedSocket(entry.mux)
-    const mutable = serverSocket as {
-      send(data: unknown, callback: (error?: Error) => void): void
-    }
-    mutable.send = (_data, callback): void => {
-      callback(new Error('fixture ws write failure'))
-    }
+    failWrites(acceptedSocket(entry.mux))
 
     const closed = once(client, 'close')
     release()
@@ -186,6 +178,43 @@ describe('Remote stream mux server carrier lifecycle', () => {
     expect(String(closeEvent[1])).toBe('Remote stream failure could not be delivered')
   })
 
+  it('closes the carrier when the end frame cannot be written', async () => {
+    const entry = await startMux(async () => (async function *(): AsyncIterable<never> {})())
+    const client = await connect(entry.url)
+    failWrites(acceptedSocket(entry.mux))
+
+    const closed = once(client, 'close')
+    client.send(openFrame('empty'))
+    const closeEvent = await closed
+    expect(closeEvent[0]).toBe(1011)
+    expect(String(closeEvent[1])).toBe('Remote stream failure could not be delivered')
+  })
+
+  it('leaves a failed stream silent once its socket is no longer open', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const entry = await startMux(async () => {
+      opened.resolve(undefined)
+      throw new Error('fixture opener failure')
+    })
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    const serverSocket = acceptedSocket(entry.mux)
+    Object.defineProperty(serverSocket, 'readyState', { configurable: true, value: WebSocket.CLOSING })
+    try {
+      client.send(openFrame('silent'))
+      await opened.promise
+      // The failure path awaits nothing before it inspects the socket, so one
+      // macrotask hop drains every microtask it can schedule.
+      await new Promise<void>((resolve) => { setImmediate(resolve) })
+      expect(frames).toEqual([])
+    } finally {
+      Reflect.deleteProperty(serverSocket, 'readyState')
+    }
+    expect(serverSocket.readyState).toBe(WebSocket.OPEN)
+    client.close()
+    await once(client, 'close')
+  })
+
   it('contains an item produced after its socket closes', async () => {
     let release!: () => void
     const released = new Promise<void>((resolve) => { release = resolve })
@@ -210,9 +239,9 @@ describe('Remote stream mux server carrier lifecycle', () => {
     const didOpen = new Promise<void>((resolve) => { opened = resolve })
     let returned!: () => void
     const didReturn = new Promise<void>((resolve) => { returned = resolve })
-    const entry = await startMux(async (_endpoint, _payload, signal) => {
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => {
       opened()
-      return cleanlyCancelled(signal, returned)
+      return cleanlyCancelled(control.signal, returned)
     })
     const client = await connect(entry.url)
     client.send(openFrame('active'))
@@ -228,16 +257,254 @@ describe('Remote stream mux server carrier lifecycle', () => {
   })
 })
 
-const mapFailure: RemoteStreamFailureMapper = error => ({
-  code: 'internal',
-  message: error instanceof Error ? error.message : String(error),
-  details: {},
+describe('Remote stream mux server Peer binding', () => {
+  it('closes an upgrade at once when the admitted Peer scope is already disposed', async () => {
+    const peer = await fixturePeer()
+    await peer.dispose()
+    const opened = vi.fn()
+    const entry = await startMux(async (_endpoint, _payload, _uplink, _peer, control) => {
+      opened()
+      return waitForAbort(control.signal)
+    }, 2_000, 262_144, peer)
+    const client = new WebSocket(entry.url)
+    const closeEvent = await once(client, 'close')
+    expect(closeEvent[0]).toBe(1001)
+    expect(String(closeEvent[1])).toBe('peer left')
+    expect(opened).not.toHaveBeenCalled()
+  })
+
+  it('hands the admitted Peer to every opener and closes the socket when its scope is disposed', async () => {
+    const peer = await fixturePeer()
+    const seen: PeerScope[] = []
+    const entry = await startMux(async (_endpoint, _payload, _uplink, opened, control) => {
+      seen.push(opened)
+      return waitForAbort(control.signal)
+    }, 2_000, 262_144, peer)
+    const client = await connect(entry.url)
+    client.send(openFrame('bound'))
+    await vi.waitFor(() => { expect(seen).toHaveLength(1) })
+    expect(seen[0]).toBe(peer)
+
+    const closed = once(client, 'close')
+    await peer.dispose()
+    const closeEvent = await closed
+    expect(closeEvent[0]).toBe(1001)
+    expect(String(closeEvent[1])).toBe('peer left')
+  })
 })
 
-async function startMux(open: RemoteStreamOpener, heartbeatIntervalMs = 2_000): Promise<RunningMux> {
-  const mux = new RemoteStreamMuxServer(open, mapFailure, heartbeatIntervalMs)
+describe('Remote stream mux server uplink', () => {
+  it('buffers uplink items sent before the opener resolves and half-closes on end', async () => {
+    const release = Promise.withResolvers<undefined>()
+    const entry = await startMux(async (_endpoint, _payload, uplink) => {
+      await release.promise
+      return echoUplink(uplink)
+    })
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    const received = countMessages(acceptedSocket(entry.mux))
+    client.send(openFrame('echo'))
+    client.send(itemFrame('echo', 'one'))
+    client.send(itemFrame('echo'))
+    await vi.waitFor(() => { expect(received.count).toBe(3) })
+    expect(frames).toEqual([])
+
+    release.resolve(undefined)
+    await vi.waitFor(() => {
+      expect(frames).toEqual([
+        { type: 'item', streamId: 'echo', value: 'one' },
+        { type: 'item', streamId: 'echo' },
+      ])
+    })
+    client.send(endFrame('echo'))
+    await vi.waitFor(() => { expect(frames.at(-1)).toEqual({ type: 'end', streamId: 'echo' }) })
+    expect(frames).toHaveLength(3)
+    client.close()
+    await once(client, 'close')
+  })
+
+  it('fails a stream on an item after end and keeps the socket open', async () => {
+    const entry = await startMux(async (endpoint, _payload, uplink, _peer, control) =>
+      endpoint === 'fixture/echo' ? echoUplink(uplink) : waitForAbort(control.signal))
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    client.send(openFrame('held'))
+    client.send(endFrame('held'))
+    client.send(endFrame('held'))
+    client.send(itemFrame('held', 'late'))
+    await vi.waitFor(() => {
+      expect(frames).toEqual([{
+        type: 'error',
+        streamId: 'held',
+        error: {
+          code: 'gateway/protocol',
+          message: 'api gateway: Remote stream uplink item after end',
+          details: { endpoint: 'fixture/follow' },
+        },
+      }])
+    })
+
+    expect(client.readyState).toBe(WebSocket.OPEN)
+    client.send(openFrame('again', 'fixture/echo'))
+    client.send(itemFrame('again', 'still served'))
+    await vi.waitFor(() => {
+      expect(frames.at(-1)).toEqual({ type: 'item', streamId: 'again', value: 'still served' })
+    })
+    client.close()
+    await once(client, 'close')
+  })
+
+  it('fails a stream whose buffered uplink exceeds the configured bytes and drops later items', async () => {
+    const release = Promise.withResolvers<undefined>()
+    const entry = await startMux(async () => (async function *(): AsyncIterable<never> {
+      await release.promise
+    })(), 2_000, 48)
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    const received = countMessages(acceptedSocket(entry.mux))
+    client.send(openFrame('big'))
+    client.send(itemFrame('big', 'x'.repeat(64)))
+    client.send(itemFrame('big', 'dropped'))
+    client.send(endFrame('big'))
+    await vi.waitFor(() => { expect(received.count).toBe(4) })
+    expect(frames).toEqual([])
+
+    release.resolve(undefined)
+    await vi.waitFor(() => {
+      expect(frames).toEqual([{
+        type: 'error',
+        streamId: 'big',
+        error: {
+          code: 'gateway/uplink-overflow',
+          message: 'api gateway: Remote stream uplink exceeded 48 buffered bytes',
+          details: { endpoint: 'fixture/follow' },
+        },
+      }])
+    })
+    client.close()
+    await once(client, 'close')
+  })
+
+  it('drops uplink frames for a stream it no longer owns and keeps the socket open', async () => {
+    const entry = await startMux(async (endpoint, _payload, uplink, _peer, control) =>
+      endpoint === 'fixture/echo' ? echoUplink(uplink) : waitForAbort(control.signal))
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    const received = countMessages(acceptedSocket(entry.mux))
+    client.send(itemFrame('absent', 1))
+    client.send(endFrame('absent'))
+    client.send(openFrame('live', 'fixture/echo'))
+    client.send(itemFrame('live', 'served'))
+    await vi.waitFor(() => { expect(received.count).toBe(4) })
+    await vi.waitFor(() => { expect(frames).toEqual([{ type: 'item', streamId: 'live', value: 'served' }]) })
+    expect(client.readyState).toBe(WebSocket.OPEN)
+    client.close()
+    await once(client, 'close')
+  })
+
+  it('ends a pending uplink read when the socket closes', async () => {
+    const read = Promise.withResolvers<unknown>()
+    const opened = Promise.withResolvers<undefined>()
+    const entry = await startMux(async (_endpoint, _payload, uplink, _peer, control) => {
+      uplink[Symbol.asyncIterator]().next().then(read.resolve, read.resolve)
+      opened.resolve(undefined)
+      return waitForAbort(control.signal)
+    })
+    const client = await connect(entry.url)
+    client.send(openFrame('pending'))
+    await opened.promise
+    client.close()
+    await once(client, 'close')
+    await expect(read.promise).resolves.toMatchObject({ message: 'Remote stream socket closed' })
+  })
+
+  it('drops uplink items after the Host stops reading', async () => {
+    const release = Promise.withResolvers<undefined>()
+    const returned = Promise.withResolvers<undefined>()
+    const entry = await startMux(async (_endpoint, _payload, uplink) => {
+      const iterator = uplink[Symbol.asyncIterator]()
+      const first: IteratorResult<unknown, undefined> = await iterator.next()
+      await iterator.return?.()
+      returned.resolve(undefined)
+      return (async function *(): AsyncIterable<unknown> {
+        await release.promise
+        yield { first: first.value, afterReturn: (await iterator.next()).done }
+      })()
+    })
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    const received = countMessages(acceptedSocket(entry.mux))
+    client.send(openFrame('closed'))
+    client.send(itemFrame('closed', 'one'))
+    await returned.promise
+    client.send(itemFrame('closed', 'two'))
+    client.send(endFrame('closed'))
+    client.send(itemFrame('closed', 'three'))
+    await vi.waitFor(() => { expect(received.count).toBe(5) })
+
+    release.resolve(undefined)
+    await vi.waitFor(() => {
+      expect(frames).toEqual([
+        { type: 'item', streamId: 'closed', value: { first: 'one', afterReturn: true } },
+        { type: 'end', streamId: 'closed' },
+      ])
+    })
+    client.close()
+    await once(client, 'close')
+  })
+
+  it('reports a second uplink consumer and a second pending read as stream failures', async () => {
+    const entry = await startMux(async (endpoint, _payload, uplink) => {
+      const iterator = uplink[Symbol.asyncIterator]()
+      if (endpoint === 'fixture/twice') uplink[Symbol.asyncIterator]()
+      void iterator.next().catch(() => undefined)
+      await iterator.next()
+      return echoUplink(uplink)
+    })
+    const client = await connect(entry.url)
+    const frames = collectFrames(client)
+    client.send(openFrame('twice', 'fixture/twice'))
+    client.send(openFrame('pending', 'fixture/pending'))
+    await vi.waitFor(() => {
+      expect(frames).toEqual(expect.arrayContaining([
+        {
+          type: 'error',
+          streamId: 'twice',
+          error: { code: 'internal', message: 'api gateway: Remote stream uplink inbox already has a consumer', details: {} },
+        },
+        {
+          type: 'error',
+          streamId: 'pending',
+          error: { code: 'internal', message: 'api gateway: Remote stream uplink inbox has one pending read', details: {} },
+        },
+      ]))
+    })
+    expect(frames).toHaveLength(2)
+    client.close()
+    await once(client, 'close')
+  })
+})
+
+const mapFailure: RemoteStreamFailureMapper = (error) => {
+  const remote = remoteErrorOf(error)
+  if (remote !== undefined) return { code: remote.code, message: remote.message, details: remote.details }
+  return {
+    code: 'internal',
+    message: error instanceof Error ? error.message : String(error),
+    details: {},
+  }
+}
+
+async function startMux(
+  open: RemoteStreamOpener,
+  heartbeatIntervalMs = 2_000,
+  streamInboxBytes = 262_144,
+  peer?: PeerScope,
+): Promise<RunningMux> {
+  const admitted = peer ?? await fixturePeer()
+  const mux = new RemoteStreamMuxServer(open, mapFailure, heartbeatIntervalMs, streamInboxBytes)
   const http = createServer()
-  http.on('upgrade', (request, socket, head) => { mux.handleUpgrade(request, socket, head) })
+  http.on('upgrade', (request, socket, head) => { mux.handleUpgrade(request, socket, head, admitted) })
   await new Promise<void>((resolve, reject) => {
     http.once('error', reject)
     http.listen(0, '127.0.0.1', () => {
@@ -252,6 +519,18 @@ async function startMux(open: RemoteStreamOpener, heartbeatIntervalMs = 2_000):
   return entry
 }
 
+/** A Peer whose scope is a plain Cordis fiber, so `peer.ctx.effect` and `dispose()` behave as the registry's do. */
+async function fixturePeer(): Promise<PeerScope> {
+  const root = new Context()
+  const fiber = root.plugin(() => {})
+  await fiber
+  return {
+    id: 'fixture-peer' as PeerId,
+    ctx: fiber.ctx,
+    dispose: async () => { await fiber.dispose() },
+  }
+}
+
 async function connect(url: string, autoPong = true): Promise<WebSocket> {
   const socket = new WebSocket(url, { autoPong })
   await once(socket, 'open')
@@ -265,8 +544,45 @@ function acceptedSocket(mux: RemoteStreamMuxServer): WebSocket {
   return socket
 }
 
-function openFrame(streamId: string): string {
-  return JSON.stringify({ type: 'open', streamId, endpoint: 'fixture/follow', payload: {} })
+function collectFrames(client: WebSocket): Record<string, unknown>[] {
+  const frames: Record<string, unknown>[] = []
+  client.on('message', (data) => {
+    if (!Buffer.isBuffer(data)) throw new TypeError('fixture expected a Buffer frame')
+    frames.push(JSON.parse(data.toString('utf8')) as Record<string, unknown>)
+  })
+  return frames
+}
+
+/** Count the text frames the mux has already dispatched, so a test can wait for the Host to hold them. */
+function countMessages(serverSocket: WebSocket): { count: number } {
+  const received = { count: 0 }
+  serverSocket.on('message', () => { received.count += 1 })
+  return received
+}
+
+function failWrites(serverSocket: WebSocket): void {
+  const mutable = serverSocket as {
+    send(data: unknown, callback: (error?: Error) => void): void
+  }
+  mutable.send = (_data, callback): void => {
+    callback(new Error('fixture ws write failure'))
+  }
+}
+
+function openFrame(streamId: string, endpoint = 'fixture/follow'): string {
+  return JSON.stringify({ type: 'open', streamId, endpoint, payload: {} })
+}
+
+function itemFrame(streamId: string, value?: unknown): string {
+  return JSON.stringify(value === undefined ? { type: 'item', streamId } : { type: 'item', streamId, value })
+}
+
+function endFrame(streamId: string): string {
+  return JSON.stringify({ type: 'end', streamId })
+}
+
+async function *echoUplink(uplink: AsyncIterable<unknown>): AsyncIterable<unknown> {
+  for await (const value of uplink) yield value
 }
 
 async function *waitForAbort(signal: AbortSignal): AsyncIterable<never> {
diff --git a/packages/api/job-controller/README.i18n.yaml b/packages/api/job-controller/README.i18n.yaml
new file mode 100644
index 0000000000..31fcbbd285
--- /dev/null
+++ b/packages/api/job-controller/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/api/job-controller/README.md
+README.md: d3698758cc144c033037759a834944870948284d
+README.zh.md: d9744b4d19cfff6d73923d0d26e3e817bc54c1a3
diff --git a/packages/api/job-controller/README.md b/packages/api/job-controller/README.md
new file mode 100644
index 0000000000..d3698758cc
--- /dev/null
+++ b/packages/api/job-controller/README.md
@@ -0,0 +1,67 @@
+---
+description: "Host and Client job streams: the roster one session can see and one job's retained output, mirrored to the browser without touching the model's consuming cursor."
+kind: "package-reference"
+---
+# Job Controller
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`@deepseek-ai/dsh-api-job-controller` owns the Host `ctx.jobController` service and the generated Client `ctx.remote.job` namespace. Its two Remote streams are projections of `ctx.jobs`: `job.list` mirrors the jobs one session can see as whole-set frames, and `job.follow` delivers one job's retained output from an absolute byte offset. The Client half installs `ctx.jobs`, the reference-counted service whose rosters and accumulated views the session-header job list renders. Neither stream touches the model's consuming cursor or the completion-notice ledger.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The Host controller requires the job registry (`dsh-jobs-local` in the shipped compositions) and fails to load without it. `job.list({ sessionId })` yields the session's visible set — its own jobs plus every unowned job — once on open and again after each coalesced burst of lifecycle commits (registration, progress, stopping, settlement, removal); output appends never refresh the roster, since a settled projection already carries the final byte count. `job.follow({ sessionId?, jobId, from? })` passes `sessionId` to registry `get` and `readAt` — an unowned job needs no session — and yields one `opened` anchor carrying the job projection, coalesced `output` frames, then one terminal `status` once the job has settled and its ring is drained, after which the stream closes normally; a removal announced mid-stream (the owner's teardown) closes it with the removed job's terminal projection. Both reads are non-consuming: the model's `job_output` cursor and notice state never observe them.
+
+The Client entry installs `ctx.jobs` (`IJobs`), backed by the package-internal `ClientJobsModel`. `watchRows(sessionId)` keeps one roster stream open per watched session however many viewers hold it and drops the rows after the last release; a reconnect's first frame is already the whole truth. `observe(sessionId, jobId)` opens one Gateway stream per job however many viewers expand it, keeps a bounded render tail per job with `gapBefore` marking eviction or resume gaps, closes the view on the terminal frame or records a stream failure on it, and drops the view after the last viewer releases. The plugin resolves the Gateway stream factory and the `job` namespace while its own context is current, because stream (re)opens run on caller stacks whose dynamic context has not declared `remote.job`.
+
+### Config
+
+| Field | Default | Meaning |
+|---|---:|---|
+| `observeFlushMs` | `100` | Coalescing window after a registry commit before the next rows or output read, in milliseconds |
+| `observeMaxFrameBytes` | `65,536` | Soft byte budget per observation output frame; one larger chunk ships whole |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-job-controller) is the exhaustive source for accepted fields and their JSDoc.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as job observation is browser and Host control state; it registers no prompt, tool, or session event. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md).
+
+#### KV Cache effect
+
+No direct effect; observation reads never touch model requests.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- The ring is a best-effort live preview, not a terminal transcript: producers' pull sources are copied per poll round, so two streams' writes inside one poll window land stdout first, and the client concatenates chunks regardless of `channel`.
+- Both streams are process-local: a Host restart loses every ring and roster; a resumed observation then anchors on an empty registry, and a re-opened roster starts empty.
+- Per-session fencing is enforced by the caller argument of each registry read; the Remote layer itself serves any connected browser.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The controller is a stateless projection of `ctx.jobs` reads; the registry's own `@deepseek-ai/dsh-jobs/invariant` owns the event protocol and event-versus-read relations these streams forward.
diff --git a/packages/api/job-controller/README.zh.md b/packages/api/job-controller/README.zh.md
new file mode 100644
index 0000000000..d9744b4d19
--- /dev/null
+++ b/packages/api/job-controller/README.zh.md
@@ -0,0 +1,67 @@
+---
+description: "Host 与 Client 的 job 流：把一个会话看得到的名册与一个 job 的保留输出镜像到浏览器，不触碰模型的消耗型游标。"
+kind: "package-reference"
+---
+# Job Controller
+
+[English](README.md) | 中文
+
+## 概述
+
+`@deepseek-ai/dsh-api-job-controller` 拥有 Host 的 `ctx.jobController` 服务与生成的 Client `ctx.remote.job` namespace。它的两条 Remote 流都是 `ctx.jobs` 的投影：`job.list` 以整集帧镜像一个会话看得到的 job；`job.follow` 从绝对字节偏移发送一个 job 的保留输出。Client 半侧安装 `ctx.jobs`——按引用计数的服务，会话头部任务列表渲染其名册与累积视图。两条流都不触碰模型的消耗型游标与完成播报台账。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+Host 控制器要求 job 注册表（已发布组合里是 `dsh-jobs-local`），缺少则不加载。`job.list({ sessionId })` 产出该会话可见的集合——自己的 job 加上所有无主 job——打开时一次，之后每一轮聚合过的生命周期提交（注册、进度、停止中、结算、移除）后再一次；输出追加从不刷新名册，因为结算后的投影已经带着最终字节数。`job.follow({ sessionId?, jobId, from? })` 把 `sessionId` 传给注册表的 `get` 与 `readAt`——无主 job 不需要 session——先产出一个携带 job 投影的 `opened` 锚帧，再是聚合的 `output` 帧，job 结算且环排干后产出一个终态 `status`，随后流正常关闭；流中若通告了移除（拥有者 teardown），则以被移除 job 的终态投影收尾。两种读取都是非消耗的：模型侧 `job_output` 游标与完成播报状态永远观察不到它们。
+
+Client 入口安装 `ctx.jobs`（`IJobs`），由包内部的 `ClientJobsModel` 支撑。`watchRows(sessionId)` 不论多少查看器持有都只为每个被关注的会话开一条名册流，最后一个释放后丢弃行；重连后的首帧已经是完整事实。`observe(sessionId, jobId)` 不论多少查看器展开同一 job 都只开一条 Gateway 流，按 job 保留有界的渲染尾部并用 `gapBefore` 标记淘汰或续读缺口，在终态帧上关闭视图或把流失败记到视图上，最后一个查看器释放后丢弃视图。插件在自己的上下文仍是当前上下文时解析 Gateway 流工厂与 `job` namespace，因为流的（重）开启跑在未声明 `remote.job` 的调用栈上。
+
+### 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---:|---|
+| `observeFlushMs` | `100` | 注册表提交到下一次名册或输出读取之间的聚合窗口，毫秒 |
+| `observeMaxFrameBytes` | `65,536` | 每个观测输出帧的软字节预算；更大的单块整块发送 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-job-controller)是所有受支持字段及其 JSDoc 的完整来源。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。job 观测是浏览器与 Host 的控制状态；它不注册任何提示词、工具或会话事件。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。
+
+#### KV 缓存影响
+
+无直接影响；观测读取从不触碰模型请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 环是尽力而为的实时预览，不是终端转录：生产者的拉取源按轮询轮次复制，同一轮询窗口内两条流的写入先 stdout 落地，客户端拼接 chunk 时也不区分 `channel`。
+- 两条流都是进程本地的：Host 重启丢失全部环与名册，续读的观测随后锚定在空注册表上，重开的名册从空开始。
+- 按 session 的访问限制由注册表每次读取时的调用方参数强制；Remote 层本身服务任何已连接浏览器。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。控制器是 `ctx.jobs` 读取的无状态投影；这些流转发的事件协议与事件对读取的关系由注册表自己的 `@deepseek-ai/dsh-jobs/invariant` 拥有。
diff --git a/packages/api/job-controller/package.json b/packages/api/job-controller/package.json
new file mode 100644
index 0000000000..30fcb07689
--- /dev/null
+++ b/packages/api/job-controller/package.json
@@ -0,0 +1,86 @@
+{
+  "name": "@deepseek-ai/dsh-api-job-controller",
+  "description": "Job Remote observation stream and the reference-counted client job-output service",
+  "version": "0.1.6-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/api/job-controller"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "external": [
+        "@deepseek-ai/dsh-api-gateway/client"
+      ],
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway",
+        "@deepseek-ai/dsh-client-connection"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^",
+    "@deepseek-ai/schemastery": "workspace:^",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-jobs": "workspace:^",
+    "@deepseek-ai/dsh-jobs-local": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^"
+  }
+}
diff --git a/packages/api/job-controller/src/client/index.ts b/packages/api/job-controller/src/client/index.ts
new file mode 100644
index 0000000000..8c4f161ea2
--- /dev/null
+++ b/packages/api/job-controller/src/client/index.ts
@@ -0,0 +1,36 @@
+/**
+ * Job Controller client half: installs `ctx.jobs` over the generated `job`
+ * Remote namespace. The plugin resolves both Remote faces it drives while its
+ * own context is current, because stream (re)opens run on caller stacks — a
+ * React event, a carrier retry — whose dynamic context has not declared
+ * `remote.job`.
+ * @module @deepseek-ai/dsh-api-job-controller/client
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-api-job-controller/remote'
+import { ClientJobsModel } from './model.ts'
+import { ClientJobs } from './service.ts'
+
+export type { JobsSnapshot, ObservedJob } from './model.ts'
+// The `ctx.jobs` contract. Its module also carries the Context augmentation
+// that declares `ctx.jobs`, which reaches consumers only through this export:
+// declaration emit drops the value import above.
+export type { IJobs } from './service.ts'
+export type {
+  JobChunk, JobFollowFrame, JobFollowRequest, JobListFrame, JobListRequest, JobView,
+} from '../types.ts'
+
+/** Required Client Remote services. */
+export const inject = ['remote', 'remote.job']
+
+/**
+ * Install the client jobs service.
+ * @param ctx - Client root Context.
+ */
+export function apply(ctx: Context): void {
+  // Read the namespace now, not inside `open`: see the module JSDoc.
+  const { remote } = ctx
+  const { job } = remote
+  new ClientJobs(ctx, { $stream: options => remote.$stream(options), job }, new ClientJobsModel())
+}
diff --git a/packages/api/job-controller/src/client/model.ts b/packages/api/job-controller/src/client/model.ts
new file mode 100644
index 0000000000..6f87a5d39e
--- /dev/null
+++ b/packages/api/job-controller/src/client/model.ts
@@ -0,0 +1,216 @@
+/**
+ * React-free client job state: the roster each watched session can see, fed
+ * by `job.list` frames, and per-job accumulated output views fed by
+ * `job.follow` frames. Pure data plus subscriptions — transport wiring stays
+ * in the client service, UI stays in slot components.
+ * @module @deepseek-ai/dsh-api-job-controller/client/model
+ */
+
+import { notifySubscribers } from '@deepseek-ai/dsh-client-store'
+import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
+import type { JobView } from '@deepseek-ai/dsh-jobs/view'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { JobFollowFrame } from '../types.ts'
+
+/** Bounded per-job render tail, in UTF-16 code units. */
+const RENDER_TAIL_LIMIT = 128 * 1024
+
+/** One observed job's live view state. */
+export interface ObservedJob {
+  readonly jobId: JobId
+  /** Accumulated output tail, bounded to the render limit. */
+  readonly text: string
+  /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */
+  readonly gapBefore: boolean
+  /** True while the observation stream is open and the job has not settled. */
+  readonly streaming: boolean
+  /** Terminal observation failure, when the stream ended abnormally. */
+  readonly error?: string
+}
+
+/** Immutable client job state. */
+export interface JobsSnapshot {
+  /**
+   * The jobs each watched session can see, keyed by session id. A session
+   * nobody watches, or one that sees no job, has no key, so consumers read
+   * absence rather than a sentinel.
+   */
+  readonly rows: Readonly<Record<string, readonly JobView[]>>
+  /** Live observation state keyed by job id. */
+  readonly observed: Readonly<Record<string, ObservedJob>>
+}
+
+/** Bare observable source for the client job snapshot. */
+export interface JobsSource {
+  /** Read the identity-stable current snapshot. */
+  getSnapshot(): JobsSnapshot
+  /**
+   * Subscribe to snapshot changes.
+   * @param listener - invalidation callback.
+   * @returns unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void
+}
+
+/** Mutable observation bookkeeping behind one {@link ObservedJob} view. */
+interface ObservedState {
+  view: ObservedJob
+  /** Resume offset for the next generation's `from`. */
+  cursor: number | undefined
+}
+
+/** Owns the per-session rosters and per-job observation state. */
+export class ClientJobsModel implements JobsSource {
+  private readonly rowsBySession = new Map<string, readonly JobView[]>()
+  private readonly observedStates = new Map<string, ObservedState>()
+  private readonly listeners = new Set<() => void>()
+  private snapshotCache: JobsSnapshot = { rows: {}, observed: {} }
+  private snapshotDirty = false
+
+  getSnapshot(): JobsSnapshot {
+    if (this.snapshotDirty) {
+      const rows: Record<string, readonly JobView[]> = {}
+      for (const [id, jobs] of this.rowsBySession) rows[id] = jobs
+      const observed: Record<string, ObservedJob> = {}
+      for (const [id, state] of this.observedStates) observed[id] = state.view
+      this.snapshotCache = { rows, observed }
+      this.snapshotDirty = false
+    }
+    return this.snapshotCache
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /**
+   * Replace one session's roster with a `rows` frame's whole set. An empty
+   * set is stored as an absent key.
+   * @param sessionId - the watched session.
+   * @param jobs - the complete visible set.
+   */
+  rowsReplaced(sessionId: SessionId, jobs: readonly JobView[]): void {
+    const key = String(sessionId)
+    if (jobs.length === 0) {
+      if (!this.rowsBySession.delete(key)) return
+    } else {
+      this.rowsBySession.set(key, jobs)
+    }
+    this.changed()
+  }
+
+  /**
+   * Drop one session's roster after its last watcher stops or its stream fails.
+   * @param sessionId - the no-longer-watched session.
+   */
+  rowsDropped(sessionId: SessionId): void {
+    if (!this.rowsBySession.delete(String(sessionId))) return
+    this.changed()
+  }
+
+  /**
+   * The resume offset for one job's next observation generation.
+   * @param id - observed job.
+   * @returns the last accepted `next`, or undefined for a fresh observation.
+   */
+  cursorOf(id: JobId): number | undefined {
+    return this.observedStates.get(String(id))?.cursor
+  }
+
+  /**
+   * Install or reset observation state when a generation's anchor arrives.
+   * @param id - observed job.
+   * @param frame - the generation's `opened` anchor.
+   */
+  observeOpened(id: JobId, frame: Extract<JobFollowFrame, { type: 'opened' }>): void {
+    const existing = this.observedStates.get(String(id))
+    // A fresh view anchored past offset zero starts after an evicted head
+    // (fresh observations anchor at the registry's earliest retained byte), so
+    // it owes the same gap mark a live observer earned from lossy reads. A
+    // resume that already accumulated text keeps its recorded gap state.
+    const freshPastHead = (existing === undefined || existing.view.text === '') && frame.from > 0
+    const view: ObservedJob = {
+      jobId: id,
+      text: existing?.view.text ?? '',
+      gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.job.output.earliest || freshPastHead,
+      streaming: true,
+    }
+    this.observedStates.set(String(id), { view, cursor: frame.from })
+    this.changed()
+  }
+
+  /**
+   * Append one output frame's chunks to the bounded render tail.
+   * @param id - observed job.
+   * @param frame - a coalesced `output` frame.
+   */
+  observeOutput(id: JobId, frame: Extract<JobFollowFrame, { type: 'output' }>): void {
+    const state = this.observedStates.get(String(id))
+    /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */
+    if (state === undefined) return
+    let text = state.view.text + frame.chunks.map(chunk => chunk.text).join('')
+    let gapBefore = state.view.gapBefore || frame.lossy === true
+      || frame.chunks.some(chunk => chunk.gapBefore === true)
+    if (text.length > RENDER_TAIL_LIMIT) {
+      let cut = text.length - RENDER_TAIL_LIMIT
+      // Never split a surrogate pair at the render bound.
+      const unit = text.charCodeAt(cut)
+      if (unit >= 0xDC00 && unit <= 0xDFFF) cut += 1
+      text = text.slice(cut)
+      gapBefore = true
+    }
+    state.view = { ...state.view, text, gapBefore }
+    state.cursor = frame.next
+    this.changed()
+  }
+
+  /**
+   * Close the live view once the terminal `status` frame arrived: the ring is
+   * drained and the roster row carries the settled projection.
+   * @param id - observed job.
+   */
+  observeSettled(id: JobId): void {
+    const state = this.observedStates.get(String(id))
+    /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */
+    if (state === undefined) return
+    state.view = { ...state.view, streaming: false }
+    this.changed()
+  }
+
+  /**
+   * Record a terminal observation failure.
+   * @param id - observed job.
+   * @param error - the stream's terminal failure.
+   */
+  observeFailed(id: JobId, error: unknown): void {
+    const state = this.observedStates.get(String(id))
+    if (state === undefined) {
+      // A failure before the anchor — a rejected request, a job gone between
+      // the click and the open — still owes the panel its notice; a later
+      // successful anchor replaces this view and resumes from no cursor.
+      this.observedStates.set(String(id), {
+        view: { jobId: id, text: '', gapBefore: false, streaming: false, error: String(error) },
+        cursor: undefined,
+      })
+      this.changed()
+      return
+    }
+    state.view = { ...state.view, streaming: false, error: String(error) }
+    this.changed()
+  }
+
+  /**
+   * Drop observation state after the last observer stops.
+   * @param id - the no-longer-observed job.
+   */
+  observeStopped(id: JobId): void {
+    if (!this.observedStates.delete(String(id))) return
+    this.changed()
+  }
+
+  private changed(): void {
+    this.snapshotDirty = true
+    notifySubscribers(this.listeners, 'jobs')
+  }
+}
diff --git a/packages/api/job-controller/src/client/service.ts b/packages/api/job-controller/src/client/service.ts
new file mode 100644
index 0000000000..e3eb06a623
--- /dev/null
+++ b/packages/api/job-controller/src/client/service.ts
@@ -0,0 +1,257 @@
+/**
+ * The `ctx.jobs` client service: reference-counted streams over the `job`
+ * namespace — one `job.list` roster stream per watched session and one
+ * `job.follow` stream per observed job — so overlapping viewers share a
+ * stream, rosters resume whole after a reconnect, and observations resume
+ * from the model's cursor.
+ * @module @deepseek-ai/dsh-api-job-controller/client/service
+ */
+
+import { Service, type Context } from '@deepseek-ai/cordis'
+import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
+import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { JobFollowFrame, JobFollowRequest, JobListFrame, JobListRequest } from '../types.ts'
+import type { ClientJobsModel, JobsSource } from './model.ts'
+
+/** The generated `job` namespace face the stream runners drive. */
+export interface JobRemote {
+  /**
+   * Open one roster generation.
+   * @param request - the session whose visible set to mirror.
+   * @param signal - generation cancellation.
+   * @returns the whole-set frame sequence of one generation.
+   */
+  list(request: JobListRequest, signal?: AbortSignal): AsyncIterable<JobListFrame>
+  /**
+   * Open one observation generation.
+   * @param request - target job, owning session, and optional resume offset.
+   * @param signal - generation cancellation.
+   * @returns the frame sequence of one generation.
+   */
+  follow(request: JobFollowRequest, signal?: AbortSignal): AsyncIterable<JobFollowFrame>
+}
+
+/** Remote faces the runners drive: the Gateway stream factory and the `job` namespace. */
+export interface JobsRemote {
+  readonly $stream: ClientRemote['$stream']
+  readonly job: JobRemote
+}
+
+/** The client jobs service face. */
+export interface IJobs {
+  /** Rosters and per-job observation state. */
+  readonly state: JobsSource
+  /**
+   * Keep one session's roster current; reference-counted, so two watchers of
+   * the same session share one stream and the rows leave with the last.
+   * @param sessionId - the session whose visible jobs to mirror.
+   * @returns stop function releasing this watcher's reference.
+   */
+  watchRows(sessionId: SessionId): () => void
+  /**
+   * Start observing one job's live output; reference-counted, so two viewers
+   * of the same job share one stream.
+   * @param sessionId - owning session used for the fenced read; undefined for an unowned job.
+   * @param id - job to observe.
+   * @returns stop function releasing this observer's reference.
+   */
+  observe(sessionId: SessionId | undefined, id: JobId): () => void
+}
+
+/** One reference-counted stream. */
+interface StreamEntry {
+  refs: number
+  stopped: boolean
+  dispose: () => Promise<void>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** React-free client job rosters and observation control. */
+    jobs: IJobs
+  }
+}
+
+/** Owns the bare jobs snapshot and the per-session and per-job streams. */
+export class ClientJobs extends Service implements IJobs {
+  readonly state: JobsSource
+  private readonly rowsEntries = new Map<string, StreamEntry>()
+  private readonly observations = new Map<string, StreamEntry>()
+
+  /**
+   * @param ctx - client root Context.
+   * @param remote - the Gateway stream factory plus the generated `job` namespace, both resolved by the caller.
+   * @param model - shared client jobs model.
+   */
+  constructor(
+    ctx: Context,
+    private readonly remote: JobsRemote,
+    private readonly model: ClientJobsModel,
+  ) {
+    super(ctx, 'jobs')
+    this.state = model
+    ctx.effect(() => async () => {
+      const open = [...this.rowsEntries.values(), ...this.observations.values()]
+      this.rowsEntries.clear()
+      this.observations.clear()
+      for (const entry of open) entry.stopped = true
+      // Cordis awaits an async disposer, so the fiber stays unloading until
+      // every carrier iterator has closed and a successor plugin instance
+      // cannot overlap one. A carrier whose teardown fails is stopped all the
+      // same; its failure has no consumer here.
+      await Promise.allSettled(open.map(entry => entry.dispose()))
+    }, 'job-controller.client.streams')
+  }
+
+  watchRows(sessionId: SessionId): () => void {
+    return this.acquire(
+      this.rowsEntries,
+      String(sessionId),
+      () => this.startRows(sessionId),
+      () => { this.model.rowsDropped(sessionId) },
+    )
+  }
+
+  observe(sessionId: SessionId | undefined, id: JobId): () => void {
+    return this.acquire(
+      this.observations,
+      String(id),
+      () => this.startObservation(sessionId, id),
+      () => { this.model.observeStopped(id) },
+    )
+  }
+
+  /** Share the live entry under `key` or start one, and hand back its release. */
+  private acquire(
+    entries: Map<string, StreamEntry>,
+    key: string,
+    start: () => StreamEntry,
+    cleared: () => void,
+  ): () => void {
+    const existing = entries.get(key)
+    if (existing !== undefined && !existing.stopped) {
+      existing.refs += 1
+      return this.releaser(entries, key, existing, cleared)
+    }
+    const entry = start()
+    entries.set(key, entry)
+    return this.releaser(entries, key, entry, cleared)
+  }
+
+  /**
+   * Release closures bind the exact entry they were minted for, never the
+   * map's current occupant: a later acquire on the same key may have replaced
+   * a stopped entry, and decrementing or disposing through the key alone
+   * would tear down that newer stream's references.
+   */
+  private releaser(entries: Map<string, StreamEntry>, key: string, entry: StreamEntry, cleared: () => void): () => void {
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      entry.refs -= 1
+      if (entry.refs > 0) return
+      if (entries.get(key) === entry) entries.delete(key)
+      entry.stopped = true
+      void entry.dispose().then(() => {
+        // Clear the state only while no successor holds the key: a re-acquire
+        // inside the dispose round-trip already refilled the model, and a
+        // stale clear would blank it for good.
+        if (entries.has(key)) return
+        cleared()
+      })
+    }
+  }
+
+  private startRows(sessionId: SessionId): StreamEntry {
+    const name = `job rows ${String(sessionId)}`
+    const stream = this.remote.$stream<JobListFrame>({
+      name,
+      open: signal => this.remote.job.list({ sessionId }, signal),
+      // The roster has no natural end while it is watched: an end after the
+      // first frame is a carrier interruption (a Host reload closes the
+      // generation) and the next generation's whole set loses nothing. An end
+      // before the first frame is terminal.
+      ended: accepted => accepted
+        ? new RemoteStreamCarrierError(`${name} ended before release`)
+        : new Error(`${name} ended before its first frame`),
+    })
+    const entry: StreamEntry = {
+      refs: 1,
+      stopped: false,
+      dispose: () => stream.dispose(),
+    }
+    void (async () => {
+      try {
+        for await (const item of stream) {
+          this.model.rowsReplaced(sessionId, item.value.jobs)
+          item.accept()
+        }
+      } catch {
+        // A terminal stream failure leaves nothing current to show; the model
+        // drops the roster rather than keeping a stale set on screen.
+        if (!entry.stopped) this.model.rowsDropped(sessionId)
+      } finally {
+        entry.stopped = true
+        void entry.dispose()
+      }
+    })()
+    return entry
+  }
+
+  private startObservation(sessionId: SessionId | undefined, id: JobId): StreamEntry {
+    const name = `job observation ${String(id)}`
+    const stream = this.remote.$stream<JobFollowFrame>({
+      name,
+      open: (signal) => {
+        const from = this.model.cursorOf(id)
+        return this.remote.job.follow(
+          {
+            jobId: id,
+            ...sessionId !== undefined ? { sessionId } : {},
+            ...from !== undefined ? { from } : {},
+          },
+          signal,
+        )
+      },
+      // A premature end after the anchor is retryable (a Host reload closes the
+      // generation); resuming from the cursor loses nothing. An end before the
+      // anchor is terminal.
+      ended: accepted => accepted
+        ? new RemoteStreamCarrierError(`${name} ended before settlement`)
+        : new Error(`${name} ended before its anchor`),
+    })
+    const entry: StreamEntry = {
+      refs: 1,
+      stopped: false,
+      dispose: () => stream.dispose(),
+    }
+    void (async () => {
+      try {
+        for await (const item of stream) {
+          const frame = item.value
+          if (frame.type === 'opened') {
+            this.model.observeOpened(id, frame)
+            item.accept()
+            continue
+          }
+          if (frame.type === 'output') {
+            this.model.observeOutput(id, frame)
+            continue
+          }
+          // Terminal status: leave the loop before the generation end is
+          // classified, then close the stream for good.
+          this.model.observeSettled(id)
+          break
+        }
+      } catch (error) {
+        if (!entry.stopped) this.model.observeFailed(id, error)
+      } finally {
+        entry.stopped = true
+        void entry.dispose()
+      }
+    })()
+    return entry
+  }
+}
diff --git a/packages/api/job-controller/src/index.ts b/packages/api/job-controller/src/index.ts
new file mode 100644
index 0000000000..3c463dd85c
--- /dev/null
+++ b/packages/api/job-controller/src/index.ts
@@ -0,0 +1,97 @@
+/**
+ * Host job Remote owner: streams the background-job roster one session can
+ * see and one job's retained output to browsers over the generated `job`
+ * namespace. Both streams are projections of `ctx.jobs`; the model's
+ * consuming cursor and notice state never observe them.
+ * @module @deepseek-ai/dsh-api-job-controller
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type {} from '@deepseek-ai/dsh-jobs'
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import { observeJobOutput } from './observe.ts'
+import { streamJobRows } from './rows.ts'
+import type { JobFollowFrame, JobFollowRequest, JobListFrame, JobListRequest } from './types.ts'
+
+export type * from './types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Host job Remote namespace owner. */
+    jobController: JobController
+  }
+}
+
+/** Default coalescing window between reads, in milliseconds. */
+const DEFAULT_OBSERVE_FLUSH_MS = 100
+
+/** Default soft byte budget per output frame. */
+const DEFAULT_OBSERVE_MAX_FRAME_BYTES = 64 * 1024
+
+/** Job Controller deployment policy. */
+export interface Config {
+  /** Coalescing window after a registry commit before the next rows or output read, in milliseconds (default 100). */
+  readonly observeFlushMs?: number
+  /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */
+  readonly observeMaxFrameBytes?: number
+}
+
+/** Host service backing the generated `ctx.remote.job` namespace. */
+export class JobController extends TypertRemoteService {
+  static inject = ['jobs', 'typert']
+
+  static Config: z<Config> = z.object({
+    observeFlushMs: z.natural().min(1).default(DEFAULT_OBSERVE_FLUSH_MS),
+    observeMaxFrameBytes: z.natural().min(1).default(DEFAULT_OBSERVE_MAX_FRAME_BYTES),
+  })
+
+  private readonly observeFlushMs: number
+  private readonly observeMaxFrameBytes: number
+
+  /**
+   * @param ctx - Host context carrying the job registry.
+   * @param config - observation cadence and framing policy.
+   */
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'jobController', { namespace: 'job' })
+    // schemastery (the exported Config schema) has already filled the defaulted
+    // fields; the assertion records that resolution, not a hidden fallback.
+    const resolved = config as Required<Config>
+    this.observeFlushMs = resolved.observeFlushMs
+    this.observeMaxFrameBytes = resolved.observeMaxFrameBytes
+  }
+
+  /**
+   * Stream the jobs one session can see — its own plus every unowned job —
+   * as whole-set frames: one on open, then one after each coalesced burst of
+   * lifecycle commits. The stream has no natural end; the carrier closes it.
+   * @param request - the session whose visible set to mirror.
+   * @param signal - cancellation owned by the Remote stream carrier.
+   * @returns the roster frames.
+   */
+  @Remote({ mode: 'stream' })
+  list(request: JobListRequest, signal: AbortSignal): AsyncIterable<JobListFrame> {
+    return streamJobRows(this.ctx.jobs, request, { flushMs: this.observeFlushMs }, signal)
+  }
+
+  /**
+   * Stream one job's retained output from an absolute byte offset, then its
+   * terminal projection once settled and drained. Non-consuming: the
+   * model-facing cursor and notice state never observe these reads. The
+   * request's session is the fenced read's caller; the registry rejects a
+   * job the session cannot see and an unknown job.
+   * @param request - target job, owning session, and optional resume offset.
+   * @param signal - cancellation owned by the Remote stream carrier.
+   * @returns anchor, coalesced output frames, and the terminal status.
+   */
+  @Remote({ mode: 'stream' })
+  follow(request: JobFollowRequest, signal: AbortSignal): AsyncIterable<JobFollowFrame> {
+    return observeJobOutput(this.ctx.jobs, request, {
+      flushMs: this.observeFlushMs,
+      maxFrameBytes: this.observeMaxFrameBytes,
+    }, signal)
+  }
+}
+
+export default JobController
diff --git a/packages/api/job-controller/src/observe.ts b/packages/api/job-controller/src/observe.ts
new file mode 100644
index 0000000000..31b4682bed
--- /dev/null
+++ b/packages/api/job-controller/src/observe.ts
@@ -0,0 +1,132 @@
+/** Per-job observation generations: anchor, coalesced output, terminal status. */
+
+import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
+import type { JobChunk, JobRegistry, JobStatus, JobView } from '@deepseek-ai/dsh-jobs'
+import type { JobFollowFrame, JobFollowRequest } from './types.ts'
+import { OutputWaiter, sleep } from './wake.ts'
+
+/** Cadence and framing bounds for one observation generation. */
+export interface ObserveJobOptions {
+  /** Coalescing window after a wake before reading, in milliseconds. */
+  readonly flushMs: number
+  /**
+   * Soft byte budget per `output` frame. Accumulated chunks flush once the
+   * budget is met; one chunk larger than the budget ships whole (the
+   * registry's retention cap is the hard bound on any single chunk).
+   */
+  readonly maxFrameBytes: number
+}
+
+function isTerminal(status: JobStatus): boolean {
+  return status !== 'running' && status !== 'stopping'
+}
+
+/**
+ * Stream one job's retained output from an absolute offset: one `opened`
+ * anchor, coalesced `output` frames as the ring advances, then one terminal
+ * `status` after the settled job is drained, after which the generation
+ * closes normally. A removal announced mid-generation (the owner's teardown)
+ * closes it with the removed job's terminal projection instead of a failed
+ * read. Reads are non-consuming — the model-facing cursor and
+ * notice state never observe them; reconnecting callers resume by passing
+ * the last frame's `next` as `from`. The request's session is the fenced
+ * read's caller: the registry rejects a job the session cannot see and an
+ * unknown job.
+ * @param registry - the live job registry.
+ * @param request - target job, owning session, and optional resume offset.
+ * @param options - cadence and framing bounds.
+ * @param signal - generation cancellation owned by the Remote stream carrier.
+ * @returns the observation frame sequence for one generation.
+ */
+export async function* observeJobOutput(
+  registry: JobRegistry,
+  request: JobFollowRequest,
+  options: ObserveJobOptions,
+  signal: AbortSignal,
+): AsyncIterable<JobFollowFrame> {
+  if (request.from !== undefined && (!Number.isSafeInteger(request.from) || request.from < 0)) {
+    throw new Error(`invalid observe offset: expected a non-negative safe integer, got ${JSON.stringify(request.from)}`)
+  }
+  signal.throwIfAborted()
+  // The brand is nominal typing only; the wire boundary stamps it here rather
+  // than value-importing the registry package's constructor.
+  const id = String(request.jobId) as JobId
+  const waiter = new OutputWaiter()
+  // A removal announced during the generation: the owner's teardown settled
+  // and dropped the record, so the projection it announced is the last word
+  // and the read after the flush window would only find an unknown id.
+  let removed: JobView | undefined
+  // Subscribe before the first read so an append between the anchor read and
+  // the wait cannot be missed.
+  const unsubscribe = registry.events.subscribe({ owners: 'all' }, (event) => {
+    const changed = event.type === 'output' ? event.id : event.job.id
+    if (changed !== id) return
+    if (event.type === 'removed') removed = event.job
+    waiter.wake()
+  })
+  try {
+    let job = registry.get(id, request.sessionId)
+    let cursor = request.from ?? job.output.earliest
+    yield { type: 'opened', job, from: cursor }
+    while (!signal.aborted) {
+      if (removed !== undefined) {
+        yield { type: 'status', job: removed }
+        return
+      }
+      const read = registry.readAt(id, cursor, request.sessionId)
+      if (read.chunks.length > 0 || read.lossy) {
+        yield* outputFrames(read.chunks, read.next, read.lossy, options.maxFrameBytes)
+      }
+      cursor = read.next
+      job = registry.get(id, request.sessionId)
+      if (isTerminal(job.status) && cursor >= job.output.total) {
+        yield { type: 'status', job }
+        return
+      }
+      await waiter.wait(signal)
+      // Let a burst accumulate so producer chatter becomes bounded frames.
+      await sleep(options.flushMs, signal)
+    }
+  } finally {
+    unsubscribe()
+  }
+}
+
+/** Split one read into frames along the soft per-frame byte budget. */
+function* outputFrames(
+  chunks: readonly JobChunk[],
+  next: number,
+  lossy: boolean,
+  maxFrameBytes: number,
+): Iterable<JobFollowFrame> {
+  let batch: JobChunk[] = []
+  let batchBytes = 0
+  let flaggedLossy = lossy
+  for (const chunk of chunks) {
+    batch.push(chunk)
+    batchBytes += Buffer.byteLength(chunk.text, 'utf8')
+    if (batchBytes >= maxFrameBytes) {
+      const last = batch[batch.length - 1]
+      /* v8 ignore start -- a non-empty batch always has a last chunk; the arm only discharges noUncheckedIndexedAccess. */
+      const end = last === undefined ? next : last.at + Buffer.byteLength(last.text, 'utf8')
+      /* v8 ignore stop */
+      yield {
+        type: 'output',
+        chunks: batch,
+        next: end,
+        ...flaggedLossy ? { lossy: true as const } : {},
+      }
+      flaggedLossy = false
+      batch = []
+      batchBytes = 0
+    }
+  }
+  if (batch.length > 0 || flaggedLossy) {
+    yield {
+      type: 'output',
+      chunks: batch,
+      next,
+      ...flaggedLossy ? { lossy: true as const } : {},
+    }
+  }
+}
diff --git a/packages/api/job-controller/src/rows.ts b/packages/api/job-controller/src/rows.ts
new file mode 100644
index 0000000000..9ef6564979
--- /dev/null
+++ b/packages/api/job-controller/src/rows.ts
@@ -0,0 +1,53 @@
+/** Per-session roster generations: the caller-visible job set, replaced whole after every lifecycle change. */
+
+import type { JobRegistry } from '@deepseek-ai/dsh-jobs'
+import type { JobListFrame, JobListRequest } from './types.ts'
+import { OutputWaiter, sleep } from './wake.ts'
+
+/** Cadence bound for one roster generation. */
+export interface RowsOptions {
+  /** Coalescing window after a lifecycle event before the next rows read, in milliseconds. */
+  readonly flushMs: number
+}
+
+/**
+ * Stream the jobs one session can see: one frame on open, then one after
+ * every lifecycle commit that touches a visible job (registration, progress,
+ * stopping, settlement, removal), coalesced over `flushMs`. Output appends
+ * never refresh the roster — a settled projection already carries the final
+ * byte count — so the stream is quiet while a job merely writes. Reads are
+ * projections; the model's cursor and notice state never observe them.
+ * @param registry - the live job registry.
+ * @param request - the session whose visible set to mirror.
+ * @param options - the coalescing window.
+ * @param signal - generation cancellation owned by the Remote stream carrier.
+ * @returns the roster frame sequence for one generation.
+ */
+export async function* streamJobRows(
+  registry: JobRegistry,
+  request: JobListRequest,
+  options: RowsOptions,
+  signal: AbortSignal,
+): AsyncIterable<JobListFrame> {
+  signal.throwIfAborted()
+  const waiter = new OutputWaiter()
+  // Subscribe before the first read so a commit between the read and the
+  // wait cannot be missed.
+  const unsubscribe = registry.events.subscribe({ owners: 'all' }, (event) => {
+    if (event.type === 'output') return
+    const owner = event.job.owner
+    if (owner === undefined || owner === request.sessionId) waiter.wake()
+  })
+  try {
+    yield { type: 'rows', jobs: registry.list(request.sessionId) }
+    while (true) {
+      await waiter.wait(signal)
+      // Let a burst of commits settle into one frame.
+      await sleep(options.flushMs, signal)
+      if (signal.aborted) return
+      yield { type: 'rows', jobs: registry.list(request.sessionId) }
+    }
+  } finally {
+    unsubscribe()
+  }
+}
diff --git a/packages/api/job-controller/src/types.ts b/packages/api/job-controller/src/types.ts
new file mode 100644
index 0000000000..aa02d2061f
--- /dev/null
+++ b/packages/api/job-controller/src/types.ts
@@ -0,0 +1,70 @@
+/**
+ * Wire types of the generated `job` Remote namespace: the per-session roster
+ * stream and the per-job observation stream. Client-safe: no Host imports.
+ * @module @deepseek-ai/dsh-api-job-controller/types
+ */
+
+import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
+import type { JobChunk, JobView } from '@deepseek-ai/dsh-jobs/view'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+export type { JobChunk, JobView } from '@deepseek-ai/dsh-jobs/view'
+
+/** Target of one `job.list` stream: the session whose visible jobs the stream mirrors. */
+export interface JobListRequest {
+  readonly sessionId: SessionId
+}
+
+/**
+ * One `job.list` frame: the complete set the session can see — its own jobs
+ * plus every unowned job — after a lifecycle change. Whole-set replacement,
+ * so a reconnect's first frame is already the truth.
+ */
+export interface JobListFrame {
+  readonly type: 'rows'
+  readonly jobs: readonly JobView[]
+}
+
+/** Target of one `job.follow` stream: the job, its owning session, and an optional resume offset. */
+export interface JobFollowRequest {
+  /**
+   * Owning session for the fenced read. Omitted for an unowned job, which any
+   * caller may observe.
+   */
+  readonly sessionId?: SessionId
+  readonly jobId: JobId
+  /**
+   * Absolute byte offset to resume from (a prior frame's `next`). Omitted, the
+   * stream starts at the oldest retained byte.
+   */
+  readonly from?: number
+}
+
+/**
+ * Job observation stream frames: one `opened` anchor carrying the job's
+ * projection (its `output.earliest` and `output.total` at open time) and the
+ * offset the first `output` frame continues from, then coalesced `output`
+ * batches, then — once the job has settled and its ring is drained — one
+ * terminal `status` carrying the settled projection, after which the stream
+ * closes normally. Status rides the same stream as output so settlement can
+ * never race a still-open output channel.
+ */
+export type JobFollowFrame =
+  | {
+    readonly type: 'opened'
+    readonly job: JobView
+    /** Offset the first `output` frame continues from. */
+    readonly from: number
+  }
+  | {
+    readonly type: 'output'
+    readonly chunks: readonly JobChunk[]
+    /** Offset to resume from after this frame. */
+    readonly next: number
+    /** Bytes between the requested offset and `chunks` were already evicted. */
+    readonly lossy?: true
+  }
+  | {
+    readonly type: 'status'
+    readonly job: JobView
+  }
diff --git a/packages/api/job-controller/src/wake.ts b/packages/api/job-controller/src/wake.ts
new file mode 100644
index 0000000000..489699cb3c
--- /dev/null
+++ b/packages/api/job-controller/src/wake.ts
@@ -0,0 +1,60 @@
+/**
+ * Wake bookkeeping shared by the two observation generators: a wake-flag
+ * waiter that never loses a wake between waits, and an abortable sleep that
+ * coalesces bursts into bounded frames.
+ * @module @deepseek-ai/dsh-api-job-controller/wake
+ */
+
+/** Wake-flag waiter: a wake between waits is never lost. */
+export class OutputWaiter {
+  private dirty = false
+  private resolve: (() => void) | undefined
+
+  /** Record one wake; releases a pending wait or arms the next one. */
+  wake(): void {
+    this.dirty = true
+    this.resolve?.()
+  }
+
+  /**
+   * Resolve on the next wake, immediately when one already arrived, or on abort.
+   * @param signal - generation cancellation.
+   * @returns settles when woken or aborted.
+   */
+  wait(signal: AbortSignal): Promise<void> {
+    if (this.dirty || signal.aborted) {
+      this.dirty = false
+      return Promise.resolve()
+    }
+    return new Promise((resolve) => {
+      const finish = (): void => {
+        signal.removeEventListener('abort', finish)
+        /* v8 ignore next -- one wait owns the sole installed resolver. */
+        if (this.resolve === finish) this.resolve = undefined
+        this.dirty = false
+        resolve()
+      }
+      this.resolve = finish
+      signal.addEventListener('abort', finish, { once: true })
+    })
+  }
+}
+
+/**
+ * Sleep for the coalescing window, or return at once when aborted.
+ * @param ms - window in milliseconds.
+ * @param signal - generation cancellation.
+ * @returns settles after the window or on abort.
+ */
+export function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve()
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms)
+    function done(): void {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', done)
+      resolve()
+    }
+    signal.addEventListener('abort', done, { once: true })
+  })
+}
diff --git a/packages/api/job-controller/tests/built-lib.e2e.ts b/packages/api/job-controller/tests/built-lib.e2e.ts
new file mode 100644
index 0000000000..e0d45bdce3
--- /dev/null
+++ b/packages/api/job-controller/tests/built-lib.e2e.ts
@@ -0,0 +1,42 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Built-artifact smoke for the generated job Remote codecs. This package's
+ * program compiles only the `JobKindMap` merges it can see (`bash`,
+ * `subagent`), while the Host registers `pwsh`, `pty-send`, and every other
+ * producer kind, so the wire projection's `kind` must reach the codec as an
+ * open string rather than the literal union this program observes.
+ */
+
+const artifact = join(fileURLToPath(new URL('..', import.meta.url)), 'lib/typert.host.js')
+
+interface BuiltInvocation {
+  readonly method: string
+  readonly result: { create(): { safeParse(value: unknown): { success: boolean } } }
+}
+
+const row = {
+  id: 'pty-send-1',
+  kind: 'pty-send',
+  label: 'send',
+  status: 'running',
+  startedAt: 1,
+  output: { total: 0, earliest: 0 },
+}
+
+describe.skipIf(!existsSync(artifact))('job Remote built codecs', () => {
+  it('accept a row whose kind this program never compiled, and still reject a status outside the lifecycle', async () => {
+    const { TYPERT } = await import(pathToFileURL(artifact).href) as { TYPERT: { invocations: readonly BuiltInvocation[] } }
+    const schemaOf = (method: string): ReturnType<BuiltInvocation['result']['create']> => {
+      const invocation = TYPERT.invocations.find(candidate => candidate.method === method)
+      if (invocation === undefined) throw new Error(`no generated job.${method} invocation`)
+      return invocation.result.create()
+    }
+    expect(schemaOf('list').safeParse({ type: 'rows', jobs: [row] }).success).toBe(true)
+    expect(schemaOf('follow').safeParse({ type: 'opened', job: row, from: 0 }).success).toBe(true)
+    expect(schemaOf('follow').safeParse({ type: 'status', job: { ...row, status: 'paused' } }).success).toBe(false)
+  })
+})
diff --git a/packages/api/job-controller/tests/client-apply.client.spec.ts b/packages/api/job-controller/tests/client-apply.client.spec.ts
new file mode 100644
index 0000000000..0dd43b6f41
--- /dev/null
+++ b/packages/api/job-controller/tests/client-apply.client.spec.ts
@@ -0,0 +1,73 @@
+import { Context } from '@deepseek-ai/cordis'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import { RemoteStream, type RemoteStreamOptions } from '@deepseek-ai/dsh-api-gateway/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as JobClient from '../src/client/index.ts'
+import type { JobFollowFrame, JobListFrame } from '../src/types.ts'
+
+const contexts = new Set<Context>()
+
+afterEach(async () => {
+  await Promise.all([...contexts].map(async (ctx) => { await ctx.fiber.dispose() }))
+  contexts.clear()
+})
+
+/** Mount the client half over a captured `remote.job` namespace and a real Gateway stream carrier. */
+async function mount(): Promise<{ ctx: Context; observeCalls: unknown[]; rowsCalls: unknown[] }> {
+  const ctx = new Context()
+  contexts.add(ctx)
+  const observeCalls: unknown[] = []
+  const rowsCalls: unknown[] = []
+  const connection: ConnectionHandle = {
+    isLoopback: true,
+    generation: { getSnapshot: () => ({ id: 1, host: { home: '/home/fixture' } }), subscribe: () => () => {} },
+    state: { getSnapshot: () => 'connected' as const, subscribe: () => () => {} },
+    rpc: { call: () => Promise.reject(new Error('unexpected generic RPC call')) },
+    reconnect: () => {},
+    registerGenerationSource: () => () => {},
+    start: () => ({ stop: () => {} }),
+  }
+  const job = {
+    // The fake streams never yield; opening and releasing must leave no state behind.
+    list: (request: unknown) => {
+      rowsCalls.push(request)
+      return (async function* (): AsyncGenerator<JobListFrame> {})()
+    },
+    follow: (request: unknown) => {
+      observeCalls.push(request)
+      return (async function* (): AsyncGenerator<JobFollowFrame> {})()
+    },
+  }
+  ctx.reflect.provide('remote', {
+    $stream: <Item>(options: RemoteStreamOptions<Item>) => new RemoteStream(connection, options),
+    job,
+  })
+  ctx.reflect.provide('remote.job', job)
+  await ctx.plugin(JobClient)
+  return { ctx, observeCalls, rowsCalls }
+}
+
+async function flush(): Promise<void> {
+  for (let index = 0; index < 12; index++) await Promise.resolve()
+}
+
+describe('Job Controller Client apply', () => {
+  it('declares the Remote services it binds', () => {
+    expect(JobClient.inject).toEqual(['remote', 'remote.job'])
+  })
+
+  it('installs ctx.jobs over the captured job namespace', async () => {
+    const { ctx, observeCalls, rowsCalls } = await mount()
+    expect(ctx.jobs).toBeDefined()
+    const stopRows = ctx.jobs.watchRows('session-1' as SessionId)
+    const stopObserve = ctx.jobs.observe('session-1' as SessionId, 'bash-1' as never)
+    await flush()
+    expect(rowsCalls).toEqual([{ sessionId: 'session-1' }])
+    expect(observeCalls).toEqual([{ sessionId: 'session-1', jobId: 'bash-1' }])
+    stopRows()
+    stopObserve()
+    await flush()
+    expect(ctx.jobs.state.getSnapshot()).toEqual({ rows: {}, observed: {} })
+  })
+})
diff --git a/packages/api/job-controller/tests/host-harness.ts b/packages/api/job-controller/tests/host-harness.ts
new file mode 100644
index 0000000000..85609166b0
--- /dev/null
+++ b/packages/api/job-controller/tests/host-harness.ts
@@ -0,0 +1,101 @@
+import { Context } from '@deepseek-ai/cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { JobAppendOptions, JobHandle, JobOutcome } from '@deepseek-ai/dsh-jobs'
+import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+
+/** A registry with a tiny ring so eviction is cheap to reach. */
+export async function harness(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LocalJobRegistry, { retainBytes: 64, settledRetainBytes: 64 })
+  ctx.jobs.attachController('job-controller-test')
+  return ctx
+}
+
+/** Register a live agent for `rawId` under its own lifecycle scope. */
+export async function registerAgent(ctx: Context, rawId: string): Promise<Agent & { disposeScope: () => Promise<void> }> {
+  const scopeFiber = ctx.plugin(() => {})
+  const id = SessionId(rawId)
+  const session = Session.create(id)
+  const agent: Agent & { disposeScope: () => Promise<void> } = {
+    id,
+    options: {},
+    session,
+    inbox: unsupportedInbox(),
+    status: 'idle',
+    ctx: scopeFiber.ctx,
+    send: () => {},
+    followup: () => {},
+    steer: () => {},
+    inject: () => {},
+    cancel: () => {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
+    disposeScope: () => scopeFiber.dispose(),
+  }
+  await ctx.agents.register(agent)
+  return agent
+}
+
+/**
+ * Start one push-producer job whose `done` settles on demand; expose the
+ * handle's writers. A cancel settles the job as killed unless `slowStop`
+ * keeps it stopping until the test settles it.
+ */
+export function startJob(ctx: Context, options: { label?: string; owner?: SessionId; slowStop?: boolean } = {}) {
+  let settle!: (outcome: JobOutcome) => void
+  let handle!: JobHandle
+  const id = ctx.jobs.start({
+    kind: 'bash',
+    label: options.label ?? 'echo',
+    ...options.owner !== undefined ? { owner: options.owner } : {},
+    run: (job) => {
+      handle = job
+      return {
+        cancel() { if (options.slowStop !== true) settle({ status: 'killed' }) },
+        done: new Promise<JobOutcome>((resolve) => { settle = resolve }),
+      }
+    },
+  })
+  return {
+    id,
+    append: (text: string, opts?: JobAppendOptions) => { handle.append(text, opts) },
+    progress: (line: string) => { handle.updateProgress(line) },
+    settle: async (outcome: JobOutcome) => {
+      settle(outcome)
+      await new Promise(resolve => setTimeout(resolve, 0))
+    },
+  }
+}
+
+/** Read frames until `count` arrive or the generator finishes, then abort. */
+export async function collect<Frame>(
+  iterable: AsyncIterable<Frame>,
+  count: number,
+  abort: AbortController,
+): Promise<Frame[]> {
+  const frames: Frame[] = []
+  const iterator = iterable[Symbol.asyncIterator]()
+  try {
+    while (frames.length < count) {
+      const step = await iterator.next()
+      if (step.done) return frames
+      frames.push(step.value)
+    }
+  } finally {
+    abort.abort()
+    await iterator.next().catch(() => undefined)
+  }
+  return frames
+}
+
+export const wait = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))
+
+/** The next yielded frame, or undefined once the generator finished. */
+export async function next<Frame>(iterator: AsyncIterator<Frame>): Promise<Frame | undefined> {
+  const step = await iterator.next()
+  return step.done === true ? undefined : step.value
+}
diff --git a/packages/api/job-controller/tests/model.client.spec.ts b/packages/api/job-controller/tests/model.client.spec.ts
new file mode 100644
index 0000000000..1c56724a26
--- /dev/null
+++ b/packages/api/job-controller/tests/model.client.spec.ts
@@ -0,0 +1,567 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { ClientJobsModel } from '../src/client/model.ts'
+import { ClientJobs } from '../src/client/service.ts'
+import type { JobFollowFrame, JobListFrame, JobView } from '../src/types.ts'
+
+const ID = 'bash-1' as JobId
+const S1 = 'alice' as SessionId
+const S2 = 'bob' as SessionId
+
+function view(over: Partial<JobView> = {}): JobView {
+  return {
+    id: ID, kind: 'bash', label: 'pnpm run build', status: 'running', startedAt: 5,
+    output: { total: 0, earliest: 0 },
+    ...over,
+  }
+}
+
+function opened(model: ClientJobsModel, over: Partial<{ from: number; earliest: number; total: number }> = {}): void {
+  model.observeOpened(ID, {
+    type: 'opened',
+    job: view({ output: { total: over.total ?? 0, earliest: over.earliest ?? 0 } }),
+    from: over.from ?? 0,
+  })
+}
+
+describe('ClientJobsModel rows', () => {
+  it('replaces a session roster whole, stores an empty set as absence, and drops on release', () => {
+    const model = new ClientJobsModel()
+    let notified = 0
+    model.subscribe(() => { notified += 1 })
+    model.rowsReplaced(S1, [view()])
+    model.rowsReplaced(S2, [view({ id: 'pwsh-1' as JobId, label: 'other' })])
+    expect(model.getSnapshot().rows[S1]).toEqual([view()])
+    expect(model.getSnapshot().rows[S2]?.[0]?.label).toBe('other')
+
+    // Last-wins: the newer whole set replaces, it does not merge.
+    model.rowsReplaced(S1, [view({ status: 'completed' })])
+    expect(model.getSnapshot().rows[S1]).toEqual([view({ status: 'completed' })])
+    expect(notified).toBe(3)
+
+    model.rowsReplaced(S1, [])
+    expect(S1 in model.getSnapshot().rows).toBe(false)
+    // An empty set over an absent key changes nothing.
+    model.rowsReplaced(S1, [])
+    expect(notified).toBe(4)
+
+    model.rowsDropped(S2)
+    expect(model.getSnapshot().rows).toEqual({})
+    model.rowsDropped(S2)
+    expect(notified).toBe(5)
+  })
+})
+
+describe('ClientJobsModel observation', () => {
+  it('accumulates output, advances the resume cursor, and closes on settlement', () => {
+    const model = new ClientJobsModel()
+    opened(model)
+    expect(model.cursorOf(ID)).toBe(0)
+    model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'a' }, { at: 1, text: 'b' }], next: 2 })
+    model.observeOutput(ID, { type: 'output', chunks: [{ at: 2, text: 'c' }], next: 3 })
+    expect(model.cursorOf(ID)).toBe(3)
+    const live = model.getSnapshot().observed[String(ID)]
+    expect(live?.text).toBe('abc')
+    expect(live?.streaming).toBe(true)
+    model.observeSettled(ID)
+    expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false)
+  })
+
+  it('keeps snapshot identity stable between changes and notifies subscribers', () => {
+    const model = new ClientJobsModel()
+    let notified = 0
+    const unsubscribe = model.subscribe(() => { notified += 1 })
+    const before = model.getSnapshot()
+    expect(model.getSnapshot()).toBe(before)
+    opened(model)
+    expect(notified).toBe(1)
+    expect(model.getSnapshot()).not.toBe(before)
+    unsubscribe()
+    model.observeStopped(ID)
+    expect(notified).toBe(1)
+  })
+
+  it('marks gaps from lossy frames, gap chunks, and a resume behind the retained head', () => {
+    const model = new ClientJobsModel()
+    opened(model, { from: 4, earliest: 8, total: 10 })
+    expect(model.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true)
+
+    const clean = new ClientJobsModel()
+    opened(clean)
+    clean.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'x', gapBefore: true }], next: 1 })
+    expect(clean.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true)
+
+    const lossy = new ClientJobsModel()
+    opened(lossy)
+    lossy.observeOutput(ID, { type: 'output', chunks: [], next: 5, lossy: true })
+    expect(lossy.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true)
+  })
+
+  it('marks a fresh observation anchored past the evicted head', () => {
+    // Fresh observations anchor at the registry's earliest retained byte, so
+    // from === earliest > 0 means the head was already discarded.
+    const fresh = new ClientJobsModel()
+    opened(fresh, { from: 60_240, earliest: 60_240, total: 321_328 })
+    expect(fresh.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true)
+
+    // A retry that accumulated no text yet earns the mark the same way.
+    const retried = new ClientJobsModel()
+    opened(retried)
+    expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(false)
+    opened(retried, { from: 6, earliest: 6, total: 6 })
+    expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true)
+  })
+
+  it('bounds the render tail without splitting a surrogate pair', () => {
+    const model = new ClientJobsModel()
+    opened(model)
+    const emoji = '😀'.repeat((64 * 1024) + 8)
+    model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: emoji }], next: emoji.length * 2 })
+    const live = model.getSnapshot().observed[String(ID)]
+    expect(live?.gapBefore).toBe(true)
+    expect(live!.text.length).toBeLessThanOrEqual(128 * 1024)
+    // The bound landed between pairs: the surviving text still round-trips.
+    expect(/^(?:😀)+$/u.test(live!.text)).toBe(true)
+  })
+
+  it('trims a plain-ASCII tail without a boundary shift', () => {
+    const model = new ClientJobsModel()
+    opened(model)
+    const long = 'x'.repeat((128 * 1024) + 5)
+    model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: long }], next: long.length })
+    const live = model.getSnapshot().observed[String(ID)]
+    expect(live?.text.length).toBe(128 * 1024)
+    expect(live?.gapBefore).toBe(true)
+  })
+
+  it('advances the cut past a low surrogate landing exactly on the bound', () => {
+    const model = new ClientJobsModel()
+    opened(model)
+    // 'z' + one emoji + odd ASCII tail puts a low surrogate exactly at the cut index.
+    const text = 'z😀' + 'a'.repeat((128 * 1024) - 1)
+    model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text }], next: text.length })
+    const live = model.getSnapshot().observed[String(ID)]
+    expect(live?.text.length).toBe((128 * 1024) - 1)
+    expect(live?.text.startsWith('a')).toBe(true)
+  })
+
+  it('preserves accumulated text across a reconnect anchor and clears on stop', () => {
+    const model = new ClientJobsModel()
+    opened(model)
+    model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'kept' }], next: 4 })
+    opened(model, { from: 4, earliest: 0, total: 4 })
+    expect(model.getSnapshot().observed[String(ID)]?.text).toBe('kept')
+    model.observeStopped(ID)
+    expect(model.getSnapshot().observed[String(ID)]).toBeUndefined()
+    expect(model.cursorOf(ID)).toBeUndefined()
+    // A second stop is inert.
+    model.observeStopped(ID)
+  })
+
+  it('records a terminal stream failure on the live view, or on a fresh view before the anchor', () => {
+    const model = new ClientJobsModel()
+    opened(model)
+    model.observeFailed(ID, new Error('carrier gone'))
+    const live = model.getSnapshot().observed[String(ID)]
+    expect(live?.streaming).toBe(false)
+    expect(live?.error).toContain('carrier gone')
+    // A failure before any anchor still surfaces: the panel gets the notice on
+    // an empty, non-streaming view, and a retry anchors from no cursor.
+    model.observeFailed('bash-9' as JobId, new Error('ended before its anchor'))
+    const early = model.getSnapshot().observed['bash-9']
+    expect(early).toMatchObject({ jobId: 'bash-9', text: '', gapBefore: false, streaming: false })
+    expect(early?.error).toContain('ended before its anchor')
+    expect(model.cursorOf('bash-9' as JobId)).toBeUndefined()
+  })
+})
+
+/** One scripted logical stream: frames are pushed by the test, never reopened. */
+class FakeStream<Frame> {
+  disposed = false
+  /** Model a carrier whose disposal surfaces as an iterator throw. */
+  throwOnDispose = false
+  /** Hold the dispose promise open until {@link releaseDispose}. */
+  deferDispose = false
+  private disposeRelease: (() => void) | undefined
+  private disposePending: Promise<void> | undefined
+  private readonly frames: Frame[] = []
+  private waiter: (() => void) | undefined
+  private failure: Error | undefined
+  readonly accepts: number[] = []
+
+  push(frame: Frame): void {
+    this.frames.push(frame)
+    this.waiter?.()
+  }
+
+  poison(error: Error): void {
+    this.failure = error
+    this.waiter?.()
+  }
+
+  dispose(): Promise<void> {
+    if (this.throwOnDispose && this.failure === undefined) {
+      this.failure = new Error('carrier tore down')
+    } else {
+      this.disposed = true
+    }
+    this.waiter?.()
+    if (this.deferDispose) {
+      // Repeat disposals (releaser plus the consumer's finally) share one
+      // deferred promise, so releaseDispose resumes every waiter.
+      this.disposePending ??= new Promise((resolve) => { this.disposeRelease = resolve })
+      return this.disposePending
+    }
+    return Promise.resolve()
+  }
+
+  releaseDispose(): void {
+    this.disposeRelease?.()
+  }
+
+  async *[Symbol.asyncIterator]() {
+    let generation = 1
+    while (!this.disposed) {
+      if (this.failure !== undefined) throw this.failure
+      const frame = this.frames.shift()
+      if (frame === undefined) {
+        await new Promise<void>((resolve) => { this.waiter = resolve })
+        continue
+      }
+      yield {
+        generation,
+        value: frame,
+        signal: new AbortController().signal,
+        accept: () => { this.accepts.push(generation) },
+      }
+      generation = 1
+    }
+  }
+}
+
+interface StreamOptions {
+  name: string
+  open: (signal: AbortSignal) => unknown
+  ended: (accepted: boolean) => Error
+}
+
+function bench() {
+  const ctx = new Context()
+  const model = new ClientJobsModel()
+  const streams: { options: StreamOptions; stream: FakeStream<JobFollowFrame> & FakeStream<JobListFrame> }[] = []
+  const observeCalls: unknown[] = []
+  const rowsCalls: unknown[] = []
+  const remote = {
+    $stream: (options: StreamOptions) => {
+      const stream = new FakeStream<never>()
+      streams.push({ options, stream })
+      return stream
+    },
+    job: {
+      follow: (request: unknown) => {
+        observeCalls.push(request)
+        return { [Symbol.asyncIterator]: async function* () { /* never yields */ } }
+      },
+      list: (request: unknown) => {
+        rowsCalls.push(request)
+        return { [Symbol.asyncIterator]: async function* () { /* never yields */ } }
+      },
+    },
+  }
+  const jobs = new ClientJobs(ctx, remote as never, model)
+  return { ctx, model, jobs, streams, observeCalls, rowsCalls }
+}
+
+const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+const anchor = (): JobFollowFrame => ({ type: 'opened', job: view(), from: 0 })
+
+describe('ClientJobs roster streams', () => {
+  it('shares one roster stream per session and drops the rows after the last release', async () => {
+    const { model, jobs, streams, rowsCalls } = bench()
+    const first = jobs.watchRows(S1)
+    const second = jobs.watchRows(S1)
+    jobs.watchRows(S2)
+    expect(streams.map(entry => entry.options.name)).toEqual(['job rows alice', 'job rows bob'])
+    streams[0]!.options.open(new AbortController().signal)
+    expect(rowsCalls.at(-1)).toEqual({ sessionId: 'alice' })
+
+    const { stream } = streams[0]!
+    stream.push({ type: 'rows', jobs: [view()] })
+    await tick()
+    expect(model.getSnapshot().rows[S1]).toEqual([view()])
+    expect(stream.accepts).toHaveLength(1)
+    stream.push({ type: 'rows', jobs: [view({ status: 'completed' })] })
+    await tick()
+    expect(model.getSnapshot().rows[S1]?.[0]?.status).toBe('completed')
+
+    first()
+    first()
+    expect(stream.disposed).toBe(false)
+    second()
+    await tick()
+    expect(stream.disposed).toBe(true)
+    expect(S1 in model.getSnapshot().rows).toBe(false)
+    expect(streams[1]!.stream.disposed).toBe(false)
+  })
+
+  it('classifies a roster end as retryable only after the first frame', () => {
+    const { jobs, streams } = bench()
+    jobs.watchRows(S1)
+    const { options } = streams[0]!
+    expect(options.ended(true).name).toBe('RemoteStreamCarrierError')
+    expect(options.ended(false).name).toBe('Error')
+  })
+
+  it('drops the roster on a terminal stream failure', async () => {
+    const { model, jobs, streams } = bench()
+    jobs.watchRows(S1)
+    const { stream } = streams[0]!
+    stream.push({ type: 'rows', jobs: [view()] })
+    await tick()
+    expect(model.getSnapshot().rows[S1]).toBeDefined()
+    stream.poison(new Error('frame decode broke'))
+    await tick()
+    expect(S1 in model.getSnapshot().rows).toBe(false)
+  })
+
+  it('stays silent when the carrier teardown itself throws after the last release', async () => {
+    const { model, jobs, streams } = bench()
+    const stop = jobs.watchRows(S1)
+    const { stream } = streams[0]!
+    stream.throwOnDispose = true
+    stream.push({ type: 'rows', jobs: [view()] })
+    await tick()
+    // The releaser drops the rows and marks the entry stopped, then its
+    // dispose surfaces as an iterator throw — which the consumer swallows for
+    // a stopped entry instead of dropping twice or failing loud.
+    stop()
+    await tick()
+    expect(model.getSnapshot().rows).toEqual({})
+  })
+
+  it('a re-watch inside the dispose round-trip keeps its fresh rows', async () => {
+    const { model, jobs, streams } = bench()
+    const stop = jobs.watchRows(S1)
+    const first = streams[0]!.stream
+    first.deferDispose = true
+    first.push({ type: 'rows', jobs: [view()] })
+    await tick()
+
+    stop()
+    // Re-watch while the previous generation's dispose is still in flight.
+    jobs.watchRows(S1)
+    const second = streams[1]!.stream
+    second.push({ type: 'rows', jobs: [view({ label: 'fresh' })] })
+    await tick()
+
+    first.releaseDispose()
+    await tick()
+    // The stale post-dispose clear must not blank the successor's rows.
+    expect(model.getSnapshot().rows[S1]?.[0]?.label).toBe('fresh')
+  })
+})
+
+describe('ClientJobs observation streams', () => {
+  it('feeds anchor, output, and terminal frames into the model, then closes', async () => {
+    const { model, jobs, streams } = bench()
+    jobs.observe(undefined, ID)
+    const { stream } = streams[0]!
+    expect(streams[0]!.options.name).toBe('job observation bash-1')
+    stream.push(anchor())
+    stream.push({ type: 'output', chunks: [{ at: 0, text: 'hi' }], next: 2 })
+    await tick()
+    expect(model.getSnapshot().observed[String(ID)]?.text).toBe('hi')
+    expect(stream.accepts).toHaveLength(1)
+
+    stream.push({ type: 'status', job: view({ status: 'completed' }) })
+    await tick()
+    expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false)
+    expect(stream.disposed).toBe(true)
+  })
+
+  it('shares one stream across observers and stops after the last release', async () => {
+    const { model, jobs, streams } = bench()
+    const first = jobs.observe(undefined, ID)
+    const second = jobs.observe(undefined, ID)
+    expect(streams).toHaveLength(1)
+    streams[0]!.stream.push(anchor())
+    await tick()
+
+    first()
+    first()
+    expect(streams[0]!.stream.disposed).toBe(false)
+    second()
+    await tick()
+    expect(streams[0]!.stream.disposed).toBe(true)
+    expect(model.getSnapshot().observed[String(ID)]).toBeUndefined()
+  })
+
+  it('a late release of a superseded observation neither tears down nor clears its successor', async () => {
+    const { model, jobs, streams } = bench()
+    const firstStop = jobs.observe(undefined, ID)
+    const first = streams[0]!.stream
+    first.push(anchor())
+    first.push({ type: 'status', job: view({ status: 'completed' }) })
+    await tick()
+    // A successor observation replaces the settled entry while the first
+    // observer still holds its releaser.
+    const secondStop = jobs.observe(undefined, ID)
+    const second = streams[1]!.stream
+    second.push(anchor())
+    await tick()
+
+    firstStop()
+    await tick()
+    expect(second.disposed).toBe(false)
+    expect(model.getSnapshot().observed[String(ID)]).toBeDefined()
+
+    secondStop()
+    await tick()
+    expect(second.disposed).toBe(true)
+    expect(model.getSnapshot().observed[String(ID)]).toBeUndefined()
+  })
+
+  it('a re-observation inside the dispose round-trip keeps its fresh view', async () => {
+    const { model, jobs, streams } = bench()
+    const stop = jobs.observe(undefined, ID)
+    const first = streams[0]!.stream
+    first.deferDispose = true
+    first.push(anchor())
+    await tick()
+
+    stop()
+    // Re-expand while the previous generation's dispose is still in flight.
+    jobs.observe(undefined, ID)
+    const second = streams[1]!.stream
+    second.push(anchor())
+    await tick()
+
+    first.releaseDispose()
+    await tick()
+    // The stale post-dispose clear must not blank the successor's view.
+    expect(model.getSnapshot().observed[String(ID)]).toBeDefined()
+    second.push({ type: 'output', chunks: [{ at: 0, text: 'alive' }], next: 5 })
+    await tick()
+    expect(model.getSnapshot().observed[String(ID)]?.text).toBe('alive')
+  })
+
+  it('opens a fresh stream for a re-observed job and resumes from the model cursor', async () => {
+    const { jobs, streams, observeCalls, model } = bench()
+    const stop = jobs.observe(S1, ID)
+    streams[0]!.stream.push(anchor())
+    streams[0]!.stream.push({ type: 'output', chunks: [{ at: 0, text: 'abc' }], next: 3 })
+    await tick()
+    // The generation opener reads the live cursor at open time and carries the
+    // fenced-read session.
+    streams[0]!.options.open(new AbortController().signal)
+    expect(observeCalls.at(-1)).toEqual({ jobId: ID, sessionId: 'alice', from: 3 })
+
+    stop()
+    await tick()
+    jobs.observe(undefined, ID)
+    expect(streams).toHaveLength(2)
+    streams[1]!.options.open(new AbortController().signal)
+    // Stopped observation dropped the cursor: the fresh stream starts unanchored.
+    expect(observeCalls.at(-1)).toEqual({ jobId: ID })
+    expect(model.cursorOf(ID)).toBeUndefined()
+  })
+
+  it('classifies a premature end as retryable only after the anchor', () => {
+    const { jobs, streams } = bench()
+    jobs.observe(undefined, ID)
+    const { options } = streams[0]!
+    expect(options.ended(true).name).toBe('RemoteStreamCarrierError')
+    expect(options.ended(false).name).toBe('Error')
+  })
+
+  it('records a consumer failure on the live view', async () => {
+    const { model, jobs, streams } = bench()
+    jobs.observe(undefined, ID)
+    const { stream } = streams[0]!
+    stream.push(anchor())
+    await tick()
+    stream.poison(new Error('frame decode broke'))
+    await tick()
+    const live = model.getSnapshot().observed[String(ID)]
+    expect(live?.error).toContain('frame decode broke')
+    expect(live?.streaming).toBe(false)
+  })
+
+  it('treats a release after service disposal as inert and stays silent for post-stop failures', async () => {
+    const { ctx, model, jobs, streams } = bench()
+    const stop = jobs.observe(undefined, ID)
+    const { stream } = streams[0]!
+    stream.push(anchor())
+    await tick()
+    // Poison wakes the consumer, but the synchronous stop lands first, so the
+    // failure arrives on an already-stopped entry and stays silent.
+    stream.poison(new Error('after stop'))
+    stop()
+    await tick()
+    expect(model.getSnapshot().observed[String(ID)]).toBeUndefined()
+
+    const second = jobs.observe(undefined, ID)
+    await ctx.fiber.dispose()
+    // The disposal path already removed every entry; a live releaser whose
+    // entry is gone is inert.
+    second()
+  })
+
+  it('stays silent when the carrier teardown itself throws after a stop', async () => {
+    const { model, jobs, streams } = bench()
+    const stop = jobs.observe(undefined, ID)
+    const { stream } = streams[0]!
+    stream.throwOnDispose = true
+    stream.push(anchor())
+    await tick()
+    // The releaser marks the entry stopped, then its dispose surfaces as an
+    // iterator throw — which the consumer swallows for a stopped entry.
+    stop()
+    await tick()
+    expect(model.getSnapshot().observed[String(ID)]?.error).toBeUndefined()
+  })
+
+  it('holds service disposal until every open stream reports quiescence', async () => {
+    const { ctx, jobs, streams } = bench()
+    jobs.watchRows(S1)
+    jobs.observe(undefined, ID)
+    for (const { stream } of streams) stream.deferDispose = true
+    await tick()
+
+    let settled = false
+    const disposal = ctx.fiber.dispose().then(() => { settled = true })
+    await tick()
+    // Both carriers were told to stop, but neither iterator has closed yet:
+    // the fiber must still be unloading, or a successor plugin instance could
+    // overlap the old generation's iterator.
+    expect(streams.every(entry => entry.stream.disposed)).toBe(true)
+    expect(settled).toBe(false)
+
+    streams[0]!.stream.releaseDispose()
+    await tick()
+    expect(settled).toBe(false)
+    streams[1]!.stream.releaseDispose()
+    await disposal
+    expect(settled).toBe(true)
+  })
+
+  it('records a terminal stream failure and service disposal closes live streams', async () => {
+    const { ctx, model, jobs, streams } = bench()
+    jobs.observe(undefined, ID)
+    const failing = streams[0]!.stream
+    failing.push(anchor())
+    await tick()
+    // Simulate a terminal consumer failure by disposing the underlying stream:
+    // the consumer loop ends without a status frame and cleans up.
+    const spy = vi.spyOn(model, 'observeFailed')
+    await failing.dispose()
+    await tick()
+
+    jobs.observe(undefined, 'bash-2' as JobId)
+    await ctx.fiber.dispose()
+    expect(streams.every(entry => entry.stream.disposed)).toBe(true)
+    expect(spy).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/api/job-controller/tests/observe.host.spec.ts b/packages/api/job-controller/tests/observe.host.spec.ts
new file mode 100644
index 0000000000..583862eeac
--- /dev/null
+++ b/packages/api/job-controller/tests/observe.host.spec.ts
@@ -0,0 +1,305 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { JobId } from '@deepseek-ai/dsh-jobs'
+import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import { JobController } from '../src/index.ts'
+import { observeJobOutput } from '../src/observe.ts'
+import type { ObserveJobOptions } from '../src/observe.ts'
+import type { JobFollowFrame } from '../src/types.ts'
+import { collect, harness, next, registerAgent, startJob, wait } from './host-harness.ts'
+
+const OBSERVE: ObserveJobOptions = { flushMs: 5, maxFrameBytes: 1024 }
+
+describe('observeJobOutput', () => {
+  function observed(ctx: Context, request: { jobId: JobId; sessionId?: SessionId; from?: number }) {
+    const abort = new AbortController()
+    const frames: JobFollowFrame[] = []
+    const stream = observeJobOutput(ctx.jobs, request, OBSERVE, abort.signal)
+    const done = (async () => {
+      for await (const frame of stream) frames.push(frame)
+    })()
+    return { abort, frames, done }
+  }
+
+  it('anchors, streams coalesced output, and closes with the terminal projection', async () => {
+    const ctx = await harness()
+    const job = startJob(ctx)
+    job.append('early ')
+    const { frames, done } = observed(ctx, { jobId: job.id })
+    await wait(20)
+    job.append('live', { channel: 'stderr' })
+    await wait(20)
+    await job.settle({ status: 'completed', detail: 'exit code: 0' })
+    await done
+
+    expect(frames[0]).toMatchObject({
+      type: 'opened',
+      from: 0,
+      job: { id: job.id, status: 'running', output: { earliest: 0, total: 6 } },
+    })
+    const outputs = frames.filter(frame => frame.type === 'output')
+    const text = outputs.flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('')
+    expect(text).toBe('early live')
+    expect(outputs.at(-1)?.next).toBe(10)
+    expect(outputs.flatMap(frame => frame.chunks).find(chunk => chunk.text === 'live')?.channel).toBe('stderr')
+    expect(frames.at(-1)).toMatchObject({
+      type: 'status',
+      job: { status: 'completed', detail: 'exit code: 0', output: { total: 10 } },
+    })
+  })
+
+  it('resumes from an explicit offset and flags an evicted resume lossy', async () => {
+    const ctx = await harness()
+    const job = startJob(ctx, { label: 'spam' })
+    job.append('a'.repeat(60))
+    job.append('b'.repeat(60))
+    await job.settle({ status: 'completed' })
+
+    const fresh = observed(ctx, { jobId: job.id, from: 0 })
+    await fresh.done
+    const output = fresh.frames.find(frame => frame.type === 'output')
+    expect(output?.lossy).toBe(true)
+    expect(output?.chunks.map(chunk => chunk.text).join('')).toBe('b'.repeat(60))
+
+    const resumed = observed(ctx, { jobId: job.id, from: 120 })
+    await resumed.done
+    expect(resumed.frames.some(frame => frame.type === 'output')).toBe(false)
+    expect(resumed.frames.at(-1)?.type).toBe('status')
+  })
+
+  it('splits oversized reads along the frame budget', async () => {
+    const ctx = await harness()
+    const job = startJob(ctx, { label: 'wide' })
+    job.append('x'.repeat(30))
+    job.append('y'.repeat(30))
+    await job.settle({ status: 'completed' })
+    const abort = new AbortController()
+    const frames = await collect<JobFollowFrame>(
+      observeJobOutput(ctx.jobs, { jobId: job.id }, { flushMs: 5, maxFrameBytes: 30 }, abort.signal),
+      5,
+      abort,
+    )
+    const outputs = frames.filter(frame => frame.type === 'output')
+    expect(outputs).toHaveLength(2)
+    expect(outputs[0]?.next).toBe(30)
+    expect(outputs[1]?.next).toBe(60)
+  })
+
+  it('carries the lossy flag on the first frame of a split evicted read', async () => {
+    const ctx = await harness()
+    const job = startJob(ctx, { label: 'evicted split' })
+    job.append('a'.repeat(40))
+    job.append('b'.repeat(40))
+    job.append('c'.repeat(40))
+    await job.settle({ status: 'completed' })
+    const abort = new AbortController()
+    const frames = await collect<JobFollowFrame>(
+      observeJobOutput(ctx.jobs, { jobId: job.id, from: 0 }, { flushMs: 5, maxFrameBytes: 40 }, abort.signal),
+      5,
+      abort,
+    )
+    const outputs = frames.filter(frame => frame.type === 'output')
+    expect(outputs[0]?.lossy).toBe(true)
+    expect(outputs[1]?.lossy).toBeUndefined()
+  })
+
+  it('reads owned output through the request session and rejects foreign, bad, and unknown input', async () => {
+    const ctx = await harness()
+    const owner = await registerAgent(ctx, 'alice')
+    const job = startJob(ctx, { label: 'secret', owner: owner.id })
+    job.append('classified')
+    await job.settle({ status: 'completed' })
+
+    const { frames, done } = observed(ctx, { jobId: job.id, sessionId: owner.id })
+    await done
+    expect(frames.some(frame => frame.type === 'output'
+      && frame.chunks.some(chunk => chunk.text === 'classified'))).toBe(true)
+
+    const foreign = new AbortController()
+    await expect(collect(
+      observeJobOutput(ctx.jobs, { jobId: job.id }, OBSERVE, foreign.signal),
+      1,
+      foreign,
+    )).rejects.toThrow(/belongs to another session/)
+
+    const abort = new AbortController()
+    await expect(collect(
+      observeJobOutput(ctx.jobs, { jobId: job.id, sessionId: owner.id, from: -1 }, OBSERVE, abort.signal),
+      1,
+      abort,
+    )).rejects.toThrow(/invalid observe offset/)
+
+    const abortUnknown = new AbortController()
+    await expect(collect(
+      observeJobOutput(ctx.jobs, { jobId: JobId('bash-999') }, OBSERVE, abortUnknown.signal),
+      1,
+      abortUnknown,
+    )).rejects.toThrow(/unknown job/)
+  })
+
+  it('anchors with the live progress and takes the fast wait path for a wake that lands mid-yield', async () => {
+    const ctx = await harness()
+    const job = startJob(ctx)
+    job.progress('3/10')
+    const abort = new AbortController()
+    const iterator = observeJobOutput(ctx.jobs, { jobId: job.id }, OBSERVE, abort.signal)[Symbol.asyncIterator]()
+
+    const anchor = await iterator.next()
+    expect(anchor.value).toMatchObject({ type: 'opened', job: { progress: '3/10' } })
+    // Both chunks land while the generator is suspended on a yield, so each
+    // wake precedes the loop's wait(): draining the first chunk must pass
+    // through the already-woken fast path to read the second.
+    job.append('woken')
+    const first = await iterator.next()
+    expect(first.value).toMatchObject({ type: 'output' })
+    job.append('again')
+    const second = await iterator.next()
+    expect(second.value).toMatchObject({ type: 'output' })
+    const pending = iterator.next()
+    await job.settle({ status: 'completed' })
+    const status = await pending
+    expect(status.value).toMatchObject({ type: 'status', job: { status: 'completed' } })
+    expect((await iterator.next()).done).toBe(true)
+  })
+
+  it('ignores output signals for other jobs while waiting', async () => {
+    const ctx = await harness()
+    const watched = startJob(ctx, { label: 'watched' })
+    const noisy = startJob(ctx, { label: 'noisy' })
+    const { abort, frames, done } = observed(ctx, { jobId: watched.id })
+    await wait(15)
+    noisy.append('unrelated')
+    await wait(15)
+    await watched.settle({ status: 'completed' })
+    await done
+    abort.abort()
+    expect(frames.filter(frame => frame.type === 'output')).toEqual([])
+    await noisy.settle({ status: 'completed' })
+  })
+
+  it("closes with the removed job's terminal projection when the owner's teardown drops it mid-observation", async () => {
+    const ctx = await harness()
+    const owner = await registerAgent(ctx, 'observer-owner')
+    const job = startJob(ctx, { label: 'torn down', owner: owner.id })
+    job.append('partial')
+    const { frames, done } = observed(ctx, { jobId: job.id, sessionId: owner.id })
+    await wait(20)
+    // Teardown cancels, settles, and removes the record within one microtask
+    // chain; the generation wakes on the removal and closes without a read.
+    await owner.disposeScope()
+    await done
+    expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status'])
+    expect(frames.at(-1)).toMatchObject({ type: 'status', job: { id: job.id, status: 'killed' } })
+    expect(() => ctx.jobs.get(job.id, owner.id)).toThrow(/unknown job/)
+  })
+
+  it('stops cleanly on abort while waiting for output', async () => {
+    const ctx = await harness()
+    const job = startJob(ctx, { label: 'idle' })
+    const { abort, frames, done } = observed(ctx, { jobId: job.id })
+    await wait(20)
+    abort.abort()
+    await done
+    expect(frames[0]?.type).toBe('opened')
+    expect(frames.at(-1)?.type).not.toBe('status')
+    await job.settle({ status: 'completed' })
+  })
+})
+
+describe('JobController', () => {
+  async function controllerHarness() {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(LocalJobRegistry)
+    await ctx.plugin(TypertRegistry)
+    ctx.jobs.attachController('job-controller-test')
+    await ctx.plugin(JobController, {})
+    return ctx
+  }
+
+  async function liveOwner(ctx: Context, rawId: string): Promise<Agent> {
+    const session = ctx.sessions.create(SessionId(rawId))
+    const owner: Agent = {
+      id: session.id,
+      options: {},
+      session,
+      inbox: unsupportedInbox(),
+      status: 'idle',
+      ctx,
+      send: () => {},
+      followup: () => {},
+      steer: () => {},
+      inject: () => {},
+      cancel: () => {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
+    }
+    await ctx.agents.register(owner)
+    return owner
+  }
+
+  it('waits for the job registry instead of serving without one', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TypertRegistry)
+    ctx.plugin(JobController, {})
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(ctx.get('jobController')).toBeUndefined()
+  })
+
+  it('observe reads an owned job through the request session', async () => {
+    const ctx = await controllerHarness()
+    const owner = await liveOwner(ctx, 'observing-session')
+    const job = startJob(ctx, { label: 'owned run', owner: owner.id })
+    job.append('hi')
+    await job.settle({ status: 'completed' })
+
+    const abort = new AbortController()
+    const frames = await collect<JobFollowFrame>(
+      ctx.jobController.follow({ sessionId: owner.id, jobId: job.id }, abort.signal),
+      3,
+      abort,
+    )
+    expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status'])
+  })
+
+  it('observes an unowned job without a request session', async () => {
+    const ctx = await controllerHarness()
+    const job = startJob(ctx, { label: 'unowned run' })
+    job.append('open access')
+    await job.settle({ status: 'completed' })
+
+    const abort = new AbortController()
+    const frames = await collect<JobFollowFrame>(
+      ctx.jobController.follow({ jobId: job.id }, abort.signal),
+      3,
+      abort,
+    )
+    expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status'])
+  })
+
+  it('rows mirrors the session-visible set and follows a settlement', async () => {
+    const ctx = await controllerHarness()
+    const owner = await liveOwner(ctx, 'listing-session')
+    const owned = startJob(ctx, { label: 'owned', owner: owner.id })
+    startJob(ctx, { label: 'shared' })
+
+    const abort = new AbortController()
+    const iterator = ctx.jobController.list({ sessionId: owner.id }, abort.signal)[Symbol.asyncIterator]()
+    const first = await next(iterator)
+    expect(first?.jobs.map(job => job.label)).toEqual(['owned', 'shared'])
+    const pending = next(iterator)
+    await owned.settle({ status: 'completed', detail: 'exit code: 0' })
+    const second = await pending
+    expect(second?.jobs.find(job => job.id === owned.id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' })
+    abort.abort()
+    expect(await next(iterator)).toBeUndefined()
+  })
+})
diff --git a/packages/api/job-controller/tests/rows.host.spec.ts b/packages/api/job-controller/tests/rows.host.spec.ts
new file mode 100644
index 0000000000..48bb30aedc
--- /dev/null
+++ b/packages/api/job-controller/tests/rows.host.spec.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { streamJobRows } from '../src/rows.ts'
+import { harness, next, registerAgent, startJob, wait } from './host-harness.ts'
+
+const ROWS = { flushMs: 5 }
+
+describe('streamJobRows', () => {
+  it('opens with the visible set and re-sends it after each coalesced lifecycle burst', async () => {
+    const ctx = await harness()
+    const alice = await registerAgent(ctx, 'alice')
+    const bob = await registerAgent(ctx, 'bob')
+    startJob(ctx, { label: 'shared' })
+    const mine = startJob(ctx, { label: 'mine', owner: alice.id })
+    startJob(ctx, { label: 'theirs', owner: bob.id })
+
+    const abort = new AbortController()
+    const iterator = streamJobRows(ctx.jobs, { sessionId: alice.id }, ROWS, abort.signal)[Symbol.asyncIterator]()
+    const first = await next(iterator)
+    expect(first?.jobs.map(job => job.label)).toEqual(['shared', 'mine'])
+
+    // Another owner's lifecycle and this job's own output never wake the roster;
+    // the next frame is the one the settlement earns, and it carries the final
+    // byte count without a frame per append.
+    startJob(ctx, { label: 'theirs too', owner: bob.id })
+    mine.append('progress bytes')
+    await wait(20)
+    const pending = next(iterator)
+    await mine.settle({ status: 'completed', detail: 'exit code: 0' })
+    const second = await pending
+    expect(second?.jobs.map(job => job.label)).toEqual(['shared', 'mine'])
+    expect(second?.jobs[1]).toMatchObject({ status: 'completed', detail: 'exit code: 0', output: { total: 14 } })
+    abort.abort()
+    expect(await next(iterator)).toBeUndefined()
+  })
+
+  it('follows progress, stopping, and registration commits', async () => {
+    const ctx = await harness()
+    const alice = await registerAgent(ctx, 'alice')
+    const job = startJob(ctx, { label: 'first', owner: alice.id, slowStop: true })
+    const abort = new AbortController()
+    const iterator = streamJobRows(ctx.jobs, { sessionId: alice.id }, ROWS, abort.signal)[Symbol.asyncIterator]()
+    await next(iterator)
+
+    job.progress('3/10')
+    expect((await next(iterator))?.jobs[0]).toMatchObject({ progress: '3/10' })
+    ctx.jobs.kill(job.id, alice.id, 'enough')
+    expect((await next(iterator))?.jobs[0]).toMatchObject({ status: 'stopping', progress: '3/10' })
+    startJob(ctx, { label: 'second', owner: alice.id })
+    expect((await next(iterator))?.jobs.map(entry => entry.label)).toEqual(['first', 'second'])
+    abort.abort()
+    expect(await next(iterator)).toBeUndefined()
+    await job.settle({ status: 'killed' })
+  })
+
+  it('drops an owner\'s rows when its lifecycle ends, keeping the unowned set', async () => {
+    const ctx = await harness()
+    const alice = await registerAgent(ctx, 'alice')
+    startJob(ctx, { label: 'shared' })
+    startJob(ctx, { label: 'mine', owner: alice.id })
+    const abort = new AbortController()
+    const iterator = streamJobRows(ctx.jobs, { sessionId: alice.id }, ROWS, abort.signal)[Symbol.asyncIterator]()
+    expect((await next(iterator))?.jobs).toHaveLength(2)
+
+    await alice.disposeScope()
+    // Teardown cancels, settles, and removes the owned job; the frames land in
+    // that order, and the last one holds the unowned job alone.
+    let frame = await next(iterator)
+    while (frame !== undefined && frame.jobs.length !== 1) frame = await next(iterator)
+    expect(frame?.jobs.map(job => job.label)).toEqual(['shared'])
+    abort.abort()
+    expect(await next(iterator)).toBeUndefined()
+  })
+
+  it('stops cleanly on abort while idle and refuses an already-aborted signal', async () => {
+    const ctx = await harness()
+    startJob(ctx, { label: 'idle' })
+    const abort = new AbortController()
+    const iterator = streamJobRows(ctx.jobs, { sessionId: 'nobody' as never }, ROWS, abort.signal)[Symbol.asyncIterator]()
+    expect((await next(iterator))?.jobs.map(job => job.label)).toEqual(['idle'])
+    await wait(10)
+    abort.abort()
+    expect(await next(iterator)).toBeUndefined()
+
+    const aborted = new AbortController()
+    aborted.abort()
+    const refused = streamJobRows(ctx.jobs, { sessionId: 'nobody' as never }, ROWS, aborted.signal)[Symbol.asyncIterator]()
+    await expect(refused.next()).rejects.toThrow()
+  })
+})
diff --git a/packages/api/job-controller/tsconfig.client.json b/packages/api/job-controller/tsconfig.client.json
new file mode 100644
index 0000000000..34a2202060
--- /dev/null
+++ b/packages/api/job-controller/tsconfig.client.json
@@ -0,0 +1,23 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "files": [
+    "src/client/index.ts",
+    "src/client/model.ts",
+    "src/client/service.ts",
+    "src/types.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../gateway/tsconfig.client.json" },
+    { "path": "../../client/connection/tsconfig.client.json" },
+    { "path": "../../client/store" },
+    { "path": "../../core/session" },
+    { "path": "../../jobs/jobs" },
+    { "path": "../../typert/protocol" }
+  ]
+}
diff --git a/packages/api/job-controller/tsconfig.host.json b/packages/api/job-controller/tsconfig.host.json
new file mode 100644
index 0000000000..4e5c8c3f01
--- /dev/null
+++ b/packages/api/job-controller/tsconfig.host.json
@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/index.ts",
+    "src/observe.ts",
+    "src/rows.ts",
+    "src/types.ts",
+    "src/wake.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../core/session" },
+    { "path": "../../jobs/jobs" },
+    { "path": "../../typert/protocol" }
+  ]
+}
diff --git a/packages/api/job-controller/tsconfig.json b/packages/api/job-controller/tsconfig.json
new file mode 100644
index 0000000000..2a0b0e33f7
--- /dev/null
+++ b/packages/api/job-controller/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.host.json" },
+    { "path": "./tsconfig.client.json" }
+  ]
+}
diff --git a/packages/api/job-controller/tsdown.config.ts b/packages/api/job-controller/tsdown.config.ts
new file mode 100644
index 0000000000..0391bc61bf
--- /dev/null
+++ b/packages/api/job-controller/tsdown.config.ts
@@ -0,0 +1,7 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle(
+  '@deepseek-ai/dsh-api-job-controller',
+  ['lib/types/index.js'],
+  { hostPhase: true },
+)
diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json
index 8a20b05e13..005d3fbc19 100644
--- a/packages/api/remotes/package.json
+++ b/packages/api/remotes/package.json
@@ -63,8 +63,12 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-presets": "workspace:^",
     "@deepseek-ai/dsh-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-api-job-controller": "workspace:^",
+    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
     "@deepseek-ai/dsh-api-settings-controller": "workspace:^",
     "@deepseek-ai/dsh-api-workspace-controller": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-file-upload": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-cordis-host-runner": "workspace:^",
     "@deepseek-ai/dsh-credentials": "workspace:^",
@@ -73,10 +77,12 @@
     "@deepseek-ai/dsh-host-plugin-inventory": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-message-feedback": "workspace:^",
+    "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-permission-presets": "workspace:^",
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-settings": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",
     "@deepseek-ai/dsh-user-questions": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts
index 5ba2f791fc..d1220b9b93 100644
--- a/packages/api/remotes/src/client/index.ts
+++ b/packages/api/remotes/src/client/index.ts
@@ -17,6 +17,7 @@ import fileUploadsRemote from '@deepseek-ai/dsh-client-file-upload/remote'
 import sessionReferencesRemote from '@deepseek-ai/dsh-session-reference/remote'
 import subagentsRemote from '@deepseek-ai/dsh-subagent/remote'
 import sessionRemote from '@deepseek-ai/dsh-api-session-controller/remote'
+import jobRemote from '@deepseek-ai/dsh-api-job-controller/remote'
 import workspaceRemote from '@deepseek-ai/dsh-api-workspace-controller/remote'
 import terminalRemote from '@deepseek-ai/dsh-api-terminal-controller/remote'
 import workspaceFilesRemote from '@deepseek-ai/dsh-api-workspace-files/remote'
@@ -46,13 +47,14 @@ export type {} from '@deepseek-ai/dsh-subagent/remote'
 export type * from '@deepseek-ai/dsh-subagent/client'
 export type {} from '@deepseek-ai/dsh-api-session-controller/remote'
 export type * from '@deepseek-ai/dsh-api-session-controller/types'
+export type {} from '@deepseek-ai/dsh-api-job-controller/remote'
+export type * from '@deepseek-ai/dsh-api-job-controller/types'
 export type {} from '@deepseek-ai/dsh-api-workspace-controller/remote'
 export type * from '@deepseek-ai/dsh-api-workspace-controller/types'
 export type {} from '@deepseek-ai/dsh-api-workspace-files/remote'
 export type * from '@deepseek-ai/dsh-api-workspace-files/types'
 export type {} from '@deepseek-ai/dsh-api-terminal-controller/remote'
 export type * from '@deepseek-ai/dsh-api-terminal-controller/types'
-export type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types'
 // The forwarded-event allowlist's selection seat: without it in the consumer's
 // compilation face `TypertRemoteEvent` is `never` and every `$on` call fails.
 export type { ApiRemoteForwardedEvent } from '../types.ts'
@@ -168,7 +170,8 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
     for (const contribution of [
       agentPresetsRemote, commandsRemote, settingsControllerRemote, goalsRemote, llmRemote, dynamicRemote,
       pluginInventoryRemote, pluginManagerRemote, messageFeedbackRemote, sessionFeedbackRemote, fileUploadsRemote, sessionReferencesRemote,
-      permissionPresetsRemote, subagentsRemote, sessionRemote, workspaceRemote, workspaceFilesRemote, terminalRemote, officeToPdfRemote,
+      permissionPresetsRemote, subagentsRemote, sessionRemote, jobRemote, workspaceRemote, workspaceFilesRemote, terminalRemote,
+      officeToPdfRemote,
     ]) {
       disposers.push(await ctx.remote.$mount(contribution))
     }
diff --git a/packages/api/remotes/tsconfig.client.json b/packages/api/remotes/tsconfig.client.json
index 301798c890..d7464526d3 100644
--- a/packages/api/remotes/tsconfig.client.json
+++ b/packages/api/remotes/tsconfig.client.json
@@ -68,6 +68,9 @@
     {
       "path": "../../interaction/user-questions"
     },
+    {
+      "path": "../job-controller/tsconfig.client.json"
+    },
     {
       "path": "../session-controller/tsconfig.client.json"
     },
diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml
index f0c39d8dbb..0e8bb05b38 100644
--- a/packages/api/session-controller/README.i18n.yaml
+++ b/packages/api/session-controller/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/session-controller/README.md
-README.md: c9f63d462c6e291abda7312c66c8fffcd7109c57
-README.zh.md: f6d03b45b6bf9d3e809e70154adacd59ce341721
+README.md: 6d8479ea7a88a1a68df559b04cfd13c9f44421cd
+README.zh.md: 2591bbf86fba57deabc0a4282c868d84b24ec105
diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md
index c9f63d462c..6d8479ea7a 100644
--- a/packages/api/session-controller/README.md
+++ b/packages/api/session-controller/README.md
@@ -37,9 +37,13 @@ Explicit-id `session.create` adopts a live Session or resumes a persisted Sessio
 
 Client list refreshes retain unchanged row objects and reuse the items array when order and values match. Each row's `retainedBy` contains positive local reference-source counts; Host metadata refreshes cannot overwrite them. Cache membership checks use a per-refresh ID set, so reconciliation grows linearly with the current list and retained cache sizes. Host summary updates replace running and Agent availability; local create/fork responses only fill missing metadata on existing rows. Removed ordinary Sessions retain projection stores only when their catalogs contain children.
 
+Background-job rows and observation streams belong to [`dsh-api-job-controller`](../job-controller/README.md); the control stream carries projections only.
+
 Projection reads retain loading and failure state independently of their values. Reconnect cancels reads from the previous connection and reloads previously requested projections; live membership updates arrive through the control stream. Parent availability comes from Host summaries and remains unknown until a summary or a successful list baseline establishes it. Address lookup resolves projected children without selecting them or creating scopes.
 
-The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, `append`, and `settle-assistant` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. The Web adapter explicitly opts into cursorless Assistant frames: each opening carries the active attempt's `startedAfterSeq`, `nextIndex`, and compact stream, and every stream member becomes a Client-only `assistant/live-chunk` entry ordered between durable cursors. The Host captures a follower-local arrival ordinal with that baseline and suppresses buffered frames at or before the cut; a replacement Agent may restart frame revision at one. A durable `assistant/message` or `assistant/attempt` arriving after an active opening stays staged only when its seq follows `startedAfterSeq` and its Turn and Step match; the matching end type, seq, and index publishes one named settlement delta that retires the attempt's transient rows and adds the durable entry while earlier same-step retries remain visible. Revision, dense-index, or settlement gaps for a known attempt reopen follow, while a controller that missed the start ignores unknown-attempt frames and publishes their durable settlement normally. An abandoned end publishes a settlement delta without a durable entry so its transient rows retire immediately. A durable gap-repair page has no Assistant baseline, so its held notification reopens follow once for a paired page and baseline. Every history record covers exactly its event seq. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces jobs and projection state instead of treating transient values as durable events. At each ready Host generation, a synchronous Client subscription clears retained projection values and watermarks before refreshing queries and restarting the control stream, including Sessions absent from the control baseline. The first control stream waits for generation readiness, so its opening values cannot precede invalidation. Outstanding list responses from the previous generation cannot republish those values. Within a generation, a delayed control baseline cannot overwrite or clear newer sequenced values, whether they arrived through a live Session's list block, a history page, or a frame; a cached list block, viewed from the projection cache for a cold Session, yields to the connected Session's baseline whatever watermark it carries. The durable `inbox` projection carries both pending lists through the same cold-read and reconnect path as other projections. Client Agent contexts provide the identity used by the independent [`fileUpload`](../../client/file-upload/README.md) service; Session objects expose lifecycle, prompt, queue, and history operations rather than file transfer.
+Accepted prompts and observed running keep their Client display conversion across list refresh, reconnect, and Session-object replacement. The Manager retains these observations by Session id; they do not establish durable history. Drafts, projection stores, and sidebar display rules retain their existing behavior. The [blank rollback decision](../../../.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.md) defines retention and late-response handling.
+
+The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, `append`, and `settle-assistant` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. The Web adapter explicitly opts into cursorless Assistant frames: each opening carries the active attempt's `startedAfterSeq`, `nextIndex`, and compact stream, and every stream member becomes a Client-only `assistant/live-chunk` entry ordered between durable cursors. The Host captures a follower-local arrival ordinal with that baseline and suppresses buffered frames at or before the cut; a replacement Agent may restart frame revision at one. A durable `assistant/message` or `assistant/attempt` arriving after an active opening stays staged only when its seq follows `startedAfterSeq` and its Turn and Step match; the matching end type, seq, and index publishes one named settlement delta that retires the attempt's transient rows and adds the durable entry while earlier same-step retries remain visible. Revision, dense-index, or settlement gaps for a known attempt reopen follow, while a controller that missed the start ignores unknown-attempt frames and publishes their durable settlement normally. An abandoned end publishes a settlement delta without a durable entry so its transient rows retire immediately. A durable gap-repair page has no Assistant baseline, so its held notification reopens follow once for a paired page and baseline. Every history record covers exactly its event seq. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces projection state instead of treating transient values as durable events. At each ready Host generation, a synchronous Client subscription clears retained projection values and watermarks before refreshing queries and restarting the control stream, including Sessions absent from the control baseline. The first control stream waits for generation readiness, so its opening values cannot precede invalidation. Outstanding list responses from the previous generation cannot republish those values. Within a generation, a delayed control baseline cannot overwrite or clear newer sequenced values, whether they arrived through a live Session's list block, a history page, or a frame; a cached list block, viewed from the projection cache for a cold Session, yields to the connected Session's baseline whatever watermark it carries. The durable `inbox` projection carries both pending lists through the same cold-read and reconnect path as other projections. Client Agent contexts provide the identity used by the independent [`fileUpload`](../../client/file-upload/README.md) service; Session objects expose lifecycle, prompt, queue, and history operations rather than file transfer.
 
 The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The echo stores ordered image previews and durable file references. Session derives its `transcript`, `queued`, or `steering` placement from the current running state and requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, including pending messages in the `inbox` projection. An echo retires one animation frame after its durable event or queue occurrence is observed, immediately when its identified prompt fails or is abandoned, and as failed on disposal. Each retirement fires `onRetire` exactly once; an observed retirement includes the ordered durable attachment references so the composer can release successful cards while preserving failed drafts. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone.
 
@@ -61,13 +65,15 @@ Attachment authorization reads declared content fields of built-in Session event
 
 `sessions.retain(target, { source, signal? })` immediately acquires one exact Client generation and starts its shared initial history opening. The target is a known Session id or a durable direct-parent subagent address; the Host validates an explicit address when history opens. The returned reference supports idempotent `release()` and `Symbol.dispose`; its `ready` Promise follows the shared `Session.open()` result and resolves to the exact binding when that attempt settles, including when a Remote failure is represented by `openState: 'error'`. It rejects when `Session.open()` rejects, its waiter is cancelled, or the reference is released early. Cancelling one waiter does not cancel another owner's opening. `sessions.using(target, options, operation)` waits for that settlement, holds its reference until the callback settles, and propagates rejected readiness and callback failures.
 
-References keep local Session data, scoped Contexts, and history streams alive, not Host Agents. Ordinary Session retention never adds a catalog row. Retained subagents with a known direct-parent address keep a fallback row and notify list readers even before the parent catalog arrives; these rows do not join Host-list membership. Fork-title assignment sends rename directly and applies the returned title projection without retaining the child or opening its history. Final release withdraws the generation before teardown; later acquisition can create a new generation with the same id. `binding(id)` and `scope(id)` only borrow an existing generation. `retainInfo(id)` observes stable read-only source counts independently of catalog membership and performs no history I/O. Consumer source keys are declaration-merge extensible; navigation and completion acknowledgement belong to UI consumers, not this Controller. See [Client Session references](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.md) for ownership and teardown rules.
+References keep local Session data, scoped Contexts, and history streams alive, not Host Agents. Ordinary Session retention never adds a catalog row. Retained subagents with a known direct-parent address keep a fallback row and notify list readers even before the parent catalog arrives; these rows do not join Host-list membership. Fork-title assignment sends rename directly and applies the returned title projection without retaining the child or opening its history. Final release withdraws the generation before teardown; later acquisition can create a new generation with the same id. `binding(id)` and `scope(id)` only borrow an existing generation. `retainInfo(id)` observes stable read-only source counts independently of catalog membership and performs no history I/O. Consumer source keys are declaration-merge extensible; navigation and completion acknowledgement belong to UI consumers, not this Controller. See [Client Session references](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.md) for ownership and teardown rules. An unknown-mode subagent address permits history reads with direct-parent validation. Successful descriptor restoration determines the displayed mode; failures remain local to the child, and control requests still require a confirmed continuable identity.
 
 <a id="session-media-references"></a>
 ## Session media references
 
 `SessionMediaReferences` mounts `GET|HEAD /api/file?path=<absolute path>` on the authenticated `connection.fetch` channel when `connection`, `fs`, and `attachments` are composed. It reads ordinary files through `ctx.fs`, including temporary paths outside registered workspaces and files in remote providers. Neither directory containment nor MIME categories restrict access; `mime-types` supplies the response type, with `application/octet-stream` for unknown extensions. GET reuses `readBytes` for preflight and ongoing byte limits; HEAD reads metadata only. All files use `ctx.attachments.imageLimits.maxImageBytes` (normally 20 MiB); exceeding this limit returns 413. Responses contain the complete file, ignore Range, and carry `private, no-store`, `nosniff`, and a sandbox CSP so directly opened HTML/SVG cannot execute with the API origin. The Client rewrite lives in `ui-chat` (`AssistantMarkdown`); audio/video responses are available, while Markdown audio/video player nodes remain separate work.
 
+`workspacePathApplications({ path })` returns the serving desktop’s file handlers after the same filesystem mapping check used by `openWorkspacePath`. An optional `application` in the open request selects a currently registered handler without changing the system default. Application names, default selection, icons, and platform coverage come from [native-command](../../util/native-command/README.md). These operations do not activate an Agent or append Session events. Native failures return bounded messages; original command errors remain Host-side causes.
+
 -----
 
 <a id="configuration"></a>
@@ -95,10 +101,11 @@ No direct effect; model requests remain owned by the Agent and LLM packages.
 <a id="known-limitations-and-deferred-work"></a>
 
 - The image byte cap does not validate decoded dimensions or pixel count.
-- Control baselines represent process-local state and therefore cannot reconstruct jobs after a Host restart.
 - A failed follow resumption remains visible to the caller instead of retrying indefinitely.
 - The raw browser upload is one streaming HTTP request without resumable offsets; a retry sends the file again from byte zero.
 - File-reference completion uses the shared Agent lookup and can resume a cold Session; the `skills/list` catalog is the non-activating alternative for skill metadata.
+- Accepted/running display memory lives only in Client memory and is lost on page reload.
+- That memory is not shared between tabs: one tab can show a converted row while another still shows `New Session` for the same Session.
 
 
 <a id="dev-note"></a>
diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md
index f6d03b45b6..2591bbf86f 100644
--- a/packages/api/session-controller/README.zh.md
+++ b/packages/api/session-controller/README.zh.md
@@ -37,9 +37,13 @@ Client 列表行和驻留 Session 使用当前 `sessionListMetadata` 投影纠
 
 Client 列表刷新保留未变化的行对象，并在顺序和值均相同时复用条目数组。每行的 `retainedBy` 包含正数的本地引用来源计数，Host 元数据刷新不能覆盖它们。缓存成员检查使用每次刷新构建的 ID 集合，因此对账成本随当前列表和保留缓存的规模线性增长。 Host 摘要更新会替换运行状态与 Agent 可用性；本地 create/fork 响应只补充已有行缺失的元数据。普通 Session 被移除后，仅在目录仍有子项时保留其投影 store。
 
+后台 job 的名册行与观测流属于 [`dsh-api-job-controller`](../job-controller/README.zh.md)；控制流只承载投影。
+
 投影读取独立于其值保留加载与失败状态。重连会取消上一连接的读取，并重新加载已请求的投影；实时成员更新通过 control stream 到达。父 Agent 可用性来自 Host 摘要，在收到对应摘要或成功的列表 baseline 前保持未知。地址查找直接解析投影中的子项，不会选择它们或创建 scope。
 
-Client 适配器提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend`、`append` 与 `settle-assistant` 变更，并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词：`loadOlder()` 拉一页 50 条消息，而 `loadThrough(seq)`——轮次跳转加载器——按每页 200 条消息循环拉取直到窗口覆盖目标 seq，重复调用会下调共享目标，遇到无进展的页即停止，忙碌状态复用同一个 `loadingOlder` 快照位。Web 适配器显式选择接收无 cursor 的 Assistant frame：每个 opening 携带活跃 attempt 的 `startedAfterSeq`、`nextIndex` 与紧凑 stream，每个 stream member 都成为排在持久 cursor 之间的 Client-only `assistant/live-chunk` 条目。Host 会随该 baseline 捕获 follower 本地到达序号，并抑制该 cut 及之前的 buffered frame；replacement Agent 可以从 revision 一重新开始。活跃 opening 之后到达的持久 `assistant/message` 或 `assistant/attempt` 只有在其 seq 晚于 `startedAfterSeq` 且轮次与步骤匹配时才会保持暂存；匹配的 end type、seq 与 index 会发布一个具名 settlement delta，删除该 attempt 的瞬态 row、加入持久条目，并保留同一步骤中更早的 retry。已知 attempt 的 revision、密集 index 或 settlement 缺口会重新打开 follow；若 controller 错过 start，则忽略 unknown-attempt frame，并正常发布其持久 settlement。Abandoned end 会发布不含持久条目的 settlement delta，使瞬态 row 立即退出。持久缺口修复 page 不携带 Assistant baseline，因此 held notification 会重新打开 follow 一次，以取得配对的 page 与 baseline。每条历史 record 只覆盖自身的事件 seq。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 jobs 和 projection 状态，而不会把瞬态值当作 durable event。每次 Host generation 就绪时，同步的 Client 订阅会先清除保留的投影值及其水位，再刷新查询并重新打开 control stream，其中也包括 control baseline 中没有列出的 Session。首次 control stream 会等待 generation 就绪，确保其 opening 值不会先于旧状态清理到达。上一代尚未完成的 list 响应无法重新发布这些值。同一 generation 内，延迟到达的 control baseline 不能覆盖或清除较新的 sequenced 值，无论它们来自活 Session 的 list block、history page 还是 frame；冷 Session 从 projection cache 看出来的 cached list block 则不论水位都让位于建连 Session 的 baseline。持久 `inbox` 投影通过与其他投影相同的冷读取和重连路径传输两份待处理列表。Client Agent 上下文提供独立 [`fileUpload`](../../client/file-upload/README.zh.md) 服务使用的身份；Session 对象提供生命周期、prompt、queue 与历史操作，不提供文件传输。
+已受理的提示词与已观察到的运行，会使客户端展示转换跨列表刷新、重连及 Session 对象替换保留。Manager 按 Session id 保留这些观察；它们不证明持久历史已经产生。草稿、投影存储和侧边栏展示规则保留原有行为。[blank 回退修复决策](../../../.agents/notes/implemented/bug-fix/2026-09-15-client-session-blank-reconciliation.zh.md) 定义保留期限及迟到响应处理。
+
+Client 适配器提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend`、`append` 与 `settle-assistant` 变更，并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词：`loadOlder()` 拉一页 50 条消息，而 `loadThrough(seq)`——轮次跳转加载器——按每页 200 条消息循环拉取直到窗口覆盖目标 seq，重复调用会下调共享目标，遇到无进展的页即停止，忙碌状态复用同一个 `loadingOlder` 快照位。Web 适配器显式选择接收无 cursor 的 Assistant frame：每个 opening 携带活跃 attempt 的 `startedAfterSeq`、`nextIndex` 与紧凑 stream，每个 stream member 都成为排在持久 cursor 之间的 Client-only `assistant/live-chunk` 条目。Host 会随该 baseline 捕获 follower 本地到达序号，并抑制该 cut 及之前的 buffered frame；replacement Agent 可以从 revision 一重新开始。活跃 opening 之后到达的持久 `assistant/message` 或 `assistant/attempt` 只有在其 seq 晚于 `startedAfterSeq` 且轮次与步骤匹配时才会保持暂存；匹配的 end type、seq 与 index 会发布一个具名 settlement delta，删除该 attempt 的瞬态 row、加入持久条目，并保留同一步骤中更早的 retry。已知 attempt 的 revision、密集 index 或 settlement 缺口会重新打开 follow；若 controller 错过 start，则忽略 unknown-attempt frame，并正常发布其持久 settlement。Abandoned end 会发布不含持久条目的 settlement delta，使瞬态 row 立即退出。持久缺口修复 page 不携带 Assistant baseline，因此 held notification 会重新打开 follow 一次，以取得配对的 page 与 baseline。每条历史 record 只覆盖自身的事件 seq。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 projection 状态，而不会把瞬态值当作 durable event。每次 Host generation 就绪时，同步的 Client 订阅会先清除保留的投影值及其水位，再刷新查询并重新打开 control stream，其中也包括 control baseline 中没有列出的 Session。首次 control stream 会等待 generation 就绪，确保其 opening 值不会先于旧状态清理到达。上一代尚未完成的 list 响应无法重新发布这些值。同一 generation 内，延迟到达的 control baseline 不能覆盖或清除较新的 sequenced 值，无论它们来自活 Session 的 list block、history page 还是 frame；冷 Session 从 projection cache 看出来的 cached list block 则不论水位都让位于建连 Session 的 baseline。持久 `inbox` 投影通过与其他投影相同的冷读取和重连路径传输两份待处理列表。Client Agent 上下文提供独立 [`fileUpload`](../../client/file-upload/README.zh.md) 服务使用的身份；Session 对象提供生命周期、prompt、queue 与历史操作，不提供文件传输。
 
 Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与提示词之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。回显按顺序存放图片预览与持久文件引用。Session 根据当前运行状态与请求的投递模式推导其 `transcript`、`queued` 或 `steering` 位置，并在序列化期间保留该位置。提示词的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，`inbox` 投影中的待处理消息也保留同一 source。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，带标识的提示词失败或被放弃时立即退休，销毁时按 failed 退休。每次退休恰好触发一次 `onRetire`；observed 退休还会携带有序的持久附件引用，让 composer 释放成功卡片并保留失败草稿。回显只存在于 Client 内存；刷新与重连只从持久事件重建会话。
 
@@ -61,13 +65,15 @@ Fork 复制 `atSeq` 所选的精确事件前缀，包含切点事件，允许在
 
 `sessions.retain(target, { source, signal? })` 立即获取一个精确 Client generation 的引用，并启动其共享的首次历史打开。目标是已知 Session id 或持久的直接父子 subagent 地址；Host 在打开历史时校验显式地址。返回引用支持幂等的 `release()` 和 `Symbol.dispose`；其 `ready` Promise 跟随共享的 `Session.open()` 结果，并在该次尝试结算时解析为确切 binding，包括 Remote failure 以 `openState: 'error'` 表示的情况。仅当 `Session.open()` 拒绝、等待方取消或引用提前释放时，`ready` 才拒绝。取消一个等待方不会取消其他 owner 的打开。`sessions.using(target, options, operation)` 等待该次结算，持有引用直到回调结束，并传播被拒绝的就绪与回调失败。
 
-引用保活本地会话数据、作用域 Context 和历史流，不保活 Host Agent。普通 Session 不因保留引用而添加目录行。已保留且具有明确直接父子地址的 subagent 即使尚未收到父目录，也会保留兜底行并通知列表读取方；这些行不加入 Host 列表成员集合。Fork 标题设置直接发送 rename 并应用返回的标题投影，不 retain 子会话，也不打开其历史。最后一个引用释放时，generation 先退出可访问映射，再执行清理；后续获取可以为同一 id 创建新 generation。`binding(id)` 和 `scope(id)` 只借用已有 generation。`retainInfo(id)` 独立于目录成员关系观察稳定的只读来源计数，不执行历史 I/O。消费方来源键可通过声明合并扩展；导航和完成确认属于 UI 消费方，不属于本控制器。所有权与清理规则见 [Client 会话引用](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.zh.md)。
+引用保活本地会话数据、作用域 Context 和历史流，不保活 Host Agent。普通 Session 不因保留引用而添加目录行。已保留且具有明确直接父子地址的 subagent 即使尚未收到父目录，也会保留兜底行并通知列表读取方；这些行不加入 Host 列表成员集合。Fork 标题设置直接发送 rename 并应用返回的标题投影，不 retain 子会话，也不打开其历史。最后一个引用释放时，generation 先退出可访问映射，再执行清理；后续获取可以为同一 id 创建新 generation。`binding(id)` 和 `scope(id)` 只借用已有 generation。`retainInfo(id)` 独立于目录成员关系观察稳定的只读来源计数，不执行历史 I/O。消费方来源键可通过声明合并扩展；导航和完成确认属于 UI 消费方，不属于本控制器。所有权与清理规则见 [Client 会话引用](../../../.agents/notes/implemented/architecture/2026-09-15-client-session-references.zh.md)。 模式未知的子代理地址允许读取历史，但仍校验直接父级。成功恢复 descriptor 后确定展示模式；失败只影响该子会话，控制请求仍要求已确认的 continuable 身份。
 
 <a id="session-media-references"></a>
 ## 会话媒体引用
 
 当 `connection`、`fs` 与 `attachments` 均被组合时，`SessionMediaReferences` 在鉴权 `connection.fetch` 通道上挂载 `GET|HEAD /api/file?path=<绝对路径>`。它通过 `ctx.fs` 读取普通文件，包括已注册工作区之外的临时路径与远程提供方中的文件。目录包含关系与 MIME 类别均不限制访问；`mime-types` 提供响应类型，未知扩展名使用 `application/octet-stream`。GET 复用 `readBytes` 执行读取前及读取中的字节限制；HEAD 只读取元数据。所有文件均使用 `ctx.attachments.imageLimits.maxImageBytes`（通常为 20 MiB）；超过此上限返回 413。响应包含完整文件，忽略 Range，并携带 `private, no-store`、`nosniff` 与沙箱 CSP，使直接打开的 HTML/SVG 无法以 API 源身份执行脚本。客户端重写位于 `ui-chat`（`AssistantMarkdown`）；音视频文件响应已可用，Markdown 音视频播放器节点仍是独立工作。
 
+`workspacePathApplications({ path })` 使用与 `openWorkspacePath` 相同的文件系统映射校验，返回服务端桌面上该文件的关联应用。打开请求中的可选 `application` 指定当前关联的应用，不修改系统默认应用。应用名称、默认项、图标和平台支持范围由 [native-command](../../util/native-command/README.zh.md) 提供。这些操作不激活 Agent，也不追加会话事件。原生操作失败时返回简短消息，原始命令异常作为 Host 端原因保留。
+
 -----
 
 <a id="configuration"></a>
@@ -95,10 +101,11 @@ Fork 复制 `atSeq` 所选的精确事件前缀，包含切点事件，允许在
 <a id="known-limitations-and-deferred-work"></a>
 
 - 图片字节上限不校验解码后的尺寸或像素数。
-- Control baseline 表示进程本地状态，因此 Host 重启后无法重建 jobs。
 - follow 恢复失败会对调用方可见，而不会无限重试。
 - 浏览器原始字节上传使用一次不带断点续传偏移的流式 HTTP 请求；重试会从第零字节重新传输整个文件。
 - 文件引用补全使用共享 Agent lookup，因此可能恢复冷 Session；`skills/list` 目录是不激活 Agent 的 skill 元数据读取路径。
+- 受理/运行的展示记忆只存在于客户端内存，页面重载后即丢失。
+- 该记忆不在 tab 之间共享：同一会话可能在一个 tab 中已转正，在另一个 tab 中仍显示为 `New Session`。
 
 
 <a id="dev-note"></a>
diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json
index 643c553e0a..a391fefa37 100644
--- a/packages/api/session-controller/package.json
+++ b/packages/api/session-controller/package.json
@@ -87,7 +87,6 @@
     "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-file-reference": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",
-    "@deepseek-ai/dsh-jobs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-native-command": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
@@ -107,9 +106,6 @@
     "@deepseek-ai/dsh-workspace": "workspace:^"
   },
   "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-jobs": {
-      "optional": true
-    },
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
@@ -134,7 +130,6 @@
     "@deepseek-ai/dsh-file-reference": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
-    "@deepseek-ai/dsh-jobs": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-native-command": "workspace:^",
     "@deepseek-ai/dsh-permission-presets": "workspace:^",
diff --git a/packages/api/session-controller/src/client/sessions/lineage.ts b/packages/api/session-controller/src/client/sessions/lineage.ts
index 56d06d3e43..b0b49311f3 100644
--- a/packages/api/session-controller/src/client/sessions/lineage.ts
+++ b/packages/api/session-controller/src/client/sessions/lineage.ts
@@ -19,7 +19,10 @@ export interface SessionListEntry {
   title?: string
   updatedAt: number
   running: boolean
-  /** Summary blankness reconciled with `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer). */
+  /**
+   * New Session presentation and reuse eligibility, reconciled with
+   * `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer).
+   */
   blank: boolean
   parentSessionId?: SessionId
   /** Coarse durable origin for navigation filtering; not a continuation capability. */
diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts
index d3564d763b..50af09df13 100644
--- a/packages/api/session-controller/src/client/sessions/manager.ts
+++ b/packages/api/session-controller/src/client/sessions/manager.ts
@@ -10,7 +10,6 @@ import type {
   SessionProjectionHints,
   SessionRenameValue,
   SessionSummary,
-  SessionJob as JobView,
 } from '../../types.ts'
 import { mergeOrderedBaseline } from '../ordered-baseline.ts'
 import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client'
@@ -56,8 +55,7 @@ export interface SessionListSnapshot {
   phase: SessionListPhase
   error: RemoteFailure | null
   projectionsBySession: Readonly<Record<SessionId, SessionProjectionSnapshot>>
-  /** Background jobs per session; an absent key is an empty set. */
-  jobsBySession: Readonly<Record<SessionId, readonly JobView[]>>
+
 }
 
 /** Shared projection values and the lifecycle of their explicit baseline read. */
@@ -87,6 +85,15 @@ export class SessionManager {
   private readonly sessions = new Map<SessionId, Session>()
   /** In-flight Session disposals remain here after instances leave `sessions`, so manager disposal can await quiescence. */
   private readonly sessionDisposals = new Set<Promise<void>>()
+  /**
+   * Accepted/running presentation must survive a later empty-history list
+   * response. Host-asserted running is recorded even before a row, instance, or
+   * address holds the identity — the listing that would hold it may not have
+   * landed yet — while the client-local acceptance callback requires a current
+   * holder, because it can arrive from a replaced or already-dropped Session.
+   */
+  private readonly engagedSessions = new Set<SessionId>()
+  private disposed = false
   /** Per-session projection value stores, retained independently of instance arrival (the
    *  title-snapshot precedent, generalized): push frames land here whether or not the Session
    *  is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
@@ -103,12 +110,7 @@ export class SessionManager {
   private readonly addresses = new Map<SessionId, SubagentAddress>()
   private readonly projectionLoads = new Map<SessionId, ProjectionLoad>()
   private readonly projectionInflight = new Map<SessionId, ProjectionInflight>()
-  /**
-   * Background jobs per session, last-wins from Session Controller's control
-   * stream. An empty set is stored as an absent key, so absence and `[]` are
-   * one representation.
-   */
-  private readonly jobsBySession = new Map<SessionId, readonly JobView[]>()
+
 
   private listSnapshotCache: SessionListSnapshot
   /** Entry-identity cache (reference stability): list rebuilds reuse the previous entry
@@ -184,6 +186,7 @@ export class SessionManager {
     if (session !== expected) return Promise.resolve()
     this.sessions.delete(sessionId)
     this.addresses.delete(sessionId)
+    this.pruneEngagement(sessionId, this.retainedIds(this.summaries))
     return this.startSessionDisposal(session)
   }
 
@@ -192,6 +195,10 @@ export class SessionManager {
    * @returns once catalog requests and every Session stream have stopped.
    */
   async dispose(): Promise<void> {
+    this.disposed = true
+    this.listMutations = null
+    this.listInflight = null
+    this.engagedSessions.clear()
     const reads = [...this.projectionInflight.values()]
     for (const { controller } of reads) controller.abort()
     this.projectionInflight.clear()
@@ -235,7 +242,7 @@ export class SessionManager {
       // instance (consistency when the list precedes open).
       const summary = this.summaries.find(s => s.sessionId === sessionId)
       if (summary !== undefined) {
-        session.handleBlank(summary.blank)
+        session.handleBlank(this.effectiveBlank(summary))
         session.handleRunning(summary.running)
       } else {
         const address = this.addresses.get(sessionId)
@@ -268,12 +275,44 @@ export class SessionManager {
       // The sender's local first-send flip mirrors into the list row so the
       // session surfaces (lists filter on blank) before any host frame lands.
       onEngaged: (engaged) => {
-        this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
+        if (this.disposed || !this.retainedIds(this.summaries).has(engaged.sessionId)) return
+        // An identity already on the ledger needs no second row mutation.
+        if (!this.engagedSessions.has(engaged.sessionId)) {
+          this.engagedSessions.add(engaged.sessionId)
+          this.recordMutation({ kind: 'engaged', sessionId: engaged.sessionId })
+        }
+        this.sessions.get(engaged.sessionId)?.handleBlank(false)
       },
       projections: this.projectionStore(sessionId),
     })
   }
 
+  private effectiveBlank(summary: SessionSummary): boolean {
+    return summary.blank && !this.engagedSessions.has(summary.sessionId)
+  }
+
+  /**
+   * Identities an engagement may still belong to: the given list rows, resident
+   * Session instances, and retained child addresses.
+   * @param summaries - list rows of the caller's snapshot.
+   * @returns the retained identity set.
+   */
+  private retainedIds(summaries: readonly SessionSummary[]): Set<SessionId> {
+    const retained = new Set(summaries.map(summary => summary.sessionId))
+    for (const sessionId of this.sessions.keys()) retained.add(sessionId)
+    for (const sessionId of this.addresses.keys()) retained.add(sessionId)
+    return retained
+  }
+
+  /**
+   * Forget one engagement that no retained identity holds.
+   * @param sessionId - identity whose engagement may be dropped.
+   * @param retained - identities from {@link retainedIds} for the caller's snapshot.
+   */
+  private pruneEngagement(sessionId: SessionId, retained: ReadonlySet<SessionId>): void {
+    if (!retained.has(sessionId)) this.engagedSessions.delete(sessionId)
+  }
+
   /** Resident per-session projection store (create-on-demand; outlives instantiation). */
   private projectionStore(sessionId: SessionId): ProjectionValueStore {
     let store = this.projectionStores.get(sessionId)
@@ -367,15 +406,27 @@ export class SessionManager {
           const baseline: SessionSummary[] = this.listPhase === 'pending'
             ? [...result.value.items]
             : mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId)
-          this.summaries = mutations.reduce(applyMutation, baseline)
+          // A removal supersedes running observed in the pull, including after re-addition.
+          const removedSincePull = new Set<SessionId>()
+          for (const mutation of mutations) {
+            if (mutation.kind === 'remove') removedSincePull.add(mutation.sessionId)
+          }
+          for (const s of baseline) {
+            if (s.running && !removedSincePull.has(s.sessionId)) this.engagedSessions.add(s.sessionId)
+          }
+          const summaries = mutations.reduce(applyMutation, baseline)
+          this.summaries = summaries
+          // A full list can remove identities without a removal frame.
+          const retained = this.retainedIds(summaries)
+          for (const sessionId of this.engagedSessions) this.pruneEngagement(sessionId, retained)
           this.listState = 'idle'
           this.listPhase = 'ready'
           this.updateParentAvailability()
-          // Sessions reconcile list blank hints with their current metadata projection.
+          // Resident Sessions and list rows share one display blank, reconciled with the metadata projection.
           for (const s of this.summaries) {
             const session = this.sessions.get(s.sessionId)
             if (session === undefined) continue
-            session.handleBlank(s.blank)
+            session.handleBlank(this.effectiveBlank(s))
             session.handleRunning(s.running)
           }
           // Land each row's projection block in the per-session value store
@@ -524,6 +575,7 @@ export class SessionManager {
 
   /** Apply immediately and retain for replay when a list response is in flight. */
   private recordMutation(mutation: SessionListMutation): void {
+    if (this.disposed) return
     this.listMutations?.push(mutation)
     this.summaries = applyMutation(this.summaries, mutation)
     this.notifier.markDirty()
@@ -569,21 +621,11 @@ export class SessionManager {
       this.replaceControlBaseline(frame.value)
       return
     }
-    if (frame.type === 'projection') {
-      this.projectionStore(frame.sessionId).apply(frame.key, frame.value, SessionSeq(frame.seq))
-      this.notifier.markDirty()
-      return
-    }
-    if (frame.jobs.length === 0) this.jobsBySession.delete(frame.sessionId)
-    else this.jobsBySession.set(frame.sessionId, frame.jobs)
+    this.projectionStore(frame.sessionId).apply(frame.key, frame.value, SessionSeq(frame.seq))
     this.notifier.markDirty()
   }
 
   private replaceControlBaseline(baseline: SessionControlBaseline): void {
-    this.jobsBySession.clear()
-    for (const [sessionId, jobs] of Object.entries(baseline.jobs)) {
-      if (jobs.length > 0) this.jobsBySession.set(sessionId as SessionId, jobs)
-    }
 
     for (const [sessionId, block] of Object.entries(baseline.projections)) {
       const store = this.projectionStore(sessionId as SessionId)
@@ -599,7 +641,8 @@ export class SessionManager {
    */
   handleSessionAdded(summary: SessionSummary): void {
     this.mergeSummary(summary)
-    this.sessions.get(summary.sessionId)?.handleBlank(summary.blank)
+    if (!this.disposed && summary.running) this.engagedSessions.add(summary.sessionId)
+    this.sessions.get(summary.sessionId)?.handleBlank(this.effectiveBlank(summary))
     if (summary.projections !== undefined) this.applyListBlock(summary.sessionId, summary.projections)
   }
 
@@ -639,11 +682,11 @@ export class SessionManager {
       : { kind: 'remove', sessionId })
     if (durableSubagent) this.sessions.get(sessionId)?.handleRunning(false)
     else this.sessions.get(sessionId)?.handleRemoved()
-    this.jobsBySession.delete(sessionId)
     const catalog = this.projectionStores.get(sessionId)?.values().subagentCatalog
     if (!durableSubagent && (catalog === undefined || catalog.length === 0)) {
       this.projectionStores.delete(sessionId)
     }
+    this.pruneEngagement(sessionId, this.retainedIds(this.summaries))
     this.projectionInflight.get(sessionId)?.controller.abort()
     this.projectionInflight.delete(sessionId)
     this.projectionLoads.delete(sessionId)
@@ -660,6 +703,7 @@ export class SessionManager {
    * @param running - current Agent running state.
    */
   handleSessionStatus(sessionId: SessionId, running: boolean): void {
+    if (!this.disposed && running) this.engagedSessions.add(sessionId)
     this.recordMutation({ kind: 'status', sessionId, running, agentAvailable: true })
     this.updateParentAvailability()
     this.sessions.get(sessionId)?.handleRunning(running)
@@ -716,7 +760,7 @@ export class SessionManager {
       return {
         ...summary,
         // Cached list hints can precede a history opening or control update.
-        blank: summary.blank && metadata?.blank !== false,
+        blank: this.effectiveBlank(summary) && metadata?.blank !== false,
         updatedAt: Math.max(summary.updatedAt, metadata?.lastPromptAt ?? 0),
         ...(typeof title === 'string' && title !== '' ? { title } : {}),
         ...(projectionValues === undefined ? {} : { projectionValues }),
@@ -750,7 +794,6 @@ export class SessionManager {
         sessionId,
         { values: store.values(), state: 'idle', error: null, ...this.projectionLoads.get(sessionId) },
       ])),
-      jobsBySession: Object.fromEntries(this.jobsBySession),
     }
   }
 }
@@ -786,8 +829,7 @@ function applyMutation(summaries: readonly SessionSummary[], mutation: SessionLi
     case 'remove':
       return summaries.filter(summary => summary.sessionId !== mutation.sessionId)
     case 'status':
-      // running:true doubles as the cross-client blank flip (a blank session
-      // never runs, so the first running frame proves a message landed).
+      // Running converts display state; it does not establish durable history.
       return summaries.map(summary => summary.sessionId === mutation.sessionId
         && (summary.running !== mutation.running
           || summary.agentAvailable !== mutation.agentAvailable || (mutation.running && summary.blank))
diff --git a/packages/api/session-controller/src/client/sessions/service.ts b/packages/api/session-controller/src/client/sessions/service.ts
index 28b22c796a..48d8f6a533 100644
--- a/packages/api/session-controller/src/client/sessions/service.ts
+++ b/packages/api/session-controller/src/client/sessions/service.ts
@@ -5,7 +5,6 @@ import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import { workspaceTitleOf } from '@deepseek-ai/dsh-util-workspace-path'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 import { SESSION_SEARCH_RESULT_LIMIT } from '../../types.ts'
-import type { SessionJob as JobView } from '../../types.ts'
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
 import {
   createSnapshotStore, notifySubscribers, type ObservableSnapshot, type SnapshotStore,
@@ -39,7 +38,8 @@ export interface SessionSummary {
   /** Local ownership counts; Host metadata refreshes cannot overwrite them. */
   readonly retainedBy: SessionRetainInfo['retainedBy']
   /**
-   * Blankness from the Host summary reconciled with `sessionListMetadata`.
+   * New Session presentation and reuse eligibility, derived from the Host
+   * summary, `sessionListMetadata`, and client acceptance/running observations.
    * New Session reuses a blank one targeting the same workspace. Filtering
    * stays with the consumer: the store carries every row, while the Workspace
    * browser shows only the selected blank entry.
@@ -60,12 +60,6 @@ export interface SessionListState {
   phase: SessionListPhase
   /** Shared projection values and explicit-read state, including unopened Sessions. */
   projectionsBySession: Readonly<Record<SessionId, SessionProjectionSnapshot>>
-  /**
-   * Background jobs each session can see, mirrored last-wins from Session
-   * Controller's control baseline and `jobs` frames. A missing key is an empty
-   * set, so consumers read absence rather than a sentinel.
-   */
-  jobsBySession: Readonly<Record<SessionId, readonly JobView[]>>
 }
 
 /** Structured session-create failure. */
@@ -262,7 +256,7 @@ export class ClientSessions implements ISessions {
   ) {
     this.manager = new SessionManager(remote)
     this.list = createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, phase: 'pending', projectionsBySession: {}, jobsBySession: {},
+      ids: [], byId: {}, phase: 'pending', projectionsBySession: {},
     })
     const disposeManagerProjection = this.manager.subscribe(() => { this.projectList() })
     rootCtx.effect(() => async () => {
@@ -613,7 +607,7 @@ export class ClientSessions implements ISessions {
   private projectList(): void {
     const previousById = this.list.getSnapshot().byId
     const {
-      items, phase, projectionsBySession, jobsBySession,
+      items, phase, projectionsBySession,
     } = this.manager.getListSnapshot()
     const ids: SessionId[] = []
     const byId: Record<SessionId, SessionSummary> = {}
@@ -680,7 +674,7 @@ export class ClientSessions implements ISessions {
         ...(title === undefined ? {} : { title, displayTitle: title }),
       }
     }
-    this.list.set({ ids, byId, phase, projectionsBySession, jobsBySession })
+    this.list.set({ ids, byId, phase, projectionsBySession })
   }
 
   private startScopeDrop(
diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts
index fb1eb7a01d..ec880192f0 100644
--- a/packages/api/session-controller/src/client/sessions/session.ts
+++ b/packages/api/session-controller/src/client/sessions/session.ts
@@ -66,12 +66,9 @@ export interface SessionOptions {
   /** Whether the exact direct parent Agent is available in Host summaries; absent until known. */
   parentAvailable?: boolean
   /**
-   * First ACCEPTED prompt on a blank session (fires at most once, on the
-   * prompt RPC's success response): the manager mirrors the blank→false flip
-   * into its list row so the session surfaces without waiting for a host
-   * frame. Acceptance is the flip point because it proves the user message
-   * is in the host log; a rejected first prompt keeps the session blank
-   * (hidden, still reusable by connectWorkspace).
+   * Publish each accepted prompt to the Manager, including after this Session
+   * object is replaced. Acceptance converts display state, but does not
+   * establish that a turn started or reached durable history.
    */
   onEngaged?(session: Session): void
   /**
@@ -117,7 +114,7 @@ export class Session implements SessionFace {
   private promptAttempted = false
   /** A first accepted prompt stays in the engaging phase until its turn is observable. */
   private firstPromptPendingTurn = false
-  /** Empty-log mirror (see ConversationSnapshot.blank); unknown bare sessions begin conservatively blank. */
+  /** New Session display state; unknown bare sessions begin conservatively blank. */
   private blankBit = true
   private removed = false
   private promptError: PromptError | null = null
@@ -291,19 +288,12 @@ export class Session implements SessionFace {
       this.notifier.markDirty()
       return result
     }
-    // Blank flips on ACCEPTANCE, not attempt: an accepted prompt starts the
-    // conversation's first turn on the host (the host criterion — a logged
-    // turn/start — is fact, not optimism; standalone command and projection
-    // events never flip it), while a rejected first prompt must keep the
-    // session blank — the client-side blank mirror only ever lowers, so
-    // flipping early on a failure would surface the session forever and
-    // strip its connectWorkspace reuse eligibility against the host's
-    // authority.
+    // Rejection must leave a first prompt blank and eligible for workspace reuse.
     if (this.blankBit) {
       this.blankBit = false
-      this.options.onEngaged?.(this)
       this.notifier.markDirty()
     }
+    this.options.onEngaged?.(this)
     return result
   }
 
@@ -514,8 +504,7 @@ export class Session implements SessionFace {
    * @param running - the new running state.
    */
   handleRunning(running: boolean): void {
-    // Turn-start conversion: a blank session never runs, so the first
-    // running:true proves another side's first message landed.
+    // Running converts display state without establishing durable turn history.
     if (running && this.blankBit) {
       this.blankBit = false
       this.notifier.markDirty()
@@ -553,9 +542,12 @@ export class Session implements SessionFace {
   }
 
   /**
-   * Relay list blankness without overriding a started conversation established
-   * by the current projection, a local prompt, or running state.
-   * @param blank - whether the list or projection reports an unstarted conversation.
+   * Apply the Manager's effective display blank, further reconciled with the
+   * current `sessionListMetadata` projection. Local send attempts and current
+   * running state prevent re-blanking; an earlier false summary alone does not.
+   * The Manager retains acceptance and earlier running observations across
+   * Session-object replacement.
+   * @param blank - New Session display state after Manager reconciliation.
    */
   handleBlank(blank: boolean): void {
     blank = blank && this.projections.values().sessionListMetadata?.blank !== false
@@ -813,6 +805,7 @@ export class Session implements SessionFace {
   }
 
   private buildSnapshot(): SessionSnapshot {
+    const identity = this.projections.values().subagent
     return {
       sessionId: this.sessionId,
       pendingSubmissions: this.pendingSubmissions,
@@ -820,7 +813,9 @@ export class Session implements SessionFace {
       subagent: this.address === undefined
         ? null
         : {
-          address: this.address,
+          address: this.address.mode === 'unknown' && identity != null
+            ? { ...this.address, mode: identity.mode }
+            : this.address,
           ...(this.parentAvailable === undefined ? {} : { parentAvailable: this.parentAvailable }),
         },
       removed: this.removed,
diff --git a/packages/api/session-controller/src/control.ts b/packages/api/session-controller/src/control.ts
index 3fb8d0032e..8d27396d29 100644
--- a/packages/api/session-controller/src/control.ts
+++ b/packages/api/session-controller/src/control.ts
@@ -1,9 +1,7 @@
-/** Live Session jobs and projection state with reconnect baselines. */
+/** Live Session projection state with reconnect baselines. */
 
 import type { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Deque } from '@deepseek-ai/dsh-deque'
-import type { JobSnapshot } from '@deepseek-ai/dsh-jobs'
 import type {
   Session, SessionId,
 } from '@deepseek-ai/dsh-session'
@@ -11,7 +9,6 @@ import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type {
   SessionControlBaseline,
   SessionControlFrame,
-  SessionJob,
   SessionProjectionBaseline,
   SessionProjectionValues,
 } from './types.ts'
@@ -20,7 +17,7 @@ import type {
 export class SessionControlController {
   private readonly streams = new Set<ControlQueue>()
 
-  /** @param ctx - Host context carrying live Agent, projection, and jobs services. */
+  /** @param ctx - Host context carrying live Agent and projection services. */
   constructor(private readonly ctx: Context) {
     ctx.sessionProjections.onChanged((session, key, value, seq) => {
       this.broadcast({
@@ -31,13 +28,6 @@ export class SessionControlController {
         seq,
       })
     })
-    ctx.inject(['jobs'], (jobsCtx) => {
-      jobsCtx.jobs.onJobsChanged((owner) => { this.onJobsChanged(owner) })
-    })
-    ctx.on('session/created', (session) => {
-      const jobs = this.jobsFor(this.ctx.agents.get(session.id))
-      if (jobs.length > 0) this.broadcast({ type: 'jobs', sessionId: session.id, jobs })
-    })
     ctx.effect(() => () => {
       for (const stream of this.streams) stream.end()
       this.streams.clear()
@@ -64,13 +54,7 @@ export class SessionControlController {
 
   private baseline(): SessionControlBaseline {
     const sessions = this.ctx.sessions.list()
-    const jobs = Object.create(null) as Record<SessionId, readonly SessionJob[]>
-    for (const session of sessions) {
-      const agent = this.ctx.agents.get(session.id)
-      jobs[session.id] = this.jobsFor(agent)
-    }
     return {
-      jobs,
       projections: this.projectionBaseline(sessions),
     }
   }
@@ -90,25 +74,6 @@ export class SessionControlController {
     return blocks
   }
 
-  private onJobsChanged(owner: Agent | undefined): void {
-    if (owner !== undefined) {
-      this.broadcast({ type: 'jobs', sessionId: owner.id, jobs: this.jobsFor(owner) })
-      return
-    }
-    for (const session of this.ctx.sessions.list()) {
-      this.broadcast({
-        type: 'jobs',
-        sessionId: session.id,
-        jobs: this.jobsFor(this.ctx.agents.get(session.id)),
-      })
-    }
-  }
-
-  private jobsFor(agent: Agent | undefined): SessionJob[] {
-    const jobs = this.ctx.get('jobs')
-    return jobs === undefined ? [] : jobs.list(agent).map(jobView)
-  }
-
   private broadcast(frame: SessionControlFrame): void {
     for (const stream of this.streams) stream.push(frame)
   }
@@ -154,15 +119,3 @@ class ControlQueue {
     }
   }
 }
-
-function jobView(job: JobSnapshot): SessionJob {
-  return {
-    id: job.id,
-    kind: job.kind,
-    label: job.label,
-    status: job.status,
-    ...(job.detail === undefined ? {} : { detail: job.detail }),
-    startedAt: job.startedAt,
-    ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }),
-  }
-}
diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts
index a22badc1f1..069ee3bf32 100644
--- a/packages/api/session-controller/src/history.ts
+++ b/packages/api/session-controller/src/history.ts
@@ -364,7 +364,7 @@ function validateAddress(
       reason: 'unsupported',
     })
   }
-  if (identity.mode !== address.mode) {
+  if (address.mode !== 'unknown' && identity.mode !== address.mode) {
     throw new RemoteError('subagent/unauthorized', 'subagent mode does not match the supplied address', {
       childSessionId: address.childSessionId,
     })
diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts
index b6f5f0dfa0..d830d2b661 100644
--- a/packages/api/session-controller/src/index.ts
+++ b/packages/api/session-controller/src/index.ts
@@ -8,7 +8,7 @@ import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-client-file-upload'
-import { canOpenNativePath, nativeFileManager, openNativeAssociatedPath, revealNativePath } from '@deepseek-ai/dsh-native-command'
+import { canOpenNativePath, nativeFileManager, nativeFileApplications, openNativeFileApplication, openNativeAssociatedPath, revealNativePath } from '@deepseek-ai/dsh-native-command'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionInspection } from '@deepseek-ai/dsh-session-persistence'
 import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query'
@@ -29,6 +29,7 @@ import { SessionSkillCatalog } from './skill-catalog.ts'
 import { SessionMediaReferences } from './media-references.ts'
 import type {
   ModelCatalog,
+  SessionWorkspacePathApplication,
   SessionAttachmentRequest,
   SessionAttachmentValue,
   SessionCancelRequest,
@@ -83,6 +84,10 @@ export interface Config {
 export interface SessionControllerInternals {
   /** Native default-application handoff. */
   readonly openPath?: (path: string, signal: AbortSignal) => Promise<void>
+  /** Native file-association query. */
+  readonly fileApplications?: typeof nativeFileApplications
+  /** Explicit registered-application handoff. */
+  readonly openFileApplication?: typeof openNativeFileApplication
   /** Native file-manager handoff. */
   readonly revealPath?: (path: string, signal: AbortSignal) => Promise<void>
   /** Native handoff availability probe. */
@@ -115,6 +120,8 @@ export class SessionController extends TypertRemoteService {
   private readonly history: SessionHistoryController
   private readonly listState: ApiSessionList
   private readonly openPath: (path: string, signal: AbortSignal) => Promise<void>
+  private readonly fileApplications: typeof nativeFileApplications
+  private readonly openFileApplication: typeof openNativeFileApplication
   private readonly revealPath: (path: string, signal: AbortSignal) => Promise<void>
   private readonly canOpenPath: () => boolean
   private readonly promotions = new Set<Promise<void>>()
@@ -142,6 +149,8 @@ export class SessionController extends TypertRemoteService {
     }, 'session-controller.promotions')
     this.history = new SessionHistoryController(ctx, (observation) => { this.promote(observation) })
     this.listState = new ApiSessionList(ctx)
+    this.fileApplications = internals.fileApplications ?? nativeFileApplications
+    this.openFileApplication = internals.openFileApplication ?? openNativeFileApplication
     this.openPath = internals.openPath ?? openNativeAssociatedPath
     this.revealPath = internals.revealPath ?? revealNativePath
     this.canOpenPath = internals.canOpenPath
@@ -309,35 +318,59 @@ export class SessionController extends TypertRemoteService {
     request: SessionOpenWorkspacePathRequest,
     signal: AbortSignal,
   ): Promise<SessionOpenWorkspacePathValue> {
-    if (request.path.length === 0) {
-      throw new RemoteError(
-        'gateway/bad-request',
-        'session.openWorkspacePath requires a non-empty path',
-        {},
-      )
-    }
-    signal.throwIfAborted()
     try {
-      const hostPath = resolve(request.path)
-      const { fs } = this.ctx
-      const mapped = fs.processPathFromHostPath(hostPath)
-      if (mapped === undefined || fs.processPath(await fs.resolve(mapped, { signal })) !== hostPath) {
-        throw new Error('Path has no verified Host path')
-      }
-      signal.throwIfAborted()
-      if (request.action === 'reveal') await this.revealPath(request.path, signal)
-      else await this.openPath(request.path, signal)
+      const path = await this.verifyDesktopPath(request.path, signal)
+      if (request.action === 'reveal') await this.revealPath(path, signal)
+      else if (request.application !== undefined) await this.openFileApplication(path, request.application, signal)
+      else await this.openPath(path, signal)
       return { opened: true }
     } catch (error: unknown) {
       if (signal.aborted) throw new RemoteError('gateway/cancelled', 'path open was aborted', {})
+      if (error instanceof RemoteError) throw error
       throw new RemoteError(
         'gateway/internal',
-        `path open failed: ${error instanceof Error ? error.message : String(error)}`,
+        'path open failed',
         {},
+        { cause: error },
       )
     }
   }
 
+  /**
+   * Query current file handlers on the serving desktop without activating an Agent.
+   * @param request - file path in Host filesystem syntax.
+   * @param signal - caller lifetime, propagated to filesystem and desktop queries.
+   * @returns OS application names, icons, and default selection; empty when desktop opening is unavailable.
+   * @throws RemoteError when the path is invalid, the query is cancelled, or native discovery fails.
+   */
+  @Remote('workspacePathApplications')
+  async workspacePathApplications(
+    request: { readonly path: string }, signal: AbortSignal,
+  ): Promise<readonly SessionWorkspacePathApplication[]> {
+    if (!this.canOpenPath()) return []
+    try {
+      const path = await this.verifyDesktopPath(request.path, signal)
+      return await this.fileApplications(path, signal)
+    } catch (error: unknown) {
+      if (signal.aborted) throw new RemoteError('gateway/cancelled', 'application query was aborted', {})
+      if (error instanceof RemoteError) throw error
+      throw new RemoteError('gateway/internal', 'file application query failed', {}, { cause: error })
+    }
+  }
+
+  private async verifyDesktopPath(path: string, signal: AbortSignal): Promise<string> {
+    if (path.length === 0) throw new RemoteError('gateway/bad-request', 'A non-empty file path is required', {})
+    signal.throwIfAborted()
+    const hostPath = resolve(path)
+    const { fs } = this.ctx
+    const mapped = fs.processPathFromHostPath(hostPath)
+    if (mapped === undefined || fs.processPath(await fs.resolve(mapped, { signal })) !== hostPath) {
+      throw new RemoteError('gateway/bad-request', 'Path has no verified Host path', {})
+    }
+    signal.throwIfAborted()
+    return hostPath
+  }
+
   /**
    * Rename one Session after explicitly resuming it.
    * @param request - Session identity and proposed title.
@@ -465,6 +498,7 @@ export class SessionController extends TypertRemoteService {
     return this.controlState.control(signal)
   }
 
+
 }
 
 export { buildModelCatalog }
diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts
index 37294a6dbb..9e3da329ee 100644
--- a/packages/api/session-controller/src/types.ts
+++ b/packages/api/session-controller/src/types.ts
@@ -1,4 +1,5 @@
 /** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */
+import type { NativeFileApplication } from '@deepseek-ai/dsh-native-command/types'
 
 import type {
   AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType,
@@ -8,7 +9,6 @@ import type { LlmAttemptId, MessageId } from '@deepseek-ai/dsh-llm/brand'
 import type { TextBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionId, SessionSeqCursor } from '@deepseek-ai/dsh-session/types'
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types'
-import type { JobId } from '@deepseek-ai/dsh-jobs/brand'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 
@@ -381,6 +381,8 @@ export interface SessionCancelValue {
 export interface SessionOpenWorkspacePathRequest {
   /** File-manager navigation when requested; omission uses the default application. */
   readonly action?: 'reveal'
+  /** Registered application identifier; ignored for reveal. Omission preserves the operating system default. */
+  readonly application?: string
   /** Path after best-effort Session workspace resolution, in Host filesystem syntax. */
   readonly path: string
 }
@@ -407,7 +409,7 @@ export type SessionAddress =
     readonly kind: 'subagent'
     readonly parentSessionId: SessionId
     readonly childSessionId: SessionId
-    readonly mode: 'one-shot' | 'continuable'
+    readonly mode: 'one-shot' | 'continuable' | 'unknown'
   }
 
 /** One non-activating Session projection read. */
@@ -552,20 +554,8 @@ export type SessionFollowFrame =
   | SessionEventEntry
   | { readonly type: 'assistant-stream'; readonly frame: SessionAssistantStreamFrame }
 
-/** Browser-safe background-job row. */
-export interface SessionJob {
-  readonly id: JobId
-  readonly kind: string
-  readonly label: string
-  readonly status: 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
-  readonly detail?: string
-  readonly startedAt: number
-  readonly finishedAt?: number
-}
-
 /** Complete live control baseline emitted once per control stream generation. */
 export interface SessionControlBaseline {
-  readonly jobs: Readonly<Record<SessionId, readonly SessionJob[]>>
   readonly projections: Readonly<Record<SessionId, SessionProjectionBaseline>>
 }
 
@@ -580,7 +570,6 @@ export interface SessionProjectionUpdate {
 /** Host-wide live state stream. Each generation starts with exactly one baseline. */
 export type SessionControlFrame =
   | { readonly type: 'baseline'; readonly value: SessionControlBaseline }
-  | { readonly type: 'jobs'; readonly sessionId: SessionId; readonly jobs: readonly SessionJob[] }
   | ({ readonly type: 'projection' } & SessionProjectionUpdate)
 
 declare module '@deepseek-ai/cordis' {
@@ -624,3 +613,6 @@ declare module '@deepseek-ai/cordis' {
 
 /** JSON-compatible projection value accepted by list consumers. */
 export type SessionProjectionValue = JsonValue
+
+/** Application metadata returned by the serving desktop for one file. */
+export type SessionWorkspacePathApplication = NativeFileApplication
diff --git a/packages/api/session-controller/tests/client-apply.client.spec.ts b/packages/api/session-controller/tests/client-apply.client.spec.ts
index 5323f64b17..11c98407eb 100644
--- a/packages/api/session-controller/tests/client-apply.client.spec.ts
+++ b/packages/api/session-controller/tests/client-apply.client.spec.ts
@@ -18,7 +18,7 @@ const ROSTER = webApp.closure([SELF])
 const it = createClientTest({ roster: ROSTER })
 const EVENTS = '$events'
 const CONTROL = 'session/control'
-const BASELINE = { type: 'baseline', value: { jobs: {}, projections: {} } }
+const BASELINE = { type: 'baseline', value: { projections: {} } }
 /** The first client boot pays the cold module transform of the cone. */
 const COLD_BOOT_TIMEOUT_MS = 60_000
 
@@ -88,7 +88,7 @@ describe('Session Controller Client apply', () => {
     }] }))
     let projection = { asOfSeq: 20, values: { title: 'Before restart' } }
     mock.stream(CONTROL, (_args, stream) => {
-      stream.push({ type: 'baseline', value: { jobs: {}, projections: { [sessionId]: projection } } })
+      stream.push({ type: 'baseline', value: { projections: { [sessionId]: projection } } })
     })
     const { client, sessions } = await bench(start)
     await vi.waitFor(() => {
diff --git a/packages/api/session-controller/tests/control-jobs.host.spec.ts b/packages/api/session-controller/tests/control-jobs.host.spec.ts
deleted file mode 100644
index 46b3dff031..0000000000
--- a/packages/api/session-controller/tests/control-jobs.host.spec.ts
+++ /dev/null
@@ -1,237 +0,0 @@
-import { Context } from '@deepseek-ai/cordis'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { JobOutcome } from '@deepseek-ai/dsh-jobs'
-import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
-import type { Session } from '@deepseek-ai/dsh-session'
-import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
-import { describe, expect, it } from 'vitest'
-import { SessionControlController } from '../src/control.ts'
-import type { SessionControlFrame } from '../src/types.ts'
-import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
-
-type BaselineFrame = Extract<SessionControlFrame, { type: 'baseline' }>
-type JobFrame = Extract<SessionControlFrame, { type: 'jobs' }>
-
-function producer(label = 'sleep 60') {
-  let settle!: (outcome: JobOutcome) => void
-  const reads = { count: 0 }
-  const spec = {
-    kind: 'bash' as const,
-    label,
-    run: () => ({
-      cancel: () => {},
-      done: new Promise<JobOutcome>((resolve) => { settle = resolve }),
-      readOutput: () => { reads.count += 1; return 'stolen output' },
-    }),
-  }
-  return { spec, reads, settle: (outcome: JobOutcome) => { settle(outcome) } }
-}
-
-async function harness(withJobs: boolean): Promise<{
-  ctx: Context
-  session: Session
-  agent: Agent
-  control: SessionControlController
-}> {
-  const ctx = new Context()
-  await ctx.plugin(SessionStore)
-  await ctx.plugin(SessionProjectionRegistry)
-  await ctx.plugin(AgentRegistry)
-  if (withJobs) {
-    await ctx.plugin(LocalJobRegistry)
-    ctx.jobs.attachController('session-controller-test')
-  }
-  const session = ctx.sessions.create()
-  const agent: Agent = {
-    id: session.id,
-    options: {},
-    session,
-    inbox: unsupportedInbox(),
-    status: 'idle',
-    ctx,
-    send: () => {},
-    followup: () => {},
-    steer: () => {},
-    inject: () => {},
-    cancel: () => {},
-    runMaintenance: task => task(new AbortController().signal),
-    whenIdle: () => Promise.resolve(),
-  }
-  await ctx.agents.register(agent)
-  const control = new SessionControlController(ctx)
-  await new Promise(resolve => setTimeout(resolve, 0))
-  return { ctx, session, agent, control }
-}
-
-async function baseline(control: SessionControlController): Promise<BaselineFrame> {
-  const abort = new AbortController()
-  const iterator = control.control(abort.signal)[Symbol.asyncIterator]()
-  const first = await iterator.next()
-  abort.abort()
-  await iterator.next()
-  if (first.done || first.value.type !== 'baseline') throw new Error('missing control baseline')
-  return first.value
-}
-
-async function collectJobs(
-  iterable: AsyncIterable<SessionControlFrame>,
-  count: number,
-  abort: AbortController,
-): Promise<JobFrame[]> {
-  const jobs: JobFrame[] = []
-  for await (const frame of iterable) {
-    if (frame.type !== 'jobs') continue
-    jobs.push(frame)
-    if (jobs.length >= count) abort.abort()
-  }
-  return jobs
-}
-
-describe('Session control jobs baseline', () => {
-  it('represents an attached session with no jobs as an empty set', async () => {
-    const { session, control } = await harness(true)
-    const frame = await baseline(control)
-    expect(frame.value.jobs[session.id]).toEqual([])
-  })
-
-  it('carries the visible set when the stream opens', async () => {
-    const { ctx, session, agent, control } = await harness(true)
-    ctx.jobs.start({ ...producer('pnpm run build').spec, owner: agent })
-    const frame = await baseline(control)
-    const jobs = frame.value.jobs[session.id]
-    expect(jobs).toHaveLength(1)
-    const [job] = jobs ?? []
-    expect(job?.startedAt).toBeTypeOf('number')
-    expect({ ...job, startedAt: 0 }).toEqual({
-      id: 'bash-1',
-      kind: 'bash',
-      label: 'pnpm run build',
-      status: 'running',
-      startedAt: 0,
-    })
-  })
-})
-
-describe('Session control jobs updates', () => {
-  it('publishes existing unowned jobs when a Session attaches after the stream opens', async () => {
-    const { ctx, control } = await harness(true)
-    const abort = new AbortController()
-    const iterator = control.control(abort.signal)[Symbol.asyncIterator]()
-    await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'baseline' } })
-    const task = producer('already running')
-    const id = ctx.jobs.start(task.spec)
-    await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'jobs' } })
-
-    const created = ctx.sessions.create(SessionId('late-session'))
-    await expect(iterator.next()).resolves.toMatchObject({
-      value: {
-        type: 'jobs',
-        sessionId: created.id,
-        jobs: [expect.objectContaining({ id, label: 'already running' })],
-      },
-    })
-
-    task.settle({ status: 'completed' })
-    abort.abort()
-    await iterator.return?.()
-  })
-
-  it('pushes the owner whole set on registration, stopping, and settlement', async () => {
-    const { ctx, session, agent, control } = await harness(true)
-    const abort = new AbortController()
-    const collected = collectJobs(control.control(abort.signal), 3, abort)
-
-    const task = producer()
-    const id = ctx.jobs.start({ ...task.spec, owner: agent })
-    ctx.jobs.kill(id, agent, 'test')
-    task.settle({ status: 'killed', detail: 'signal: SIGTERM' })
-
-    const frames = await collected
-    expect(frames.map(frame => frame.sessionId)).toEqual([session.id, session.id, session.id])
-    expect(frames.map(frame => frame.jobs[0]?.status)).toEqual(['running', 'stopping', 'killed'])
-    expect(frames[2]?.jobs[0]?.detail).toBe('signal: SIGTERM')
-    expect(frames[2]?.jobs[0]?.finishedAt).toBeTypeOf('number')
-  })
-
-  it('drops internal registry fields from the browser view', async () => {
-    const { ctx, agent, control } = await harness(true)
-    const abort = new AbortController()
-    const collected = collectJobs(control.control(abort.signal), 1, abort)
-    ctx.jobs.start({ ...producer().spec, owner: agent, outputLimitBytes: 1_024 })
-
-    const [frame] = await collected
-    expect(Object.keys(frame?.jobs[0] ?? {}).sort()).toEqual([
-      'id',
-      'kind',
-      'label',
-      'startedAt',
-      'status',
-    ])
-  })
-
-  it('fans an unowned change out to every attached session', async () => {
-    const { ctx, control } = await harness(true)
-    const second = ctx.sessions.create()
-    const abort = new AbortController()
-    const collected = collectJobs(control.control(abort.signal), 2, abort)
-
-    ctx.jobs.start(producer('open to every caller').spec)
-
-    const frames = await collected
-    expect(new Set(frames.map(frame => frame.sessionId)).size).toBe(2)
-    expect(frames.some(frame => frame.sessionId === second.id)).toBe(true)
-    for (const frame of frames) expect(frame.jobs[0]?.label).toBe('open to every caller')
-  })
-
-  it('does not resume persisted sessions while projecting an unowned change', async () => {
-    const { ctx, control } = await harness(true)
-    const coldId = SessionId('session-cold-tasks')
-    let loaded = false
-    ctx.provide('sessionPersistence', {
-      list: async () => [{ version: SESSION_FORMAT_VERSION, id: coldId, createdAt: 5, cwd: '/tmp' }],
-      locate: () => undefined,
-      load: () => { loaded = true; throw new Error('job projection must not load a cold log') },
-    } as never)
-    const abort = new AbortController()
-    const collected = collectJobs(control.control(abort.signal), 1, abort)
-
-    ctx.jobs.start(producer().spec)
-    await collected
-    expect(loaded).toBe(false)
-    expect(ctx.agents.get(coldId)).toBeUndefined()
-  })
-
-  it('reports empty sets when no jobs registry is composed', async () => {
-    const { session, control } = await harness(false)
-    const frame = await baseline(control)
-    expect(frame.value.jobs[session.id]).toEqual([])
-  })
-
-  it('never consumes model output while projecting a lifecycle', async () => {
-    const { ctx, agent, control } = await harness(true)
-    const abort = new AbortController()
-    const collected = collectJobs(control.control(abort.signal), 3, abort)
-
-    const task = producer()
-    const id = ctx.jobs.start({ ...task.spec, owner: agent })
-    ctx.jobs.kill(id, agent, 'test')
-    task.settle({ status: 'killed', detail: 'signal: SIGTERM' })
-    await collected
-
-    expect(task.reads.count).toBe(0)
-  })
-
-  it('never consumes model output while producing a baseline', async () => {
-    const { ctx, agent, control } = await harness(true)
-    const task = producer()
-    ctx.jobs.start({ ...task.spec, owner: agent })
-
-    const frame = await baseline(control)
-
-    expect(frame.value.jobs[agent.id]).toHaveLength(1)
-    expect(task.reads.count).toBe(0)
-  })
-
-})
diff --git a/packages/api/session-controller/tests/control-queue.host.spec.ts b/packages/api/session-controller/tests/control-queue.host.spec.ts
index 0c635753ea..ad24ad94fb 100644
--- a/packages/api/session-controller/tests/control-queue.host.spec.ts
+++ b/packages/api/session-controller/tests/control-queue.host.spec.ts
@@ -118,6 +118,23 @@ describe('Session control Inbox projection', () => {
     await iterator.next()
   })
 
+  it('projects inbox state for live and cold sessions', async () => {
+    const { ctx, control, inbox } = await harness()
+    inbox.append('next-turn', message('queued'))
+    const cold = ctx.sessions.create(SessionId('cold-session'))
+
+    const abort = new AbortController()
+    const iterator = control.control(abort.signal)[Symbol.asyncIterator]()
+    const opened = await iterator.next()
+    if (opened.done || opened.value.type !== 'baseline') throw new Error('missing baseline')
+    expect(opened.value.value.projections[cold.id]?.values.inbox).toEqual({ 'next-turn': [], 'next-step': [] })
+    expect(opened.value.value.projections['queue-session' as SessionId]?.values.inbox).toMatchObject({
+      'next-turn': [expect.objectContaining({ content: [{ type: 'text', text: 'queued' }] })],
+    })
+    abort.abort()
+    await iterator.next()
+  })
+
   it('projects the prompt rpcId from a user-rpc source and omits it elsewhere', async () => {
     const { control, inbox } = await harness()
     const identified = createUserMessage({
diff --git a/packages/api/session-controller/tests/inbox-projection.client.spec.ts b/packages/api/session-controller/tests/inbox-projection.client.spec.ts
index 9ae17056e6..0522c8db35 100644
--- a/packages/api/session-controller/tests/inbox-projection.client.spec.ts
+++ b/packages/api/session-controller/tests/inbox-projection.client.spec.ts
@@ -79,7 +79,7 @@ describe('Inbox projection intake', () => {
 
         manager.handleControlFrame({
           type: 'baseline',
-          value: { jobs: {}, projections: { [SID]: {
+          value: { projections: { [SID]: {
             asOfSeq: 20, values: key === 'included' ? { inbox: stale } : {},
           } } },
         })
@@ -107,7 +107,7 @@ describe('Inbox projection intake', () => {
       manager.handleControlFrame({ ...inboxFrame({ ...empty, 'next-turn': [ghost] }), seq: 20 })
       manager.handleControlFrame({ ...inboxFrame(empty), sessionId: hiddenSessionId, seq: 20 })
       const face = manager.get(SID).projections.faceOf('inbox')
-      const baseline = { type: 'baseline', value: { jobs: {}, projections: {} } } as const
+      const baseline = { type: 'baseline', value: { projections: {} } } as const
       const result = ok({ items: [
         { sessionId: SID, updatedAt: 1, running: false, blank: false, agentAvailable: false,
           projections: { kind: 'cached' as const, asOfSeq: 1, values: { inbox: empty } } },
diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts
index b41ee673c8..4d91e0b77f 100644
--- a/packages/api/session-controller/tests/manager.client.spec.ts
+++ b/packages/api/session-controller/tests/manager.client.spec.ts
@@ -3,11 +3,11 @@
  * frame routing, and control baselines for uninstantiated sessions.
  */
 
-import { describe, expect, vi } from 'vitest'
+import { describe, expect, onTestFinished, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client'
 import { SessionSeq } from '@deepseek-ai/dsh-session/types'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
-import type { SessionControlFrame } from '@deepseek-ai/dsh-api-session-controller/types'
 import { ok, type RemoteMock } from '@deepseek-ai/dsh-remote-mock'
 import {
   createClientTest, type ClientTestFixtures, webApp,
@@ -48,6 +48,318 @@ function makeManager(
 }
 
 describe('SessionManager instances', () => {
+  it.for(['event', 'list'] as const)(
+    'forgets running when an unretained identity disappears through a %s',
+    async (source, { mock, remote }) => {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+      await manager.refreshList()
+      manager.handleSessionStatus(S1, true)
+      manager.handleSessionStatus(S1, false)
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+
+      if (source === 'event') manager.handleSessionRemoved(S1)
+      else {
+        remote.session.list.mockResolvedValueOnce(ok({ items: [] }))
+        await manager.refreshList()
+      }
+      expect(manager.getListSnapshot().items).toEqual([])
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    },
+  )
+
+  it('retains acceptance while an unlisted Session remains resident, then forgets it on drop', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const session = manager.get(S1)
+    await session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    remote.session.list.mockResolvedValue(ok({ items: [] }))
+
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items).toEqual([])
+    expect(session.getSnapshot().blank).toBe(false)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+
+    await manager.refreshList()
+    await manager.drop(S1, session)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+  })
+
+  it('retains running for an unlisted child with only a retained address', async ({ mock, remote }) => {
+    const address: SubagentAddress = { parentSessionId: S1, childSessionId: S2, mode: 'continuable' }
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.resolveTarget(address)
+    manager.handleSessionAdded(summary(S2, { blank: true }))
+    manager.handleSessionStatus(S2, true)
+    manager.handleSessionStatus(S2, false)
+    remote.session.list.mockResolvedValueOnce(ok({ items: [] }))
+
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items).toEqual([])
+    manager.handleSessionAdded(summary(S2, { blank: true }))
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+  })
+
+  it('retains running for a row added during a pull whose baseline omits it', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    manager.handleSessionStatus(S1, true)
+    manager.handleSessionStatus(S1, false)
+    const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValueOnce(response.promise)
+    const refreshing = manager.refreshList()
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    response.resolve(ok({ items: [] }))
+
+    await refreshing
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+  })
+
+  it.for(['result', 'transport'] as const)(
+    'retains running observed before listing when the pull fails through %s',
+    async (source, { mock, remote }) => {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionStatus(S1, true)
+      manager.handleSessionStatus(S1, false)
+      const error = new RemoteError('gateway/internal', 'list unavailable', {})
+      if (source === 'result') remote.session.list.mockResolvedValueOnce(err(error))
+      else remote.session.list.mockRejectedValueOnce(error)
+
+      await manager.refreshList()
+      expect(manager.getListSnapshot().state).toBe('error')
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    },
+  )
+
+  it('accepts a later blank baseline without an acceptance or running observation', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: false }))
+    const session = manager.get(S1)
+    expect(session.getSnapshot().blank).toBe(false)
+    remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+
+    await manager.refreshList()
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(session.getSnapshot().blank).toBe(true)
+  })
+
+  it('retains acceptance received before the first list response', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValueOnce(response.promise)
+    const refreshing = manager.refreshList()
+    const session = manager.get(S1)
+    await session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    expect(manager.getListSnapshot().items).toEqual([])
+    response.resolve(ok({ items: [summary(S1, { blank: true })] }))
+
+    await refreshing
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(session.getSnapshot().blank).toBe(false)
+  })
+
+  it('keeps a rejected first prompt blank across refresh and object replacement', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    remote.session.prompt.mockResolvedValueOnce(err(new RemoteError('session/agent-busy', 'busy', { reason: 'x' })))
+    const session = manager.get(S1)
+    expect((await session.prompt([{ type: 'text', text: 'first' }], 'queue')).ok).toBe(false)
+    remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+    await manager.refreshList()
+    await manager.drop(S1, session)
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(manager.get(S1).getSnapshot().blank).toBe(true)
+  })
+
+  it('ignores running from a list response that predates removal, including after re-addition', async ({ mock, remote }) => {
+    for (const readdBeforeResponse of [false, true]) {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+      const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+      remote.session.list.mockReturnValueOnce(response.promise)
+      const refreshing = manager.refreshList()
+      manager.handleSessionRemoved(S1)
+      if (readdBeforeResponse) manager.handleSessionAdded(summary(S1, { blank: true }))
+
+      response.resolve(ok({ items: [summary(S1, { blank: true, running: true })] }))
+      await refreshing
+      if (!readdBeforeResponse) {
+        expect(manager.getListSnapshot().items).toEqual([])
+        manager.handleSessionAdded(summary(S1, { blank: true }))
+      }
+
+      expect(manager.getListSnapshot().items[0]).toMatchObject({ blank: true, running: false })
+    }
+  })
+
+  it('retains running observations after re-addition while an older list response is pending', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const response = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValue(response.promise)
+    const refreshing = manager.refreshList()
+    manager.handleSessionRemoved(S1)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    manager.handleSessionStatus(S1, true)
+    manager.handleSessionStatus(S1, false)
+
+    response.resolve(ok({ items: [summary(S1, { blank: true })] }))
+    await refreshing
+
+    expect(manager.getListSnapshot().items[0]).toMatchObject({ blank: false, running: false })
+  })
+
+  it('applies late acceptance to a re-added list row without materializing its Session', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+    remote.session.prompt.mockReturnValue(acceptance.promise)
+    const session = manager.get(S1)
+    const sending = session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    manager.handleSessionRemoved(S1)
+    await manager.drop(S1, session)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const getSession = vi.spyOn(manager, 'get')
+    onTestFinished(() => { getSession.mockRestore() })
+    acceptance.resolve(ok({ accepted: true }))
+    await sending
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(getSession).not.toHaveBeenCalled()
+  })
+
+  it('publishes a late acceptance to the replacement Session with the same id', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+    remote.session.prompt.mockReturnValue(acceptance.promise)
+    const session = manager.get(S1)
+    const sending = session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    await manager.drop(S1, session)
+    const replacement = manager.get(S1)
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(replacement.getSnapshot().blank).toBe(true)
+    acceptance.resolve(ok({ accepted: true }))
+    await sending
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(replacement.getSnapshot().blank).toBe(false)
+    await manager.drop(S1, session)
+    expect(manager.get(S1)).toBe(replacement)
+  })
+
+  it('keeps accepted presentation when its Session is rebuilt', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const session = manager.get(S1)
+    await session.prompt([{ type: 'text', text: 'first' }], 'queue')
+    await manager.drop(S1, session)
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(manager.get(S1).getSnapshot().blank).toBe(false)
+  })
+
+  it('publishes acceptance from a nonblank sender after its list row is replaced', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const sender = manager.get(S1)
+    await sender.prompt([{ type: 'text', text: 'first' }], 'queue')
+    const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+    remote.session.prompt.mockReturnValueOnce(acceptance.promise)
+    const sending = sender.prompt([{ type: 'text', text: 'next' }], 'queue')
+    manager.handleSessionRemoved(S1)
+    await manager.drop(S1, sender)
+    manager.handleSessionAdded(summary(S1, { blank: true }))
+    const replacement = manager.get(S1)
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(true)
+    expect(replacement.getSnapshot().blank).toBe(true)
+
+    acceptance.resolve(ok({ accepted: true }))
+    await sending
+
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    expect(replacement.getSnapshot().blank).toBe(false)
+  })
+
+  it('keeps observed running presentation across idle empty-history summaries', async ({ mock, remote }) => {
+    for (const source of ['addition', 'refresh'] as const) {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+      const session = manager.get(S1)
+      manager.handleSessionStatus(S1, true)
+      manager.handleSessionStatus(S1, false)
+      expect(session.getSnapshot().blank).toBe(false)
+
+      if (source === 'addition') manager.handleSessionAdded(summary(S1, { blank: true }))
+      else {
+        remote.session.list.mockResolvedValueOnce(ok({ items: [summary(S1, { blank: true })] }))
+        await manager.refreshList()
+      }
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+      expect(session.getSnapshot().blank).toBe(false)
+    }
+  })
+
+  it('does not restore a removed row or publish after disposal when acceptance arrives late', async ({ mock, remote }) => {
+    for (const dispose of [false, true]) {
+      const manager = makeManager(mock, remote)
+      onTestFinished(() => manager.dispose())
+      manager.handleSessionAdded(summary(S1, { blank: true }))
+      const acceptance = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.prompt>>>()
+      remote.session.prompt.mockReturnValue(acceptance.promise)
+      const session = manager.get(S1)
+      const sending = session.prompt([{ type: 'text', text: 'first' }], 'queue')
+      manager.handleSessionRemoved(S1)
+      if (dispose) await manager.dispose()
+      else await manager.drop(S1, session)
+      const notify = vi.fn()
+      const unsubscribe = manager.subscribe(notify)
+      onTestFinished(unsubscribe)
+      acceptance.resolve(ok({ accepted: true }))
+      await sending
+      expect(manager.getListSnapshot().items).toEqual([])
+      expect(notify).not.toHaveBeenCalled()
+    }
+  })
+
+  it('keeps accepted presentation across a later list refresh without a turn', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    remote.session.list.mockResolvedValue(ok({ items: [summary(S1, { blank: true })] as never[] }))
+    await manager.refreshList()
+    await manager.get(S1).prompt([{ type: 'text', text: 'first' }], 'queue')
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+
+    await manager.refreshList()
+    expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+  })
+
   it('lazily builds one resident instance per id and syncs the running bit from the list', async ({ mock, remote }) => {
     remote.session.list.mockResolvedValue(ok({ items: [summary(S1, { running: true })] as never[] }))
     const manager = makeManager(mock, remote)
@@ -213,10 +525,9 @@ describe('list lifecycle', () => {
       // The control baseline is the connected Session's own value: it replaces
       // the list-surface title even at the same cursor.
       manager.handleControlFrame({
-        type: 'baseline', value: { jobs: { [S1]: [] }, projections: { [S1]: { asOfSeq: -1, values: { title: 'cold baseline' } } } },
+        type: 'baseline', value: { projections: { [S1]: { asOfSeq: -1, values: { title: 'cold baseline' } } } },
       })
       expect(manager.getListSnapshot().items[0]?.title).toBe('cold baseline')
-      expect(manager.getListSnapshot().jobsBySession).toEqual({})
     } finally {
       await manager.dispose()
     }
@@ -353,7 +664,6 @@ describe('list lifecycle', () => {
       manager.handleControlFrame({
         type: 'baseline',
         value: {
-          jobs: {},
           projections: { [S1]: { asOfSeq: 2, values: { title: 'Durable' } } },
         },
       })
@@ -504,6 +814,25 @@ describe('subagent catalogs', () => {
     })
   })
 
+  it('resolves an unknown browsing mode from the child projection without changing parent membership', async ({ mock, start }) => {
+    mock.load(sessionWorld)
+    const client = await start()
+    const manager = new SessionManager(client.ctx.remote)
+    const entries = [{ id: S2, createdAt: 1, mode: 'unknown' as const }]
+    manager.handleControlFrame({ type: 'projection', sessionId: S1, key: 'subagentCatalog', seq: 0, value: entries })
+    const address = manager.subagentAddress(S2)!
+    expect(address).toEqual({ parentSessionId: S1, childSessionId: S2, mode: 'unknown' })
+    manager.resolveTarget(address)
+    const child = manager.get(S2)
+    expect(child.getSnapshot().subagent?.address.mode).toBe('unknown')
+    manager.handleControlFrame({ type: 'projection', sessionId: S2, key: 'subagent', seq: 0,
+      value: { seq: SessionSeq(0), mode: 'continuable', label: 'repaired child' } })
+    await child.open()
+    expect(child.getSnapshot().subagent?.address).toEqual({ ...address, mode: 'continuable' })
+    expect(manager.getListSnapshot().projectionsBySession[S1]?.values.subagentCatalog).toEqual(entries)
+    await manager.dispose()
+  })
+
   it('publishes pushed membership without a catalog request or an instantiated parent', ({ mock, remote }) => {
     const manager = makeManager(mock, remote)
     manager.handleSessionAdded(summary(S2, { origin: 'subagent', parentSessionId: S1, running: true }))
@@ -876,6 +1205,32 @@ describe('remaining branches', () => {
 })
 
 describe('connected generation', () => {
+  it('does not prune running observations from a superseded empty list response', async ({ mock, remote }) => {
+    const manager = makeManager(mock, remote)
+    onTestFinished(() => manager.dispose())
+    const oldList = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    const newList = Promise.withResolvers<Awaited<ReturnType<typeof remote.session.list>>>()
+    remote.session.list.mockReturnValueOnce(oldList.promise).mockReturnValueOnce(newList.promise)
+    const oldPull = manager.refreshList()
+    manager.handleSessionStatus(S1, true)
+    manager.handleSessionStatus(S1, false)
+    manager.handleConnected()
+    const newPull = manager.refreshList()
+    try {
+      oldList.resolve(ok({ items: [] }))
+      await oldPull
+      expect(manager.getListSnapshot().state).toBe('loading')
+      newList.resolve(ok({ items: [summary(S1, { blank: true })] }))
+      await newPull
+
+      expect(manager.getListSnapshot().items[0]?.blank).toBe(false)
+    } finally {
+      oldList.resolve(ok({ items: [] }))
+      newList.resolve(ok({ items: [] }))
+      await Promise.all([oldPull, newPull])
+    }
+  })
+
   it.for(['old-first', 'new-first'] as const)(
     'ignores a previous generation list response (%s)',
     async (order, { mock, remote }) => {
@@ -1064,64 +1419,3 @@ describe('running facts without UI reminders', () => {
     expect(manager.getListSnapshot()).not.toHaveProperty('current')
   })
 })
-
-describe('background-job mirror', () => {
-  const view = (over: Partial<{ id: string; status: string; label: string }> = {}) => ({
-    id: 'bash-1', kind: 'bash', label: 'pnpm run build', status: 'running', startedAt: 5, ...over,
-  })
-  const tasksFrame = (
-    sessionId: SessionId,
-    jobs: unknown[],
-  ): Extract<SessionControlFrame, { type: 'jobs' }> => ({
-    type: 'jobs', sessionId, jobs: jobs as never,
-  })
-
-  it('mirrors the whole set last-wins, keyed per session, with no Session instance needed', ({ mock, remote }) => {
-    const manager = makeManager(mock, remote)
-    manager.handleControlFrame(tasksFrame(S1, [view()]))
-    manager.handleControlFrame(tasksFrame(S2, [view({ id: 'pwsh-1', label: 'other' })]))
-    const first = manager.getListSnapshot().jobsBySession
-    expect(first[S1]).toEqual([view()])
-    expect(first[S2]?.[0]?.label).toBe('other')
-
-    // Last-wins: the newer whole set replaces, it does not merge.
-    manager.handleControlFrame(tasksFrame(S1, [view({ status: 'completed' })]))
-    expect(manager.getListSnapshot().jobsBySession[S1]).toEqual([view({ status: 'completed' })])
-  })
-
-  it('stores an emptied set as an absent key so absence and [] read alike', ({ mock, remote }) => {
-    const manager = makeManager(mock, remote)
-    manager.handleControlFrame(tasksFrame(S1, [view()]))
-    expect(S1 in manager.getListSnapshot().jobsBySession).toBe(true)
-    manager.handleControlFrame(tasksFrame(S1, []))
-    expect(S1 in manager.getListSnapshot().jobsBySession).toBe(false)
-  })
-
-  it('clears the mirror when the next control baseline has no jobs', ({ mock, remote }) => {
-    const manager = makeManager(mock, remote)
-    manager.handleControlFrame(tasksFrame(S1, [view()]))
-    manager.handleControlFrame({
-      type: 'baseline',
-      value: { jobs: {}, projections: {} },
-    })
-    expect(S1 in manager.getListSnapshot().jobsBySession).toBe(false)
-  })
-
-  it('drops the rows when the session is removed, whichever stream lands first', ({ mock, remote }) => {
-    const manager = makeManager(mock, remote)
-    manager.handleSessionAdded(summary(S1, { blank: true }))
-    manager.handleControlFrame(tasksFrame(S1, [view()]))
-    manager.handleSessionRemoved(S1)
-    expect(S1 in manager.getListSnapshot().jobsBySession).toBe(false)
-  })
-
-  it('notifies list subscribers so an open header re-renders without a poll', async ({ mock, remote }) => {
-    const manager = makeManager(mock, remote)
-    const seen = vi.fn()
-    manager.subscribe(seen)
-    manager.handleControlFrame(tasksFrame(S1, [view()]))
-    // The notifier batches on a microtask; the frame itself is already applied.
-    await Promise.resolve()
-    expect(seen).toHaveBeenCalled()
-  })
-})
diff --git a/packages/api/session-controller/tests/projection-store.client.spec.ts b/packages/api/session-controller/tests/projection-store.client.spec.ts
index 3ab6ab2de1..c3a14febf3 100644
--- a/packages/api/session-controller/tests/projection-store.client.spec.ts
+++ b/packages/api/session-controller/tests/projection-store.client.spec.ts
@@ -241,7 +241,6 @@ describe('manager frame routing', () => {
     manager.handleControlFrame({
       type: 'baseline',
       value: {
-        jobs: {},
         projections: { [sid('s1')]: { asOfSeq: 2, values: {} } },
       },
     })
@@ -267,7 +266,6 @@ describe('manager frame routing', () => {
     manager.handleControlFrame({
       type: 'baseline',
       value: {
-        jobs: {},
         projections: { [sid('s1')]: { asOfSeq: 2, values: { title: 'Connected title' } } },
       },
     })
@@ -299,7 +297,6 @@ describe('manager frame routing', () => {
     manager.handleControlFrame({
       type: 'baseline',
       value: {
-        jobs: {},
         projections: { [sid('s1')]: { asOfSeq: 2, values: { title: 'Delayed baseline' } } },
       },
     })
diff --git a/packages/api/session-controller/tests/session-open-workspace-path.host.spec.ts b/packages/api/session-controller/tests/session-open-workspace-path.host.spec.ts
index 6a14c7761d..e8216b5214 100644
--- a/packages/api/session-controller/tests/session-open-workspace-path.host.spec.ts
+++ b/packages/api/session-controller/tests/session-open-workspace-path.host.spec.ts
@@ -1,3 +1,4 @@
+import { resolve } from 'node:path'
 import * as nativeCommand from '@deepseek-ai/dsh-native-command'
 import { Context } from '@deepseek-ai/cordis'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
@@ -65,11 +66,11 @@ describe('session/openWorkspacePath', () => {
 
     await expect(remote.openWorkspacePath({ path: '/workspace/project/src/a.ts' }, signal))
       .resolves.toEqual({ ok: true, value: { opened: true } })
-    expect(openPath).toHaveBeenCalledWith('/workspace/project/src/a.ts', signal)
+    expect(openPath).toHaveBeenCalledWith(resolve('/workspace/project/src/a.ts'), signal)
     expect(ctx.agents.list()).toEqual([])
   })
 
-  it('preserves relative and absolute Host-resolvable paths', async () => {
+  it('normalizes relative and absolute Host-resolvable paths', async () => {
     const ctx = await context()
     const openPath = vi.fn((_path: string, _signal: AbortSignal) => Promise.resolve())
     const remote = createSessionTestRemote(ctx, {
@@ -80,7 +81,7 @@ describe('session/openWorkspacePath', () => {
 
     await remote.openWorkspacePath({ path: '/workspace/result.html' })
     await remote.openWorkspacePath({ path: 'result.html' })
-    expect(openPath.mock.calls.map(call => call[0])).toEqual(['/workspace/result.html', 'result.html'])
+    expect(openPath.mock.calls.map(call => call[0])).toEqual([resolve('/workspace/result.html'), resolve('result.html')])
   })
 
   it('rejects empty paths before opening anything', async () => {
@@ -100,7 +101,7 @@ describe('session/openWorkspacePath', () => {
   it('preserves native opener failure and cancellation results', async () => {
     const ctx = await context()
     const openPath = vi.fn((_path: string, _signal: AbortSignal) =>
-      Promise.reject(new Error('desktop unavailable')))
+      Promise.reject(new Error('Command failed: powershell.exe -EncodedCommand private-script-text')))
     const remote = createSessionTestRemote(ctx, {
       defaultModelSelection: () => ({ provider: 'p', model: 'm' }),
       cwd: '/default',
@@ -110,7 +111,7 @@ describe('session/openWorkspacePath', () => {
     await expect(remote.openWorkspacePath({ path: 'result.html' }))
       .resolves.toMatchObject({
         ok: false,
-        error: { code: 'gateway/internal', message: 'path open failed: desktop unavailable' },
+        error: { code: 'gateway/internal', message: 'path open failed' },
       })
 
     const aborted = new AbortController()
@@ -139,7 +140,7 @@ describe('session/openWorkspacePath', () => {
     await expect(controller.openWorkspacePath({
       path: 'second.html',
     }, new AbortController().signal)).rejects.toMatchObject({
-      code: 'gateway/internal', message: 'path open failed: desktop unavailable',
+      code: 'gateway/internal', message: 'path open failed',
     })
   })
 })
@@ -156,7 +157,7 @@ it('reports Host file-manager metadata and dispatches reveal separately from def
     expect(controller.workspaceDesktop()).toMatchObject({ available: true, name: expect.any(String) as string })
     const signal = new AbortController().signal
     await controller.openWorkspacePath({ path: '/workspace/report.txt', action: 'reveal' }, signal)
-    expect(revealPath).toHaveBeenCalledWith('/workspace/report.txt', signal)
+    expect(revealPath).toHaveBeenCalledWith(resolve('/workspace/report.txt'), signal)
     expect(openPath).not.toHaveBeenCalled()
   } finally { await ctx.fiber.dispose() }
 })
@@ -186,7 +187,7 @@ it.each(['open', 'reveal'] as const)('rejects an unmapped remote path before nat
     defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/default', openPath, revealPath,
   })
   await expect(controller.openWorkspacePath({ path: '/remote/report.html', ...(action === 'reveal' ? { action } : {}) }, new AbortController().signal))
-    .rejects.toMatchObject({ code: 'gateway/internal', message: 'path open failed: Path has no verified Host path' })
+    .rejects.toMatchObject({ code: 'gateway/bad-request', message: 'Path has no verified Host path' })
   expect(openPath).not.toHaveBeenCalled()
   expect(revealPath).not.toHaveBeenCalled()
 })
@@ -200,7 +201,7 @@ it('rejects a filesystem mapping that resolves to another process path', async (
     defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/default', openPath,
   })
   await expect(controller.openWorkspacePath({ path: '/report.html' }, new AbortController().signal))
-    .rejects.toMatchObject({ code: 'gateway/internal', message: 'path open failed: Path has no verified Host path' })
+    .rejects.toMatchObject({ code: 'gateway/bad-request', message: 'Path has no verified Host path' })
   expect(openPath).not.toHaveBeenCalled()
 })
 
@@ -213,5 +214,61 @@ it('dispatches default-app opening to the association adapter', async () => {
   })
   const signal = new AbortController().signal
   await controller.openWorkspacePath({ path: '/report.html' }, signal)
-  expect(open).toHaveBeenCalledWith('/report.html', signal)
+  expect(open).toHaveBeenCalledWith(resolve('/report.html'), signal)
+})
+
+
+it('uses the same path verification for handler queries and explicit application opening', async () => {
+  const ctx = await context()
+  const applications = [{ id: '/Applications/Music.app', name: 'Music', default: true, icon: null }]
+  const fileApplications = vi.fn(async () => applications)
+  const openFileApplication = vi.fn(async () => {})
+  const controller = createSessionTestController(ctx, {
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/default', nativeOpen: true,
+    fileApplications, openFileApplication,
+  })
+  const signal = new AbortController().signal
+  expect(await controller.workspacePathApplications({ path: '/file.mp3' }, signal)).toEqual(applications)
+  await controller.openWorkspacePath({ path: '/file.mp3', application: applications[0]!.id }, signal)
+  expect(openFileApplication).toHaveBeenCalledWith(expect.stringContaining('file.mp3'), applications[0]!.id, signal)
+  const mapping = vi.spyOn(ctx.fs, 'processPathFromHostPath').mockReturnValue(undefined)
+  onTestFinished(() => { mapping.mockRestore() })
+  await expect(controller.workspacePathApplications({ path: '/remote.mp3' }, signal)).rejects.toThrow('verified Host path')
+  await expect(controller.openWorkspacePath({ path: '/remote.mp3', application: applications[0]!.id }, signal)).rejects.toThrow('verified Host path')
+  expect(fileApplications).toHaveBeenCalledOnce()
+  expect(openFileApplication).toHaveBeenCalledOnce()
+})
+
+
+it('avoids desktop queries when unavailable and rejects an empty query path', async () => {
+  const fileApplications = vi.fn(async () => [])
+  const unavailable = createSessionTestController(await context(), {
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/default', nativeOpen: false, fileApplications,
+  })
+  expect(await unavailable.workspacePathApplications({ path: '/file.mp3' }, new AbortController().signal)).toEqual([])
+  const available = createSessionTestController(await context(), {
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/default', nativeOpen: true, fileApplications,
+  })
+  await expect(available.workspacePathApplications({ path: '' }, new AbortController().signal)).rejects.toMatchObject({ code: 'gateway/bad-request' })
+  expect(fileApplications).not.toHaveBeenCalled()
+})
+
+
+it('returns bounded query failures and classifies cancellation through the Remote', async () => {
+  const lifetime = new AbortController()
+  const fileApplications = vi.fn()
+    .mockRejectedValueOnce(new Error('Command failed: osascript -e private-script-text'))
+    .mockImplementationOnce(async () => {
+      lifetime.abort()
+      throw new Error('native query stopped')
+    })
+  const remote = createSessionTestRemote(await context(), {
+    defaultModelSelection: () => ({ provider: 'p', model: 'm' }), cwd: '/default', nativeOpen: true, fileApplications,
+  })
+  await expect(remote.workspacePathApplications({ path: '/file.mp3' })).resolves.toMatchObject({
+    ok: false, error: { code: 'gateway/internal', message: 'file application query failed' },
+  })
+  await expect(remote.workspacePathApplications({ path: '/file.mp3' }, lifetime.signal)).resolves.toMatchObject({
+    ok: false, error: { code: 'gateway/cancelled' },
+  })
 })
diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts
index fd49737fb1..0c93b71af4 100644
--- a/packages/api/session-controller/tests/session.client.spec.ts
+++ b/packages/api/session-controller/tests/session.client.spec.ts
@@ -625,6 +625,30 @@ describe('prompt and cancel errors', () => {
     expect(session.getSnapshot()).toMatchObject({ running: true, awaitingFirstTurn: false })
   })
 
+  it('does not await a first turn when the history already contains one', async ({ mock, start }) => {
+    const session = await sessionBench(mock, start, SID)
+    session.handleBlank(false)
+    const inFlight = session.prompt([{ type: 'text', text: '继续' }], 'queue')
+    expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: true, awaitingFirstTurn: false })
+    expect((await inFlight).ok).toBe(true)
+    expect(session.getSnapshot()).toMatchObject({ blank: false, awaitingFirstTurn: false })
+  })
+
+  it('keeps an accepted first prompt converted when a later prompt is rejected', async ({ mock, start }) => {
+    const session = await sessionBench(mock, start, SID)
+    session.handleBlank(true)
+    expect((await session.prompt([{ type: 'text', text: '第一次' }], 'queue')).ok).toBe(true)
+    session.handleRunning(true)
+    session.handleRunning(false)
+    mock.remote.session.prompt.mockResolvedValue(err(new RemoteError('session/agent-busy', 'busy', { reason: 'x' })))
+
+    expect((await session.prompt([{ type: 'text', text: '第二次' }], 'queue')).ok).toBe(false)
+    expect(session.getSnapshot()).toMatchObject({
+      blank: false, running: false, awaitingFirstTurn: false,
+      promptError: { op: 'send', error: { code: 'session/agent-busy' } },
+    })
+  })
+
   it('keeps the attempted-first-prompt state when the Host rejects the prompt', async ({ mock, start }) => {
     const session = await sessionBench(mock, start, SID)
     session.handleBlank(true)
diff --git a/packages/api/session-controller/tests/sessions-service.client.spec.ts b/packages/api/session-controller/tests/sessions-service.client.spec.ts
index 52da57850d..d4061def11 100644
--- a/packages/api/session-controller/tests/sessions-service.client.spec.ts
+++ b/packages/api/session-controller/tests/sessions-service.client.spec.ts
@@ -7,7 +7,7 @@ import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
 import { LlmAttemptId } from '@deepseek-ai/dsh-llm'
 import { RemoteStreamCarrierError } from '@deepseek-ai/dsh-api-gateway/client'
 import { SESSION_FORMAT_VERSION, SessionSeq } from '@deepseek-ai/dsh-session/types'
-import { ok, type RemoteMock } from '@deepseek-ai/dsh-remote-mock'
+import { ok, streamHandle, type RemoteMock } from '@deepseek-ai/dsh-remote-mock'
 import { createClientTest, webApp } from '@deepseek-ai/dsh-client-test-runtime/src/assembly/index.ts'
 import { ClientSessions, SessionCreateError, SessionForkError } from '../src/client/sessions/service.ts'
 import { scopeOf } from '../src/client/scope.ts'
@@ -461,7 +461,7 @@ describe('scope tree', () => {
     using reference = b.svc.retainAgentScope(sid('s-early'))
     const scoped = reference.binding.ctx
     expect(scopeOf(scoped)).toBe('s-early')
-    b.svc.handleControlFrame({ type: 'baseline', value: { jobs: {}, projections: {} } })
+    b.svc.handleControlFrame({ type: 'baseline', value: { projections: {} } })
     await feedList(b, [])
     expect(b.svc.scope(sid('s-early'))).toBe(scoped)
     reference.release()
@@ -551,7 +551,7 @@ describe('Agent scope disposal lifecycle', () => {
       if (signal === undefined) throw new Error('fixture requires a signal')
       followSignal = signal
       let opened = false
-      return {
+      return streamHandle<SessionFollowFrame>({
         [Symbol.asyncIterator]: () => ({
           next: () => {
             if (!opened) {
@@ -588,7 +588,7 @@ describe('Agent scope disposal lifecycle', () => {
             })
           },
         }),
-      }
+      })
     })
     const readiness = b.ctx.plugin(() => undefined)
     await readiness
@@ -625,7 +625,7 @@ describe('Agent scope disposal lifecycle', () => {
       const closeGate = Promise.withResolvers<undefined>()
       closeGates.set(sessionId, closeGate)
       let opened = false
-      return {
+      return streamHandle<SessionFollowFrame>({
         [Symbol.asyncIterator]: () => ({
           next: () => {
             if (!opened) {
@@ -655,7 +655,7 @@ describe('Agent scope disposal lifecycle', () => {
             })
           },
         }),
-      }
+      })
     })
     const readiness = b.ctx.plugin(() => undefined)
     await readiness
diff --git a/packages/api/session-controller/tests/test-remote.ts b/packages/api/session-controller/tests/test-remote.ts
index b4d3db8198..f0abf92ca0 100644
--- a/packages/api/session-controller/tests/test-remote.ts
+++ b/packages/api/session-controller/tests/test-remote.ts
@@ -1,4 +1,5 @@
 /** Test-only direct Remote face over the Session Controller's internal controllers. */
+import type { SessionControllerInternals } from '../src/index.ts'
 
 import { SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Context } from '@deepseek-ai/cordis'
@@ -48,6 +49,7 @@ import type {
   SessionListValue,
   SessionOpenWorkspacePathRequest,
   SessionOpenWorkspacePathValue,
+  SessionWorkspacePathApplication,
   SessionPage,
   SessionPageRequest,
   SessionPromptRequest,
@@ -65,6 +67,9 @@ import type {
 
 /** Direct test face matching the generated `ctx.remote.session` unary methods. */
 export interface TestSessionRemote {
+  workspacePathApplications(
+    request: { readonly path: string }, signal?: AbortSignal,
+  ): Promise<RemoteResult<readonly SessionWorkspacePathApplication[]>>
   canOpenWorkspacePath(): Promise<RemoteResult<boolean>>
   list(request: SessionListRequest, signal?: AbortSignal): Promise<RemoteResult<SessionListValue>>
   search(request: SessionSearchRequest, signal?: AbortSignal): Promise<RemoteResult<SessionSearchValue>>
@@ -94,6 +99,8 @@ export interface TestSessionRemoteDefaults {
   readonly nativeOpen?: boolean
   readonly saveDefaultModelSelection?: (selection: AgentModelSelection) => void | Promise<void>
   readonly openPath?: (path: string, signal: AbortSignal) => Promise<void>
+  readonly fileApplications?: SessionControllerInternals['fileApplications']
+  readonly openFileApplication?: SessionControllerInternals['openFileApplication']
   readonly revealPath?: (path: string, signal: AbortSignal) => Promise<void>
   readonly canOpenPath?: () => boolean
 }
@@ -288,6 +295,8 @@ function installControllers(
       },
       {
         ...defaults.openPath === undefined ? {} : { openPath: defaults.openPath },
+        ...defaults.fileApplications === undefined ? {} : { fileApplications: defaults.fileApplications },
+        ...defaults.openFileApplication === undefined ? {} : { openFileApplication: defaults.openFileApplication },
         ...defaults.revealPath === undefined ? {} : { revealPath: defaults.revealPath },
         ...defaults.canOpenPath === undefined ? {} : { canOpenPath: defaults.canOpenPath },
       },
@@ -334,6 +343,9 @@ export function createSessionTestRemote(
 ): TestSessionRemote {
   const direct = createSessionTestController(ctx, defaults)
   return {
+    workspacePathApplications: (request, signal = new AbortController().signal) => remoteResult(
+      () => direct.workspacePathApplications(request, signal), signal,
+    ),
     canOpenWorkspacePath: () => remoteResult(() => direct.canOpenWorkspacePath()),
     list: (request, signal = new AbortController().signal) => remoteResult(
       () => direct.list(request, signal),
diff --git a/packages/api/session-controller/tests/transport.client.spec.ts b/packages/api/session-controller/tests/transport.client.spec.ts
index ece1a9ff99..b0efb1b9bb 100644
--- a/packages/api/session-controller/tests/transport.client.spec.ts
+++ b/packages/api/session-controller/tests/transport.client.spec.ts
@@ -5,9 +5,10 @@ import {
   type RemoteStreamOptions,
 } from '@deepseek-ai/dsh-api-gateway/client'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+import { streamHandle } from '@deepseek-ai/dsh-remote-mock'
 import { LlmAttemptId } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session/types'
-import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { RemoteResult, RemoteStreamHandle } from '@deepseek-ai/dsh-typert-protocol'
 import {
   createSessionControlStream,
   SessionEventStream,
@@ -106,7 +107,11 @@ class ScriptedSessionRemote implements SessionTransportRemote {
     private readonly holdControl = true,
   ) {}
 
-  async *follow(request: SessionFollowRequest, signal = new AbortController().signal): AsyncIterable<SessionFollowFrame> {
+  follow(request: SessionFollowRequest, signal = new AbortController().signal): RemoteStreamHandle<SessionFollowFrame, never> {
+    return streamHandle(this.followFrames(request, signal))
+  }
+
+  private async *followFrames(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame> {
     const generation = this.generations.shift()
     if (generation === undefined) throw new Error('no scripted Session generation')
     this.followRequests.push(request)
@@ -128,7 +133,11 @@ class ScriptedSessionRemote implements SessionTransportRemote {
     return Promise.resolve(result)
   }
 
-  async *control(signal = new AbortController().signal): AsyncIterable<SessionControlFrame> {
+  control(signal = new AbortController().signal): RemoteStreamHandle<SessionControlFrame, never> {
+    return streamHandle(this.controlSequence(signal))
+  }
+
+  private async *controlSequence(signal: AbortSignal): AsyncIterable<SessionControlFrame> {
     for (const frame of this.controlFrames) yield frame
     if (this.holdControl && !signal.aborted) {
       await new Promise<void>((resolve) => {
@@ -657,10 +666,10 @@ describe('Session Client stream adapters', () => {
   it('maps the Host-wide control baseline and deltas into one snapshot stream', async () => {
     const baseline: SessionControlFrame = {
       type: 'baseline',
-      value: { jobs: {}, projections: {} },
+      value: { projections: {} },
     }
     const update: SessionControlFrame = {
-      type: 'jobs', sessionId: 'session-1' as never, jobs: [],
+      type: 'projection', sessionId: 'session-1' as never, key: 'title', value: 'updated', seq: 1,
     }
     const remote = new ScriptedSessionRemote([], [], [baseline, update])
     const accept = vi.fn<(frame: SessionControlFrame) => void>()
@@ -692,7 +701,7 @@ describe('Session Client stream adapters', () => {
 
     const baseline: SessionControlFrame = {
       type: 'baseline',
-      value: { jobs: {}, projections: {} },
+      value: { projections: {} },
     }
     const carrierFailed = vi.fn()
     const failed = vi.fn()
diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts
index 04b43972e9..341aaf4e86 100644
--- a/packages/api/session-controller/tests/transport.host.spec.ts
+++ b/packages/api/session-controller/tests/transport.host.spec.ts
@@ -451,6 +451,16 @@ describe('SessionHistoryController', () => {
     }, signal)).resolves.toMatchObject({
       records: [{ type: 'event', event: { type: 'subagent/descriptor' } }],
     })
+    await expect(transport.page({
+      address: { kind: 'subagent', parentSessionId, childSessionId, mode: 'unknown' },
+      throughSeq: 0,
+    }, signal)).resolves.toMatchObject({
+      records: [{ type: 'event', event: { type: 'subagent/descriptor' } }],
+    })
+    await expect(transport.page({
+      address: { kind: 'subagent', parentSessionId: SessionId('other-parent'), childSessionId, mode: 'unknown' },
+      throughSeq: 0,
+    }, signal)).rejects.toMatchObject({ code: 'subagent/unauthorized' })
     await expect(transport.page({
       address: {
         kind: 'subagent',
diff --git a/packages/api/session-controller/tsconfig.client.json b/packages/api/session-controller/tsconfig.client.json
index 3bb07893e2..a1375420ca 100644
--- a/packages/api/session-controller/tsconfig.client.json
+++ b/packages/api/session-controller/tsconfig.client.json
@@ -28,6 +28,7 @@
     { "path": "../../util/crypto" },
     { "path": "../../util/workspace-path" },
     { "path": "../../workspace/workspace" },
-    { "path": "../../typert/protocol" }
+    { "path": "../../typert/protocol" },
+    { "path": "../../util/native-command" }
   ]
 }
diff --git a/packages/api/terminal-controller/package.json b/packages/api/terminal-controller/package.json
index 35e9e26ae2..8862def77e 100644
--- a/packages/api/terminal-controller/package.json
+++ b/packages/api/terminal-controller/package.json
@@ -73,6 +73,7 @@
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-client-store": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-remote-mock": "workspace:^",
     "@deepseek-ai/dsh-sandbox": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/api/terminal-controller/tests/model.client.spec.ts b/packages/api/terminal-controller/tests/model.client.spec.ts
index eb2b64a92a..2c34b9c54b 100644
--- a/packages/api/terminal-controller/tests/model.client.spec.ts
+++ b/packages/api/terminal-controller/tests/model.client.spec.ts
@@ -4,6 +4,7 @@ import { afterEach, expect, it, vi } from 'vitest'
 import { RemoteStream, RemoteStreamCarrierError, type ClientRemote, type RemoteStreamOptions } from '@deepseek-ai/dsh-api-gateway/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { RemoteError, type RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { streamMethod } from '@deepseek-ai/dsh-remote-mock'
 import type {} from '@deepseek-ai/dsh-api-terminal-controller/remote'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { TerminalView, type TerminalRemote } from '../src/client/model.ts'
@@ -31,22 +32,22 @@ function failure(message: string): RemoteResult<never> {
 
 function fixture(prepareStream?: <Item>(stream: RemoteStream<Item>) => void) {
   const remote: TerminalRemote = {
-    retain: vi.fn<TerminalRemote['retain']>(async function* (_session, _id, signal) {
+    retain: vi.fn<TerminalRemote['retain']>(streamMethod<TerminalRemote['retain']>(async function* (_session, _id, signal) {
       yield { type: 'retained' }
       await new Promise<void>((resolve) => {
         if (signal?.aborted) resolve()
         else signal?.addEventListener('abort', () => { resolve() }, { once: true })
       })
-    }),
+    })),
     shells: vi.fn<TerminalRemote['shells']>(async () => success([info.shell])),
     environment: vi.fn<TerminalRemote['environment']>(async () => success(environment)), list: vi.fn<TerminalRemote['list']>(async () => success([])),
     create: vi.fn<TerminalRemote['create']>(async (_sessionId, request) => success({ ...info, id: request.id })),
     close: vi.fn<TerminalRemote['close']>(async () => success(undefined)), rename: vi.fn<TerminalRemote['rename']>(async () => success(undefined)),
     write: vi.fn<TerminalRemote['write']>(async () => success(undefined)), resize: vi.fn<TerminalRemote['resize']>(async () => success(undefined)),
-    follow: vi.fn<TerminalRemote['follow']>(async function* (_sessionId, id, attachmentId, signal) {
+    follow: vi.fn<TerminalRemote['follow']>(streamMethod<TerminalRemote['follow']>(async function* (_sessionId, id, attachmentId, signal) {
       yield { type: 'snapshot', sequence: 0, screen: 'ready', info: { ...info, id, controllerId: attachmentId } }
       await untilAborted(signal)
-    }),
+    })),
   }
   const options: RemoteStreamOptions<unknown>[] = []
   const streams: { dispose(): Promise<void>; restart(): void }[] = []
@@ -103,7 +104,7 @@ it('does not let a late input failure downgrade a newer connection', async () =>
 
 it('waits for render acknowledgement before publishing subsequent output', async () => {
   const { model, remote } = fixture()
-  vi.mocked(remote.follow).mockImplementation(async function* (_sessionId, id, controllerId, signal) {
+  vi.mocked(remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* (_sessionId, id, controllerId, signal) {
     const frames: TerminalFrame[] = [
       { type: 'snapshot', sequence: 0, screen: '', info: { ...info, id, controllerId } },
       { type: 'output', sequence: 1, data: 'first' },
@@ -111,7 +112,7 @@ it('waits for render acknowledgement before publishing subsequent output', async
     ]
     for (const frame of frames) yield frame
     await untilAborted(signal)
-  })
+  }))
   await mount(model)
   await expect.poll(() => model.state.getSnapshot().render?.frame.type).toBe('snapshot')
   acknowledge(model)
@@ -209,7 +210,7 @@ it.each([
   ['repeated snapshot', [{ type: 'snapshot', sequence: 4, screen: '', info }, { type: 'snapshot', sequence: 4, screen: '', info }], 'Unexpected terminal screen snapshot'],
 ] satisfies readonly (readonly [string, readonly TerminalFrame[], string])[])('refuses a malformed output stream: %s', async (_name, frames, message) => {
   const { model, remote } = fixture()
-  vi.mocked(remote.follow).mockImplementation(async function* () { yield* frames })
+  vi.mocked(remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* () { yield* frames }))
   await mount(model)
   if (frames[0]?.type === 'snapshot') {
     await expect.poll(() => model.state.getSnapshot().render).toBeDefined()
@@ -221,10 +222,10 @@ it.each([
 
 it('retains an exited screen and closes controls when its stream ends', async () => {
   const { model, remote } = fixture()
-  vi.mocked(remote.follow).mockImplementation(async function* (_sessionId, id, controllerId) {
+  vi.mocked(remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* (_sessionId, id, controllerId) {
     yield { type: 'snapshot', sequence: 0, screen: 'last screen', info: { ...info, id, controllerId } }
     yield { type: 'state', info: { ...info, id, controllerId, state: 'exited', exitCode: 3 } }
-  })
+  }))
   await connected(model)
   await expect.poll(() => model.state.getSnapshot().phase).toBe('closed')
   expect(model.state.getSnapshot()).toMatchObject({ writable: false, info: { state: 'exited', exitCode: 3 }, render: { frame: { screen: 'last screen' } } })
@@ -232,9 +233,9 @@ it('retains an exited screen and closes controls when its stream ends', async ()
 
 it('reports an attachment ending while the shell is still running and permits manual reconnect', async () => {
   const { model, remote } = fixture()
-  vi.mocked(remote.follow).mockImplementationOnce(async function* (_sessionId, id, controllerId) {
+  vi.mocked(remote.follow).mockImplementationOnce(streamMethod<TerminalRemote['follow']>(async function* (_sessionId, id, controllerId) {
     yield { type: 'snapshot', sequence: 0, screen: '', info: { ...info, id, controllerId } }
-  })
+  }))
   await connected(model)
   await expect.poll(() => model.state.getSnapshot().issue).toBe('attachmentEnded')
   model.connect()
@@ -243,11 +244,11 @@ it('reports an attachment ending while the shell is still running and permits ma
 
 it('publishes remote control transfer without replacing the retained screen', async () => {
   const { model, remote } = fixture()
-  vi.mocked(remote.follow).mockImplementation(async function* (_sessionId, id, controllerId, signal) {
+  vi.mocked(remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* (_sessionId, id, controllerId, signal) {
     yield { type: 'snapshot', sequence: 0, screen: 'retained', info: { ...info, id, controllerId } }
     yield { type: 'state', info: { ...info, id } }
     await untilAborted(signal)
-  })
+  }))
   await connected(model)
   await expect.poll(() => model.state.getSnapshot().writable).toBe(false)
   expect(model.state.getSnapshot().render?.frame).toMatchObject({ type: 'snapshot', screen: 'retained' })
@@ -298,10 +299,10 @@ it('ignores an already delivered screen when its attachment is replaced before t
 it('ignores an already settled stream error after a newer attachment has become writable', async () => {
   const barrier = deliveryBarrier()
   const { model, remote } = fixture(barrier.prepare)
-  vi.mocked(remote.follow).mockImplementationOnce(async function* () {
+  vi.mocked(remote.follow).mockImplementationOnce(streamMethod<TerminalRemote['follow']>(async function* () {
     yield* []
     throw new Error('retired attachment failed')
-  })
+  }))
   await mount(model)
   await barrier.ready
   model.connect()
@@ -338,12 +339,12 @@ it.each(['write', 'resize'] as const)('keeps a fresh attachment writable when a
   const { model, remote, generation } = fixture()
   generation.set({ id: 1, host: { home: '/home/fixture' } })
   const disconnected = Promise.withResolvers<undefined>()
-  vi.mocked(remote.follow).mockImplementationOnce(async function* (_sessionId, id, controllerId, signal) {
+  vi.mocked(remote.follow).mockImplementationOnce(streamMethod<TerminalRemote['follow']>(async function* (_sessionId, id, controllerId, signal) {
     yield { type: 'snapshot', sequence: 0, screen: 'before disconnect', info: { ...info, id, controllerId } }
     await Promise.race([disconnected.promise, untilAborted(signal)])
     if (signal?.aborted) return
     throw new RemoteStreamCarrierError('connection lost')
-  })
+  }))
   await connected(model)
   const pending = Promise.withResolvers<RemoteResult<void>>()
   if (operation === 'write') {
@@ -516,12 +517,12 @@ it.each(['write', 'resize'] as const)('keeps the output connection when %s loses
   const transfer = Promise.withResolvers<undefined>()
   const response = Promise.withResolvers<RemoteResult<void>>()
   cleanups.push(() => { transfer.resolve(undefined); response.resolve(success(undefined)) })
-  vi.mocked(remote.follow).mockImplementation(async function* (_session, id, controllerId, signal) {
+  vi.mocked(remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* (_session, id, controllerId, signal) {
     yield { type: 'snapshot', sequence: 0, screen: 'retained screen', info: { ...info, id, controllerId } }
     await transfer.promise
     yield { type: 'state', info: { ...info, id } }
     await untilAborted(signal)
-  })
+  }))
   await connected(model)
   vi.mocked(remote[operation]).mockReturnValueOnce(response.promise)
   if (operation === 'write') model.write('before transfer')
@@ -542,12 +543,12 @@ it('keeps an exited screen when a pending input is refused after the exit state
   const exit = Promise.withResolvers<undefined>()
   const response = Promise.withResolvers<RemoteResult<void>>()
   cleanups.push(() => { exit.resolve(undefined); response.resolve(success(undefined)) })
-  vi.mocked(remote.follow).mockImplementation(async function* (_session, id, controllerId, signal) {
+  vi.mocked(remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* (_session, id, controllerId, signal) {
     yield { type: 'snapshot', sequence: 0, screen: 'final screen', info: { ...info, id, controllerId } }
     await exit.promise
     yield { type: 'state', info: { ...info, id, state: 'exited', exitCode: 0 } }
     await untilAborted(signal)
-  })
+  }))
   await connected(model)
   vi.mocked(remote.write).mockReturnValueOnce(response.promise)
   model.write('exit race')
diff --git a/packages/api/terminal-controller/tests/recovery.client.spec.ts b/packages/api/terminal-controller/tests/recovery.client.spec.ts
index b8ed76b366..690dd9bf0d 100644
--- a/packages/api/terminal-controller/tests/recovery.client.spec.ts
+++ b/packages/api/terminal-controller/tests/recovery.client.spec.ts
@@ -4,6 +4,7 @@ import { afterEach, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { RemoteError, type RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { streamMethod } from '@deepseek-ai/dsh-remote-mock'
 import { RemoteStream, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
 import type {} from '@deepseek-ai/dsh-api-terminal-controller/remote'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -29,25 +30,25 @@ function storage() {
 
 function fixture() {
   const remote: TerminalRemote = {
-    retain: vi.fn<TerminalRemote['retain']>(async function* (_session, _id, signal) {
+    retain: vi.fn<TerminalRemote['retain']>(streamMethod<TerminalRemote['retain']>(async function* (_session, _id, signal) {
       yield { type: 'retained' }
       await new Promise<void>((resolve) => {
         if (signal?.aborted) resolve()
         else signal?.addEventListener('abort', () => { resolve() }, { once: true })
       })
-    }),
+    })),
     shells: vi.fn<TerminalRemote['shells']>(async () => success([info.shell])),
     environment: vi.fn<TerminalRemote['environment']>(async () => success(environment)), list: vi.fn<TerminalRemote['list']>(async () => success([])),
     create: vi.fn<TerminalRemote['create']>(async (_session, request) => success({ ...info, id: request.id })),
     close: vi.fn<TerminalRemote['close']>(async () => success(undefined)), rename: vi.fn<TerminalRemote['rename']>(async () => success(undefined)),
     write: vi.fn<TerminalRemote['write']>(async () => success(undefined)), resize: vi.fn<TerminalRemote['resize']>(async () => success(undefined)),
-    follow: vi.fn<TerminalRemote['follow']>(async function* (_session, id, controllerId, signal) {
+    follow: vi.fn<TerminalRemote['follow']>(streamMethod<TerminalRemote['follow']>(async function* (_session, id, controllerId, signal) {
       yield { type: 'snapshot', sequence: 0, screen: 'retained', info: { ...info, id, controllerId } }
       await new Promise<void>((resolve) => {
         if (signal?.aborted) resolve()
         else signal?.addEventListener('abort', () => { resolve() }, { once: true })
       })
-    }),
+    })),
   }
   const gateway: Pick<ClientRemote, '$stream'> = { $stream: options => new RemoteStream({ generation: createSnapshotStore(undefined) }, options) }
   function view() {
@@ -489,7 +490,7 @@ it('waits for both active and detached stream finalizers during plugin disposal
   const finished = [Promise.withResolvers<undefined>(), Promise.withResolvers<undefined>()]
   cleanups.push(() => { for (const barrier of release) barrier.resolve(undefined) })
   let index = 0
-  vi.mocked(h.remote.follow).mockImplementation(async function* (_session, id, controllerId, signal) {
+  vi.mocked(h.remote.follow).mockImplementation(streamMethod<TerminalRemote['follow']>(async function* (_session, id, controllerId, signal) {
     const current = index++
     try {
       yield { type: 'snapshot', sequence: 0, screen: 'screen', info: { ...info, id, controllerId } }
@@ -502,7 +503,7 @@ it('waits for both active and detached stream finalizers during plugin disposal
       await release[current]!.promise
       finished[current]!.resolve(undefined)
     }
-  })
+  }))
   const model = service.view(sessionId, 'tab', 'tab')
   model.mount()
   await model.refresh()
@@ -625,14 +626,14 @@ it('waits for the window hold acknowledgement before restoring an output attachm
   const h = fixture()
   vi.mocked(h.remote.list).mockResolvedValue(success([info]))
   const acknowledge = Promise.withResolvers<undefined>()
-  vi.mocked(h.remote.retain).mockImplementation(async function* (_session, _id, signal) {
+  vi.mocked(h.remote.retain).mockImplementation(streamMethod<TerminalRemote['retain']>(async function* (_session, _id, signal) {
     await acknowledge.promise
     yield { type: 'retained' }
     await new Promise<void>((resolve) => {
       if (signal?.aborted) resolve()
       else signal?.addEventListener('abort', () => { resolve() }, { once: true })
     })
-  })
+  }))
   const { service } = await h.service()
   service.retainTabs([{ sessionId, tabId: 'restored', contentId: 'restored' }])
   const model = service.view(sessionId, 'restored', 'restored')
diff --git a/packages/api/terminal-controller/tests/retention.client.spec.ts b/packages/api/terminal-controller/tests/retention.client.spec.ts
index a6c0f88ed1..11a87f3fe1 100644
--- a/packages/api/terminal-controller/tests/retention.client.spec.ts
+++ b/packages/api/terminal-controller/tests/retention.client.spec.ts
@@ -2,6 +2,7 @@
 import { afterEach, expect, it, vi } from 'vitest'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { RemoteStream, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
+import { streamMethod } from '@deepseek-ai/dsh-remote-mock'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { TerminalRemote } from '../src/client/model.ts'
 import { TerminalWindowHold } from '../src/client/retention.ts'
@@ -9,9 +10,14 @@ import type { TerminalRetentionFrame, WebTerminalId } from '../src/types.ts'
 
 const holds: TerminalWindowHold[] = []
 afterEach(async () => { await Promise.all(holds.splice(0).map(hold => hold.dispose())) })
-function hold(retain: TerminalRemote['retain']) {
+function hold(retain: Parameters<typeof streamMethod<TerminalRemote['retain']>>[0]) {
   const gateway: Pick<ClientRemote, '$stream'> = { $stream: options => new RemoteStream({ generation: createSnapshotStore(undefined) }, options) }
-  const held = new TerminalWindowHold(gateway, { retain } as TerminalRemote, 'session' as SessionId, 'terminal' as WebTerminalId)
+  const held = new TerminalWindowHold(
+    gateway,
+    { retain: streamMethod<TerminalRemote['retain']>(retain) } as TerminalRemote,
+    'session' as SessionId,
+    'terminal' as WebTerminalId,
+  )
   holds.push(held)
   return held
 }
diff --git a/packages/api/workspace-controller/README.i18n.yaml b/packages/api/workspace-controller/README.i18n.yaml
index cd584226a9..0520266936 100644
--- a/packages/api/workspace-controller/README.i18n.yaml
+++ b/packages/api/workspace-controller/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/workspace-controller/README.md
-README.md: 46556b0105bb5186cf27b56faee4127b358eac9b
-README.zh.md: 9d210c10486a71772cf6c0a10480b734fa992441
+README.md: 27053331007681eb373b4537514bbe701dad660d
+README.zh.md: d0726496de5dcf623fedb531ad988b3c608fc2ac
diff --git a/packages/api/workspace-controller/README.md b/packages/api/workspace-controller/README.md
index 46556b0105..2705333100 100644
--- a/packages/api/workspace-controller/README.md
+++ b/packages/api/workspace-controller/README.md
@@ -26,6 +26,20 @@ The Host controller serializes mutations whose correctness depends on current re
 
 The Client entry provides `ClientWorkspaceModel` and `createWorkspaceStateStream()`. The model owns Workspace rows, registry order, archived and pinned Session identities, unary mutation echoes, and stream/unary race resolution. A newer Host row wins by `updatedAt`; a committed stream order outranks an older unary response; a removed Workspace id cannot be resurrected by delayed data. Pin snapshots change only when their identities or order change. The package exposes framework-neutral snapshots and subscriptions, leaving navigation policy and React hooks to the UI owner.
 
+<a id="first-use-workspace"></a>
+### First-use Workspace
+
+`workspace.initializeDefault({ directoryName, title })` returns the durable default Workspace; the Client service exposes the same request as `workspaces.initializeDefault(request, signal?)`. The [Workspace Client](../../client/ui-workspace/README.md) resolves these names from its startup language. The Host places the directory under its account's `<Documents>/deepseek-harness`, including on remote Web hosts. The directory name must be one non-blank segment without separators, colon, NUL, surrounding whitespace, or a trailing dot; the title must be non-blank. OS filename restrictions also apply. Linux system lookup requires `xdg-user-dir` with an enabled Documents directory; hosts without it must configure `documentsDirectory` or use the folder picker.
+
+The [Workspace registry](../../workspace/workspace/README.md#first-use-workspace) owns eligibility, directory creation, and durable initialization. An existing default Workspace is returned without another Documents lookup; request names do not rename it. Ineligible first use returns `undefined`, so startup can leave directory selection to the user. Invalid names reject with `gateway/bad-request`; lookup and creation failures use standard Remote error handling. Initialization creates no Session and sends no message.
+
+| Configuration | Default | Purpose |
+| --- | --- | --- |
+| `documentsDirectory` | System Documents directory | Fully qualified Host directory override |
+| `documentsLookupTimeoutMs` | `10000` | Positive maximum duration of OS directory lookup, in milliseconds |
+
+Documents lookup holds the registry mutation queue, so other Workspace mutations, including registration of a picked directory, can wait up to `documentsLookupTimeoutMs`. Cancellation can stop the lookup; after resolution succeeds, it does not roll back creation or registration.
+
 -----
 
 <a id="model-experience"></a>
diff --git a/packages/api/workspace-controller/README.zh.md b/packages/api/workspace-controller/README.zh.md
index 9d210c1048..d0726496de 100644
--- a/packages/api/workspace-controller/README.zh.md
+++ b/packages/api/workspace-controller/README.zh.md
@@ -26,6 +26,20 @@ Host 控制器会串行执行正确性取决于当前注册表状态的变更，
 
 Client 入口提供 `ClientWorkspaceModel` 和 `createWorkspaceStateStream()`。该模型拥有 Workspace 行、registry 顺序、归档与置顶会话身份、一元变更回显，以及流与一元调用的竞态处理。较新的 Host 行按 `updatedAt` 获胜；已提交的流顺序优先于较旧的一元响应；已经移除的 Workspace id 不会被延迟数据复活。置顶快照仅在会话身份或顺序变化时更新。该包公开与框架无关的快照和订阅，把导航策略与 React 钩子留给 UI owner。
 
+<a id="first-use-workspace"></a>
+### 首次使用工作区
+
+`workspace.initializeDefault({ directoryName, title })` 返回持久化的默认工作区；Client service 通过 `workspaces.initializeDefault(request, signal?)` 提供同一请求。[Workspace Client](../../client/ui-workspace/README.zh.md)按启动时的语言解析这些名称。Host 将目录放在其账户的 `<Documents>/deepseek-harness` 下，远程 Web Host 也遵循此规则。目录名必须是非空的单个片段，不能含分隔符、冒号、NUL、首尾空白或末尾句点；标题不能为空。操作系统的文件名限制同样适用。Linux 系统查询要求存在 `xdg-user-dir` 且启用了 Documents 目录；不具备该条件的 Host 必须配置 `documentsDirectory` 或使用文件夹选择器。
+
+[Workspace 注册表](../../workspace/workspace/README.zh.md#first-use-workspace)负责资格判断、目录创建和持久化初始化。已有默认工作区直接返回，不再查询 Documents；请求中的名称不会将其重命名。不满足首次使用条件时返回 `undefined`，启动流程可将目录选择留给用户。名称无效时以 `gateway/bad-request` 拒绝；查询和创建失败遵循标准 Remote 错误处理。初始化不创建 Session，也不发送消息。
+
+| 配置 | 默认值 | 用途 |
+| --- | --- | --- |
+| `documentsDirectory` | 系统 Documents 目录 | 完全限定的 Host 目录覆盖值 |
+| `documentsLookupTimeoutMs` | `10000` | 操作系统目录查询的正数最大时长，单位为毫秒 |
+
+Documents 查询占用注册表变更队列，因此其他 Workspace 变更（包括登记已选目录）最多可能等待 `documentsLookupTimeoutMs`。取消可以停止查询；解析成功后，取消不会回滚创建或登记。
+
 -----
 
 <a id="model-experience"></a>
diff --git a/packages/api/workspace-controller/package.json b/packages/api/workspace-controller/package.json
index 48881e37ce..8085412c62 100644
--- a/packages/api/workspace-controller/package.json
+++ b/packages/api/workspace-controller/package.json
@@ -66,6 +66,8 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/dsh-deque": "workspace:^",
+    "@deepseek-ai/dsh-native-command": "workspace:^",
+    "@deepseek-ai/schemastery": "workspace:^",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
diff --git a/packages/api/workspace-controller/src/client/index.ts b/packages/api/workspace-controller/src/client/index.ts
index 9a1af4c2e7..a9a98085f8 100644
--- a/packages/api/workspace-controller/src/client/index.ts
+++ b/packages/api/workspace-controller/src/client/index.ts
@@ -17,7 +17,7 @@ export type {
 } from './model.ts'
 export { WorkspaceController, WorkspaceCreateError } from './service.ts'
 export type { IWorkspaces, WorkspaceSource } from './service.ts'
-export type { WorkspaceId, WorkspaceView } from '../types.ts'
+export type { WorkspaceId, WorkspaceInitializeDefaultRequest, WorkspaceView } from '../types.ts'
 
 type WorkspaceBaselineFrame = Extract<WorkspaceFollowFrame, { type: 'baseline' }>
 
diff --git a/packages/api/workspace-controller/src/client/model.ts b/packages/api/workspace-controller/src/client/model.ts
index 570b70aeb3..25a84d655e 100644
--- a/packages/api/workspace-controller/src/client/model.ts
+++ b/packages/api/workspace-controller/src/client/model.ts
@@ -12,6 +12,7 @@ import type {
   WorkspaceCreateValue,
   WorkspaceDeleteValue,
   WorkspaceInsertSessionBeforeRequest,
+  WorkspaceInitializeDefaultRequest,
   WorkspaceOrderValue,
   WorkspacePinSessionRequest,
   WorkspacePinValue,
@@ -101,6 +102,20 @@ export class ClientWorkspaceModel implements WorkspaceFollowSink {
     return result
   }
 
+  /**
+   * Initialize the default Workspace and merge its authoritative row.
+   * @param request - initial directory name and title.
+   * @param signal - caller lifetime.
+   * @returns generated Remote result.
+   */
+  async initializeDefault(
+    request: WorkspaceInitializeDefaultRequest, signal?: AbortSignal,
+  ): Promise<RemoteResult<WorkspaceValue | undefined>> {
+    const result = await this.remote.initializeDefault(request, signal)
+    if (result.ok && result.value !== undefined) this.upsert(result.value.workspace)
+    return result
+  }
+
   /**
    * Rename a Workspace and merge the unary result immediately.
    * @param workspaceId - target Workspace.
diff --git a/packages/api/workspace-controller/src/client/service.ts b/packages/api/workspace-controller/src/client/service.ts
index 00998f8519..393fed0b7f 100644
--- a/packages/api/workspace-controller/src/client/service.ts
+++ b/packages/api/workspace-controller/src/client/service.ts
@@ -4,7 +4,7 @@ import { Service, type Context } from '@deepseek-ai/cordis'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { RemoteFailure } from '@deepseek-ai/dsh-typert-protocol'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
-import type { WorkspaceView } from '../types.ts'
+import type { WorkspaceInitializeDefaultRequest, WorkspaceView } from '../types.ts'
 import type { ClientWorkspaceModel, WorkspaceSnapshot } from './model.ts'
 
 /** Structured create failure for callers that distinguish Host business errors. */
@@ -39,6 +39,13 @@ export interface IWorkspaces {
    * @returns the created or idempotently resolved Workspace.
    */
   create(input: { path: string }): Promise<WorkspaceView>
+  /**
+   * Initialize or reuse the default Workspace.
+   * @param request - initial directory name and title.
+   * @param signal - caller lifetime.
+   * @returns the prepared Workspace, or undefined when first-use initialization is ineligible; rejects on preparation failure.
+   */
+  initializeDefault(request: WorkspaceInitializeDefaultRequest, signal?: AbortSignal): Promise<WorkspaceView | undefined>
   /**
    * Rename a Workspace.
    * @param workspaceId - target Workspace.
@@ -110,6 +117,12 @@ export class WorkspaceController extends Service implements IWorkspaces {
     return result.value.workspace
   }
 
+  async initializeDefault(request: WorkspaceInitializeDefaultRequest, signal?: AbortSignal): Promise<WorkspaceView | undefined> {
+    const result = await this.model.initializeDefault(request, signal)
+    if (!result.ok) throw new WorkspaceCreateError(result.error)
+    return result.value?.workspace
+  }
+
   async rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView> {
     const result = await this.model.rename(workspaceId, title)
     if (!result.ok) throw commandError('rename', result.error)
diff --git a/packages/api/workspace-controller/src/default-directory.ts b/packages/api/workspace-controller/src/default-directory.ts
new file mode 100644
index 0000000000..2001b903c6
--- /dev/null
+++ b/packages/api/workspace-controller/src/default-directory.ts
@@ -0,0 +1,79 @@
+/** Resolve the Host account's Documents directory for first-use Workspace creation. */
+
+import { homedir } from 'node:os'
+import { posix, win32 } from 'node:path'
+import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
+
+/** Platform observations replaceable in directory-resolution tests. */
+interface DocumentsDirectoryInternals {
+  readonly platform?: NodeJS.Platform
+  readonly home?: string
+  readonly run?: NativeCommandRunner
+}
+
+/**
+ * Validate a configured or OS-returned Documents path without resolving it against cwd.
+ * @param directory - fully qualified directory spelling.
+ * @param platform - Host platform.
+ * @returns the normalized directory.
+ */
+export function validateDocumentsDirectory(directory: string, platform: NodeJS.Platform = process.platform): string {
+  const paths = platform === 'win32' ? win32 : posix
+  const root = paths.parse(directory).root
+  if (!paths.isAbsolute(directory) || (platform === 'win32' && (root === '\\' || root === '/'))) {
+    throw new Error(`Documents directory must be fully qualified: '${directory}'`)
+  }
+  return paths.normalize(directory)
+}
+
+/**
+ * Resolve the first-use directory on the Host without creating files.
+ * @param directoryName - validated single directory name supplied by the Client.
+ * @param documentsDirectory - explicit deployment override for the system Documents directory.
+ * @param signal - caller lifetime and lookup deadline.
+ * @param internals - platform facts and native command runner.
+ * @returns the absolute candidate path.
+ */
+export async function defaultWorkspaceDirectory(
+  directoryName: string,
+  documentsDirectory: string | undefined,
+  signal: AbortSignal,
+  internals: DocumentsDirectoryInternals = {},
+): Promise<string> {
+  const platform = internals.platform ?? process.platform
+  const paths = platform === 'win32' ? win32 : posix
+  signal.throwIfAborted()
+  let directory = documentsDirectory
+  if (directory === undefined) {
+    const run = internals.run ?? runNativeCommand
+    let stdout: string
+    switch (platform) {
+      case 'darwin':
+        ({ stdout } = await run('osascript', [
+          '-e', 'POSIX path of (path to documents folder from user domain without folder creation)',
+        ], signal))
+        break
+      case 'win32':
+        ({ stdout } = await run('powershell.exe', [
+          '-NoLogo', '-NoProfile', '-NonInteractive', '-Command',
+          '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); '
+          + '[Environment]::GetFolderPath([Environment+SpecialFolder]::MyDocuments, '
+          + '[Environment+SpecialFolderOption]::DoNotVerify)',
+        ], signal))
+        break
+      case 'linux':
+        ({ stdout } = await run('xdg-user-dir', ['DOCUMENTS'], signal))
+        break
+      default:
+        throw new Error(`system Documents directory is unavailable on ${platform}`)
+    }
+    directory = stdout.replace(/[\r\n]+$/, '')
+    // XDG reports the home directory when this user directory is disabled.
+    if (directory === '' || (platform === 'linux' && paths.normalize(directory) === (internals.home ?? homedir()))) {
+      throw new Error('system Documents directory is unavailable')
+    }
+  }
+  directory = validateDocumentsDirectory(directory, platform)
+  signal.throwIfAborted()
+  return paths.join(directory, 'deepseek-harness', directoryName)
+}
diff --git a/packages/api/workspace-controller/src/index.ts b/packages/api/workspace-controller/src/index.ts
index deb547e791..928f52f883 100644
--- a/packages/api/workspace-controller/src/index.ts
+++ b/packages/api/workspace-controller/src/index.ts
@@ -1,10 +1,12 @@
 /** Host Workspace Remote owner: explicit commands and reconnect-safe state. */
 
 import { Context } from '@deepseek-ai/cordis'
-import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import z from '@deepseek-ai/schemastery'
+import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { WorkspaceCommands } from './commands.ts'
 import { DirectoryPickerController } from './directory-picker.ts'
-import { WorkspaceFeed } from './feed.ts'
+import { WorkspaceFeed, workspaceView } from './feed.ts'
+import { defaultWorkspaceDirectory, validateDocumentsDirectory } from './default-directory.ts'
 import type {
   WorkspaceArchiveSessionRequest,
   WorkspaceArchiveValue,
@@ -14,6 +16,7 @@ import type {
   WorkspaceDeleteValue,
   WorkspaceFollowFrame,
   WorkspaceInsertBeforeRequest,
+  WorkspaceInitializeDefaultRequest,
   WorkspaceInsertSessionBeforeRequest,
   WorkspaceOrderValue,
   WorkspacePinSessionRequest,
@@ -27,6 +30,17 @@ import type {
 export type * from './types.ts'
 export { DirectoryPickerController } from './directory-picker.ts'
 
+/** First-use directory policy for the Host account. */
+export interface Config {
+  /** Override the system Documents directory with a fully qualified path. */
+  documentsDirectory?: string
+  /** Maximum duration of the operating system's Documents lookup. */
+  documentsLookupTimeoutMs?: number
+}
+
+/** Directory policy after schema defaults have been applied. */
+type ResolvedConfig = Config & { documentsLookupTimeoutMs: number }
+
 declare module '@deepseek-ai/cordis' {
   interface Context {
     /** Host Workspace business API and Remote namespace owner. */
@@ -38,12 +52,23 @@ declare module '@deepseek-ai/cordis' {
 export class WorkspaceController extends TypertRemoteService {
   static inject = ['typert', 'workspaceRegistry']
 
+  static Config: z<Config, ResolvedConfig> = z.object({
+    documentsDirectory: z.string(),
+    documentsLookupTimeoutMs: z.natural().min(1).default(10_000),
+  })
+
+  private readonly config: ResolvedConfig
   private readonly commands: WorkspaceCommands
   private readonly feed: WorkspaceFeed
 
-  /** @param ctx - Host context containing the Workspace registry. */
-  constructor(ctx: Context) {
+  /**
+   * @param ctx - Host context containing the Workspace registry.
+   * @param config - first-use directory policy.
+   */
+  constructor(ctx: Context, config: Config = {}) {
     super(ctx, 'workspaceController', { namespace: 'workspace' })
+    this.config = WorkspaceController.Config(config)
+    if (this.config.documentsDirectory !== undefined) validateDocumentsDirectory(this.config.documentsDirectory)
     this.commands = new WorkspaceCommands(ctx)
     this.feed = new WorkspaceFeed(ctx)
     // This package is the Loader entry for both Remote owners it hosts: the
@@ -63,6 +88,29 @@ export class WorkspaceController extends TypertRemoteService {
     return this.commands.create(request)
   }
 
+  /**
+   * Initialize or reuse the default Workspace during first-use startup.
+   * @param request - initial directory name and title; never rename an existing default.
+   * @param signal - caller lifetime; cancels native directory lookup.
+   * @returns the durable Workspace, or undefined when first-use initialization is ineligible; creates no Session or message.
+   */
+  @Remote('initializeDefault')
+  async initializeDefault(request: WorkspaceInitializeDefaultRequest, signal: AbortSignal): Promise<WorkspaceValue | undefined> {
+    const { directoryName, title } = request
+    if (directoryName.trim() === '' || directoryName !== directoryName.trim()
+      || directoryName.endsWith('.') || /[/\\:\0]/.test(directoryName) || title.trim() === '') {
+      throw new RemoteError('gateway/bad-request', 'default Workspace requires a directory name and non-blank title', {})
+    }
+    const workspace = await this.ctx.workspaceRegistry.initializeDefault(async () => {
+      const timeout = AbortSignal.timeout(this.config.documentsLookupTimeoutMs)
+      const path = await defaultWorkspaceDirectory(
+        directoryName, this.config.documentsDirectory, AbortSignal.any([signal, timeout]),
+      )
+      return { path, title }
+    })
+    return workspace === undefined ? undefined : { workspace: workspaceView(workspace) }
+  }
+
   /**
    * Rename one Workspace to a unique non-blank title.
    * @param request - Workspace identity and proposed title.
diff --git a/packages/api/workspace-controller/src/types.ts b/packages/api/workspace-controller/src/types.ts
index f2b78e024b..97188d9f23 100644
--- a/packages/api/workspace-controller/src/types.ts
+++ b/packages/api/workspace-controller/src/types.ts
@@ -54,6 +54,14 @@ export interface WorkspaceCreateRequest {
   readonly path: string
 }
 
+/** Names chosen by the first-use Client before default Workspace initialization. */
+export interface WorkspaceInitializeDefaultRequest {
+  /** Host rejects blank names, separators, colon, NUL, surrounding whitespace, and trailing dots; OS filename restrictions also apply. */
+  readonly directoryName: string
+  /** Initial display title, retained across language changes. */
+  readonly title: string
+}
+
 /** Created or previously registered Workspace. */
 export interface WorkspaceCreateValue {
   readonly workspace: WorkspaceView
diff --git a/packages/api/workspace-controller/tests/default-directory.host.spec.ts b/packages/api/workspace-controller/tests/default-directory.host.spec.ts
new file mode 100644
index 0000000000..5878f42432
--- /dev/null
+++ b/packages/api/workspace-controller/tests/default-directory.host.spec.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { NativeCommandRunner } from '@deepseek-ai/dsh-native-command'
+import { defaultWorkspaceDirectory, validateDocumentsDirectory } from '../src/default-directory.ts'
+
+describe('system Documents directory', () => {
+  it.each([
+    ['darwin', '/Users/a/文档/\n', '/Users/a/文档/deepseek-harness/默认工作区', 'osascript'],
+    ['win32', 'D:\\Redirected Documents\r\n', 'D:\\Redirected Documents\\deepseek-harness\\默认工作区', 'powershell.exe'],
+    ['linux', '/home/a/My Documents\n', '/home/a/My Documents/deepseek-harness/默认工作区', 'xdg-user-dir'],
+  ] as const)('uses the %s account directory and preserves spaces and Unicode', async (platform, stdout, path, command) => {
+    const run = vi.fn<NativeCommandRunner>(async () => ({ stdout, stderr: '' }))
+    const signal = new AbortController().signal
+    await expect(defaultWorkspaceDirectory('默认工作区', undefined, signal, { platform, run })).resolves.toBe(path)
+    expect(run).toHaveBeenCalledWith(command, expect.any(Array), signal)
+  })
+
+  it.each(['Default workspace', '默认工作区', 'default-workspace'])('uses the configured directory with name %s', async (folder) => {
+    const run = vi.fn<NativeCommandRunner>()
+    await expect(defaultWorkspaceDirectory(folder, '/documents', new AbortController().signal, { platform: 'linux', run }))
+      .resolves.toBe(`/documents/deepseek-harness/${folder}`)
+    expect(run).not.toHaveBeenCalled()
+  })
+
+  it.each(['', '\r\n', '/home/a\n'])('rejects an unavailable XDG directory %j', async (stdout) => {
+    const run: NativeCommandRunner = async () => ({ stdout, stderr: '' })
+    await expect(defaultWorkspaceDirectory('Default workspace', undefined, new AbortController().signal, { platform: 'linux', home: '/home/a', run }))
+      .rejects.toThrow('unavailable')
+  })
+
+  it('propagates lookup failure and cancellation', async () => {
+    const run: NativeCommandRunner = async () => { throw new Error('lookup denied') }
+    await expect(defaultWorkspaceDirectory('Default workspace', undefined, new AbortController().signal, { platform: 'darwin', run }))
+      .rejects.toThrow('lookup denied')
+    await expect(defaultWorkspaceDirectory('Default workspace', '/documents', AbortSignal.abort(), { platform: 'linux' }))
+      .rejects.toThrow()
+    await expect(defaultWorkspaceDirectory('Default workspace', undefined, new AbortController().signal, { platform: 'freebsd' }))
+      .rejects.toThrow('unavailable')
+  })
+
+  it.each(['relative', 'C:relative', '\\rooted'])('rejects a Windows path without a fully qualified root: %s', (path) => {
+    expect(() => validateDocumentsDirectory(path, 'win32')).toThrow('fully qualified')
+  })
+
+  it('accepts redirected UNC Documents directories', () => {
+    expect(validateDocumentsDirectory('\\\\server\\share\\Documents', 'win32')).toBe('\\\\server\\share\\Documents')
+    expect(() => validateDocumentsDirectory('relative', 'linux')).toThrow('fully qualified')
+  })
+})
diff --git a/packages/api/workspace-controller/tests/model.client.spec.ts b/packages/api/workspace-controller/tests/model.client.spec.ts
index b126805183..ade48b44b0 100644
--- a/packages/api/workspace-controller/tests/model.client.spec.ts
+++ b/packages/api/workspace-controller/tests/model.client.spec.ts
@@ -22,7 +22,8 @@ import type {
   WorkspaceId,
   WorkspaceView,
 } from '../src/types.ts'
-import { RemoteError, type RemoteFailure, type RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import { RemoteError, type RemoteFailure, type RemoteResult, type RemoteStreamHandle } from '@deepseek-ai/dsh-typert-protocol'
+import { streamHandle } from '@deepseek-ai/dsh-remote-mock'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 
 const sid = (id: string): SessionId => id as SessionId
@@ -68,6 +69,7 @@ function deferred<T>(): Deferred<T> {
 }
 
 class FakeWorkspaceRemote implements WorkspaceRemote {
+  readonly initializeDefault = vi.fn<WorkspaceRemote['initializeDefault']>(async () => remoteOk({ workspace: workspace('default') }))
   readonly calls: Array<{ readonly method: string; readonly request: unknown }> = []
   onCreate: (request: WorkspaceCreateRequest) => Promise<RemoteResult<WorkspaceCreateValue>> = request =>
     Promise.resolve(remoteOk({ workspace: workspace(request.path.split('/').pop() ?? 'workspace'), created: true }))
@@ -146,7 +148,9 @@ class FakeWorkspaceRemote implements WorkspaceRemote {
     return this.onUnpinSession(request)
   }
 
-  async *follow(_signal?: AbortSignal): AsyncGenerator<WorkspaceFollowFrame> {}
+  follow(_signal?: AbortSignal): RemoteStreamHandle<WorkspaceFollowFrame, never> {
+    return streamHandle<WorkspaceFollowFrame>((async function* () {})())
+  }
 
   private record(method: string, request: unknown): void {
     this.calls.push({ method, request })
@@ -167,6 +171,26 @@ function baseline(
 }
 
 describe('ClientWorkspaceModel', () => {
+  it('publishes the prepared Workspace and leaves the list unchanged on refusal', async () => {
+    const remote = new FakeWorkspaceRemote()
+    const model = modelFor(remote)
+    baseline(model)
+    const signal = new AbortController().signal
+    await expect(model.initializeDefault({ directoryName: '默认工作区', title: '默认工作区' }, signal)).resolves.toMatchObject({ ok: true })
+    expect(remote.initializeDefault).toHaveBeenCalledWith({ directoryName: '默认工作区', title: '默认工作区' }, signal)
+    expect(model.getSnapshot().items.map(item => item.workspaceId)).toEqual(['default'])
+    const before = model.getSnapshot()
+    remote.initializeDefault.mockResolvedValueOnce(remoteOk(undefined))
+    await expect(model.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' }))
+      .resolves.toEqual({ ok: true, value: undefined })
+    expect(model.getSnapshot()).toBe(before)
+    remote.initializeDefault.mockResolvedValueOnce(workspaceError(
+      new RemoteError('gateway/bad-request', 'choose a folder', {}),
+    ))
+    await expect(model.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' })).resolves.toMatchObject({ ok: false })
+    expect(model.getSnapshot()).toBe(before)
+  })
+
   it('replaces reconnect state and applies ordered increments', () => {
     const model = modelFor()
     expect(model.getSnapshot()).toMatchObject({ phase: 'pending', state: 'loading' })
diff --git a/packages/api/workspace-controller/tests/remote/workspace.client.ts b/packages/api/workspace-controller/tests/remote/workspace.client.ts
index 6857e8e31d..b8951c0c39 100644
--- a/packages/api/workspace-controller/tests/remote/workspace.client.ts
+++ b/packages/api/workspace-controller/tests/remote/workspace.client.ts
@@ -91,6 +91,7 @@ export function followGenerations(generations: readonly StreamScript[]): StreamS
 /** Default answers: every command accepted and echoed back as the row or set it names. */
 export const workspaceWorld: RemoteTable = {
   unary: {
+    'workspace/initializeDefault': (): RemoteResult<WorkspaceValue> => ok({ workspace: workspace('default') }),
     'workspace/create': (request: WorkspaceCreateRequest): RemoteResult<WorkspaceCreateValue> => ok({
       workspace: workspace('created', { path: request.path }), created: true,
     }),
diff --git a/packages/api/workspace-controller/tests/transport.client.spec.ts b/packages/api/workspace-controller/tests/transport.client.spec.ts
index b99406b00c..220f83e069 100644
--- a/packages/api/workspace-controller/tests/transport.client.spec.ts
+++ b/packages/api/workspace-controller/tests/transport.client.spec.ts
@@ -310,6 +310,18 @@ describe('Workspace state stream', () => {
 })
 
 describe('WorkspaceController', () => {
+  it('returns no Workspace when startup is ineligible without changing the list', async ({ mock, start }) => {
+    const { remote, client } = await gatewayClient(mock, start)
+    const model = new ClientWorkspaceModel(remote.workspace)
+    model.replaceBaseline({ items: [], archivedSessionIds: [], pinnedSessionIds: [] })
+    const controller = new WorkspaceController(client.ctx, model)
+    const before = model.getSnapshot()
+    mock.remote.workspace.initializeDefault.mockResolvedValueOnce({ ok: true, value: undefined })
+    await expect(controller.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' }))
+      .resolves.toBeUndefined()
+    expect(model.getSnapshot()).toBe(before)
+  })
+
   it('publishes the model source and exposes successful Workspace commands', async ({ mock, start }) => {
     const { remote, client } = await gatewayClient(mock, start)
     const model = new ClientWorkspaceModel(remote.workspace)
@@ -318,6 +330,7 @@ describe('WorkspaceController', () => {
 
     expect(controller.list).toBe(model)
     expect(client.ctx.workspaces.list).toBe(model)
+    await expect(controller.initializeDefault({ directoryName: '默认工作区', title: '默认工作区' }, new AbortController().signal)).resolves.toMatchObject({ workspaceId: 'default' })
     await expect(controller.create({ path: '/work/created' })).resolves.toMatchObject({ workspaceId: 'created' })
     await expect(controller.rename(wid('one'), 'renamed')).resolves.toMatchObject({ title: 'renamed' })
     await expect(controller.insertBefore(wid('one'))).resolves.toBeUndefined()
@@ -330,6 +343,7 @@ describe('WorkspaceController', () => {
     await expect(controller.unpinSession(sid('session'))).resolves.toBeUndefined()
     await expect(controller.delete(wid('one'))).resolves.toBeUndefined()
     // Each command crosses the wire as one positional request object.
+    expect(mock.log.requests('workspace/initializeDefault')).toEqual([{ directoryName: '默认工作区', title: '默认工作区' }])
     expect(mock.log.requests('workspace/create')).toEqual([{ path: '/work/created' }])
     expect(mock.log.requests('workspace/rename')).toEqual([{ workspaceId: 'one', title: 'renamed' }])
     expect(mock.log.requests('workspace/insertBefore')).toEqual([{ workspaceId: 'one' }])
@@ -347,6 +361,9 @@ describe('WorkspaceController', () => {
     const missingWorkspace = new RemoteError('workspace/not-found', 'gone', { workspaceId: wid('missing') })
     const missingSession = new RemoteError('session/not-found', 'missing session', { sessionId: sid('session') })
 
+    mock.remote.workspace.initializeDefault.mockResolvedValueOnce(err(new RemoteError('gateway/internal', 'directory denied', {})))
+    await expect(controller.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' })).rejects.toBeInstanceOf(WorkspaceCreateError)
+
     mock.remote.workspace.create.mockResolvedValueOnce(err(new RemoteError('workspace/invalid-path', 'missing path', { path: '/missing' })))
     const create = controller.create({ path: '/missing' })
     await expect(create).rejects.toBeInstanceOf(WorkspaceCreateError)
diff --git a/packages/api/workspace-controller/tests/workspace-controller.host.spec.ts b/packages/api/workspace-controller/tests/workspace-controller.host.spec.ts
index 722b132255..0656aaf8bf 100644
--- a/packages/api/workspace-controller/tests/workspace-controller.host.spec.ts
+++ b/packages/api/workspace-controller/tests/workspace-controller.host.spec.ts
@@ -41,7 +41,7 @@ function deferred<T>(): Deferred<T> {
   return { promise, resolve }
 }
 
-async function harness() {
+async function harness(options: { systemDocuments?: boolean } = {}) {
   const root = realpathSync.native(mkdtempSync(join(tmpdir(), 'dsh-workspace-controller-')))
   tempDirs.push(root)
   const ctx = new Context()
@@ -59,7 +59,7 @@ async function harness() {
     lookups: { configure: () => dispose },
     contexts: { configureHost: () => dispose },
   } as never)
-  const controller = new WorkspaceController(ctx)
+  const controller = new WorkspaceController(ctx, options.systemDocuments === true ? {} : { documentsDirectory: root })
   return { controller, ctx, root, storageDomain }
 }
 
@@ -416,3 +416,57 @@ describe('WorkspaceController follow', () => {
     await expect(closing).resolves.toEqual({ done: true, value: undefined })
   })
 })
+
+describe('first-use Remote', () => {
+  it('reuses an initialized Workspace without looking up system Documents', async () => {
+    const { controller, ctx, root } = await harness({ systemDocuments: true })
+    const workspace = await ctx.workspaceRegistry.initializeDefault(async () => ({ path: root, title: 'Existing default' }))
+    const signal = AbortSignal.abort()
+    await expect(controller.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' }, signal))
+      .resolves.toMatchObject({ workspace: { workspaceId: workspace!.id, path: root, title: 'Existing default' } })
+  })
+
+  it.each(['', ' ', '.', '..', '../outside', 'nested/name', 'nested\\name', 'C:outside', 'name\0', '.. ', 'tail.'])(
+    'rejects invalid directory name %j before invoking the registry', async (directoryName) => {
+      const { controller, ctx } = await harness()
+      const initialize = vi.spyOn(ctx.workspaceRegistry, 'initializeDefault').mockResolvedValue(undefined)
+      await expect(controller.initializeDefault({ directoryName, title: 'Default workspace' }, new AbortController().signal))
+        .rejects.toMatchObject({ code: 'gateway/bad-request' })
+      expect(initialize).not.toHaveBeenCalled()
+    },
+  )
+
+  it('rejects a blank initial title before invoking the registry', async () => {
+    const { controller, ctx } = await harness()
+    const initialize = vi.spyOn(ctx.workspaceRegistry, 'initializeDefault').mockResolvedValue(undefined)
+    await expect(controller.initializeDefault({ directoryName: 'default-workspace', title: ' ' }, new AbortController().signal))
+      .rejects.toMatchObject({ code: 'gateway/bad-request' })
+    expect(initialize).not.toHaveBeenCalled()
+  })
+
+  it('uses the requested display title independently of the directory name', async () => {
+    const { controller, root } = await harness()
+    const result = await controller.initializeDefault({ directoryName: 'default-workspace', title: 'Default workspace' }, new AbortController().signal)
+    expect(result?.workspace).toMatchObject({ path: join(root, 'deepseek-harness', 'default-workspace'), title: 'Default workspace' })
+  })
+
+  it('returns a durable Workspace without allocating a Session', async () => {
+    const { controller, ctx, root } = await harness()
+    const signal = new AbortController().signal
+    const result = await controller.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' }, signal)
+    expect(result!.workspace.path).toBe(join(root, 'deepseek-harness', 'Default workspace'))
+    expect(existsSync(result!.workspace.path)).toBe(true)
+    expect(ctx.sessions.list()).toEqual([])
+    expect(await controller.initializeDefault({ directoryName: '默认工作区', title: '默认工作区' }, signal)).toEqual(result)
+  })
+
+  it('skips ineligible first use and propagates preparation failures', async () => {
+    const { controller, ctx, root } = await harness()
+    await ctx.workspaceRegistry.create(root)
+    await expect(controller.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' }, new AbortController().signal))
+      .resolves.toBeUndefined()
+    vi.spyOn(ctx.workspaceRegistry, 'initializeDefault').mockRejectedValueOnce(new Error('permission denied'))
+    await expect(controller.initializeDefault({ directoryName: 'Default workspace', title: 'Default workspace' }, new AbortController().signal))
+      .rejects.toThrow('permission denied')
+  })
+})
diff --git a/packages/api/workspace-controller/tsconfig.host.json b/packages/api/workspace-controller/tsconfig.host.json
index 10c17a0c23..17fda7ee38 100644
--- a/packages/api/workspace-controller/tsconfig.host.json
+++ b/packages/api/workspace-controller/tsconfig.host.json
@@ -10,15 +10,18 @@
     "src/types.ts",
     "src/commands.ts",
     "src/directory-picker.ts",
-    "src/feed.ts"
+    "src/feed.ts",
+    "src/default-directory.ts"
   ],
   "references": [
     { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
     { "path": "../../core/session" },
     { "path": "../../host/directory-picker" },
     { "path": "../../storage/storage-domain" },
     { "path": "../../typert/protocol" },
     { "path": "../../util/deque" },
+    { "path": "../../util/native-command" },
     { "path": "../../workspace/workspace" }
   ]
 }
diff --git a/packages/api/workspace-files/README.i18n.yaml b/packages/api/workspace-files/README.i18n.yaml
index 7611258318..0f0e41d9c1 100644
--- a/packages/api/workspace-files/README.i18n.yaml
+++ b/packages/api/workspace-files/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/workspace-files/README.md
-README.md: 6e5025b8f5543d810fa951acf5baa32a3c060494
-README.zh.md: c913145966cc982e10c7a533274941c6c52b8b55
+README.md: 0345887e58975b9ef2764144ded20a4f25e8f04d
+README.zh.md: 572b83ec37696ee32ba9c3e1e0babdf696afe903
diff --git a/packages/api/workspace-files/README.md b/packages/api/workspace-files/README.md
index 6e5025b8f5..0345887e58 100644
--- a/packages/api/workspace-files/README.md
+++ b/packages/api/workspace-files/README.md
@@ -25,29 +25,29 @@ Use this package to preview files readable through a Session's filesystem from t
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount the package beside `dsh-fs`, `dsh-sandbox-policy`, the Session store, and the Typert Gateway; the bundle does so right after the Session Controller. Every method takes the Session identity on the wire, so a Client calls `remote.workspaceFiles.read(sessionId, path, range, signal)`, `stat(sessionId, path, signal)`, `readBytes(sessionId, path, range, signal)`, `list(sessionId, path, signal)`, or `changes(sessionId, path, signal)` and never names a root itself. The Host reads a live Session header or uses persistence `stat` for a cold Session; it does not activate an Agent, read the event body, or borrow a parent Session's root. Session persistence is optional for live reads, but without it a cold Session cannot resolve and the Gateway returns `gateway/lookup-not-found`.
+Mount the package beside `dsh-fs`, `dsh-sandbox-policy`, the Session store, and the Typert Gateway; the bundle does so right after the Session Controller. Every method takes the Session identity on the wire, so a Client calls `remote.workspaceFiles.read(sessionId, path, range, signal)`, `stat(sessionId, path, signal)`, `readBytes(sessionId, path, options, signal)`, `list(sessionId, path, signal)`, or `changes(sessionId, path, signal)` and never names a root itself. The Host reads a live Session header or uses persistence `stat` for a cold Session; it does not activate an Agent, read the event body, or borrow a parent Session's root. Session persistence is optional for live reads, but without it a cold Session cannot resolve and the Gateway returns `gateway/lookup-not-found`.
 
 | Method | Returns | Purpose |
 |---|---|---|
 | `stat(path)` | `WorkspaceFileStat { absolutePath, version, bytes? }` | Identity, version, and size of one regular file, without content |
 | `read(path, { offset?, limit? })` | `WorkspaceFileText` = stat + `{ offset, text, lines, eof }` | One window of lines from a UTF-8 text file; `lines` counts them, so one empty line and a page past the end read differently |
-| `readBytes(path, { offset?, length? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | One window of raw bytes from any regular file, base64-encoded |
-| `readAll(path)` | `WorkspaceFileBytes` with `offset: 0`, `eof: true` | Complete raw bytes under `maxFileBytes`; oversized files fail instead of being truncated |
-| `readRelated(path, relativePath)` | `WorkspaceFileBytes` | Complete bytes of a file resolved from the base file's directory on the Host |
+| `readBytes(path, { range?, baseFile? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | Complete file or bounded byte range as `Uint8Array`; optionally resolve from another file's directory |
 | `list(path)` | `WorkspaceDirectoryListing { path, entries, truncated }` | Direct children of one directory |
 | `changes(path)` | stream of `WorkspaceFileWatchFrame` | Subscription readiness, then invalidations of one file or a directory's direct entries |
 
 ### Addressing and paths
 
-`read`, `readBytes`, `readAll`, `readRelated`, and `stat` accept an absolute path or one relative to the selected Session's workspace root. The composed filesystem decides whether the path is readable; the service does not impose workspace containment on file reads. `readRelated` resolves a relative filesystem path from the base file's directory, including when either file is outside the workspace. These methods report the file's absolute path in the filesystem's execution world. `list` remains workspace-scoped and reports the listed directory relative to that root. `changes` uses the same path resolution: file watches follow file-read authority, while directory watches remain workspace-scoped.
+`read`, `readBytes`, and `stat` accept an absolute path or one relative to the selected Session's workspace root. The composed filesystem decides whether the path is readable; the service does not impose workspace containment on file reads. `readBytes` with `options.baseFile` resolves the relative target `path` from that file's directory, including when either file is outside the workspace. The base file itself accepts an absolute or workspace-relative path. Both files receive the same regular-file checks; an empty target, absolute target, URL, or NUL-containing target is rejected. File results report the absolute path in the filesystem's execution world. `list` remains workspace-scoped and reports the listed directory relative to that root. `changes` uses the same path resolution: file watches follow file-read authority, while directory watches remain workspace-scoped.
 
 ### Pages
 
 `read` returns one line window, never the whole file. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines on the page and defaults to `maxLines`, which it may not exceed — a larger limit, or an offset or limit that is not a positive integer, is a `gateway/bad-request`. Lines end at `\n`, and a final `\n` terminates the last line rather than starting an empty one, so a two-line file has two lines. The page's `text` joins its lines with `\n` and carries no terminator after the last; `eof` is true when the page includes the file's last line, and an offset past the end returns an empty page with `eof` true. Every page also carries the file's `version` from the stat that preceded it, so a consumer can tell a fresh page from a stale one, and `bytes`, the complete file's size when the backend reports it. The service reads the file only up to the first character past the page, so a very large file costs one page of memory per request.
 
-### Byte windows
+### Binary reads
 
-`read` pages by lines and never by bytes; a byte window is `readBytes`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest number of bytes in the window and defaults to `maxBytes`, which it may not exceed — a longer window fails with `too-large` instead of arriving shortened, and an offset or length that is not an integer in range is a `gateway/bad-request`. The window comes back as base64 `data`, shorter than `length` at the end of the file and empty at or past it; `eof` is true when the window includes the file's last byte. Nothing is decoded and nothing is refused as binary, so an image or a NUL-laden file reads where `read` fails with `not-text`. The same `version` and `bytes` ride along as on a page.
+`read` pages by lines and never by bytes; a byte window is `readBytes(path, { range: { offset?, length? } })`. `options.range.offset` is the 0-based first byte and defaults to 0; `options.range.length` is the largest number of bytes in the window and defaults to `maxBytes`, which it may not exceed — a longer window fails with `too-large` instead of arriving shortened, and an offset or length that is not an integer in range is a `gateway/bad-request`. The window comes back as `Uint8Array` data, shorter than `length` at the end of the file and empty at or past it; `eof` is true when the window includes the file's last byte. Nothing is decoded and nothing is refused as binary, so an image or a NUL-laden file reads where `read` fails with `not-text`. The same `version` and `bytes` ride along as on a page.
+
+Pass the required options object as `{}` for a complete file under `maxFileBytes`, or `{ range: {} }` for the default byte window under `maxBytes`. Oversized complete files fail rather than arriving truncated. `baseFile` and `range` can be combined, and windows remain independent of the complete-file cap. The binary Remote uses Connection's multipart response with JSON metadata and raw bytes; the generated Client returns `Uint8Array<ArrayBuffer>` without base64 decoding. Caller cancellation reaches the filesystem. The endpoint returns data, not a navigable document.
 
 ### File-read and directory checks
 
@@ -62,7 +62,7 @@ File reads and directory listing first use `lstat` to reject a missing path, a f
 | Field | Default | Meaning |
 |---|---|---|
 | `maxBytes` | `2097152` (2 MiB) | Inclusive byte cap on one page's text and on one byte window; a larger page or window fails |
-| `maxFileBytes` | `33554432` (32 MiB) | Inclusive complete-file cap for `readAll` and `readRelated`; larger files fail with `too-large` |
+| `maxFileBytes` | `33554432` (32 MiB) | Inclusive complete-file cap for `readBytes` without `range`; larger files fail with `too-large` |
 | `maxLines` | `5000` | Default and largest page size in lines; a larger `limit` is refused |
 | `maxEntries` | `2000` | Cap on returned directory entries; the rest is dropped and reported cut |
 
@@ -74,7 +74,7 @@ Each failure is one `RemoteError` code with typed details, declared in [`src/typ
 
 ### Client file resources
 
-The browser export registers the `file` provider into `ctx.resources` and requires `resources`, `remote`, and `remote.workspaceFiles`. The bundle's single `workspace-files` row supplies both faces; the Client has no separate configuration. A component reads `WorkspaceFileStat { absolutePath, version, bytes? }` metadata through `useResource<'file'>(address)` and fetches content separately through Remote reads. Any UI, including Global components, shares the observation for the same complete address.
+The browser export registers the `file` provider into `ctx.resources` and requires `resources`, `remote`, and `remote.workspaceFiles`. The bundle's single `workspace-files` row supplies both faces; the Client has no separate configuration. A component reads `WorkspaceFileStat { absolutePath, version, bytes? }` metadata through `useResource<'file'>(address)` and fetches content separately through the text or binary Remote. Any UI, including Global components, shares the observation for the same complete address.
 
 A `session/<sessionId>/<path>` address carries the authorizing Session and a relative or absolute path; leading slashes are preserved, as in `dsh-resource://file/session/s//etc/hosts`. The Host receives the path unchanged and owns resolution and access checks; the Client needs no Session `cwd`. `absolute/<path>` remains parseable but has no authorizing Session and fails with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Unsupported addresses fail with `workspace-file/unsupported-address`. [Workspace-path](../../util/workspace-path/README.md) owns the grammar; the generic Resource layer knows only the address and `signal`.
 
@@ -94,13 +94,13 @@ One supervised `changes` stream serves each Session and requested path; consumer
 
 Reads through `ctx.fs` use the backend's read authority; the sandboxing backend fences writes and edits, not reads. A Typert lookup derives `WorkspaceFileScope` from a live Session header or the persistence service's header-only `stat`, so cold subagent Sessions need neither Agent activation nor event-body reads. The service adds regular-file checks and bounded transfer, while workspace containment belongs only to directory listing and directory watching. A page is cut from `streamText`, which decodes and rejects non-UTF-8 chunk by chunk: the cutter counts lines before the window without keeping them, admits each in-window segment against the byte cap before buffering it, and returns at the first character past the window. One `stat` before the stream names the version and size the page reports.
 
-Complete-file reads delegate size enforcement to `fs.readBytes` and encode the returned bytes as base64 for Remote responses.
+Complete-file reads delegate size enforcement to `fs.readBytes` and return raw bytes through the binary Remote.
 
 ### Source map
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`: the `workspaceFiles` service and Remote namespace, `Config`, the gates, the page cutter, `read`, `readBytes`, `readAll`, `readRelated`, `stat`, `list` |
+| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`: the `workspaceFiles` service and Remote namespace, `Config`, the gates, the page cutter, `read`, `readBytes`, `stat`, `list` |
 | [`src/changes.ts`](src/changes.ts) | `WorkspaceChangeFeed`: target watchers, matching `fs/observed` notifications, and one queue per generation |
 | [`src/types.ts`](src/types.ts) | Wire types and the `RemoteErrorDetailsMap` codes, published as `./types` for Client packages |
 | [`src/client/index.ts`](src/client/index.ts), [`provider.ts`](src/client/provider.ts), [`change-feed.ts`](src/client/change-feed.ts) | Browser plugin, file metadata, and per-target change feeds |
diff --git a/packages/api/workspace-files/README.zh.md b/packages/api/workspace-files/README.zh.md
index c913145966..572b83ec37 100644
--- a/packages/api/workspace-files/README.zh.md
+++ b/packages/api/workspace-files/README.zh.md
@@ -25,29 +25,29 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-把本包与 `dsh-fs`、`dsh-sandbox-policy`、Session store 和 Typert Gateway 一起挂载；bundle 把它紧随 Session Controller 之后挂载。每个方法都在线路上携带 Session 身份，Client 调用 `remote.workspaceFiles.read(sessionId, path, range, signal)`、`stat(sessionId, path, signal)`、`readBytes(sessionId, path, range, signal)`、`list(sessionId, path, signal)` 或 `changes(sessionId, path, signal)`，从不自己指定根。Host 读取 live Session header，cold Session 则使用持久层 `stat`；它不会激活 Agent、读取事件正文或借用父 Session 的根。live 读取不要求挂载 Session persistence；未挂载时 cold Session 无法解析，Gateway 返回 `gateway/lookup-not-found`。
+把本包与 `dsh-fs`、`dsh-sandbox-policy`、Session store 和 Typert Gateway 一起挂载；bundle 把它紧随 Session Controller 之后挂载。每个方法都在线路上携带 Session 身份，Client 调用 `remote.workspaceFiles.read(sessionId, path, range, signal)`、`stat(sessionId, path, signal)`、`readBytes(sessionId, path, options, signal)`、`list(sessionId, path, signal)` 或 `changes(sessionId, path, signal)`，从不自己指定根。Host 读取 live Session header，cold Session 则使用持久层 `stat`；它不会激活 Agent、读取事件正文或借用父 Session 的根。live 读取不要求挂载 Session persistence；未挂载时 cold Session 无法解析，Gateway 返回 `gateway/lookup-not-found`。
 
 | 方法 | 返回 | 用途 |
 |---|---|---|
 | `stat(path)` | `WorkspaceFileStat { absolutePath, version, bytes? }` | 一个普通文件的身份、版本与大小，不含内容 |
 | `read(path, { offset?, limit? })` | `WorkspaceFileText` = stat + `{ offset, text, lines, eof }` | UTF-8 文本文件的一个行窗口；`lines` 计行数，使单个空行与越过文件末尾的页可区分 |
-| `readBytes(path, { offset?, length? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | 任意普通文件的一个原始字节窗口，base64 编码 |
-| `readAll(path)` | `WorkspaceFileBytes`，其中 `offset: 0`、`eof: true` | `maxFileBytes` 内的完整原始字节；超大文件失败，不截断 |
-| `readRelated(path, relativePath)` | `WorkspaceFileBytes` | Host 从基文件目录解析出的文件的完整字节 |
+| `readBytes(path, { range?, baseFile? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | 以 `Uint8Array` 返回完整文件或有界字节范围；可从另一个文件所在目录解析目标 |
 | `list(path)` | `WorkspaceDirectoryListing { path, entries, truncated }` | 一个目录的直接子项 |
 | `changes(path)` | `WorkspaceFileWatchFrame` 流 | 订阅就绪确认，随后为单个文件或目录直接子项的失效通知 |
 
 ### 寻址与路径
 
-`read`、`readBytes`、`readAll`、`readRelated` 与 `stat` 接受绝对路径或相对于所选 Session 工作区根的路径。组合文件系统决定路径是否可读；本服务不额外要求文件读取限定于工作区。`readRelated` 从基文件所在目录解析相对文件系统路径，基文件或目标文件位于工作区外时同样适用。这些方法以文件系统执行环境中的绝对路径报告文件。`list` 仍限定于工作区，并以相对于该根的路径报告被列举目录。`changes` 使用相同的路径解析：文件监听沿用文件读取权限，目录监听仍限定于工作区。
+`read`、`readBytes` 与 `stat` 接受绝对路径或相对于所选 Session 工作区根的路径。组合文件系统决定路径是否可读；本服务不额外要求文件读取限定于工作区。`readBytes` 携带 `options.baseFile` 时，从基准文件所在目录解析相对目标 `path`，基准文件或目标文件位于工作区外时同样适用。基准文件本身接受绝对路径或工作区相对路径。两个文件执行相同的普通文件检查；目标为空、绝对路径、URL 或含 NUL 时拒绝。文件结果报告文件系统执行环境中的绝对路径。`list` 仍限定于工作区，并以相对于该根的路径报告被列举目录。`changes` 使用相同的路径解析：文件监听沿用文件读取权限，目录监听仍限定于工作区。
 
 ### 分页
 
 `read` 返回一个行窗口，绝不返回整个文件。`range.offset` 是 1 起算的首行，缺省为 1；`range.limit` 是该页最多的行数，缺省为 `maxLines` 且不得超过它——更大的 limit，或不是正整数的 offset / limit，都是 `gateway/bad-request`。行以 `\n` 结束，末尾的 `\n` 是最后一行的终止符而不是再起一空行，所以两行文件就是两行。页的 `text` 以 `\n` 连接各行，最后一行之后不带终止符；`eof` 在该页含文件最后一行时为 true，offset 越过末尾则返回空页且 `eof` 为 true。每页还带上前置 stat 得到的文件 `version`，消费方据此分辨新页与旧页，以及 `bytes`——后端能报告时的整文件大小。服务只把文件读到该页之后的第一个字符为止，所以再大的文件每次请求也只占一页内存。
 
-### 字节窗口
+### 二进制读取
 
-`read` 按行分页，绝不按字节；字节窗口走 `readBytes`。`range.offset` 是 0 起算的首字节，缺省为 0；`range.length` 是窗口最多的字节数，缺省为 `maxBytes` 且不得超过它——更长的窗口以 `too-large` 失败而不是被截短，不是整数或越界的 offset / length 则是 `gateway/bad-request`。窗口以 base64 的 `data` 返回，到文件末尾时短于 `length`，位于或越过末尾时为空；窗口含文件最后一个字节时 `eof` 为 true。不做任何解码，也不按二进制拒绝，因此图片或含 NUL 的文件在 `read` 以 `not-text` 失败之处仍可读出。与页一样附带同一 `version` 与 `bytes`。
+`read` 按行分页，绝不按字节；字节窗口走 `readBytes(path, { range: { offset?, length? } })`。`options.range.offset` 是 0 起算的首字节，缺省为 0；`options.range.length` 是窗口最多的字节数，缺省为 `maxBytes` 且不得超过它——更长的窗口以 `too-large` 失败而不是被截短，不是整数或越界的 offset / length 则是 `gateway/bad-request`。窗口以 `Uint8Array` 类型的 `data` 返回，到文件末尾时短于 `length`，位于或越过末尾时为空；窗口含文件最后一个字节时 `eof` 为 true。不做任何解码，也不按二进制拒绝，因此图片或含 NUL 的文件在 `read` 以 `not-text` 失败之处仍可读出。与页一样附带同一 `version` 与 `bytes`。
+
+必填的选项对象传 `{}` 时，在 `maxFileBytes` 上限内读取完整文件；传 `{ range: {} }` 时，在 `maxBytes` 上限内读取默认字节窗口。超大完整文件失败，不截断。`baseFile` 与 `range` 可以组合，窗口始终不受完整文件上限约束。二进制 Remote 使用 Connection 的 multipart 响应传递 JSON 元数据与原始字节；生成的 Client 直接返回 `Uint8Array<ArrayBuffer>`，无需 base64 解码。调用方取消会传到文件系统。端点返回数据，不提供可导航的文档。
 
 ### 文件读取与目录检查
 
@@ -62,7 +62,7 @@ kind: "package-reference"
 | 字段 | 默认值 | 含义 |
 |---|---|---|
 | `maxBytes` | `2097152`（2 MiB） | 单页文本与单个字节窗口的字节上限（含）；更大的页或窗口失败 |
-| `maxFileBytes` | `33554432`（32 MiB） | `readAll` 和 `readRelated` 的完整文件字节上限（含）；更大文件以 `too-large` 失败 |
+| `maxFileBytes` | `33554432`（32 MiB） | `readBytes` 未传 `range` 时的完整文件字节上限（含）；更大文件以 `too-large` 失败 |
 | `maxLines` | `5000` | 页大小的缺省值与上限（行）；更大的 `limit` 被拒绝 |
 | `maxEntries` | `2000` | 返回目录条目数上限；其余丢弃并报告截断 |
 
@@ -74,7 +74,7 @@ kind: "package-reference"
 
 ### Client 文件资源
 
-浏览器导出向 `ctx.resources` 注册 `file` 提供方，要求 `resources`、`remote` 和 `remote.workspaceFiles` 在场。bundle 中单个 `workspace-files` 条目供应两面；Client 没有单独配置。组件通过 `useResource<'file'>(address)` 读取 `WorkspaceFileStat { absolutePath, version, bytes? }` 元数据，内容另经 Remote 读取。任何 UI（包括 Global）访问同一完整地址都共享观察。
+浏览器导出向 `ctx.resources` 注册 `file` 提供方，要求 `resources`、`remote` 和 `remote.workspaceFiles` 在场。bundle 中单个 `workspace-files` 条目供应两面；Client 没有单独配置。组件通过 `useResource<'file'>(address)` 读取 `WorkspaceFileStat { absolutePath, version, bytes? }` 元数据，文本与字节内容另经对应 Remote 读取。任何 UI（包括 Global）访问同一完整地址都共享观察。
 
 `session/<sessionId>/<path>` 地址携带授权 Session，以及相对或绝对路径；前导斜杠保留，例如 `dsh-resource://file/session/s//etc/hosts`。Host 原样接收路径，负责解析与权限检查；Client 不需要 Session `cwd`。`absolute/<path>` 仍可解析，但没有授权 Session，以 `workspace-file/unknown-workspace` 失败，不借用当前或 Tab Session。不支持的地址以 `workspace-file/unsupported-address` 失败。语法由 [workspace-path](../../util/workspace-path/README.zh.md) 定义；Resource 泛型层只认地址和 `signal`。
 
@@ -94,13 +94,13 @@ kind: "package-reference"
 
 经 `ctx.fs` 的读取使用后端的读取权限；沙箱后端限制写与编辑，而不限制读取。Typert lookup 从 live Session header 或持久层的 header-only `stat` 导出 `WorkspaceFileScope`，所以 cold subagent Session 不需要激活 Agent 或读取事件正文。本服务增加普通文件检查与有界传输，工作区包含要求只属于目录列举与目录监听。页从 `streamText` 切出，后者逐块解码并拒绝非 UTF-8：切页器对窗口之前的行只计数不保留，对窗口内的每个片段先按字节上限验收再缓冲，并在窗口之后的第一个字符处返回。流之前的一次 `stat` 给出页所报告的版本与大小。
 
-完整文件读取将大小上限检查交给 `fs.readBytes`，并将返回的字节编码为 base64，供 Remote 响应使用。
+完整文件读取将大小上限检查交给 `fs.readBytes`，并通过二进制 Remote 返回原始字节。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`：`workspaceFiles` 服务与 Remote 命名空间、`Config`、四道关、切页器、`read`、`readBytes`、`readAll`、`readRelated`、`stat`、`list` |
+| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`：`workspaceFiles` 服务与 Remote 命名空间、`Config`、四道关、切页器、`read`、`readBytes`、`stat`、`list` |
 | [`src/changes.ts`](src/changes.ts) | `WorkspaceChangeFeed`：目标监听、匹配的 `fs/observed` 通知与每代流各自的队列 |
 | [`src/types.ts`](src/types.ts) | 线路类型与 `RemoteErrorDetailsMap` 错误码，以 `./types` 发布给 Client 包 |
 | [`src/client/index.ts`](src/client/index.ts)、[`provider.ts`](src/client/provider.ts)、[`change-feed.ts`](src/client/change-feed.ts) | 浏览器插件、文件元数据与按目标建立的变更流 |
diff --git a/packages/api/workspace-files/package.json b/packages/api/workspace-files/package.json
index a8b036b554..480f133ed8 100644
--- a/packages/api/workspace-files/package.json
+++ b/packages/api/workspace-files/package.json
@@ -63,9 +63,11 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-resources": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-remote-mock": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
diff --git a/packages/api/workspace-files/src/index.ts b/packages/api/workspace-files/src/index.ts
index f9807ea534..c5d1542593 100644
--- a/packages/api/workspace-files/src/index.ts
+++ b/packages/api/workspace-files/src/index.ts
@@ -32,6 +32,7 @@ import { Remote, RemoteError, TypertRemoteService, type TypertLookup } from '@de
 import { WorkspaceChangeFeed } from './changes.ts'
 import type {
   WorkspaceByteRange,
+  WorkspaceByteReadOptions,
   WorkspaceDirectoryEntry,
   WorkspaceDirectoryListing,
   WorkspaceFileBytes,
@@ -245,38 +246,29 @@ export class WorkspaceFiles extends TypertRemoteService {
   }
 
   /**
-   * Read one byte window of a regular file readable by the filesystem backend: raw
-   * bytes, no text decoding and no binary rejection.
+   * Read a complete regular file or one byte range without text decoding.
    * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
-   * @param path - absolute path or path relative to the workspace root; files outside it are allowed.
-   * @param range - the byte window; omitted fields take the window defaults.
+   * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided.
+   * @param options - optional base file and range; without a range the complete-file cap applies.
    * @param signal - caller cancellation.
-   * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+   * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
    */
   @Remote
   async readBytes(
     workspaceFileScope: WorkspaceFileScope,
     path: string,
-    range: WorkspaceByteRange,
+    options: WorkspaceByteReadOptions,
     signal: AbortSignal,
   ): Promise<WorkspaceFileBytes> {
-    const { offset, length } = this.resolveWindow(range, path)
-    const { target, info } = await this.locateFile(workspaceFileScope, path, signal)
-    const data = await this.ctx.fs.readByteRange(target, { offset, length }, signal)
-    const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size
-    return { ...this.statOf(target, info), offset, data: Buffer.from(data).toString('base64'), eof }
-  }
-
-  /**
-   * Read a complete regular file as bytes, subject to the configured full-file cap.
-   * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
-   * @param path - absolute or workspace-relative file path.
-   * @param signal - caller cancellation.
-   * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large.
-   */
-  @Remote
-  async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes> {
-    const { target, info } = await this.locateFile(workspaceFileScope, path, signal)
+    const window = options.range === undefined ? undefined : this.resolveWindow(options.range, path)
+    const resolved = options.baseFile === undefined ? path : await this.relativePath(workspaceFileScope, options.baseFile, path, signal)
+    const { target, info } = await this.locateFile(workspaceFileScope, resolved, signal)
+    if (window !== undefined) {
+      const { offset, length } = window
+      const data = await this.ctx.fs.readByteRange(target, window, signal)
+      const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size
+      return { ...this.statOf(target, info), offset, data, eof }
+    }
     const limit = this.config.maxFileBytes
     const data = await this.ctx.fs.readBytes(target, signal, limit).catch((cause: unknown) => {
       if (typeof cause === 'object' && cause !== null && 'code' in cause && cause.code === 'FS_TOO_LARGE') {
@@ -284,32 +276,7 @@ export class WorkspaceFiles extends TypertRemoteService {
       }
       throw cause
     })
-    return { ...this.statOf(target, info), offset: 0, data: Buffer.from(data).toString('base64'), eof: true }
-  }
-
-  /**
-   * Read a complete file relative to another file's directory, including outside the workspace.
-   * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
-   * @param path - base file, absolute or workspace-relative.
-   * @param relativePath - relative filesystem path, not a URL or absolute path.
-   * @param signal - caller cancellation.
-   * @returns the complete related file using the ordinary file-size and access checks.
-   */
-  @Remote
-  async readRelated(
-    workspaceFileScope: WorkspaceFileScope,
-    path: string,
-    relativePath: string,
-    signal: AbortSignal,
-  ): Promise<WorkspaceFileBytes> {
-    const relative = relativePath.replace(/\\/g, '/')
-    if (relative.length === 0 || relative.startsWith('/') || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) {
-      throw new RemoteError('gateway/bad-request', 'relativePath must be a relative filesystem path', {})
-    }
-    const { target } = await this.locateFile(workspaceFileScope, path, signal)
-    const absolute = this.ctx.fs.processPath(target)
-    const paths = absolute.startsWith('/') ? posix : win32
-    return this.readAll(workspaceFileScope, paths.resolve(paths.dirname(absolute), relative), signal)
+    return { ...this.statOf(target, info), offset: 0, data, eof: true }
   }
 
   /**
@@ -365,6 +332,17 @@ export class WorkspaceFiles extends TypertRemoteService {
     return this.feed.follow(workspaceFileScope.workspaceRoot, path, signal)
   }
 
+  private async relativePath(scope: WorkspaceFileScope, baseFile: string, path: string, signal: AbortSignal): Promise<string> {
+    const relative = path.replace(/\\/g, '/')
+    if (relative.length === 0 || relative.startsWith('/') || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) {
+      throw new RemoteError('gateway/bad-request', 'path must be relative when baseFile is provided', {})
+    }
+    const { target } = await this.locateFile(scope, baseFile, signal)
+    const absolute = this.ctx.fs.processPath(target)
+    const paths = absolute.startsWith('/') ? posix : win32
+    return paths.resolve(paths.dirname(absolute), relative)
+  }
+
   /** Apply the page defaults and caps here, so the request never carries them implicitly. */
   private resolvePage(range: WorkspaceFileRange): { offset: number; limit: number } {
     const offset = range.offset === undefined ? 1 : integerAtLeast(range.offset, 1, 'offset')
diff --git a/packages/api/workspace-files/src/types.ts b/packages/api/workspace-files/src/types.ts
index 184767f10e..ea6bc2c086 100644
--- a/packages/api/workspace-files/src/types.ts
+++ b/packages/api/workspace-files/src/types.ts
@@ -69,15 +69,23 @@ export interface WorkspaceByteRange {
   readonly length?: number
 }
 
+/** Target resolution and optional byte range for one binary file read. */
+export interface WorkspaceByteReadOptions {
+  /** Byte window; omit to read the complete file under the configured `maxFileBytes` cap. */
+  readonly range?: WorkspaceByteRange
+  /** Base file, absolute or workspace-relative; resolve the relative target from its directory. */
+  readonly baseFile?: string
+}
+
 /**
  * One byte window of a workspace file as a Client reads it: raw bytes, no text
  * decoding and no binary rejection. `bytes` is the complete file's size.
  */
-export interface WorkspaceFileBytes extends WorkspaceFileStat {
+export interface WorkspaceFileBytes<Data extends Uint8Array = Uint8Array> extends WorkspaceFileStat {
   /** First byte of the window, as requested. */
   readonly offset: number
-  /** The window's bytes in base64; empty when `offset` lies at or past the file's end. */
-  readonly data: string
+  /** Native file bytes; empty at or past EOF. */
+  readonly data: Data
   /** Whether the window includes the file's last byte. */
   readonly eof: boolean
 }
diff --git a/packages/api/workspace-files/tests/binary-rpc.spec.ts b/packages/api/workspace-files/tests/binary-rpc.spec.ts
new file mode 100644
index 0000000000..35058d58a1
--- /dev/null
+++ b/packages/api/workspace-files/tests/binary-rpc.spec.ts
@@ -0,0 +1,93 @@
+/** Workspace byte reads traverse Gateway lookup and Connection's binary RPC response. */
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { beforeEach, afterEach, expect, it, vi } from 'vitest'
+import SessionStore from '@deepseek-ai/dsh-session'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import TypertGateway from '@deepseek-ai/dsh-api-gateway'
+import { HostConnectionService } from '@deepseek-ai/dsh-client-connection/src/rpc-host.ts'
+import type { BrowserAuth } from '@deepseek-ai/dsh-client-connection/src/browser-auth.ts'
+import { createWebConnectionRpc } from '@deepseek-ai/dsh-client-connection/src/client/rpc.ts'
+import WorkspaceFiles, { type WorkspaceByteReadOptions } from '../src/index.ts'
+import { openWorkspace, type Harness } from './harness.ts'
+
+let harness: Harness
+let rpc: ReturnType<typeof createWebConnectionRpc>
+
+beforeEach(async () => {
+  harness = await openWorkspace('dsh-workspace-binary-rpc-')
+  const ctx = harness.ctx
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(TypertRegistry)
+  await ctx.plugin(TypertGateway)
+  await ctx.plugin((scope) => { new HostConnectionService(scope, [], {} as BrowserAuth) })
+  await ctx.plugin(WorkspaceFiles, { maxBytes: 8, maxFileBytes: 4, maxLines: 100, maxEntries: 100 })
+  ctx.sessions.create(harness.scope.sessionId, { meta: { cwd: harness.workspace, origin: 'subagent' } })
+  const handler = (ctx.get('connection') as HostConnectionService).createSharedFetchHandler('/api')
+  rpc = createWebConnectionRpc(async (path, init) => handler.fetch(new Request(new URL(path, 'http://host'), init)))
+})
+
+afterEach(async () => {
+  await harness.ctx.fiber.dispose()
+  await harness.dispose()
+})
+
+function read(path: string, options: WorkspaceByteReadOptions, signal = new AbortController().signal) {
+  return rpc.call('/api', 'workspaceFiles/readBytes', { args: { workspaceFileScopeId: harness.scope.sessionId, path, options } }, signal)
+}
+
+it('returns complete binary contents through the ordinary Remote endpoint', async () => {
+  const data = new Uint8Array([0, 128, 255, 1])
+  await writeFile(join(harness.workspace, '字节.bin'), data)
+  expect(await read('字节.bin', {})).toMatchObject({ ok: true, value: { offset: 0, eof: true, bytes: 4, data } })
+  expect(harness.ctx.get('agents')).toBeUndefined()
+})
+
+it.each([
+  [{}, [0, 1, 2, 3, 4, 5, 6, 7], 0, false],
+  [{ offset: 7, length: 8 }, [7, 8, 9], 7, true],
+  [{ offset: 10 }, [], 10, true],
+])('preserves range %j without reading the whole oversized file', async (range, data, offset, eof) => {
+  await writeFile(join(harness.workspace, 'base.html'), 'base')
+  await writeFile(join(harness.workspace, 'large.bin'), new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]))
+  const complete = vi.spyOn(harness.ctx.fs, 'readBytes')
+  const window = vi.spyOn(harness.ctx.fs, 'readByteRange')
+  expect(await read('large.bin', { baseFile: 'base.html', range })).toMatchObject({
+    ok: true, value: { offset, eof, bytes: 10, data: new Uint8Array(data) },
+  })
+  expect(window).toHaveBeenCalledExactlyOnceWith(expect.anything(), { offset, length: 8 }, expect.any(AbortSignal))
+  expect(complete).not.toHaveBeenCalled()
+})
+
+it('preserves full-file size failures and Gateway Session lookup failures', async () => {
+  await writeFile(join(harness.workspace, 'large'), '12345')
+  expect(await read('large', {})).toMatchObject({ ok: false, error: { code: 'workspace-file/too-large', details: { path: 'large', limit: 4 } } })
+  expect(await rpc.call('/api', 'workspaceFiles/readBytes', { args: { workspaceFileScopeId: 'missing', path: 'large', options: {} } }))
+    .toMatchObject({ ok: false, error: { code: 'gateway/lookup-not-found' } })
+})
+
+it.each([{}, { range: {} }])('propagates cancellation into the filesystem for options %j', async (options) => {
+  await writeFile(join(harness.workspace, 'file'), 'data')
+  const entered = Promise.withResolvers<undefined>()
+  const controller = new AbortController()
+  const abortable = async (signal: AbortSignal | undefined): Promise<Uint8Array> => {
+    if (signal === undefined) throw new Error('read did not receive cancellation')
+    entered.resolve(undefined)
+    return new Promise((_resolve, reject) => {
+      signal.addEventListener('abort', () => { reject(signal.reason as Error) }, { once: true })
+    })
+  }
+  if ('range' in options) vi.spyOn(harness.ctx.fs, 'readByteRange').mockImplementation((_target, _range, signal) => abortable(signal))
+  else vi.spyOn(harness.ctx.fs, 'readBytes').mockImplementation((_target, signal) => abortable(signal))
+  const failure = new Error('tab closed')
+  const pending = read('file', options, controller.signal)
+  const rejected = expect(pending).rejects.toBe(failure)
+  try {
+    await entered.promise
+    controller.abort(failure)
+    await rejected
+  } finally {
+    controller.abort(failure)
+    await rejected
+  }
+})
diff --git a/packages/api/workspace-files/tests/fake-remote.client.ts b/packages/api/workspace-files/tests/fake-remote.client.ts
index c310dc433f..ecb6aedf2b 100644
--- a/packages/api/workspace-files/tests/fake-remote.client.ts
+++ b/packages/api/workspace-files/tests/fake-remote.client.ts
@@ -3,8 +3,9 @@
  * opened `changes` generation, and a supervisor that runs one generation and
  * classifies its end the way the real one does.
  */
-import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol'
+import type { RemoteResult, RemoteStreamHandle } from '@deepseek-ai/dsh-typert-protocol'
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol'
+import { streamHandle } from '@deepseek-ai/dsh-remote-mock'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { WorkspaceFileWatchFrame, WorkspaceFileStat } from '../src/types.ts'
 import type { SupervisedStream, SupervisedStreamOptions, WorkspaceFilesRemote } from '../src/client/remote.ts'
@@ -225,7 +226,7 @@ export class FakeRemote implements WorkspaceFilesRemote {
         this.statWaiters.delete(index)
         if (this.closed) resolve(this.closedStat())
       }),
-    changes: (sessionId: SessionId, path: string, signal?: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame> => {
+    changes: (sessionId: SessionId, path: string, signal?: AbortSignal): RemoteStreamHandle<WorkspaceFileWatchFrame, never> => {
       this.calls.push('changes')
       if (signal === undefined) throw new Error('the feed must hand its signal to the Host stream')
       const source = new Source<WorkspaceFileWatchFrame>(signal)
@@ -235,7 +236,7 @@ export class FakeRemote implements WorkspaceFilesRemote {
       for (const waiter of this.watchWaiters.get(index) ?? []) waiter(watch)
       this.watchWaiters.delete(index)
       if (this.autoReady) source.push({ kind: 'ready' })
-      return source
+      return streamHandle(source)
     },
   }
 }
diff --git a/packages/api/workspace-files/tests/read-all.spec.ts b/packages/api/workspace-files/tests/read-all.spec.ts
index 21d75bd849..cd5d3b9d73 100644
--- a/packages/api/workspace-files/tests/read-all.spec.ts
+++ b/packages/api/workspace-files/tests/read-all.spec.ts
@@ -1,6 +1,6 @@
 /** Full-file reads retain the ordinary file gates and never return a silently truncated result. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { mkdir, symlink, writeFile } from 'node:fs/promises'
+import { mkdir, realpath, symlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { FsVersion } from '@deepseek-ai/dsh-fs'
 import { failureOf, openWorkspace, signal, type Harness } from './harness.ts'
@@ -10,31 +10,33 @@ let harness: Harness
 beforeEach(async () => { harness = await openWorkspace('dsh-workspace-files-read-all-') })
 afterEach(async () => { await harness.dispose() })
 
-describe('workspaceFiles.readAll', () => {
+describe('workspaceFiles.readBytes — complete files', () => {
   it('reads the complete bytes independently of the window cap', async () => {
     const bytes = Buffer.from([0, 255, 1, 2])
     await writeFile(join(harness.workspace, 'file.bin'), bytes)
-    const result = await harness.endpoint({ maxBytes: 1, maxFileBytes: 4 }).readAll(harness.scope, 'file.bin', signal())
-    expect(Buffer.from(result.data, 'base64')).toEqual(bytes)
+    const result = await harness.endpoint({ maxBytes: 1, maxFileBytes: 4 }).readBytes(harness.scope, 'file.bin', {}, signal())
+    expect(Buffer.from(result.data)).toEqual(bytes)
     expect(result).toMatchObject({ offset: 0, eof: true, bytes: 4 })
   })
 
   it('returns an empty complete file', async () => {
     await writeFile(join(harness.workspace, 'empty'), '')
-    expect(await harness.endpoint().readAll(harness.scope, 'empty', signal())).toMatchObject({ data: '', offset: 0, eof: true, bytes: 0 })
+    const result = await harness.endpoint().readBytes(harness.scope, 'empty', {}, signal())
+    expect(result.data.byteLength).toBe(0)
+    expect(result).toMatchObject({ offset: 0, eof: true, bytes: 0 })
   })
 
   it.each(['workspace', 'outside'] as const)('maps the filesystem size refusal for a %s file', async (location) => {
     const path = join(harness[location], 'large')
     await writeFile(path, 'abcde')
-    expect(await failureOf(harness.endpoint({ maxFileBytes: 4 }).readAll(harness.scope, path, signal())))
+    expect(await failureOf(harness.endpoint({ maxFileBytes: 4 }).readBytes(harness.scope, path, {}, signal())))
       .toEqual({ code: 'workspace-file/too-large', details: { path, limit: 4 } })
   })
 
   it.each([undefined, 1])('checks the actual bytes when stat reports %s', async (size) => {
     await writeFile(join(harness.workspace, 'growing'), 'abcde')
     vi.spyOn(harness.ctx.fs, 'stat').mockResolvedValue({ type: 'file', version: FsVersion('v'), ...size === undefined ? {} : { size } })
-    expect((await failureOf(harness.endpoint({ maxFileBytes: 4 }).readAll(harness.scope, 'growing', signal()))).code)
+    expect((await failureOf(harness.endpoint({ maxFileBytes: 4 }).readBytes(harness.scope, 'growing', {}, signal()))).code)
       .toBe('workspace-file/too-large')
   })
 
@@ -42,17 +44,17 @@ describe('workspaceFiles.readAll', () => {
     await mkdir(join(harness.workspace, 'directory'))
     await writeFile(join(harness.outside, 'outside'), 'outside')
     const files = harness.endpoint()
-    expect((await failureOf(files.readAll(harness.scope, 'missing', signal()))).code).toBe('workspace-file/not-found')
-    expect((await failureOf(files.readAll(harness.scope, 'directory', signal()))).code).toBe('workspace-file/not-regular-file')
-    const outside = await files.readAll(harness.scope, join(harness.outside, 'outside'), signal())
-    expect(Buffer.from(outside.data, 'base64').toString()).toBe('outside')
+    expect((await failureOf(files.readBytes(harness.scope, 'missing', {}, signal()))).code).toBe('workspace-file/not-found')
+    expect((await failureOf(files.readBytes(harness.scope, 'directory', {}, signal()))).code).toBe('workspace-file/not-regular-file')
+    const outside = await files.readBytes(harness.scope, join(harness.outside, 'outside'), {}, signal())
+    expect(Buffer.from(outside.data).toString()).toBe('outside')
   })
 
   it.each([new Error('Read denied'), new DOMException('Cancelled', 'AbortError'), null, 'backend failure', { code: 'FS_NOT_FOUND' }])(
     'preserves non-size filesystem failures: %s', async (failure) => {
       await writeFile(join(harness.workspace, 'file'), '1234')
       vi.spyOn(harness.ctx.fs, 'readBytes').mockRejectedValueOnce(failure)
-      await expect(harness.endpoint().readAll(harness.scope, 'file', signal())).rejects.toBe(failure)
+      await expect(harness.endpoint().readBytes(harness.scope, 'file', {}, signal())).rejects.toBe(failure)
     },
   )
 
@@ -60,39 +62,39 @@ describe('workspaceFiles.readAll', () => {
     await writeFile(join(harness.workspace, 'file'), '1234')
     const failure = { code: 'FS_TOO_LARGE' }
     vi.spyOn(harness.ctx.fs, 'readBytes').mockRejectedValueOnce(failure)
-    await expect(harness.endpoint({ maxFileBytes: 4 }).readAll(harness.scope, 'file', signal()))
+    await expect(harness.endpoint({ maxFileBytes: 4 }).readBytes(harness.scope, 'file', {}, signal()))
       .rejects.toMatchObject({ code: 'workspace-file/too-large', details: { path: 'file', limit: 4 }, cause: failure })
   })
 })
 
-describe('workspaceFiles.readRelated', () => {
+describe('workspaceFiles.readBytes — base file', () => {
   it('resolves relative paths from the base file directory on the Host', async () => {
     await mkdir(join(harness.workspace, 'nested'))
     await writeFile(join(harness.workspace, 'nested/base.txt'), 'base')
     await writeFile(join(harness.workspace, 'nested/near.txt'), 'near')
     await writeFile(join(harness.workspace, 'root.txt'), 'root')
     const files = harness.endpoint()
-    const near = await files.readRelated(harness.scope, 'nested/base.txt', './near.txt', signal())
-    const root = await files.readRelated(harness.scope, 'nested/base.txt', '../root.txt', signal())
-    expect(Buffer.from(near.data, 'base64').toString()).toBe('near')
-    expect(Buffer.from(root.data, 'base64').toString()).toBe('root')
-    const fromRoot = await files.readRelated(harness.scope, 'root.txt', 'nested\\near.txt', signal())
-    expect(Buffer.from(fromRoot.data, 'base64').toString()).toBe('near')
+    const near = await files.readBytes(harness.scope, './near.txt', { baseFile: 'nested/base.txt' }, signal())
+    const root = await files.readBytes(harness.scope, '../root.txt', { baseFile: 'nested/base.txt' }, signal())
+    expect(Buffer.from(near.data).toString()).toBe('near')
+    expect(Buffer.from(root.data).toString()).toBe('root')
+    const fromRoot = await files.readBytes(harness.scope, 'nested\\near.txt', { baseFile: 'root.txt' }, signal())
+    expect(Buffer.from(fromRoot.data).toString()).toBe('near')
   })
 
   it.each(['', '/outside', 'C:\\outside', '\\\\host\\share', 'https://example.test/a.js', 'bad\0path'])('rejects non-relative path %j', async (path) => {
-    expect((await failureOf(harness.endpoint().readRelated(harness.scope, 'base', path, signal()))).code).toBe('gateway/bad-request')
+    expect((await failureOf(harness.endpoint().readBytes(harness.scope, path, { baseFile: 'base' }, signal()))).code).toBe('gateway/bad-request')
   })
 
   it('resolves related files on either side of the workspace root', async () => {
     await writeFile(join(harness.workspace, 'base'), 'base')
     await writeFile(join(harness.outside, 'outside'), 'outside')
     const files = harness.endpoint()
-    expect((await failureOf(files.readRelated(harness.scope, 'missing', 'file', signal()))).code).toBe('workspace-file/not-found')
-    const fromOutside = await files.readRelated(harness.scope, join(harness.outside, 'outside'), '../workspace/base', signal())
-    const toOutside = await files.readRelated(harness.scope, 'base', '../outside/outside', signal())
-    expect(Buffer.from(fromOutside.data, 'base64').toString()).toBe('base')
-    expect(Buffer.from(toOutside.data, 'base64').toString()).toBe('outside')
+    expect((await failureOf(files.readBytes(harness.scope, 'file', { baseFile: 'missing' }, signal()))).code).toBe('workspace-file/not-found')
+    const fromOutside = await files.readBytes(harness.scope, '../workspace/base', { baseFile: join(harness.outside, 'outside') }, signal())
+    const toOutside = await files.readBytes(harness.scope, '../outside/outside', { baseFile: 'base' }, signal())
+    expect(Buffer.from(fromOutside.data).toString()).toBe('base')
+    expect(Buffer.from(toOutside.data).toString()).toBe('outside')
   })
 
   it('reads sibling assets beside an outside HTML file with escaped path characters', async () => {
@@ -100,8 +102,8 @@ describe('workspaceFiles.readRelated', () => {
     const base = join(harness.outside, 'space # assets', 'page.html')
     await writeFile(base, '<script src="./app.js"></script>')
     await writeFile(join(harness.outside, 'space # assets', 'app.js'), 'EXTERNAL_ASSET')
-    const result = await harness.endpoint().readRelated(harness.scope, base, './app.js', signal())
-    expect(Buffer.from(result.data, 'base64').toString()).toBe('EXTERNAL_ASSET')
+    const result = await harness.endpoint().readBytes(harness.scope, './app.js', { baseFile: base }, signal())
+    expect(Buffer.from(result.data).toString()).toBe('EXTERNAL_ASSET')
   })
 
   it.each([
@@ -112,16 +114,41 @@ describe('workspaceFiles.readRelated', () => {
     await writeFile(join(harness.workspace, 'base'), 'base')
     const files = harness.endpoint()
     vi.spyOn(harness.ctx.fs, 'processPath').mockReturnValue(base)
-    const read = vi.spyOn(files, 'readAll').mockResolvedValue({ absolutePath: expected, version: 'v', offset: 0, data: '', eof: true })
+    const lstat = harness.ctx.fs.lstat.bind(harness.ctx.fs)
+    const inspect = vi.spyOn(harness.ctx.fs, 'lstat').mockImplementation((path, options, abort) =>
+      path === 'base' ? lstat(path, options, abort) : Promise.resolve(undefined))
     const caller = signal()
-    await files.readRelated(harness.scope, 'base', './app.js', caller)
-    expect(read).toHaveBeenCalledWith(harness.scope, expected, caller)
+    await expect(files.readBytes(harness.scope, './app.js', { baseFile: 'base' }, caller)).rejects.toMatchObject({ code: 'workspace-file/not-found' })
+    expect(inspect).toHaveBeenLastCalledWith(expected, { cwd: harness.workspace }, caller)
+  })
+
+  it('combines a base file with a bounded range without applying the complete-file cap', async () => {
+    await mkdir(join(harness.workspace, 'nested'))
+    await writeFile(join(harness.workspace, 'nested/base.html'), 'base')
+    await writeFile(join(harness.workspace, 'nested/asset.bin'), new Uint8Array([0, 255, 128, 4, 5, 6]))
+    const completeRead = vi.spyOn(harness.ctx.fs, 'readBytes')
+    const rangeRead = vi.spyOn(harness.ctx.fs, 'readByteRange')
+    const caller = signal()
+    const result = await harness.endpoint({ maxBytes: 2, maxFileBytes: 1 }).readBytes(
+      harness.scope, './asset.bin', { baseFile: 'nested/base.html', range: { offset: 1, length: 2 } }, caller,
+    )
+    expect([...result.data]).toEqual([255, 128])
+    expect(result).toMatchObject({ absolutePath: await realpath(join(harness.workspace, 'nested/asset.bin')), offset: 1, eof: false, bytes: 6 })
+    expect(rangeRead).toHaveBeenCalledExactlyOnceWith(expect.anything(), { offset: 1, length: 2 }, caller)
+    expect(completeRead).not.toHaveBeenCalled()
+  })
+
+  it('checks the base file kind before reading the target', async () => {
+    await mkdir(join(harness.workspace, 'directory'))
+    await writeFile(join(harness.workspace, 'target'), 'target')
+    expect((await failureOf(harness.endpoint().readBytes(harness.scope, 'target', { baseFile: 'directory' }, signal()))).code)
+      .toBe('workspace-file/not-regular-file')
   })
 
   it('rejects a related symlink rather than following it', async () => {
     await writeFile(join(harness.workspace, 'base'), 'base')
     await writeFile(join(harness.workspace, 'target'), 'target')
     await symlink('target', join(harness.workspace, 'link'))
-    expect((await failureOf(harness.endpoint().readRelated(harness.scope, 'base', 'link', signal()))).code).toBe('workspace-file/not-regular-file')
+    expect((await failureOf(harness.endpoint().readBytes(harness.scope, 'link', { baseFile: 'base' }, signal()))).code).toBe('workspace-file/not-regular-file')
   })
 })
diff --git a/packages/api/workspace-files/tests/read-bytes.spec.ts b/packages/api/workspace-files/tests/read-bytes.spec.ts
index 2af2ca9927..62cb55a218 100644
--- a/packages/api/workspace-files/tests/read-bytes.spec.ts
+++ b/packages/api/workspace-files/tests/read-bytes.spec.ts
@@ -17,18 +17,16 @@ afterEach(async () => {
   await harness.dispose()
 })
 
-const endpoint = (caps?: { maxBytes?: number }): ReturnType<Harness['endpoint']> => harness.endpoint(caps)
+const endpoint = (caps?: { maxBytes?: number; maxFileBytes?: number }): ReturnType<Harness['endpoint']> => harness.endpoint(caps)
 
 /** 256 bytes, each equal to its offset: the window's content names its position. */
 const RAMP = Buffer.from(Array.from({ length: 256 }, (_, i) => i))
 
-const decode = (data: string): Buffer => Buffer.from(data, 'base64')
-
 describe('workspaceFiles.readBytes — the window', () => {
   it('returns the whole file as one window by default, with its absolute path, version, and size', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
-    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', {}, signal())
-    expect(decode(result.data).equals(RAMP)).toBe(true)
+    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: {} }, signal())
+    expect(Buffer.from(result.data).equals(RAMP)).toBe(true)
     expect(result).toMatchObject({ offset: 0, eof: true, bytes: 256 })
     expect(result.absolutePath.endsWith('ramp.bin')).toBe(true)
     expect(result.version.length).toBeGreaterThan(0)
@@ -36,61 +34,68 @@ describe('workspaceFiles.readBytes — the window', () => {
 
   it('cuts the requested window and reports that more follows', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
-    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 16, length: 8 }, signal())
-    expect([...decode(result.data)]).toEqual([16, 17, 18, 19, 20, 21, 22, 23])
+    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 16, length: 8 } }, signal())
+    expect([...result.data]).toEqual([16, 17, 18, 19, 20, 21, 22, 23])
     expect(result).toMatchObject({ offset: 16, eof: false, bytes: 256 })
   })
 
-  it('reads a window of a file far above the byte cap', async () => {
+  it('reads only a window of a file above both byte caps', async () => {
     await writeFile(join(workspace, 'huge.bin'), Buffer.alloc(200_000, 7))
-    const result = await endpoint({ maxBytes: 1024 }).readBytes(harness.scope, 'huge.bin', { offset: 199_000, length: 1024 }, signal())
-    expect(decode(result.data)).toHaveLength(1000)
+    const rangeRead = vi.spyOn(harness.ctx.fs, 'readByteRange')
+    const completeRead = vi.spyOn(harness.ctx.fs, 'readBytes')
+    const caller = signal()
+    const result = await endpoint({ maxBytes: 1024, maxFileBytes: 4 }).readBytes(harness.scope, 'huge.bin', { range: { offset: 199_000, length: 1024 } }, caller)
+    expect(rangeRead).toHaveBeenCalledExactlyOnceWith(expect.anything(), { offset: 199_000, length: 1024 }, caller)
+    expect(completeRead).not.toHaveBeenCalled()
+    expect(result.data).toHaveLength(1000)
     expect(result).toMatchObject({ eof: true, bytes: 200_000 })
   })
 
   it('infers eof from a short window when the backend reports no size', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
     vi.spyOn(harness.ctx.fs, 'stat').mockResolvedValue({ version: FsVersion('v-sizeless'), type: 'file' })
-    const full = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 0, length: 256 }, signal())
+    const full = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 0, length: 256 } }, signal())
     expect(full.eof).toBe(false)
-    const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 250, length: 10 }, signal())
+    const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 250, length: 10 } }, signal())
     expect(short).toMatchObject({ eof: true })
     expect(short.bytes).toBeUndefined()
   })
 
   it('reports eof on the window that holds the last byte, whether or not the length is reached', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
-    const exact = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 248, length: 8 }, signal())
+    const exact = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 248, length: 8 } }, signal())
     expect(exact.eof).toBe(true)
-    expect(decode(exact.data)).toHaveLength(8)
-    const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 250, length: 100 }, signal())
+    expect(exact.data).toHaveLength(8)
+    const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 250, length: 100 } }, signal())
     expect(short.eof).toBe(true)
-    expect([...decode(short.data)]).toEqual([250, 251, 252, 253, 254, 255])
+    expect([...short.data]).toEqual([250, 251, 252, 253, 254, 255])
   })
 
   it('returns an empty eof window for an offset at or past the end', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
-    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 300, length: 8 }, signal())
-    expect(result).toMatchObject({ data: '', offset: 300, eof: true, bytes: 256 })
+    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 300, length: 8 } }, signal())
+    expect(result.data).toHaveLength(0)
+    expect(result).toMatchObject({ offset: 300, eof: true, bytes: 256 })
   })
 
   it('returns an empty eof window for an empty file', async () => {
     await writeFile(join(workspace, 'empty.bin'), Buffer.alloc(0))
-    const result = await endpoint().readBytes(harness.scope, 'empty.bin', {}, signal())
-    expect(result).toMatchObject({ data: '', offset: 0, eof: true, bytes: 0 })
+    const result = await endpoint().readBytes(harness.scope, 'empty.bin', { range: {} }, signal())
+    expect(result.data).toHaveLength(0)
+    expect(result).toMatchObject({ offset: 0, eof: true, bytes: 0 })
   })
 
-  it('carries bytes a text read would refuse: NUL and invalid UTF-8 round-trip through base64', async () => {
+  it('carries bytes a text read would refuse: NUL and invalid UTF-8 round-trip as bytes', async () => {
     const raw = Buffer.from([0, 0xff, 0xfe, 0x80, 0x41, 0])
     await writeFile(join(workspace, 'blob.bin'), raw)
-    const result = await endpoint().readBytes(harness.scope, 'blob.bin', {}, signal())
-    expect(decode(result.data).equals(raw)).toBe(true)
+    const result = await endpoint().readBytes(harness.scope, 'blob.bin', { range: {} }, signal())
+    expect(Buffer.from(result.data).equals(raw)).toBe(true)
   })
 
   it('names the version a stat of the same file reports', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
     const stat = await endpoint().stat(harness.scope, 'ramp.bin', signal())
-    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', {}, signal())
+    const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: {} }, signal())
     expect(result.version).toBe(stat.version)
   })
 })
@@ -98,22 +103,22 @@ describe('workspaceFiles.readBytes — the window', () => {
 describe('workspaceFiles.readBytes — defaults and cap', () => {
   it('defaults the length to the configured byte cap', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP.subarray(0, 64))
-    const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', {}, signal())
-    expect(decode(result.data)).toHaveLength(64)
+    const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { range: {} }, signal())
+    expect(result.data).toHaveLength(64)
     expect(result.eof).toBe(true)
   })
 
   it('refuses a window longer than the cap as too-large rather than shortening it', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP)
-    const failure = await failureOf(endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { length: 65 }, signal()))
+    const failure = await failureOf(endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { range: { length: 65 } }, signal()))
     expect(failure.code).toBe('workspace-file/too-large')
     expect(failure.details).toMatchObject({ limit: 64 })
   })
 
   it('accepts a window exactly at the cap', async () => {
     await writeFile(join(workspace, 'ramp.bin'), RAMP.subarray(0, 64))
-    const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { length: 64 }, signal())
-    expect(decode(result.data)).toHaveLength(64)
+    const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { range: { length: 64 } }, signal())
+    expect(result.data).toHaveLength(64)
   })
 
   it('refuses a negative or fractional offset and a non-positive length as bad requests', async () => {
@@ -124,7 +129,7 @@ describe('workspaceFiles.readBytes — defaults and cap', () => {
       { offset: 2 ** 53 }, { offset: Number.MAX_SAFE_INTEGER, length: 2 },
     ]
     for (const range of ranges) {
-      const failure = await failureOf(endpoint().readBytes(harness.scope, 'ramp.bin', range, signal()))
+      const failure = await failureOf(endpoint().readBytes(harness.scope, 'ramp.bin', { range }, signal()))
       expect(failure.code).toBe('gateway/bad-request')
     }
   })
@@ -133,15 +138,15 @@ describe('workspaceFiles.readBytes — defaults and cap', () => {
 describe('workspaceFiles.readBytes — the gates it shares with read', () => {
   it('rejects a directory, a missing path, and an empty path', async () => {
     await mkdir(join(workspace, 'dir'))
-    expect((await failureOf(endpoint().readBytes(harness.scope, 'dir', {}, signal()))).code).toBe('workspace-file/not-regular-file')
-    expect((await failureOf(endpoint().readBytes(harness.scope, 'missing.bin', {}, signal()))).code).toBe('workspace-file/not-found')
-    expect((await failureOf(endpoint().readBytes(harness.scope, '', {}, signal()))).code).toBe('gateway/bad-request')
+    expect((await failureOf(endpoint().readBytes(harness.scope, 'dir', { range: {} }, signal()))).code).toBe('workspace-file/not-regular-file')
+    expect((await failureOf(endpoint().readBytes(harness.scope, 'missing.bin', { range: {} }, signal()))).code).toBe('workspace-file/not-found')
+    expect((await failureOf(endpoint().readBytes(harness.scope, '', { range: {} }, signal()))).code).toBe('gateway/bad-request')
   })
 
   it('reads a bounded byte window outside the workspace', async () => {
     await writeFile(join(harness.outside, 'sample.bin'), RAMP)
-    const result = await endpoint().readBytes(harness.scope, join(harness.outside, 'sample.bin'), { offset: 2, length: 4 }, signal())
-    expect(decode(result.data)).toEqual(RAMP.subarray(2, 6))
+    const result = await endpoint().readBytes(harness.scope, join(harness.outside, 'sample.bin'), { range: { offset: 2, length: 4 } }, signal())
+    expect(result.data).toEqual(RAMP.subarray(2, 6))
     expect(result).toMatchObject({ offset: 2, eof: false })
   })
 })
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index aed223888a..4414ee4397 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: 8439fb9ec1173ba24f9775ac476e64d23534a594
-README.zh.md: 0bb8c9819dacabed01905f6b7aff8c770ea3caae
+README.md: 8a62a75dc5be8c2e55d8908a46f9c91581427a46
+README.zh.md: b7c07b1018be9413f0844fb26904797102acee1e
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index 8439fb9ec1..8a62a75dc5 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -47,7 +47,7 @@ With that entry point, startup keeps every plugin that can activate. An enabled
 
 Import profile and bundle declaration types from [`@deepseek-ai/dsh-package-manifest`](../../util/package-manifest/README.md). App-boot adapts `DshPackageManifest` to `ProfileManifest` with optional package identity because local profiles need no published version. App-boot owns profile loading, JSON validation, and resolved runtime data.
 
-A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles with its own `cordis.patch.yml`. The YAML composition enables or disables HMR. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh --profile <name> --from-default-profile <template>` creates a custom profile at a new non-shipped name from one shipped template, while `dsh plugin` initializes a base-backed profile and manages its installed bundles. Bundle resolution, manifest, and patch-loading failures print a diagnostic and skip that bundle without changing its selection. Remaining bundles keep their order; profile and user-patch errors still fail startup. Skipping a bundle does not guarantee that the remaining composition can provide the required services. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
+A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles with its own `cordis.patch.yml`. A bundle's `dsh.bundle.patch` names one patch file or an ordered list of files; `bundlePatchFiles` validates the declaration and `bundlePatchPaths` resolves it to absolute paths; the layer concatenates their patch lists in that order. The YAML composition enables or disables HMR. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh --profile <name> --from-default-profile <template>` creates a custom profile at a new non-shipped name from one shipped template, while `dsh plugin` initializes a base-backed profile and manages its installed bundles. Bundle resolution, manifest, and patch-loading failures print a diagnostic and skip that bundle without changing its selection. Remaining bundles keep their order; profile and user-patch errors still fail startup. Skipping a bundle does not guarantee that the remaining composition can provide the required services. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
 
 Your machine-local preferences also live in the Harness home:
 
@@ -68,12 +68,12 @@ Before you boot, you can print the exact configuration the app will mount: the d
 
 ### Reading plugin display metadata
 
-Use `readPluginMeta(specifier, parentURL)` or `ctx.pluginPackages.metaOf(specifier, parentURL)` to read installed package display text without importing or activating the plugin. Lookup uses the complete package specifier and the caller's resolution base, respecting Node exports. File paths and file URLs return no metadata without resolving resources. Missing locale fields fall back to the accessible `package.json` at that address; malformed metadata returns an `error` diagnostic. Results retain translations for Client-side language selection. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format.
+Use `readPluginMeta(specifier, parentURL)` or `ctx.pluginPackages.metaOf(specifier, parentURL)` to read installed package display text without importing or activating the plugin. Lookup uses the complete package specifier and the caller's resolution base, respecting Node exports. File paths and file URLs return no metadata without resolving resources. Missing locale fields fall back to the accessible `package.json` at that address; malformed metadata returns an `error` diagnostic. Results retain translations for Client-side language selection. The reader also loads `package.json.icon` as an image data URL, even when locale text is complete; an icon error preserves valid text alongside the diagnostic. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format.
 
 <a id="startup-and-reload-failures"></a>
 ### Startup and reload failures
 
-Profile reconciliation returns diagnostics for unchanged inactive entries without failing an unrelated mutation. A new inactive entry, a changed configuration or fiber, or a changed diagnostic fails reconciliation; removed fibers must still finish disposal. Explicit enablement targets must activate even when their failure predates the operation.
+Profile reconciliation returns diagnostics for unchanged inactive entries without failing an unrelated mutation. A new inactive entry, a changed configuration or fiber, or a changed diagnostic fails reconciliation; removed fibers must still finish disposal. Explicit enablement targets must activate even when their failure predates the operation. Successful reconciliation returns after lifecycle settlement and diagnostic checks; volatile-only entry changes are committed by Loader during the update.
 
 After the Loader settles, app-boot warns when only optional entries are inactive. If an enabled required entry cannot activate, `boot()` rejects with `StartupError` after disposal. An independently owned logger exporter retains warning and error records through asynchronous disposal and is released before `boot()` settles. Its message groups all failed plugins and pending services, marks required entries, and retains original stacks, nested causes, and aggregate members. The CLI prints that message once and saves [full startup diagnostics](../../../apps/cli/reference/README.md#startup-diagnostics) before exiting with code 1; unrelated exceptions retain their normal stack output. In the table, stopping startup means disposing any mounted plugins and exiting nonzero without reporting readiness; continuing keeps successful plugins running. Later configuration HMR does not repeat the required-startup audit and does not roll back the whole update.
 
@@ -114,11 +114,14 @@ This section explains how the outcomes above are realized and points at the code
 ### Design notes
 
 - **Profile launch data.** `ctx.profileContext` contains only profile locations, startup bundle names, parsed invocation overlays and the telemetry opt-out value. `readProfilePatches()` composes the supplied startup profile or reads current files at those locations; callers schedule and apply the result.
-- **Process-local module resolution.** The launcher installs the runtime resolution as an interception on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer instead of the internal lookup anchor. `ctx.pluginPackages` exposes package metadata from the same runtime resolution without recording Entry imports; an installed runtime resolution is authoritative even for a miss, while low-level embedders that install the service without one retain native lookup.
+- **Process-local module resolution.** The launcher installs the runtime resolution on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer. Explicit CommonJS `paths` always retain native lookup, including paths inside profiles.
+- **Linked directories.** A profile link to an external directory admits its importers to peer-aware ancestor lookup, even without its own `package.json`. At each `D/node_modules` position, current `D/package.json` peer names present in the runtime table use the runtime package; other names use the physical candidate. A nearer physical package precedes a later peer declaration, and a peer position needs no physical `node_modules`. Installation-scope package directories are excluded from linked interception; overlapping roots do not change the importer's lookup order ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)).
+- **Package metadata.** `ctx.pluginPackages.packageOf` locates the owning package without loading code or requiring an exported `package.json`; a subpath selects its package without validating that file. The installed runtime resolution owns selection even for a miss. Low-level embedders that install the service without one retain native lookup. Display metadata uses the separate entry-aware reader described above.
 - **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution.
 - **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate Loader subtree when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint.
-- **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names atomically, while changing or removing an existing mapping requires restart.
-- **Application-owned profiles.** Application-owned profiles use the same runtime resolution. Resolution does not modify their `node_modules`; pnpm owns installed packages.
+- **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names and update linked-root membership atomically within the existing package-mapping and local-name constraints.
+- **Removing linked interception.** A successor may remove a linked root without restart. Directories outside all remaining roots use native lookup for subsequent requests, which may find a development copy or report a missing package. Existing module references and Node caches stay unchanged. Re-adding the same link name and target is allowed; pointing a previously published name at a different target is rejected even after removal ([generation rules](../../../.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md#immutable-generations)).
+- **Application-owned profiles.** Application-owned profiles use the same runtime resolution. Links within the active profile directory, including pnpm store links, are not external roots even when the profile is outside the shared profiles tree. Resolution does not modify their `node_modules`; pnpm owns installed packages.
 - **Owned Workers.** Worker build banners import `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` before bundled business code. Each Worker installs the structured-cloned runtime resolution in its own isolate. The bootstrap bundle has no static package imports. Source Worker entries retain their self-contained dependency closure, and third-party Workers receive no injection.
 - **Update completion.** App boot observes restart failures through the `internal/update` waterfall. Live patch reloads wait for the tree's fibers before auditing activation; `Fiber.update()` and `Entry.update()` alone do not establish restart success.
 - **One rejection checkpoint.** `inactiveEntries` keeps the exact reasons it folds into the boot diagnostic visible through the next process rejection checkpoint, so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal.
@@ -178,6 +181,9 @@ Boot itself changes no request prefix. `addHarnessSourceSection` places its sour
 These limits describe when this boot library is a poor fit or needs special care. They are current package constraints, not a task backlog.
 
 - **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the runtime resolution bootstrap; third-party Workers and custom `vm` linkers keep native resolution.
+- **Relinking a profile package needs a restart** — Node caches real paths, so changing the target of a profile link or a dependency link requires a process restart.
+- **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. Current peer reads do not invalidate Node caches, watch files, or validate peer version ranges.
+- **Source launches use an ESM-only hook** — CommonJS requests still need the JavaScript files selected by package exports; resolution does not supply missing build outputs.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins.
 - **A user patch replaces the whole matched config** — an id-targeted patch does not deep-merge, so a profile override restates the bundle fields it keeps.
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 0bb8c9819d..b7c07b1018 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -47,7 +47,7 @@ const ctx = await boot('dsh', resolveConfigPath(argv[2], process.env.DSH_SNAPSHO
 
 Profile 与组合包的声明类型从 [`@deepseek-ai/dsh-package-manifest`](../../util/package-manifest/README.zh.md) 导入。App-boot 将 `DshPackageManifest` 适配为包身份可选的 `ProfileManifest`，因为本地 profile 无需发布版本。App-boot 负责 profile 加载、JSON 校验和解析后的运行时数据。
 
-profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装组合包和自身 `cordis.patch.yml` 组成。YAML 组合决定是否启用 HMR。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立组合包，其他模板保留 base 加模式的组合包栈。`dsh --profile <name> --from-default-profile <template>` 从一个随附模板，在新的非内置名称处创建自定义 profile；`dsh plugin` 则初始化以 base 为基础的 profile，并管理其中安装的组合包。组合包解析、manifest 读取或 patch 加载失败时会输出诊断并跳过该组合包，不改变其选择状态。其余组合包保持原顺序；profile 和用户 patch 错误仍会导致启动失败。跳过组合包不保证剩余组合能够提供所需服务。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
+profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装组合包和自身 `cordis.patch.yml` 组成。组合包的 `dsh.bundle.patch` 指定一个 patch 文件或一个有序的文件列表；`bundlePatchFiles` 校验该声明，`bundlePatchPaths` 把它解析为绝对路径；该层按此顺序拼接各文件的 patch 列表。YAML 组合决定是否启用 HMR。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立组合包，其他模板保留 base 加模式的组合包栈。`dsh --profile <name> --from-default-profile <template>` 从一个随附模板，在新的非内置名称处创建自定义 profile；`dsh plugin` 则初始化以 base 为基础的 profile，并管理其中安装的组合包。组合包解析、manifest 读取或 patch 加载失败时会输出诊断并跳过该组合包，不改变其选择状态。其余组合包保持原顺序；profile 和用户 patch 错误仍会导致启动失败。跳过组合包不保证剩余组合能够提供所需服务。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
 
 你的机器本地偏好同样位于 harness home 中：
 
@@ -68,12 +68,12 @@ profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`head
 
 ### 读取插件展示元信息
 
-使用 `readPluginMeta(specifier, parentURL)` 或 `ctx.pluginPackages.metaOf(specifier, parentURL)` 读取已安装包的展示文本，无需导入或激活插件。查询使用完整包标识与调用方的解析基准，并遵循 Node exports。文件路径与文件 URL 不解析资源，直接返回无元信息。缺失的 locale 字段回退到该地址下可访问的 `package.json`；格式错误的元信息返回 `error` 诊断。结果保留翻译，由 Client 选择语言。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。
+使用 `readPluginMeta(specifier, parentURL)` 或 `ctx.pluginPackages.metaOf(specifier, parentURL)` 读取已安装包的展示文本，无需导入或激活插件。查询使用完整包标识与调用方的解析基准，并遵循 Node exports。文件路径与文件 URL 不解析资源，直接返回无元信息。缺失的 locale 字段回退到该地址下可访问的 `package.json`；格式错误的元信息返回 `error` 诊断。结果保留翻译，由 Client 选择语言。即使 locale 文本完整，读取器也会将 `package.json.icon` 加载为图片 data URL；图标出错时，保留有效文本并附上诊断。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。
 
 <a id="startup-and-reload-failures"></a>
 ### 启动与重载失败
 
-profile 重载返回未变化的已有故障诊断，不让无关修改因此失败。新增未激活条目、配置或 fiber 变化、诊断变化都会使重载失败；被移除的 fiber 仍须完成释放。显式启用的目标必须成功激活，即使它的故障早于本次操作。
+profile 重载返回未变化的已有故障诊断，不让无关修改因此失败。新增未激活条目、配置或 fiber 变化、诊断变化都会使重载失败；被移除的 fiber 仍须完成释放。显式启用的目标必须成功激活，即使它的故障早于本次操作。 成功重载在生命周期结束及诊断检查通过后返回；仅 volatile 的条目变化由 Loader 在更新过程中提交。
 
 Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如果已启用的 required 条目无法激活，`boot()` 会在释放资源后以 `StartupError` 拒绝。独立管理生命周期的 logger exporter 会保留异步资源释放期间的警告和错误记录，并在 `boot()` 结算前释放。其消息分组列出所有失败插件和等待的服务，标记 required 条目，并保留原始堆栈、嵌套原因和聚合错误成员。CLI 仅输出该消息一次，并在保存[完整启动诊断](../../../apps/cli/reference/README.zh.md#startup-diagnostics)后以退出码 1 结束；其他异常保留正常堆栈输出。表中的“终止启动”指释放已挂载插件并以非零码退出，不报告就绪；“继续”指保留成功运行的插件。后续配置 HMR 不会再次执行 required 启动审计，也不会回滚整个更新。
 
@@ -114,11 +114,14 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 ### 设计说明
 
 - **Profile 启动数据。** `ctx.profileContext` 只包含 profile 位置、启动时组合包名称、已解析的调用级 overlay 与遥测退出值。`readProfilePatches()` 组合传入的启动 profile，或读取这些位置上的当前文件；调用方负责调度和应用结果。
-- **进程内模块解析。** runtime 解析会在挂载 profile 条目前，将 runtime resolution 作为拦截安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、subpath、模块缓存和错误码仍由 Node 负责；路由后的 ESM 失败会报告原始 importer，而不是内部查找锚点。`ctx.pluginPackages` 从同一 runtime resolution 提供 package metadata，不记录 Entry import；安装 runtime resolution 后，即使查询未命中也以 runtime resolution 为准，仅安装服务而未提供 runtime resolution 的底层嵌入方仍使用 Node 原生查找。
+- **进程内模块解析。** launcher 在挂载 profile 条目前，将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、子路径、模块缓存和错误码仍由 Node 负责；路由后的 ESM 失败报告原始 importer。显式 CommonJS `paths` 始终保留原生查询，包括指向 profile 内的路径。
+- **链接目录。** profile 链接到树外目录时，其下的 importer 参与逐层 peer 查询，即使目标没有自身的 `package.json`。在每个 `D/node_modules` 位置，当前 `D/package.json` 的 peer 包名若存在于运行时表，就使用运行时包；其他包名查询物理候选。更近的物理包先于后续 peer 声明，peer 位置无需物理 `node_modules`。installation 作用域包目录不参与 linked 拦截，重叠 root 不改变 importer 的查询顺序（[规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)）。
+- **包元数据。** `ctx.pluginPackages.packageOf` 定位所属包，不加载代码，也不要求导出 `package.json`；子路径选择其所属包，不校验该文件。安装 runtime resolution 后，即使查询未命中也以其选包规则为准。仅安装服务而不提供 runtime resolution 的底层嵌入方保留原生查询。展示元数据使用上文另述的入口感知读取器。
 - **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin：group 行能把一个提供方与它的消费方放进同一个 `isolate` realm，而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载，而非被包含树自身的说明符解析。
 - **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy；agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时，持有并拆卸各自的独立 Loader 子树。App-boot 读取 failed fiber 来报告已记录的错误，并在一个进程检查点内合并 Loader 重复的 rejection 通知。
-- **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接；runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置，其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影；pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序，映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以原子增加 package name，修改或删除既有映射则要求重启。
-- **应用自有 profile。** 应用自有 profile 使用相同的 runtime resolution。解析过程不修改其 `node_modules`；已安装包由 pnpm 管理。
+- **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接；runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置，其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影；pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序，映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以在既有包映射和本地包名约束内原子增加 package name、更新 linked root 集合。
+- **移除链接拦截。** 后继 generation 可以移除 linked root，无需重启。目录不再被任何剩余 root 覆盖时，后续请求使用原生查询，可能找到开发副本，也可能报告缺包。已有模块引用和 Node 缓存保持不变。同名、同目标可以重新加入；曾发布的名称改指向不同目标时，即使中间移除过也会被拒绝（[generation 规则](../../../.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md#immutable-generations)）。
+- **应用自有 profile。** 应用自有 profile 使用相同的 runtime resolution。目标位于当前 profile 目录内的链接（包括 pnpm store 链接）不算外部 root，即使 profile 位于共享 profiles 树外。解析过程不修改其 `node_modules`；已安装包由 pnpm 管理。
 - **自有 Worker。** Worker 构建 banner 会在业务 bundle 前导入 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap`。每个 Worker 在自己的 isolate 中安装结构化克隆的 runtime resolution。bootstrap bundle 不静态导入任何包。源码 Worker 入口保留自包含依赖，第三方 Worker 不接受注入。
 - **更新完成。** App boot 通过 `internal/update` waterfall 观察重启失败。实时 patch 重载在检查激活状态前等待配置树中的 fiber；单独调用 `Fiber.update()` 或 `Entry.update()` 不能确定重启成功。
 - **单一 rejection 检查点。** `inactiveEntries` 把折入启动诊断的确切原因保持到下一个进程级 rejection 检查点可见，使 `installFailLoud` 能合并 Loader 的重复通知，而所有无关的未处理 rejection 仍然致命。
@@ -178,6 +181,9 @@ Loader 结算后，app-boot 在仅 optional 条目未激活时输出警告。如
 这些限制说明此启动库在何时不合适，或何时需要特别注意。它们是当前包约束，不是任务积压。
 
 - **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 runtime resolution bootstrap；第三方 Worker 与自定义 `vm` linker 保持原生解析。
+- **重新链接 profile 包需要重启**——Node 缓存真实路径，因此改变 profile 链接或依赖链接的目标需要重启进程。
+- **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外，就使用原生 Node。实时读取 peer 不会使 Node 缓存失效、监视文件或校验 peer 版本范围。
+- **源码启动只安装 ESM 钩子**——CommonJS 请求仍需要 package exports 选中的 JavaScript 文件，解析器不会补出缺失的构建产物。
 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
 - **用户 patch 会替换匹配到的整个配置**——按 id 定位的 patch 不做深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index a20d1e50ce..e5ef8a79cf 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -39,6 +39,8 @@ export {
   createRuntimeResolution,
   DEFAULT_PROFILE_BUNDLES,
   OPTIONAL_BUNDLES,
+  bundlePatchFiles,
+  bundlePatchPaths,
   initProfile,
   removeLinkProjections,
   loadProfile,
@@ -53,6 +55,7 @@ export {
   type Profile,
   type ProfileLayer,
   type ProfileManifest,
+  type LinkedRoot,
   type RuntimeResolutionOptions,
   type RuntimeResolutionEntry,
   type RuntimeResolution,
diff --git a/packages/boot/app-boot/src/package-meta.ts b/packages/boot/app-boot/src/package-meta.ts
index 434b233d1e..131082ce8a 100644
--- a/packages/boot/app-boot/src/package-meta.ts
+++ b/packages/boot/app-boot/src/package-meta.ts
@@ -1,7 +1,7 @@
-/** Read plugin display metadata through exported locale resources without evaluating plugin code. */
+/** Read plugin display text and icons through exported resources without evaluating plugin code. */
 
-import { readdirSync, readFileSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, extname, isAbsolute, relative, resolve, sep, win32 } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { ModuleLoader } from '@deepseek-ai/cordis-plugin-loader'
 import type { LocalizedText, PluginLocalizedMeta } from '@deepseek-ai/dsh-package-manifest'
@@ -11,6 +11,35 @@ const LANGUAGE_ID = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u
 
 type DisplayFields = Record<'title' | 'description', string | undefined>
 
+/** Maximum raw icon bytes admitted to plugin metadata. */
+const MAX_ICON_BYTES = 256 * 1024
+const ICON_MEDIA_TYPES = new Map([
+  ['.svg', 'image/svg+xml'], ['.png', 'image/png'], ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'], ['.webp', 'image/webp'],
+])
+
+function iconOf(value: unknown, manifestPath: string): string | undefined {
+  const icon = textOf(value, `${manifestPath}: icon`)
+  if (icon === undefined) return undefined
+  if (isAbsolute(icon) || win32.isAbsolute(icon) || /^[A-Za-z][A-Za-z\d+.-]*:/u.test(icon)) {
+    throw new Error(`${manifestPath}: icon must be a relative file path`)
+  }
+  const mediaType = ICON_MEDIA_TYPES.get(extname(icon).toLowerCase())
+  if (mediaType === undefined) throw new Error(`${manifestPath}: icon must be SVG, PNG, JPEG, or WebP`)
+  const directory = realpathSync(dirname(manifestPath))
+  const file = realpathSync(resolve(directory, icon))
+  const local = relative(directory, file)
+  if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+    throw new Error(`${manifestPath}: icon must remain inside its manifest directory`)
+  }
+  const stat = statSync(file)
+  if (!stat.isFile()) throw new Error(`${manifestPath}: icon must be a regular file`)
+  if (stat.size > MAX_ICON_BYTES) throw new Error(`${manifestPath}: icon exceeds 256 KiB`)
+  const bytes = readFileSync(file)
+  if (bytes.length > MAX_ICON_BYTES) throw new Error(`${manifestPath}: icon exceeds 256 KiB`)
+  return `data:${mediaType};base64,${bytes.toString('base64')}`
+}
+
 /**
  * Resolve a plugin resource through the active Node ESM resolver without evaluating it.
  * @param specifier - complete resource module specifier, including its locale filename.
@@ -104,7 +133,9 @@ function localizedText(
 }
 
 /**
- * Read meta.title and meta.description from a plugin's exported locale JSON files.
+ * Read localized display text and the icon declared in a plugin's exported package.json.
+ * Icons are manifest-relative SVG, PNG, JPEG, or WebP files of at most 256 KiB,
+ * contained in the manifest directory after realpath resolution. Icon failures retain display text.
  * Non-package specifiers are skipped without invoking the resource resolver.
  * Language files share the directory containing the resolved English resource;
  * each file is resolved through the complete plugin specifier before reading.
@@ -112,25 +143,29 @@ function localizedText(
  * maps retain an English fallback, ultimately the full module specifier for titles and empty for descriptions.
  * @param specifier - configured plugin module name, including any package subpath.
  * @param parentURL - owning Loader tree's module-resolution base.
- * @returns translated or fallback fields, a diagnostic, or undefined for non-package specifiers or absent display text.
+ * @returns display fields and any icon diagnostic, or undefined for non-package specifiers or absent metadata.
  */
 export function readPluginMeta(specifier: string, parentURL: string): PluginLocalizedMeta | undefined {
   if (barePackageName(specifier) === undefined) return undefined
   try {
     const englishPath = optionalResourcePath(`${specifier}/locale/en.json`, parentURL)
     const dictionaries = englishPath === undefined ? new Map<string, DisplayFields>() : dictionariesOf(englishPath, specifier, parentURL)
-    const english = dictionaries.get('en')
-    const manifestPath = english?.title === undefined || english.description === undefined
-      ? optionalResourcePath(`${specifier}/package.json`, parentURL)
-      : undefined
+    const manifestPath = optionalResourcePath(`${specifier}/package.json`, parentURL)
     const manifest = manifestPath === undefined ? undefined : readObject(manifestPath)
     const title = localizedText('title', dictionaries, fallbackText(manifest?.name), specifier)
     const description = localizedText('description', dictionaries, fallbackText(manifest?.description), '')
-    if (title === undefined && description === undefined) return undefined
-    return {
+    const text = {
       ...title === undefined ? {} : { title },
       ...description === undefined ? {} : { description },
     }
+    let icon: string | undefined
+    try {
+      icon = manifestPath === undefined ? undefined : iconOf(manifest?.icon, manifestPath)
+    } catch (error) {
+      return { ...text, error: `Plugin metadata for ${specifier}: ${String(error)}` }
+    }
+    if (title === undefined && description === undefined && icon === undefined) return undefined
+    return { ...text, ...icon === undefined ? {} : { icon } }
   } catch (error) {
     return { error: `Plugin metadata for ${specifier}: ${String(error)}` }
   }
diff --git a/packages/boot/app-boot/src/profile-resolution/resolver.ts b/packages/boot/app-boot/src/profile-resolution/resolver.ts
index cb6180cd19..ea931a5087 100644
--- a/packages/boot/app-boot/src/profile-resolution/resolver.ts
+++ b/packages/boot/app-boot/src/profile-resolution/resolver.ts
@@ -66,11 +66,34 @@ interface ResolutionRouteState {
   cjs?: string
 }
 
+interface CommonJsLookup {
+  readonly cacheable: boolean
+  resolveNative(searchPaths: readonly string[]): string
+  resolveEntry(entry: RuntimeResolutionEntry, after: string): string
+}
+
+/** The lookup positions that one interception layer fixes on an importer's ancestor chain. */
+interface LayerPositions {
+  /** Search paths with this prefix lie below the layer and are answered by their physical content. */
+  readonly localPrefix: string
+  /** Manifest anchoring Node's lookup at the layer's physical directory. */
+  readonly nativeAfter: string
+  /** Manifest anchoring Node's lookup above the layer after a CommonJS subpath miss. */
+  readonly after: string
+}
+
+/**
+ * The interception layer of one importer. A profile's layer is its parent's node_modules and answers every entry
+ * for the active profile. Linked importers apply current peer declarations at each ancestor node_modules
+ * position without memoizing the selected route.
+ */
+type InterceptionLayer =
+  | LayerPositions & { readonly kind: 'profile'; readonly active: boolean }
+  | { readonly kind: 'linked' }
+
 interface ParentRoutes {
   readonly parent: string
-  /** Profile directory owning the importer; its node_modules are local, the first ancestor above it is the interception layer. */
-  readonly localRoot: string
-  readonly activeProfile: boolean
+  readonly layer: InterceptionLayer
   readonly requests: Map<string, ResolutionRouteState>
   selfReferenceName?: string | false | null
 }
@@ -82,9 +105,9 @@ interface CompiledResolution {
   readonly profilesDir: string
   readonly profileDir: string | undefined
   readonly profilePaths: readonly string[]
-  readonly profileUrls: readonly string[]
   readonly profile: readonly string[]
-  readonly activeProfileUrls: readonly string[]
+  readonly installationPaths: readonly string[]
+  readonly linkedPaths: readonly string[]
   readonly localPackageNames: ReadonlySet<string>
   readonly esmRoutes: ResolutionRoutes
   readonly cjsRoutes: ResolutionRoutes
@@ -94,15 +117,18 @@ interface CompiledResolution {
 export interface RuntimeInterception {
   /**
    * Locate a bare package without requiring one of its exports.
+   * A package subpath selects its package directory without resolving or validating the requested file.
    * @param specifier - bare package or package-subpath specifier.
    * @param parentURL - file URL whose lookup order applies.
    * @returns selected package directory, or undefined when it is absent.
    */
   packageDir(specifier: string, parentURL: string): string | undefined
   /**
-   * Atomically publish an additive package table and fresh caches.
-   * @param successor - fully constructed additive successor generation.
-   * @throws when the profile scope or an existing package mapping changes.
+   * Atomically publish a complete successor and fresh caches. Linked roots may be added or removed.
+   * Removed roots stop intercepting uncovered directories; existing modules and Node caches remain intact.
+   * @param successor - fully constructed generation retaining existing package mappings and local names.
+   * @throws when the profile scope or existing mappings change, local names are removed or override
+   * existing mappings, or a previously published link name selects a different real directory.
    */
   replace(successor: RuntimeResolution): void
   /** Restore the native resolver methods. Interceptions dispose in reverse order. */
@@ -140,22 +166,61 @@ function prefixes(path: string): readonly string[] {
 }
 
 function compileResolution(resolution: RuntimeResolution): CompiledResolution {
-  const profilePaths = prefixes(resolution.profilesDir)
-  const profile = resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir)
   return {
     entries: new Map(resolution.entries.map(entry => [entry.name, entry])),
     profilesDir: resolution.profilesDir,
     profileDir: resolution.profileDir,
-    profilePaths,
-    profileUrls: profilePaths.map(path => pathToFileURL(path).href),
-    profile,
-    activeProfileUrls: profile.map(path => pathToFileURL(path).href),
+    profilePaths: prefixes(resolution.profilesDir),
+    profile: resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir),
+    installationPaths: [...new Set(resolution.entries
+      .filter(entry => entry.scope === 'installation')
+      .flatMap(entry => prefixes(entry.packageDir)))],
+    linkedPaths: resolution.linkedRoots.flatMap(root => prefixes(root.realPath)),
     localPackageNames: new Set(resolution.localPackageNames),
     esmRoutes: new Map(),
     cjsRoutes: new Map(),
   }
 }
 
+/**
+ * The interception layer of a profile is `<profileParent>/node_modules`: an entry occupies its name there, so its
+ * subpath misses continue above it, and a name without an entry continues at it.
+ */
+function computeProfileLayer(dir: string, active: boolean): InterceptionLayer {
+  const profileParent = dirname(dir)
+  return {
+    kind: 'profile', active,
+    localPrefix: dir + sep,
+    nativeAfter: join(profileParent, 'package.json'),
+    after: join(dirname(profileParent), 'package.json'),
+  }
+}
+
+/** The interception layer of a module path: from its profile directory inside a profiles tree, or its linked root. */
+function findInterceptionLayer(path: string, resolution: CompiledResolution): InterceptionLayer | undefined {
+  const treeRoot = resolution.profilePaths.find(prefix => path.startsWith(prefix))
+  const activeProfile = resolution.profile.find(prefix => path.startsWith(prefix))
+  const dir = treeRoot !== undefined ? profileChild(path, treeRoot) : activeProfile?.slice(0, -1)
+  if (dir !== undefined) return computeProfileLayer(dir, activeProfile !== undefined)
+  if (!startsWithin(path, resolution.linkedPaths)) return undefined
+  if (startsWithin(path, resolution.installationPaths)) return undefined
+  return { kind: 'linked' }
+}
+
+/** Package names a directory's current manifest lists as peers; an unreadable manifest lists none. */
+function readPeerNames(directory: string): ReadonlySet<string> {
+  try {
+    const manifest = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8')) as {
+      peerDependencies?: unknown
+    }
+    const peers = manifest.peerDependencies
+    return new Set(peers !== null && typeof peers === 'object' ? Object.keys(peers) : [])
+  } catch (_error) {
+    // Node reports the unreadable or invalid manifest itself when it resolves the package's own imports.
+    return new Set()
+  }
+}
+
 function startsWithin(path: string, roots: readonly string[]): boolean {
   for (const root of roots) {
     if (path.startsWith(root)) return true
@@ -298,9 +363,11 @@ function sameResolution(left: string, right: string): boolean {
 /** One mutable pointer to the immutable runtime resolution. */
 class ResolutionRouter {
   private current: CompiledResolution
+  private readonly linkedTargets: Map<string, string>
 
-  constructor(resolution: RuntimeResolution) {
+  constructor(resolution: RuntimeResolution, private readonly nodeModulePaths: (directory: string) => string[]) {
     this.current = compileResolution(resolution)
+    this.linkedTargets = new Map(resolution.linkedRoots.map(root => [root.name, root.realPath]))
   }
 
   replace(successor: RuntimeResolution): void {
@@ -330,7 +397,49 @@ class ResolutionRouter {
         throw new Error(`profile resolution: overriding ${JSON.stringify(name)} locally requires a process restart`)
       }
     }
-    this.current = compileResolution(successor)
+    // Node retains realpath caches after a root leaves the interception scope.
+    for (const root of successor.linkedRoots) {
+      const previous = this.linkedTargets.get(root.name)
+      if (previous !== undefined && !sameResolution(previous, root.realPath)) {
+        throw new Error(`profile resolution: relinking ${JSON.stringify(root.name)} requires a process restart`)
+      }
+    }
+    const next = compileResolution(successor)
+    for (const { name, realPath } of successor.linkedRoots) {
+      if (!this.linkedTargets.has(name)) this.linkedTargets.set(name, realPath)
+    }
+    this.current = next
+  }
+
+  /** Whether a module path has an interception layer: it lies in the profiles tree, the active profile, or a linked root. */
+  hasInterceptionLayerForPath(path: string): boolean {
+    return findInterceptionLayer(path, this.current) !== undefined
+  }
+
+  /** Whether an importer URL is scoped; the answer is memoized with the importer's routes. */
+  hasInterceptionLayerForUrl(parentURL: string): boolean {
+    return this.getOrCreateParentRoutesForUrl(parentURL) !== false
+  }
+
+  private createParentRoutes(parent: string, resolution: CompiledResolution): ParentRoutes | undefined {
+    const layer = findInterceptionLayer(parent, resolution)
+    return layer === undefined ? undefined : { parent, layer, requests: new Map() }
+  }
+
+  private getOrCreateParentRoutesForUrl(parentURL: string): ParentRoutes | false {
+    const resolution = this.current
+    let parentRoutes = resolution.esmRoutes.get(parentURL)
+    if (parentRoutes !== undefined) return parentRoutes
+    let parent: string | undefined
+    try {
+      parent = fileURLToPath(parentURL)
+    } catch {
+      // Only file URLs can lie inside a profile tree or linked root.
+      parent = undefined
+    }
+    parentRoutes = parent === undefined ? false : this.createParentRoutes(parent, resolution) ?? false
+    resolution.esmRoutes.set(parentURL, parentRoutes)
+    return parentRoutes
   }
 
   private routeScoped(
@@ -338,36 +447,37 @@ class ResolutionRouter {
     parentRoutes: ParentRoutes,
     resolution: CompiledResolution,
     flavor: 'esm' | 'cjs',
-    nativeResolve?: (searchPaths: readonly string[]) => string,
-    cacheable = false,
+    cjs?: CommonJsLookup,
   ): ResolutionRouteState | undefined {
-    const { parent, localRoot, requests } = parentRoutes
+    const { parent, layer, requests } = parentRoutes
+    const memo = layer.kind === 'profile' && (cjs === undefined || cjs.cacheable)
     const name = barePackageName(request)
     if (name === undefined) return undefined
 
-    if (parentRoutes.selfReferenceName === undefined) {
+    if (parentRoutes.selfReferenceName === undefined || !memo) {
       parentRoutes.selfReferenceName = selfReferenceName(parent)
     }
     if (parentRoutes.selfReferenceName === name || parentRoutes.selfReferenceName === null) {
       const state = { route: { kind: 'native' as const } }
-      requests.set(request, state)
+      if (memo) requests.set(request, state)
       return state
     }
 
+    if (layer.kind === 'linked') return this.routeLinked(request, name, parent, resolution, flavor, cjs)
+
     const target = resolution.entries.get(name)
     const candidates: string[] = []
     const localSearchPaths: string[] = []
-    const localPrefix = localRoot + sep
     for (const searchPath of createRequire(parent).resolve.paths(name) as string[]) {
-      if (!searchPath.startsWith(localPrefix)) break
+      if (!searchPath.startsWith(layer.localPrefix)) break
       localSearchPaths.push(searchPath)
       const candidate = localPackageCandidate(searchPath, name, flavor)
       if (candidate !== undefined) candidates.push(candidate)
     }
     if (candidates.length > 0) {
-      if (flavor === 'cjs' && nativeResolve !== undefined) {
+      if (cjs !== undefined) {
         try {
-          const resolved = nativeResolve(localSearchPaths)
+          const resolved = cjs.resolveNative(localSearchPaths)
           const selected = candidates.find(candidate => (
             localCandidateOwnsResolution(candidate, resolved, request, name)
           ))
@@ -375,9 +485,9 @@ class ResolutionRouter {
             const state = {
               route: { kind: 'native' as const, packageDir: selected },
               packageDir: selected,
-              ...(cacheable ? { cjs: resolved } : {}),
+              cjs: resolved,
             }
-            requests.set(request, state)
+            if (memo) requests.set(request, state)
             return state
           }
         } catch (error) {
@@ -394,24 +504,62 @@ class ResolutionRouter {
       }
     }
 
-    // The interception layer is `<profileParent>/node_modules`: a runtime resolution entry occupies its name
-    // there, so its subpath misses continue above it; a name without an entry continues at it.
-    const profileParent = dirname(localRoot)
-    const eligible = target?.scope === 'installation'
-      || (target?.scope === 'profile' && parentRoutes.activeProfile)
-    const route: ResolutionRoute = eligible
-      ? { kind: 'interception', entry: target, after: join(dirname(profileParent), 'package.json') }
-      : { kind: 'native-after-interception', parent: join(profileParent, 'package.json') }
+    const route: ResolutionRoute = target !== undefined
+      && (target.scope === 'installation' || layer.active)
+      ? { kind: 'interception', entry: target, after: layer.after }
+      : { kind: 'native-after-interception', parent: layer.nativeAfter }
     const state: ResolutionRouteState = { route }
-    if (route.kind === 'interception') requests.set(request, state)
+    if (route.kind === 'interception' && memo) requests.set(request, state)
     return state
   }
 
+  private routeLinked(
+    request: string, name: string, parent: string, resolution: CompiledResolution,
+    flavor: 'esm' | 'cjs', cjs: CommonJsLookup | undefined,
+  ): ResolutionRouteState {
+    const target = resolution.entries.get(name)
+    if (target === undefined) return { route: { kind: 'native' } }
+    const ancestors = this.nodeModulePaths(dirname(parent))
+    const ancestorSet = new Set(ancestors)
+    const searchPaths = flavor === 'esm' ? ancestors : createRequire(parent).resolve.paths(name) as string[]
+    for (const searchPath of searchPaths) {
+      const directory = dirname(searchPath)
+      if (ancestorSet.has(searchPath) && readPeerNames(directory).has(name)) {
+        const route: ResolutionRoute = { kind: 'interception', entry: target, after: join(dirname(directory), 'package.json') }
+        if (cjs === undefined) return { route }
+        try {
+          const resolved = cjs.resolveEntry(target, route.after)
+          if (localCandidateOwnsResolution(target.packageDir, resolved, request, name)) {
+            return { route, packageDir: target.packageDir, cjs: resolved }
+          }
+        } catch (error) {
+          if (!isUnselectedPackageMiss(error)) throw error
+        }
+        // This position is occupied even when a legacy CommonJS subpath is absent from the supplied package.
+        continue
+      }
+      const candidate = localPackageCandidate(searchPath, name, flavor)
+      if (candidate === undefined) continue
+      if (cjs === undefined) return { route: { kind: 'native', packageDir: candidate }, packageDir: candidate }
+      try {
+        const resolved = cjs.resolveNative([searchPath])
+        if (localCandidateOwnsResolution(candidate, resolved, request, name)) {
+          return { route: { kind: 'native', packageDir: candidate }, packageDir: candidate, cjs: resolved }
+        }
+      } catch (error) {
+        if (!isUnselectedPackageMiss(error)) throw error
+      }
+    }
+    // An exhausted CommonJS lookup must not retry the physical copies at occupied peer positions.
+    return cjs === undefined ? { route: { kind: 'native' } } : { route: { kind: 'native' }, cjs: cjs.resolveNative([]) }
+  }
+
   private routeLocalPackage(
     request: string, parentRoutes: ParentRoutes, resolution: CompiledResolution,
   ): ResolutionRouteState | undefined {
     const name = barePackageName(request)
-    if (name === undefined || !parentRoutes.activeProfile || !resolution.localPackageNames.has(name)) return undefined
+    const { layer } = parentRoutes
+    if (name === undefined || layer.kind !== 'profile' || !layer.active || !resolution.localPackageNames.has(name)) return undefined
     const state = { route: { kind: 'native' as const } }
     parentRoutes.requests.set(request, state)
     return state
@@ -419,86 +567,35 @@ class ResolutionRouter {
 
   routeUrl(request: string, parentURL: string): ResolutionRouteState | undefined {
     const resolution = this.current
-    let parentRoutes = resolution.esmRoutes.get(parentURL)
+    const parentRoutes = this.getOrCreateParentRoutesForUrl(parentURL)
     if (parentRoutes === false) return undefined
-    const cached = parentRoutes?.requests.get(request)
+    const cached = parentRoutes.requests.get(request)
     if (cached !== undefined) return cached
-    if (parentRoutes === undefined) {
-      const profileIndex = resolution.profileUrls.findIndex(prefix => parentURL.startsWith(prefix))
-      const activeProfileIndex = resolution.activeProfileUrls.findIndex(prefix => parentURL.startsWith(prefix))
-      if (profileIndex < 0 && activeProfileIndex < 0) {
-        resolution.esmRoutes.set(parentURL, false)
-        return undefined
-      }
-      let parent: string
-      try {
-        parent = fileURLToPath(parentURL)
-      } catch {
-        resolution.esmRoutes.set(parentURL, false)
-        return undefined
-      }
-      const treeRoot = resolution.profilePaths[profileIndex]
-      const localRoot = treeRoot !== undefined
-        ? profileChild(parent, treeRoot)
-        : resolution.profile[activeProfileIndex]?.slice(0, -1)
-      /* v8 ignore next -- one matching index was established above */
-      if (localRoot === undefined) return undefined
-      parentRoutes = { parent, localRoot, activeProfile: activeProfileIndex >= 0, requests: new Map() }
-      resolution.esmRoutes.set(parentURL, parentRoutes)
-    }
     const local = this.routeLocalPackage(request, parentRoutes, resolution)
     if (local !== undefined) return local
     return this.routeScoped(request, parentRoutes, resolution, 'esm')
   }
 
   routePath(
-    request: string, parent: string, nativeResolve?: (searchPaths: readonly string[]) => string, cacheable = false,
+    request: string, parent: string, cjs: CommonJsLookup,
   ): ResolutionRouteState | undefined {
     const resolution = this.current
     let parentRoutes = resolution.cjsRoutes.get(parent)
     if (parentRoutes === false) return undefined
-    const cached = parentRoutes?.requests.get(request)
+    const cached = cjs.cacheable ? parentRoutes?.requests.get(request) : undefined
     if (cached !== undefined) return cached
     if (parentRoutes === undefined) {
-      const treeRoot = resolution.profilePaths.find(prefix => parent.startsWith(prefix))
-      const activeProfile = resolution.profile.find(prefix => parent.startsWith(prefix))
-      const localRoot = treeRoot !== undefined ? profileChild(parent, treeRoot) : activeProfile?.slice(0, -1)
-      if (localRoot !== undefined) {
-        parentRoutes = { parent, localRoot, activeProfile: activeProfile !== undefined, requests: new Map() }
-        resolution.cjsRoutes.set(parent, parentRoutes)
-      }
+      parentRoutes = this.createParentRoutes(parent, resolution) ?? false
+      resolution.cjsRoutes.set(parent, parentRoutes)
+      if (parentRoutes === false) return undefined
     }
-    if (parentRoutes === undefined) {
-      resolution.cjsRoutes.set(parent, false)
-      return undefined
-    }
-    return this.routeScoped(request, parentRoutes, resolution, 'cjs', nativeResolve, cacheable)
-  }
-
-  explicitRoute(
-    request: string, paths: readonly string[],
-  ): { index: number; parent: string } | undefined {
-    if (barePackageName(request) === undefined) return undefined
-    for (const [index, path] of paths.entries()) {
-      const parent = join(resolve(path), '.dsh-profile-resolution.cjs')
-      if (startsWithin(parent, this.current.profilePaths) || startsWithin(parent, this.current.profile)) {
-        return { index, parent }
-      }
-    }
-    return undefined
-  }
-
-  nativeSelfReference(request: string, parent: string): boolean {
-    const name = barePackageName(request)
-    if (name === undefined) return false
-    const self = selfReferenceName(parent)
-    return self === name || self === null
+    return this.routeScoped(request, parentRoutes, resolution, 'cjs', cjs)
   }
 
   packageDir(specifier: string, parentURL: string): string | undefined {
     const name = barePackageName(specifier)
     if (name === undefined) return undefined
-    const state = this.routeUrl(specifier, parentURL)
+    const state = this.routeUrl(name, parentURL)
     if (state?.route.kind === 'interception') return state.route.entry.packageDir
     if (state?.packageDir !== undefined) return state.packageDir
     let parent: string
@@ -601,16 +698,8 @@ function throwWithoutCjsAnchor(error: unknown, anchor: string): never {
 export function installRuntimeInterception(
   resolution: RuntimeResolution,
 ): RuntimeInterception {
-  const router = new ResolutionRouter(resolution)
   const { esm, esmDefaultResolve, esmConditions, cjs, cjsConditions, modern } = internalModules()
-  const esmScope = new Map<string, boolean>()
-  const profilePaths = [
-    ...prefixes(resolution.profilesDir),
-    ...(resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir)),
-  ]
-  const profileUrls = profilePaths.map(path => pathToFileURL(path).href)
-  let recentEsmParent: string | undefined
-  let recentEsmScoped = false
+  const router = new ResolutionRouter(resolution, directory => cjs._nodeModulePaths(directory))
   let delegatedEsm: { parent: string | undefined; request: string } | undefined
 
   const adaptEsm = (native: EsmResolve): EsmResolve => {
@@ -620,17 +709,7 @@ export function installRuntimeInterception(
       if (delegated !== undefined && delegated.parent === parent && delegated.request === request) {
         return native(request, parent, attributes)
       }
-      if (parent === undefined) return native(request, parent, attributes)
-      let scoped = recentEsmParent === parent ? recentEsmScoped : esmScope.get(parent)
-      if (scoped === undefined) {
-        scoped = startsWithin(parent, profileUrls)
-        esmScope.set(parent, scoped)
-      }
-      if (recentEsmParent !== parent) {
-        recentEsmParent = parent
-        recentEsmScoped = scoped
-      }
-      if (!scoped) return native(request, parent, attributes)
+      if (parent === undefined || !router.hasInterceptionLayerForUrl(parent)) return native(request, parent, attributes)
       const state = router.routeUrl(request, parent)
       if (state === undefined) {
         const target = request[0] === '#'
@@ -743,7 +822,7 @@ export function installRuntimeInterception(
     parentFilename: string, main: boolean, conditions: ReadonlySet<string> | undefined,
   ): string => {
     const synthetic = new cjs(parentFilename)
-    synthetic.parent = parent
+    if (parent.parent !== undefined) synthetic.parent = parent.parent
     synthetic.filename = parentFilename
     synthetic.paths = [...searchPaths]
     const options = conditions === undefined ? undefined : { conditions }
@@ -764,39 +843,26 @@ export function installRuntimeInterception(
     return resolveFrom(pathToFileURL(route.entry.declarer).href)
   }
   const wrappedFilename: CommonJsModule['_resolveFilename'] = (request, parent, main, options) => {
-    if (delegatedCjs || !parent?.filename) {
+    if (delegatedCjs || !parent?.filename || options?.paths !== undefined) {
       return originalFilename.call(cjs, request, parent, main, options)
     }
     const parentFilename = parent.filename
-    const cacheable = options?.paths === undefined && options?.conditions === undefined
-    const explicitPaths = Array.isArray(options?.paths) ? options.paths : undefined
-    if (explicitPaths !== undefined && router.nativeSelfReference(request, parentFilename)) {
-      return originalFilename.call(cjs, request, parent, main, options)
-    }
-    const explicit = explicitPaths === undefined
-      ? undefined
-      : router.explicitRoute(request, explicitPaths)
-    if (options?.paths !== undefined && explicit === undefined) {
-      return originalFilename.call(cjs, request, parent, main, options)
-    }
-    if (explicit !== undefined && explicitPaths !== undefined && explicit.index > 0) {
-      try {
-        return originalFilename.call(cjs, request, parent, main, {
-          ...options,
-          paths: explicitPaths.slice(0, explicit.index),
-        })
-      } catch (error) {
-        if (!isUnselectedPackageMiss(error)) throw error
-      }
-    }
-    const state = router.routePath(
-      request,
-      explicit?.parent ?? parentFilename,
-      searchPaths => resolveNativeCjs(request, searchPaths, parent, parentFilename, main, options?.conditions),
-      explicit === undefined && cacheable,
-    )
+    const cacheable = options?.conditions === undefined
+    const routedOptions = options?.conditions === undefined ? undefined : { conditions: options.conditions }
+    const state = router.routePath(request, parentFilename, {
+      cacheable,
+      resolveNative: searchPaths => resolveNativeCjs(request, searchPaths, parent, parentFilename, main, options?.conditions),
+      resolveEntry: (entry, after) => {
+        delegatedCjs++
+        try {
+          return resolveRoutedCjs(request, { kind: 'interception', entry, after }, parent, main, routedOptions)
+        } finally {
+          delegatedCjs--
+        }
+      },
+    })
     if (state === undefined) {
-      const scoped = startsWithin(parentFilename, profilePaths)
+      const scoped = router.hasInterceptionLayerForPath(parentFilename)
       const conditions = options?.conditions ?? cjsConditions
       const target = request[0] === '#' && scoped
         ? packageImportsTarget(parentFilename, request, conditions)
@@ -804,52 +870,23 @@ export function installRuntimeInterception(
       if (target === undefined) return originalFilename.call(cjs, request, parent, main, options)
       return resolvePackageImportCjs(target, conditions)
     }
-    if (cacheable && state.cjs !== undefined) return state.cjs
+    if (state.cjs !== undefined) return state.cjs
     const route = state.route
     if (route.kind === 'native') {
       const result = originalFilename.call(cjs, request, parent, main, options)
       if (cacheable) state.cjs = result
       return result
     }
-    if (route.kind === 'native-after-interception' && explicit !== undefined && explicitPaths !== undefined) {
-      try {
-        return originalFilename.call(cjs, request, parent, main, {
-          ...options,
-          paths: [dirname(route.parent)],
-        })
-      } catch (error) {
-        if (!isUnselectedPackageMiss(error)) throw error
-        const remaining = explicitPaths.slice(explicit.index + 1)
-        if (remaining.length === 0) throw error
-        return wrappedFilename(request, parent, main, { ...options, paths: remaining })
-      }
-    }
     delegatedCjs++
     try {
-      const routedOptions = options?.conditions === undefined ? undefined : { conditions: options.conditions }
       let expected: string
       try {
         expected = resolveRoutedCjs(request, route, parent, main, routedOptions)
       } catch (error) {
         if (route.kind !== 'interception' || !isUnselectedPackageMiss(error)) throw error
-        try {
-          expected = resolveRoutedCjs(
-            request, { kind: 'native-after-interception', parent: route.after }, parent, main, routedOptions,
-          )
-        } catch (afterError) {
-          const remaining = explicit === undefined || explicitPaths === undefined
-            ? []
-            : explicitPaths.slice(explicit.index + 1)
-          if (!isUnselectedPackageMiss(afterError) || remaining.length === 0) {
-            throw afterError
-          }
-          delegatedCjs--
-          try {
-            return wrappedFilename(request, parent, main, { ...options, paths: remaining })
-          } finally {
-            delegatedCjs++
-          }
-        }
+        expected = resolveRoutedCjs(
+          request, { kind: 'native-after-interception', parent: route.after }, parent, main, routedOptions,
+        )
       }
       if (cacheable) state.cjs = expected
       return expected
diff --git a/packages/boot/app-boot/src/profile-resolution/service.ts b/packages/boot/app-boot/src/profile-resolution/service.ts
index fad03a2582..5523b51eaf 100644
--- a/packages/boot/app-boot/src/profile-resolution/service.ts
+++ b/packages/boot/app-boot/src/profile-resolution/service.ts
@@ -75,8 +75,9 @@ export class PluginPackages extends Service {
   }
 
   /**
-   * Publish an additive successor generation for this process and subsequently created Workers.
-   * @param successor - fully constructed successor generation.
+   * Publish a complete successor generation for this process and subsequently created Workers.
+   * Linked roots may be removed without unloading modules or clearing Node caches.
+   * @param successor - fully constructed generation accepted by {@link RuntimeInterception.replace}.
    */
   replace(successor: RuntimeResolution): void {
     if (this.interception === undefined) throw new Error('plugin-packages: runtime resolution is not installed')
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index dec0f4b13c..c377b57438 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -7,10 +7,11 @@
  * `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml`
  * (the user's own patch layer, applied after every bundle layer). Bundles are
  * npm packages whose manifest declares
- * `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the tree is
- * composed by applying each bundle's patch list in `dsh.profile.bundles` order over
- * an empty entry list, then the profile's own patches, then any launcher
- * layers (`--patch` files and flag-derived patches).
+ * `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` (one file, or an
+ * ordered list of files); the tree is composed by applying each bundle's patch
+ * lists in `dsh.profile.bundles` order over an empty entry list, then the
+ * profile's own patches, then any launcher layers (`--patch` files and
+ * flag-derived patches).
  *
  * Module resolution is two-anchor by construction: a bundle name resolves
  * first from the dsh installation (the launcher's own package), then from the
@@ -21,12 +22,12 @@
  */
 
 import { createRequire } from 'node:module'
-import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join, resolve, sep } from 'node:path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import { applyEntryPatches, type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
-import type { DshPackageManifest } from '@deepseek-ai/dsh-package-manifest'
+import type { DshBundleManifest, DshPackageManifest } from '@deepseek-ai/dsh-package-manifest'
 import { loadOverlayPatches } from './index.ts'
 import { realModuleDirectory } from './profile-resolution/legacy-links.ts'
 
@@ -45,15 +46,41 @@ export interface ProfileTemplate {
 /** Package metadata accepted by the profile reader; local profiles need no published identity. */
 export type ProfileManifest = Partial<DshPackageManifest>
 
+/**
+ * The patch files a bundle declares, as written: one file for a string
+ * `patch`, the listed files in order for an array.
+ * @param bundle - the bundle's `dsh.bundle` declaration, as read from package.json.
+ * @returns the package-relative patch file paths in application order.
+ * @throws {Error} when `patch` is neither a string nor a list of strings.
+ */
+export function bundlePatchFiles(bundle: DshBundleManifest): string[] {
+  const declared = typeof bundle.patch === 'string' ? [bundle.patch] : bundle.patch
+  if (!Array.isArray(declared) || !declared.every(file => typeof file === 'string')) {
+    throw new Error('dsh.bundle.patch must be a file path or a list of file paths')
+  }
+  return declared
+}
+
+/**
+ * Resolve a bundle declaration to its ordered absolute patch files.
+ * @param packageDir - absolute directory of the bundle package.
+ * @param bundle - the bundle's `dsh.bundle` declaration, as read from package.json.
+ * @returns the absolute patch file paths in application order.
+ * @throws {Error} when `patch` is neither a string nor a list of strings.
+ */
+export function bundlePatchPaths(packageDir: string, bundle: DshBundleManifest): string[] {
+  return bundlePatchFiles(bundle).map(file => join(packageDir, file))
+}
+
 /** One resolved bundle layer of a profile. */
 export interface ProfileLayer {
   /** The bundle's package name, as listed in `dsh.profile.bundles`. */
   packageName: string
   /** Absolute directory of the resolved bundle package. */
   packageDir: string
-  /** Absolute path of the bundle's patch file. */
-  patchPath: string
-  /** The parsed patch list. */
+  /** Absolute paths of the bundle's patch files, in application order. */
+  patchPaths: readonly string[]
+  /** The parsed patch lists of every file, concatenated in application order. */
   patches: PatchOptions[]
 }
 
@@ -85,6 +112,17 @@ export interface RuntimeResolutionEntry {
   readonly scope: 'installation' | 'profile'
 }
 
+/**
+ * A profile node_modules entry linked to a directory outside the shared profiles tree and the active profile.
+ * Importers below `realPath` use Node's real ancestor chain, with peer mappings read at each node_modules position.
+ */
+export interface LinkedRoot {
+  /** Package name of the profile `node_modules` entry, including its scope. */
+  readonly name: string
+  /** Real directory outside the shared profiles tree and active profile; a package.json is optional. */
+  readonly realPath: string
+}
+
 /** Complete immutable package table for one profile launch. */
 export interface RuntimeResolution {
   /** Directory containing every profile; its node_modules is the interception layer. */
@@ -95,6 +133,8 @@ export interface RuntimeResolution {
   readonly localPackageNames: readonly string[]
   /** Installation-scope entries followed by profile-scope entries in precedence order. */
   readonly entries: readonly RuntimeResolutionEntry[]
+  /** Active profile links to external directories, sorted by name. */
+  readonly linkedRoots: readonly LinkedRoot[]
 }
 
 /**
@@ -231,6 +271,40 @@ function symlinksUnder(modules: string): string[] {
   return links
 }
 
+/**
+ * Active profile `node_modules` entries linked outside the shared profiles tree and the active profile.
+ * Missing targets and files are not linked roots; invalid link chains retain Node's diagnostic.
+ */
+function linkedProfileRoots(profile: Profile, profilesDir: string): LinkedRoot[] {
+  const modules = join(profile.dir, 'node_modules')
+  const links = symlinksUnder(modules)
+  if (links.length === 0) return []
+  let tree: string
+  try {
+    tree = realModuleDirectory(profilesDir) + sep
+  } catch (error) {
+    // A profiles tree that is not materialized yet holds no links.
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    tree = resolve(profilesDir) + sep
+  }
+  const excludedTrees = [tree, realModuleDirectory(profile.dir) + sep]
+  const roots: LinkedRoot[] = []
+  for (const linkPath of links) {
+    let realPath: string
+    try {
+      realPath = realModuleDirectory(linkPath)
+    } catch (error) {
+      // A dangling link is not a package Node can load from the profile.
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      continue
+    }
+    if (excludedTrees.some(prefix => realPath + sep === prefix || realPath.startsWith(prefix))
+      || !statSync(realPath).isDirectory()) continue
+    roots.push({ name: relative(modules, linkPath).split(sep).join('/'), realPath })
+  }
+  return roots.sort((left, right) => left.name.localeCompare(right.name))
+}
+
 /** Whether a symlink's target directory is `root` or lies below it. */
 function pointsInto(link: string, root: string): boolean {
   try {
@@ -341,11 +415,13 @@ export async function createRuntimeResolution(
   const profilePackages: ReadonlyMap<string, string> = profile === undefined
     ? new Map<string, string>()
     : collectProfileScopePackages(profile, packageNames, profileDeclarers, profileVersions)
+  const linkedRoots = profile === undefined ? [] : linkedProfileRoots(profile, profilesDir)
   // The Promise return type is the pre-stable API; construction has no asynchronous step.
   return await Promise.resolve(Object.freeze({
     profilesDir,
     profileDir: profile?.dir,
     localPackageNames: Object.freeze(localPackageNames),
+    linkedRoots: Object.freeze(linkedRoots.map(root => Object.freeze(root))),
     entries: Object.freeze([
       ...[...packageDirs].map(([name, packageDir]) => Object.freeze({
         name, packageDir, version: versions.get(name),
@@ -567,12 +643,13 @@ export function loadProfileDirectory(
     try {
       const packageDir = resolveBundleDir(binName, packageName, installAnchor, dir)
       const bundleManifest = readProfileManifest(binName, packageDir)
-      const declared = bundleManifest.dsh?.bundle?.patch
-      if (declared === undefined) {
+      const bundle = bundleManifest.dsh?.bundle
+      if (bundle === undefined) {
         throw new Error(`${binName}: profile bundle ${JSON.stringify(packageName)} declares no dsh.bundle in its package.json`)
       }
-      const patchPath = join(packageDir, declared)
-      layers.push({ packageName, packageDir, patchPath, patches: loadOverlayPatches(binName, patchPath) })
+      const patchPaths = bundlePatchPaths(packageDir, bundle)
+      const patches = patchPaths.flatMap(patchPath => loadOverlayPatches(binName, patchPath))
+      layers.push({ packageName, packageDir, patchPaths, patches })
     } catch (error) {
       process.stderr.write(`${binName}: skipping profile bundle ${JSON.stringify(packageName)}: ${String(error)}\n`)
     }
diff --git a/packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts b/packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts
new file mode 100644
index 0000000000..624eb7ae98
--- /dev/null
+++ b/packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts
@@ -0,0 +1,644 @@
+/** Differential regressions for Node lookup with peer mappings at each linked importer's ancestor position. */
+
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createRuntimeResolution, type Profile } from '../src/profile.ts'
+import { barePackageName, installRuntimeInterception } from '../src/profile-resolution/resolver.ts'
+
+type Layout = 'single-flat' | 'single-pnpm' | 'pnpm-monorepo'
+type Method = 'esm-resolve' | 'esm-meta-resolve' | 'esm-import' | 'cjs-resolve' | 'cjs-require' | 'cjs-paths' | 'metadata'
+type Importer = 'root' | 'source' | 'nested' | 'pnpm-helper'
+type Source = 'runtime' | 'local' | 'parent' | 'workspace' | 'profile' | 'private'
+type ManifestState = 'absent' | 'plain' | 'peer'
+type ModulesState = 'absent' | 'empty' | 'target'
+
+interface DirectoryState {
+  manifest: ManifestState
+  modules: ModulesState
+}
+
+interface PeerProjection {
+  directory: string
+  peerMatches: boolean
+  physicalModules: boolean
+  physicalTarget: boolean
+  projected: boolean
+}
+
+interface MatrixCase {
+  id: string
+  family: string
+  layout: Layout
+  name: string
+  inRuntime: boolean
+  declarations: number
+  copies: number
+  importer: Importer
+  workspaceDeclarations?: number
+  helperDeclarations?: number
+  variant?: string
+  rawPeers?: unknown
+  request?: string
+  explicitStart?: 'profile'
+  comparison?: { start: DirectoryState; parent: DirectoryState; grandparent?: DirectoryState }
+  legacy?: { missingSubpaths: readonly Source[] }
+}
+
+interface Observation {
+  selected: string
+  path?: string
+  code?: string
+  message?: string
+  sameRuntimeInstance?: boolean
+  exists?: boolean
+}
+
+interface MatrixRow {
+  scenario: MatrixCase
+  declarationText: string
+  copiesText: string
+  importerPath: string
+  linkedRoots: string[]
+  methods: Record<Method, Observation>
+  comparison?: {
+    native: Record<Method, Observation>
+    reference: Record<Method, Observation>
+    peerProjection: readonly PeerProjection[]
+  }
+}
+
+interface ProbeModule {
+  source: string
+  token: object
+}
+
+interface ResolveProbeModule {
+  locate(specifier: string): string
+}
+
+interface NativeLoader {
+  getOrCreateModuleJob?: unknown
+  import<T = ProbeModule>(specifier: string, parent: string, attributes: ImportAttributes): Promise<T>
+  resolveSync(
+    first: string,
+    second: string | { specifier: string; attributes: ImportAttributes },
+    attributes?: ImportAttributes,
+  ): { url: string }
+}
+
+const requireHere = createRequire(import.meta.url)
+const nativeModule = requireHere('node:module') as { _initPaths(): void }
+const originalNodePath = process.env.NODE_PATH
+const addon = requireHere('node-addon-require-builtin') as { requireBuiltin(id: string): unknown }
+const loaderModule = addon.requireBuiltin('internal/modules/esm/loader') as {
+  getOrInitializeCascadedLoader(): NativeLoader
+}
+const loader = loaderModule.getOrInitializeCascadedLoader()
+const methods: readonly Method[] = ['esm-resolve', 'esm-meta-resolve', 'esm-import', 'cjs-resolve', 'cjs-require', 'cjs-paths', 'metadata']
+const layouts: readonly Layout[] = ['single-flat', 'single-pnpm', 'pnpm-monorepo']
+// These are real request spellings; each fixture supplies its own package implementations.
+const names = ['@deepseek-ai/dsh-tools', 'react'] as const
+const copyBits: readonly [Source, number][] = [
+  ['local', 1], ['parent', 2], ['profile', 4], ['private', 8], ['workspace', 16],
+]
+const rows: MatrixRow[] = []
+let fixtureSequence = 0
+
+// pnpm's launcher adds repository packages to NODE_PATH; fixtures must supply their own copies.
+beforeAll(() => {
+  delete process.env.NODE_PATH
+  nativeModule._initPaths()
+})
+afterAll(() => {
+  if (originalNodePath === undefined) delete process.env.NODE_PATH
+  else process.env.NODE_PATH = originalNodePath
+  nativeModule._initPaths()
+})
+
+function declarationFields(name: string, bits: number): Record<string, unknown> {
+  return {
+    ...(bits & 1 ? { dependencies: { [name]: '*' } } : {}),
+    ...(bits & 2 ? { devDependencies: { [name]: '*' } } : {}),
+    ...(bits & 4 ? { peerDependencies: { [name]: '*' } } : {}),
+  }
+}
+
+function declarations(bits: number): string {
+  return [[1, 'dependency'], [2, 'dev'], [4, 'peer']]
+    .filter(([bit]) => bits & Number(bit)).map(([, name]) => name).join('+') || 'none'
+}
+
+function copies(bits: number): string {
+  return copyBits.filter(([, bit]) => bits & bit).map(([name]) => name).join('+') || 'none'
+}
+
+function matrixCases(): MatrixCase[] {
+  const cases: MatrixCase[] = []
+  for (const layout of layouts) {
+    for (const name of names) {
+      for (const inRuntime of [false, true]) {
+        for (let declarations = 0; declarations < 8; declarations++) {
+          for (let copies = 0; copies < 8; copies++) {
+            cases.push({ id: '', family: 'root', layout, name, inRuntime, declarations, copies, importer: 'root' })
+          }
+        }
+      }
+    }
+  }
+  for (const layout of layouts) {
+    for (const name of names) {
+      for (const inRuntime of [false, true]) {
+        for (let declarations = 0; declarations < 8; declarations++) {
+          for (const importer of ['source', 'nested', 'pnpm-helper'] as const) {
+            for (const copies of [8, 9, 10, 11, 16, 17, 31]) {
+              cases.push({ id: '', family: 'placement', layout, name, inRuntime, declarations, copies, importer })
+            }
+          }
+        }
+      }
+    }
+  }
+  for (const name of names) {
+    for (const inRuntime of [false, true]) {
+      for (let declarations = 0; declarations < 8; declarations++) {
+        for (let workspaceDeclarations = 0; workspaceDeclarations < 8; workspaceDeclarations++) {
+          for (const copies of [1, 16, 17]) {
+            cases.push({ id: '', family: 'workspace-declaration', layout: 'pnpm-monorepo', name,
+              inRuntime, declarations, workspaceDeclarations, copies, importer: 'root' })
+          }
+        }
+      }
+    }
+  }
+  for (const layout of layouts) {
+    for (const name of names) {
+      for (const inRuntime of [false, true]) {
+        for (const [variant, rawPeers] of [
+          ['peer-null', null], ['peer-array', [name]], ['peer-string', name],
+          ['peer-empty', {}], ['wrong-field', {}], ['peer-range-mismatch', { [name]: '^999.0.0' }],
+        ] as const) {
+          for (const copies of [1, 19]) {
+            cases.push({ id: '', family: 'malformed-declaration', layout, name, inRuntime,
+              declarations: 2, copies, importer: 'root', variant, rawPeers })
+          }
+        }
+        for (const declarations of [2, 6]) {
+          for (const request of ['#target', `${name}/sub`, `${name}/private`, `${name}/missing`]) {
+            for (const copies of [1, 3]) {
+              cases.push({ id: '', family: 'request-form', layout, name, inRuntime,
+                declarations, copies, importer: 'root', request })
+            }
+          }
+        }
+        for (const importer of ['nested', 'pnpm-helper'] as const) {
+          for (const declarations of [2, 6]) {
+            for (const helperDeclarations of [2, 6]) {
+              for (const copies of [1, 9]) {
+                cases.push({ id: '', family: 'helper-declaration', layout, name, inRuntime,
+                  declarations, helperDeclarations, copies, importer })
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  const parents: readonly DirectoryState[] = [
+    { manifest: 'absent', modules: 'absent' },
+    { manifest: 'absent', modules: 'target' },
+    { manifest: 'plain', modules: 'target' },
+    { manifest: 'peer', modules: 'absent' },
+    { manifest: 'peer', modules: 'target' },
+  ]
+  let comparisonId = 0
+  for (const layout of ['single-flat', 'pnpm-monorepo'] as const) {
+    for (const name of names) {
+      for (const inRuntime of [false, true]) {
+        for (const startManifest of ['absent', 'plain', 'peer'] as const) {
+          for (const startModules of ['absent', 'empty', 'target'] as const) {
+            for (const parent of parents) {
+              cases.push({ id: `N${String(++comparisonId).padStart(4, '0')}`, family: 'node-comparison', layout, name,
+                inRuntime, declarations: startManifest === 'peer' ? 4 : 0, copies: 0, importer: 'root',
+                comparison: { start: { manifest: startManifest, modules: startModules }, parent } })
+            }
+          }
+        }
+        for (const importer of ['root', 'source'] as const) {
+          for (const request of [name, `${name}/sub`, `${name}/missing`, `${name}/private`]) {
+            for (const startModules of ['absent', 'target'] as const) {
+              cases.push({ id: `N${String(++comparisonId).padStart(4, '0')}`, family: 'node-comparison-files', layout, name,
+                inRuntime, declarations: 0, copies: 0, importer, request,
+                comparison: { start: { manifest: 'absent', modules: startModules },
+                  parent: { manifest: 'plain', modules: 'absent' },
+                  grandparent: { manifest: 'peer', modules: 'target' } } })
+            }
+          }
+        }
+      }
+    }
+  }
+  for (const layout of ['single-flat', 'pnpm-monorepo'] as const) {
+    for (const name of names) {
+      for (const inRuntime of [false, true]) {
+        for (const copies of [0, 4]) {
+          cases.push({ id: `N${String(++comparisonId).padStart(4, '0')}`, family: 'node-comparison-explicit', layout,
+            name, inRuntime, declarations: 4, copies, importer: 'root', explicitStart: 'profile',
+            comparison: { start: { manifest: 'peer', modules: 'target' },
+              parent: { manifest: 'absent', modules: 'absent' } } })
+        }
+      }
+    }
+  }
+  const legacyCases: readonly { start: ManifestState; parent: ManifestState; missingSubpaths: readonly Source[] }[] = [
+    { start: 'peer', parent: 'peer', missingSubpaths: [] },
+    { start: 'peer', parent: 'plain', missingSubpaths: ['runtime'] },
+    { start: 'plain', parent: 'peer', missingSubpaths: ['runtime', 'local'] },
+    { start: 'peer', parent: 'peer', missingSubpaths: ['runtime'] },
+    { start: 'plain', parent: 'peer', missingSubpaths: ['local'] },
+    { start: 'peer', parent: 'peer', missingSubpaths: ['runtime', 'workspace'] },
+  ]
+  let legacyId = 0
+  for (const layout of layouts) {
+    for (const name of names) {
+      for (const inRuntime of [false, true]) {
+        for (const entry of legacyCases) {
+          for (const request of [name, `${name}/sub.cjs`, `${name}/missing.cjs`]) {
+            cases.push({ id: `L${String(++legacyId).padStart(4, '0')}`, family: 'node-legacy', layout, name,
+              inRuntime, declarations: 0, copies: 0, importer: 'root', request,
+              variant: `missing-sub:${entry.missingSubpaths.join('+') || 'none'}`, legacy: entry,
+              comparison: { start: { manifest: entry.start, modules: 'target' },
+                parent: { manifest: entry.parent, modules: 'target' },
+                grandparent: { manifest: 'plain', modules: 'target' } } })
+          }
+        }
+      }
+    }
+  }
+  return cases.map((value, index) => ({ ...value, id: value.id || `M${String(index + 1).padStart(4, '0')}` }))
+}
+
+function put(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, content)
+}
+
+function manifest(path: string, content: Record<string, unknown>): void {
+  put(join(path, 'package.json'), JSON.stringify(content) + '\n')
+}
+
+class MatrixFixture {
+  // Node keeps resolved paths and modules after cleanup; no fixture may reuse an earlier fixture's path.
+  readonly root = realpathSync.native(mkdtempSync(join(tmpdir(), `dsh-linked-matrix-${++fixtureSequence}-`)))
+  readonly home = join(this.root, 'home')
+  readonly profileDir = join(this.home, 'profiles', 'web')
+  readonly workspace = join(this.root, 'work', 'workspace')
+  readonly packageDir: string
+  readonly sources = new Map<string, Source>()
+  readonly importerDir: string
+  readonly installDir = join(this.root, 'installation', 'node_modules', '@deepseek-ai', 'dsh')
+  readonly runtimeDir: string
+  readonly peerProjection: PeerProjection[] = []
+
+  constructor(readonly scenario: MatrixCase) {
+    this.packageDir = scenario.layout === 'pnpm-monorepo'
+      ? join(this.workspace, 'packages', 'my-plugin')
+      : join(this.root, 'work', 'my-plugin')
+    const storeOwner = scenario.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir
+    const helper = join(storeOwner, 'node_modules', '.pnpm', 'helper@1.0.0', 'node_modules', 'helper')
+    this.importerDir = scenario.importer === 'source' ? join(this.packageDir, 'src')
+      : scenario.importer === 'nested' ? join(this.packageDir, 'node_modules', 'nested-helper')
+        : scenario.importer === 'pnpm-helper' ? helper : this.packageDir
+    this.runtimeDir = join(this.installDir, 'node_modules', scenario.name)
+  }
+
+  setup(): void {
+    const value = this.scenario
+    manifest(this.installDir, {
+      name: '@deepseek-ai/dsh', version: '1.0.0',
+      dependencies: value.inRuntime ? { [value.name]: '*' } : {},
+    })
+    if (value.inRuntime) this.package(this.runtimeDir, 'runtime')
+    manifest(this.profileDir, { name: 'matrix-profile', private: true, dependencies: { 'my-plugin': '*' } })
+    if (value.layout === 'pnpm-monorepo') {
+      manifest(this.workspace, { name: 'matrix-workspace', private: true,
+        ...declarationFields(value.name, value.workspaceDeclarations ?? 0) })
+      put(join(this.workspace, 'pnpm-workspace.yaml'), "packages:\n  - 'packages/*'\n")
+    }
+    const fields = declarationFields(value.name, value.declarations)
+    if (Object.hasOwn(value, 'rawPeers')) fields.peerDependencies = value.rawPeers
+    if (value.variant === 'wrong-field') {
+      delete fields.peerDependencies
+      fields.peerDependecies = { [value.name]: '*' }
+    }
+    manifest(this.packageDir, { name: 'my-plugin', version: '1.0.0', type: 'module',
+      exports: { import: './index.mjs', require: './index.cjs' }, imports: { '#target': value.name }, ...fields })
+    put(join(this.packageDir, 'index.mjs'), 'export const plugin = true\n')
+    put(join(this.packageDir, 'index.cjs'), 'exports.plugin = true\n')
+    if (this.importerDir !== this.packageDir) {
+      if (value.importer !== 'source') manifest(this.importerDir, { name: 'matrix-helper', type: 'module',
+        ...declarationFields(value.name, value.helperDeclarations ?? 4) })
+      put(join(this.importerDir, 'probe.mjs'), 'export {}\n')
+      put(join(this.importerDir, 'probe.cjs'), '')
+    }
+    const profileLink = join(this.profileDir, 'node_modules', 'my-plugin')
+    this.link(this.packageDir, profileLink)
+    if (value.importer === 'pnpm-helper') this.link(this.importerDir, join(this.packageDir, 'node_modules', 'helper'))
+    if (value.layout !== 'single-flat') {
+      const storeOwner = value.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir
+      put(join(storeOwner, 'node_modules', '.modules.yaml'), 'nodeLinker: isolated\nvirtualStoreDir: .pnpm\n')
+    }
+    if (value.copies & 1) {
+      const local = join(this.packageDir, 'node_modules', value.name)
+      if (value.layout === 'single-flat') this.package(local, 'local')
+      else {
+        const storeOwner = value.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir
+        const target = join(storeOwner, 'node_modules', '.pnpm', `${value.name.replaceAll('/', '+')}@2.0.0`, 'node_modules', value.name)
+        this.package(target, 'local')
+        this.link(target, local)
+      }
+    }
+    if (value.copies & 2) this.package(join(dirname(this.packageDir), 'node_modules', value.name), 'parent')
+    if (value.copies & 4) this.package(join(this.profileDir, 'node_modules', value.name), 'profile')
+    if (value.copies & 8) {
+      if (value.importer === 'pnpm-helper') {
+        const storeOwner = value.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir
+        const target = join(storeOwner, 'node_modules', '.pnpm', `${value.name.replaceAll('/', '+')}@6.0.0`, 'node_modules', value.name)
+        this.package(target, 'private')
+        this.link(target, join(dirname(this.importerDir), value.name))
+      } else this.package(join(this.importerDir, 'node_modules', value.name), 'private')
+    }
+    if (value.copies & 16) this.package(join(this.workspace, 'node_modules', value.name), 'workspace')
+    if (value.comparison !== undefined) {
+      this.configureDirectory(this.importerDir, value.comparison.start, 'local')
+      this.configureDirectory(dirname(this.importerDir), value.comparison.parent, 'parent')
+      if (value.comparison.grandparent !== undefined) {
+        this.configureDirectory(dirname(dirname(this.importerDir)), value.comparison.grandparent, 'workspace')
+      }
+    }
+    put(join(this.importerDir, 'entry-query.mjs'), 'export function locate(specifier) { return import.meta.resolve(specifier) }\n')
+  }
+
+  private configureDirectory(directory: string, state: DirectoryState, source: Source): void {
+    if (state.manifest === 'absent') rmSync(join(directory, 'package.json'), { force: true })
+    else manifest(directory, { name: `matrix-${source}`, type: 'module',
+      ...(state.manifest === 'peer' ? { peerDependencies: { [this.scenario.name]: '*' } } : {}) })
+    const modules = join(directory, 'node_modules')
+    // All configured directories are inside this fixture and are changed before any module is resolved.
+    if (state.modules === 'absent') rmSync(modules, { recursive: true, force: true })
+    else {
+      mkdirSync(modules, { recursive: true })
+      if (state.modules === 'target') this.package(join(modules, this.scenario.name), source)
+    }
+  }
+
+  /** Only the reference fixture materializes peer positions; the product resolver is not replaced. */
+  projectPeerPositions(): void {
+    // A hoisted monorepo helper outside the recorded linked directory remains native.
+    if (this.importerDir !== this.packageDir && !this.importerDir.startsWith(this.packageDir + sep)) return
+    const paths = createRequire(join(this.importerDir, 'probe.cjs')).resolve.paths(this.scenario.name) ?? []
+    for (const modules of paths) {
+      if (!modules.startsWith(this.root + sep)) continue
+      const directory = dirname(modules)
+      const manifestPath = join(directory, 'package.json')
+      const info = existsSync(manifestPath)
+        ? JSON.parse(readFileSync(manifestPath, 'utf8')) as { peerDependencies?: Record<string, string> } : {}
+      const peerMatches = Object.hasOwn(info.peerDependencies ?? {}, this.scenario.name)
+      const target = join(modules, this.scenario.name)
+      const projected = peerMatches && this.scenario.inRuntime
+      this.peerProjection.push({ directory: relative(this.root, directory).split(sep).join('/'), peerMatches,
+        physicalModules: existsSync(modules), physicalTarget: existsSync(target), projected })
+      if (!projected) continue
+      const entry = lstatSync(target, { throwIfNoEntry: false })
+      if (entry?.isSymbolicLink()) unlinkSync(target)
+      else if (entry !== undefined) rmSync(target, { recursive: true })
+      this.link(this.runtimeDir, target)
+    }
+  }
+
+  private nativePackageDir(request: string, parent: string): string | undefined {
+    const name = barePackageName(request)
+    if (name === undefined) return undefined
+    for (const modules of createRequire(parent).resolve.paths(name) ?? []) {
+      const directory = join(modules, name)
+      if (existsSync(join(directory, 'package.json'))) return directory
+    }
+    return undefined
+  }
+
+  private package(dir: string, source: Source): void {
+    manifest(dir, { name: this.scenario.name, version: '2.0.0', type: 'module',
+      ...this.scenario.legacy === undefined ? { exports: { '.': { import: './index.mjs', require: './index.cjs' },
+        './sub': { import: './sub.mjs', require: './sub.cjs' },
+        './missing': { import: './missing.mjs', require: './missing.cjs' } } } : { main: './index.cjs' } })
+    for (const stem of ['index', 'sub']) {
+      if (stem === 'sub' && this.scenario.legacy?.missingSubpaths.includes(source)) continue
+      put(join(dir, `${stem}.mjs`), `export const source = ${JSON.stringify(source)}\nexport const token = {}\n`)
+      put(join(dir, `${stem}.cjs`), `exports.source = ${JSON.stringify(source)}\nexports.token = {}\n`)
+    }
+    this.sources.set(realpathSync.native(dir), source)
+  }
+
+  private link(target: string, path: string): void {
+    mkdirSync(dirname(path), { recursive: true })
+    symlinkSync(target, path, process.platform === 'win32' ? 'junction' : 'dir')
+    // import.meta.resolve retains the logical symlink spelling for missing exported files.
+    const source = this.sources.get(realpathSync.native(target))
+    if (source !== undefined) this.sources.set(path, source)
+  }
+
+  private classify(path: string): Observation {
+    const exists = existsSync(path)
+    const canonical = exists ? realpathSync.native(path) : resolve(path)
+    for (const [directory, selected] of this.sources) {
+      if (canonical === directory || canonical.startsWith(directory + sep)) {
+        return { selected, exists, path: relative(this.root, canonical).split(sep).join('/') }
+      }
+    }
+    return { selected: 'external', exists, path: canonical }
+  }
+
+  private failed(error: unknown): Observation {
+    const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
+      ? error.code : error instanceof Error ? error.name : 'UNKNOWN'
+    const message = error instanceof Error ? error.message : String(error)
+    return { selected: 'error', code, message: message.replaceAll(this.root, '<fixture>') }
+  }
+
+  async observe(mode: 'current' | 'native' = 'current'): Promise<MatrixRow> {
+    const profile: Profile = { name: 'web', dir: this.profileDir, layers: [],
+      patchPath: join(this.profileDir, 'cordis.patch.yml'), patches: [] }
+    const resolution = mode === 'current'
+      ? await createRuntimeResolution({ installAnchor: join(this.installDir, 'package.json'), profile, home: this.home }) : undefined
+    expect(realpathSync.native(join(this.profileDir, 'node_modules', 'my-plugin'))).toBe(this.packageDir)
+    const registration = resolution === undefined ? undefined : installRuntimeInterception(resolution)
+    try {
+      const request = this.scenario.request ?? this.scenario.name
+      const parent = pathToFileURL(join(this.importerDir, 'probe.mjs')).href
+      const require = createRequire(join(this.importerDir, 'probe.cjs'))
+      const query = await loader.import<ResolveProbeModule>(pathToFileURL(join(this.importerDir, 'entry-query.mjs')).href, parent, {})
+      const esmResolve = (): string => 'getOrCreateModuleJob' in loader
+        ? loader.resolveSync(parent, { specifier: request, attributes: {} }).url
+        : loader.resolveSync(request, parent, {}).url
+      const runtimeEntry = (extension: 'mjs' | 'cjs'): string => join(this.runtimeDir,
+        `${request.endsWith('/sub') || request.endsWith('/sub.cjs') ? 'sub' : 'index'}.${this.scenario.legacy === undefined ? extension : 'cjs'}`)
+      const observe = async (method: Method): Promise<Observation> => {
+        try {
+          if (method === 'metadata') {
+            const path = registration === undefined ? this.nativePackageDir(request, parent) : registration.packageDir(request, parent)
+            return path === undefined ? { selected: 'missing' } : this.classify(path)
+          }
+          const path = method === 'esm-meta-resolve' ? fileURLToPath(query.locate(request))
+            : method.startsWith('esm') ? fileURLToPath(esmResolve())
+              : method === 'cjs-paths' ? require.resolve(request, {
+                paths: [this.scenario.explicitStart === 'profile' ? this.profileDir : this.importerDir],
+              }) : require.resolve(request)
+          const result = this.classify(path)
+          // A real host package is not fixture evidence and must never be evaluated by this probe.
+          if (result.selected === 'external') return result
+          if (method === 'esm-import') {
+            const loaded = await loader.import(request, parent, {})
+            result.selected = loaded.source
+            if (this.scenario.inRuntime) {
+              const entry = runtimeEntry('mjs')
+              result.sameRuntimeInstance = existsSync(entry)
+                && loaded.token === (await loader.import(pathToFileURL(entry).href, parent, {})).token
+            }
+          } else if (method === 'cjs-require') {
+            const loaded = require(request) as ProbeModule
+            result.selected = loaded.source
+            if (this.scenario.inRuntime) {
+              const entry = runtimeEntry('cjs')
+              result.sameRuntimeInstance = existsSync(entry) && loaded.token === (require(entry) as ProbeModule).token
+            }
+          }
+          return result
+        } catch (error) { return this.failed(error) }
+      }
+      const answers = {} as Record<Method, Observation>
+      for (const method of methods) answers[method] = await observe(method)
+      return { scenario: this.scenario, declarationText: declarations(this.scenario.declarations),
+        copiesText: copies(this.scenario.copies), importerPath: relative(this.root, this.importerDir).split(sep).join('/'),
+        linkedRoots: resolution?.linkedRoots.map(root => relative(this.root, root.realPath).split(sep).join('/')) ?? [],
+        methods: answers }
+    } finally { registration?.dispose() }
+  }
+
+  dispose(): void { rmSync(this.root, { recursive: true, force: true }) }
+}
+
+function outcome(value: Observation): string {
+  return value.code ?? `${value.selected}${value.exists === false ? ':path-absent' : ''}`
+}
+
+function comparable(value: Observation): object {
+  return { outcome: outcome(value), sameRuntimeInstance: value.sameRuntimeInstance,
+    ...(value.exists ? { path: value.path } : {}) }
+}
+
+function writeNodeComparison(output: string, selected: readonly MatrixRow[]): void {
+  const records = selected.flatMap((row) => {
+    const comparison = row.comparison
+    const directories = row.scenario.comparison
+    if (comparison === undefined) return []
+    return methods.map(method => ({
+      id: row.scenario.id, layout: row.scenario.layout, name: row.scenario.name,
+      inRuntime: row.scenario.inRuntime, request: row.scenario.request ?? row.scenario.name,
+      importer: row.scenario.importer, startManifest: directories?.start.manifest ?? row.declarationText,
+      explicitStart: row.scenario.explicitStart ?? 'importer',
+      startModules: directories?.start.modules ?? row.copiesText, parentManifest: directories?.parent.manifest ?? 'layout',
+      parentModules: directories?.parent.modules ?? 'layout', grandparentManifest: directories?.grandparent?.manifest ?? 'layout',
+      grandparentModules: directories?.grandparent?.modules ?? 'layout', method,
+      native: outcome(comparison.native[method]), current: outcome(row.methods[method]),
+      peerReference: outcome(comparison.reference[method]),
+      currentMatchesReference: JSON.stringify(comparable(row.methods[method])) === JSON.stringify(comparable(comparison.reference[method])),
+    }))
+  })
+  if (records.length === 0) return
+  const columns = ['id', 'layout', 'name', 'inRuntime', 'request', 'importer', 'explicitStart', 'startManifest', 'startModules',
+    'parentManifest', 'parentModules', 'grandparentManifest', 'grandparentModules', 'method',
+    'native', 'current', 'peerReference', 'currentMatchesReference'] as const
+  const csv = [columns.join(','), ...records.map(record => columns.map(column => JSON.stringify(String(record[column]))).join(','))]
+  writeFileSync(join(output, 'node-comparison.csv'), csv.join('\n') + '\n', { flag: 'wx' })
+  const markdown = [
+    '# Node baseline and peer-position reference', '',
+    'Native, current, and reference runs use independent fixture paths. Only the reference fixture materializes peer mappings before Node resolves them. Explicit paths and importers outside recorded linked directories use the unmodified native behavior. Assertions compare selected packages, existing file paths, failure codes, and runtime module identity.', '',
+    '| ID | Layout | Package | Runtime | Request | Importer | Explicit paths start | JSON here | node_modules here | Parent JSON | Parent node_modules | Method | Native Node | Current DSH | Peer reference | Matches reference |',
+    '|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|',
+    ...records.map(record => `| ${[record.id, record.layout, record.name, record.inRuntime, record.request, record.importer,
+      record.explicitStart, record.startManifest, record.startModules, record.parentManifest, record.parentModules,
+      record.method, record.native, record.current, record.peerReference, record.currentMatchesReference].join(' | ')} |`), '',
+  ]
+  writeFileSync(join(output, 'node-comparison.md'), markdown.join('\n'), { flag: 'wx' })
+}
+
+afterAll(() => {
+  const parent = process.env.DSH_RESOLUTION_MATRIX_REPORT_DIR
+  if (parent === undefined) return
+  mkdirSync(parent, { recursive: true })
+  const output = mkdtempSync(join(resolve(parent), 'run-'))
+  const sorted = [...rows].sort((left, right) => left.scenario.id.localeCompare(right.scenario.id))
+  const csv = [
+    ['id', 'family', 'layout', 'package', 'inRuntime', 'declarations', 'workspaceDeclarations', 'helperDeclarations',
+      'variant', 'request', 'copies', 'importer', ...methods],
+    ...sorted.map(row => [row.scenario.id, row.scenario.family, row.scenario.layout, row.scenario.name,
+      row.scenario.inRuntime, row.declarationText, declarations(row.scenario.workspaceDeclarations ?? 0),
+      declarations(row.scenario.helperDeclarations ?? 4), row.scenario.variant ?? '', row.scenario.request ?? row.scenario.name,
+      row.copiesText, row.importerPath,
+      ...methods.map(method => outcome(row.methods[method]))]),
+  ].map(line => line.map(value => JSON.stringify(String(value))).join(',')).join('\n') + '\n'
+  const sourceHead = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim()
+  writeFileSync(join(output, 'matrix.json'), JSON.stringify({ node: process.versions.node, platform: process.platform,
+    sourceHead, plannedCases: matrixCases().length, observedCases: sorted.length, rule: 'native-node-with-peer-positions',
+    rows: sorted }, null, 2) + '\n', { flag: 'wx' })
+  writeFileSync(join(output, 'matrix.csv'), csv, { flag: 'wx' })
+  writeNodeComparison(output, sorted)
+  const markdown = [
+    '# Linked resolution regression matrix', '',
+    'Every row is checked against native Node with only the matching peer positions replaced by the runtime package. The node-comparison report includes both baselines and the per-operation verdict.', '',
+    '| ID | Family | Layout | Package | Runtime entry | Declaration | Workspace declaration | Helper declaration | Variant | Request | Copies | Importer | ESM resolve | import.meta.resolve | ESM import | CJS resolve | CJS require | CJS paths | Metadata |',
+    '|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|',
+    ...sorted.map(row => `| ${[row.scenario.id, row.scenario.family, row.scenario.layout, row.scenario.name, row.scenario.inRuntime,
+      row.declarationText, declarations(row.scenario.workspaceDeclarations ?? 0), declarations(row.scenario.helperDeclarations ?? 4),
+      row.scenario.variant ?? '', row.scenario.request ?? row.scenario.name, row.copiesText, row.scenario.importer,
+      ...methods.map(method => outcome(row.methods[method]))].join(' | ')} |`),
+    '',
+  ].join('\n')
+  writeFileSync(join(output, 'matrix.md'), markdown, { flag: 'wx' })
+  console.info(`Resolution matrix: ${sorted.length} observations at ${output}`)
+})
+
+describe('linked resolution differential matrix', { concurrent: false }, () => {
+  it.each(matrixCases())('$id $family $layout $name runtime=$inRuntime declarations=$declarations copies=$copies importer=$importer', async (scenario) => {
+    const fixtures: MatrixFixture[] = []
+    try {
+      const baseline = new MatrixFixture(scenario)
+      fixtures.push(baseline)
+      baseline.setup()
+      const native = await baseline.observe('native')
+      const fixture = new MatrixFixture(scenario)
+      fixtures.push(fixture)
+      fixture.setup()
+      const row = await fixture.observe()
+      const reference = new MatrixFixture(scenario)
+      fixtures.push(reference)
+      reference.setup()
+      reference.projectPeerPositions()
+      const projected = await reference.observe('native')
+      // Explicit paths are exempt from the policy and use the pristine native filesystem.
+      projected.methods['cjs-paths'] = native.methods['cjs-paths']
+      row.comparison = { native: native.methods, reference: projected.methods, peerProjection: reference.peerProjection }
+      rows.push(row)
+      if (reference.peerProjection.every(layer => !layer.projected)) expect(projected.methods).toEqual(native.methods)
+      for (const method of methods) {
+        for (const observed of [native, row, projected]) expect(observed.methods[method].selected).not.toBe('external')
+        expect(comparable(row.methods[method]), `${scenario.id}: ${method}`).toEqual(comparable(projected.methods[method]))
+      }
+      expect(Object.keys(row.methods)).toEqual(methods)
+    } finally { for (const fixture of fixtures.reverse()) fixture.dispose() }
+  })
+})
diff --git a/packages/boot/app-boot/tests/package-meta.spec.ts b/packages/boot/app-boot/tests/package-meta.spec.ts
index 07b9af374b..73484f7db9 100644
--- a/packages/boot/app-boot/tests/package-meta.spec.ts
+++ b/packages/boot/app-boot/tests/package-meta.spec.ts
@@ -1,6 +1,6 @@
 /** Plugin locale resources resolve independently of entry execution and package display fields. */
 
-import fs, { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import fs, { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
 import { syncBuiltinESMExports } from 'node:module'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -161,15 +161,122 @@ describe('plugin locale display metadata', () => {
     expect(readPluginMeta('localized', parentURL)?.error).toContain('meta.title must be a non-empty string')
   })
 
-  it('does not inspect package fallback when both English fields are supplied', () => {
-    manifest({ './locale/*.json': './locale/*.json', './package.json': './fallback.json' })
-    file(join(dir, 'fallback.json'), '{')
+  it('reads the manifest icon even when both English fields are supplied', () => {
+    manifest({ './locale/*.json': './locale/*.json', './package.json': './package.json' }, { icon: './art/team.svg' })
+    file(join(dir, 'art', 'team.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>')
     dictionary('en', { meta: { title: 'Plugin', description: 'Locale introduction' } })
     expect(readPluginMeta('localized', parentURL)).toEqual({
       title: { en: 'Plugin' }, description: { en: 'Locale introduction' },
+      icon: `data:image/svg+xml;base64,${Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>').toString('base64')}`,
     })
   })
 
+  it.each([
+    ['svg', 'image/svg+xml'], ['png', 'image/png'], ['jpg', 'image/jpeg'],
+    ['jpeg', 'image/jpeg'], ['webp', 'image/webp'], ['SVG', 'image/svg+xml'],
+  ])('encodes a package-local %s icon without executing the plugin', (extension, mediaType) => {
+    manifest({ '.': './index.js', './package.json': './package.json' }, { icon: `./icon.${extension}` })
+    const bytes = Buffer.from([0, 1, 127, 128, 255])
+    writeFileSync(join(dir, `icon.${extension}`), bytes)
+    expect(readPluginMeta('localized', parentURL)).toEqual({
+      title: 'localized', icon: `data:${mediaType};base64,${bytes.toString('base64')}`,
+    })
+  })
+
+  it('reads an icon-only subexport relative to its own manifest without inheriting the package icon', () => {
+    manifest({ './package.json': './package.json', './search/package.json': './search/manifest.json' }, { icon: './root.png' })
+    file(join(dir, 'root.png'), 'root')
+    file(join(dir, 'search', 'manifest.json'), JSON.stringify({ icon: './icon.webp' }))
+    file(join(dir, 'search', 'icon.webp'), 'search')
+    expect(readPluginMeta('localized/search', parentURL)).toEqual({
+      icon: `data:image/webp;base64,${Buffer.from('search').toString('base64')}`,
+    })
+    expect(readPluginMeta('localized/review', parentURL)).toBeUndefined()
+  })
+
+  it.each([null, false, 1, {}, [], '', '  '])('retains localized text while rejecting malformed icon %j', (icon) => {
+    manifest({ './locale/*.json': './locale/*.json', './package.json': './package.json' }, { icon })
+    dictionary('en', { meta: { title: 'Plugin', description: 'Introduction' } })
+    dictionary('zh', { meta: { title: '插件' } })
+    const { error, ...meta } = readPluginMeta('localized', parentURL)!
+    expect(meta).toEqual({ title: { en: 'Plugin', zh: '插件' }, description: { en: 'Introduction' } })
+    expect(error).toContain('icon must be a non-empty string')
+  })
+
+  it.each(['/tmp/icon.svg', 'C:\\icon.png', 'C:icon.png', '\\\\server\\share\\icon.png', 'https://example.test/icon.svg', 'data:image/svg+xml,<svg/>'])('rejects non-relative icon %s', (icon) => {
+    manifest({ './package.json': './package.json' }, { icon, description: 'Introduction' })
+    const { error, ...meta } = readPluginMeta('localized', parentURL)!
+    expect(meta).toEqual({ title: 'localized', description: 'Introduction' })
+    expect(error).toContain('icon must be a relative file path')
+  })
+
+  it.each(['icon.gif', 'icon.html', 'icon', 'icon.svg?query'])('rejects unsupported icon file %s', (icon) => {
+    manifest({ './package.json': './package.json' }, { icon })
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must be SVG, PNG, JPEG, or WebP')
+  })
+
+  it('reports missing files, directories, and paths outside the manifest directory', () => {
+    manifest({ './package.json': './package.json' }, { icon: './missing.svg' })
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('missing.svg')
+    mkdirSync(join(dir, 'missing.svg'))
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must be a regular file')
+    manifest({ './package.json': './package.json' }, { icon: '../localized-other/icon.svg' })
+    file(join(root, 'node_modules', 'localized-other', 'icon.svg'), 'outside')
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must remain inside its manifest directory')
+  })
+
+  it('accepts an icon at the byte limit and rejects one byte more', () => {
+    manifest({ './package.json': './package.json' }, { icon: './icon.png' })
+    const bytes = Buffer.alloc(256 * 1024)
+    writeFileSync(join(dir, 'icon.png'), bytes)
+    expect(readPluginMeta('localized', parentURL)?.icon).toBe(`data:image/png;base64,${bytes.toString('base64')}`)
+    writeFileSync(join(dir, 'icon.png'), Buffer.alloc(bytes.length + 1))
+    expect(readPluginMeta('localized', parentURL)?.error).toContain('icon exceeds 256 KiB')
+  })
+
+  it('rejects an icon that grows beyond the limit after its size check', () => {
+    manifest({ './package.json': './package.json' }, { icon: './icon.png' })
+    const icon = join(dir, 'icon.png')
+    file(icon, 'small')
+    const original = fs.statSync
+    const stat = vi.spyOn(fs, 'statSync')
+    try {
+      stat.mockImplementation(new Proxy(original, {
+        apply(target, receiver: unknown, args: unknown[]): unknown {
+          const result: unknown = Reflect.apply(target, receiver, args)
+          if (String(args[0]).endsWith(join('localized', 'icon.png'))) writeFileSync(icon, Buffer.alloc(256 * 1024 + 1))
+          return result
+        },
+      }))
+      syncBuiltinESMExports()
+      expect(readPluginMeta('localized', parentURL)?.error).toContain('icon exceeds 256 KiB')
+    } finally {
+      stat.mockRestore()
+      syncBuiltinESMExports()
+    }
+  })
+
+  it('rejects icons reached through an external directory link and accepts internal links', () => {
+    manifest({ './package.json': './package.json' }, { icon: './art/icon.svg' })
+    const outside = join(root, 'outside')
+    file(join(outside, 'icon.svg'), 'outside')
+    const link = join(dir, 'art')
+    symlinkSync(outside, link, 'junction')
+    try {
+      expect(readPluginMeta('localized', parentURL)?.error).toContain('icon must remain inside its manifest directory')
+    } finally {
+      unlinkSync(link)
+    }
+    const inside = join(dir, 'images')
+    file(join(inside, 'icon.svg'), 'inside')
+    symlinkSync(inside, link, 'junction')
+    try {
+      expect(readPluginMeta('localized', parentURL)?.icon).toBe(`data:image/svg+xml;base64,${Buffer.from('inside').toString('base64')}`)
+    } finally {
+      unlinkSync(link)
+    }
+  })
+
   it('keeps separate plugin exports independent even when their JavaScript entries share a directory', () => {
     manifest({
       './search': './lib/search.js', './review': './lib/review.js',
@@ -285,8 +392,9 @@ describe('plugin locale display metadata', () => {
     })
     const specifier = 'localized/locale/en.json'
     expect(resolveSync.mock.calls).toEqual(version === 'v1'
-      ? [[specifier, parentURL, {}], [specifier, parentURL, {}]]
-      : [[parentURL, { specifier, attributes: {} }], [parentURL, { specifier, attributes: {} }]])
+      ? [[specifier, parentURL, {}], [specifier, parentURL, {}], ['localized/package.json', parentURL, {}]]
+      : [[parentURL, { specifier, attributes: {} }], [parentURL, { specifier, attributes: {} }],
+        [parentURL, { specifier: 'localized/package.json', attributes: {} }]])
   })
 
   it('rejects case-equivalent language names in a directory listing', () => {
diff --git a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts
index 1be59df4f1..d066329d36 100644
--- a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts
+++ b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts
@@ -47,6 +47,7 @@ function resolution(
     profilesDir,
     profileDir,
     localPackageNames: [],
+    linkedRoots: [],
     entries: [{ name: 'metadata-lib', packageDir, version, declarer, scope: 'installation' }],
   }
 }
@@ -123,7 +124,7 @@ describe('profile package metadata service', () => {
     expect(ctx.pluginPackages.packageOf('missing-package', parentURL)).toBeUndefined()
     expect(ctx.pluginPackages.packageOf('@scope', parentURL)).toBeUndefined()
     expect(() => { ctx.pluginPackages.replace({
-      profilesDir: join(root, 'profiles'), profileDir: undefined, localPackageNames: [], entries: [],
+      profilesDir: join(root, 'profiles'), profileDir: undefined, localPackageNames: [], linkedRoots: [], entries: [],
     }) }).toThrow(/runtime resolution is not installed/u)
   })
 
@@ -160,6 +161,71 @@ describe('profile package metadata service', () => {
     )).toBeUndefined()
   })
 
+  it('removes and restores linked roots while rejecting changes to their historical targets', async () => {
+    const root = realpathSync.native(mkdtempSync(join(tmpdir(), 'dsh-linked-package-service-')))
+    roots.push(root)
+    const profilesDir = join(root, 'profiles')
+    const profileDir = join(profilesDir, 'test')
+    const runtime = join(root, 'runtime')
+    const runtimeAnchor = pkg(runtime, '1.0.0')
+    const linkedA = join(root, 'work', 'a')
+    const linkedB = join(root, 'work', 'b')
+    for (const dir of [linkedA, linkedB]) {
+      file(join(dir, 'package.json'), JSON.stringify({
+        name: 'linked-plugin', peerDependencies: { 'metadata-lib': '*' },
+      }))
+    }
+    const local = join(linkedA, 'node_modules', 'metadata-lib')
+    pkg(local, '2.0.0')
+    const parentPath = join(linkedA, 'entry.mjs')
+    file(parentPath, '')
+    const parentURL = pathToFileURL(parentPath).href
+    const require = createRequire(parentURL)
+    const linked = { name: 'linked-plugin', realPath: linkedA }
+    const initial: RuntimeResolution = {
+      ...resolution(profilesDir, profileDir, runtime, runtimeAnchor, '1.0.0'),
+      linkedRoots: [linked],
+    }
+    const removed: RuntimeResolution = { ...initial, linkedRoots: [] }
+    const relinked: RuntimeResolution = { ...initial, linkedRoots: [{ ...linked, realPath: linkedB }] }
+    const key = '@deepseek-ai/dsh-app-boot/profile-resolution'
+    const previous = getEnvironmentData(key)
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(PluginPackages, { resolution: initial })
+
+    const expectSelectedPackage = (dir: string, version: string): void => {
+      expect(ctx.pluginPackages.packageOf('metadata-lib', parentURL)).toMatchObject({
+        name: 'metadata-lib', version, dir,
+      })
+      expect(require.resolve('metadata-lib')).toBe(realpathSync.native(join(dir, 'index.cjs')))
+    }
+    expectSelectedPackage(runtime, '1.0.0')
+    expect(getEnvironmentData(key)).toEqual({ resolution: initial })
+
+    ctx.pluginPackages.replace(removed)
+    expectSelectedPackage(local, '2.0.0')
+    expect(getEnvironmentData(key)).toEqual({ resolution: removed })
+
+    ctx.pluginPackages.replace(initial)
+    expectSelectedPackage(runtime, '1.0.0')
+    expect(getEnvironmentData(key)).toEqual({ resolution: initial })
+
+    ctx.pluginPackages.replace(removed)
+    expectSelectedPackage(local, '2.0.0')
+    const removedWorkerData = getEnvironmentData(key)
+    expect(removedWorkerData).toEqual({ resolution: removed })
+    expect(() => { ctx.pluginPackages.replace(relinked) }).toThrow(
+      'profile resolution: relinking "linked-plugin" requires a process restart',
+    )
+    expectSelectedPackage(local, '2.0.0')
+    expect(getEnvironmentData(key)).toBe(removedWorkerData)
+
+    await ctx.fiber.dispose()
+    contexts.pop()
+    expect(getEnvironmentData(key)).toBe(previous)
+  })
+
   it('publishes additive generations to the process and future Workers', async () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-package-service-resolution-'))
     roots.push(root)
diff --git a/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts b/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts
index 205e6a7e57..9ca24028c6 100644
--- a/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts
+++ b/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts
@@ -34,6 +34,7 @@ it('installs the inherited resolution', async () => {
     profilesDir: '/profiles',
     profileDir: '/profiles/test',
     localPackageNames: [],
+    linkedRoots: [],
     entries: [],
   }
   harness.data = { resolution }
diff --git a/packages/boot/app-boot/tests/profile-resolution.spec.ts b/packages/boot/app-boot/tests/profile-resolution.spec.ts
index 7ce3528c8b..493202fd69 100644
--- a/packages/boot/app-boot/tests/profile-resolution.spec.ts
+++ b/packages/boot/app-boot/tests/profile-resolution.spec.ts
@@ -287,7 +287,7 @@ describe('runtime resolution', { concurrent: false }, () => {
       pkg(dirname(f.installAnchor), '@deepseek-ai/dsh', 0)
       f.profile.layers.push({
         packageName: 'bridge', packageDir: f.installed,
-        patchPath: join(f.installed, 'cordis.patch.yml'), patches: [],
+        patchPaths: [join(f.installed, 'cordis.patch.yml')], patches: [],
       })
     }
     expect(createRequire(join(bridge, 'node_modules', 'middle', 'package.json'))('leaf')).toEqual({ marker: 1 })
@@ -325,12 +325,12 @@ describe('runtime resolution', { concurrent: false }, () => {
     f.profile.layers.push({
       packageName: 'test-bundle',
       packageDir: bundleDir,
-      patchPath: join(bundleDir, 'cordis.patch.yml'),
+      patchPaths: [join(bundleDir, 'cordis.patch.yml')],
       patches: [],
     }, {
       packageName: 'later-bundle',
       packageDir: laterBundle,
-      patchPath: join(laterBundle, 'cordis.patch.yml'),
+      patchPaths: [join(laterBundle, 'cordis.patch.yml')],
       patches: [],
     })
 
@@ -407,7 +407,8 @@ describe('runtime resolution', { concurrent: false }, () => {
     registrations.push(registration)
     const require = createRequire(join(profileDir, 'entry.cjs'))
     expect(require('@deepseek-ai/dsh-core')).toEqual({ marker: 1 })
-    expect(require.resolve('@deepseek-ai/dsh-core', { paths: [profileDir] })).toBe(join(f.installed, 'index.cjs'))
+    expect(require.resolve('@deepseek-ai/dsh-core', { paths: [profileDir] }))
+      .toBe(join(f.root, 'node_modules', '@deepseek-ai/dsh-core', 'index.cjs'))
     const parent = pathToFileURL(join(profileDir, 'entry.mjs')).href
     expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
     expect(await importFrom('@deepseek-ai/dsh-core', parent)).toMatchObject({ marker: 1 })
@@ -425,9 +426,11 @@ describe('runtime resolution', { concurrent: false }, () => {
     const require = createRequire(join(f.profile.dir, 'entry.cjs'))
     expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs'))
     expect(require.resolve('@deepseek-ai/dsh-core', { paths: [alternative] })).toBe(join(alternativePackage, 'index.cjs'))
-    expect(require.resolve('@deepseek-ai/dsh-core', { paths: [f.profile.dir] })).toBe(join(f.installed, 'index.cjs'))
-    expect(require.resolve('@deepseek-ai/dsh-core', { paths: [join(f.root, 'missing'), f.profile.dir] }))
-      .toBe(join(f.installed, 'index.cjs'))
+    expect(thrownError(() => require.resolve('@deepseek-ai/dsh-core', { paths: [f.profile.dir] })))
+      .toMatchObject({ code: 'MODULE_NOT_FOUND' })
+    expect(thrownError(() => require.resolve('@deepseek-ai/dsh-core', {
+      paths: [join(f.root, 'missing'), f.profile.dir],
+    }))).toMatchObject({ code: 'MODULE_NOT_FOUND' })
     const relative = join(f.profile.dir, 'relative.cjs')
     file(relative, '')
     expect(require.resolve('./relative.cjs', { paths: [f.profile.dir] })).toBe(relative)
@@ -435,9 +438,10 @@ describe('runtime resolution', { concurrent: false }, () => {
     file(join(invalid, 'node_modules', '@deepseek-ai/dsh-core', 'package.json'), '{')
     expect(() => { require.resolve('@deepseek-ai/dsh-core', { paths: [invalid, f.profile.dir] }) })
       .toThrow(/Invalid package config/u)
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs'))
   })
 
-  it('keeps earlier explicit CommonJS paths ahead of a managed local failure', async () => {
+  it('keeps earlier explicit CommonJS paths ahead of a profile-local failure', async () => {
     const f = fixture()
     const resolution = await createRuntimeResolution({
       installAnchor: f.installAnchor,
@@ -460,7 +464,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(require.resolve('@deepseek-ai/dsh-core', { paths })).toBe(selected)
   })
 
-  it('keeps a missing legacy main before a managed explicit CommonJS path', async () => {
+  it('preserves a missing legacy main error before an explicit profile path', async () => {
     const f = fixture()
     const invalid = join(f.root, 'invalid')
     const selected = join(invalid, 'node_modules', '@deepseek-ai/dsh-core')
@@ -480,7 +484,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(runtimeError.message).toBe(nativeError.message)
   })
 
-  it('keeps a missing fallback legacy main before later explicit CommonJS paths', async () => {
+  it('preserves a missing ancestor legacy main error before later explicit CommonJS paths', async () => {
     const f = fixture()
     const name = 'fallback-invalid-main'
     const selected = join(f.root, 'node_modules', name)
@@ -502,7 +506,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(runtimeError.message).toBe(nativeError.message)
   })
 
-  it('keeps a missing fallback legacy main after a resolution miss', async () => {
+  it('preserves a missing legacy main error for explicit paths when a runtime entry is unavailable', async () => {
     const f = fixture()
     const selected = join(f.root, 'node_modules', '@deepseek-ai/dsh-core')
     file(join(selected, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', main: './missing.cjs' }))
@@ -945,7 +949,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     )).toThrow(/Cannot find/u)
   })
 
-  it('limits bundle-only entries to the active profile', async () => {
+  it('limits bundle-only interception to ordinary lookup in the active profile', async () => {
     const f = fixture()
     const bundleDir = join(f.root, 'bundle')
     pkg(bundleDir, 'test-bundle', 0, { 'bundle-only': '*' })
@@ -954,7 +958,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     f.profile.layers.push({
       packageName: 'test-bundle',
       packageDir: bundleDir,
-      patchPath: join(bundleDir, 'cordis.patch.yml'),
+      patchPaths: [join(bundleDir, 'cordis.patch.yml')],
       patches: [],
     })
     const registration = installRuntimeInterception(await resolutionOf(f))
@@ -962,10 +966,9 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(createRequire(join(f.profile.dir, 'entry.cjs'))('bundle-only')).toEqual({ marker: 4 })
     const other = join(f.root, 'profiles', 'other', 'entry.cjs')
     expect(() => { createRequire(other)('bundle-only') }).toThrow(/Cannot find module/u)
-    const resolvedBundleOnly = createRequire(other).resolve('bundle-only', {
+    expect(thrownError(() => createRequire(other).resolve('bundle-only', {
       paths: [dirname(other), f.profile.dir],
-    })
-    expect(realpathSync.native(resolvedBundleOnly)).toBe(realpathSync.native(join(bundleOnly, 'index.cjs')))
+    }))).toMatchObject({ code: 'MODULE_NOT_FOUND' })
     expect(() => createRequire(other).resolve('bundle-only', { paths: [dirname(other)] }))
       .toThrow(/Cannot find module/u)
     expect(() => createRequire(other).resolve('missing-explicit', { paths: [dirname(other)] }))
@@ -1024,7 +1027,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs')).toBe(ancestorSubpath)
   })
 
-  it('continues explicit CommonJS paths after a resolution subpath miss', async () => {
+  it('uses later explicit CommonJS paths when the profile has no matching package', async () => {
     const f = fixture()
     file(join(f.installed, 'package.json'), JSON.stringify({
       name: '@deepseek-ai/dsh-core', version: '1.0.0', type: 'module', main: './index.cjs',
@@ -1045,7 +1048,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     file(join(f.installed, 'package.json'), JSON.stringify({
       name: '@deepseek-ai/dsh-core', version: '1.0.0', main: './index.cjs',
     }))
-    // The resolution entry stands in for profiles/node_modules/@deepseek-ai/dsh-core, so this stale copy is never read.
+    // Ordinary profile lookup replaces the shared copy with the runtime entry; explicit paths still read the shared copy.
     const shared = join(f.root, 'profiles', 'node_modules', '@deepseek-ai/dsh-core')
     file(join(shared, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '9.0.0' }))
     file(join(shared, 'sub.cjs'), 'module.exports = { marker: 9 }\n')
@@ -1062,7 +1065,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs'))
     expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs')).toBe(join(home, 'sub.cjs'))
     expect(require('@deepseek-ai/dsh-core/sub.cjs')).toEqual({ marker: 3 })
-    expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs', { paths: [f.profile.dir] })).toBe(join(home, 'sub.cjs'))
+    expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs', { paths: [f.profile.dir] })).toBe(join(shared, 'sub.cjs'))
     expect(require('left-pad')).toEqual({ marker: 9 })
     // ESM resolves the subpath inside the selected package and never consults another copy.
     const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
@@ -1234,7 +1237,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     pkg(bundle, 'my-bundle', 1, { 'bridge': '*' })
     f.profile.layers.push({
       packageName: 'my-bundle', packageDir: bundle,
-      patchPath: join(bundle, 'cordis.patch.yml'), patches: [],
+      patchPaths: [join(bundle, 'cordis.patch.yml')], patches: [],
     })
     const target = join(f.root, 'old-dsh', 'node_modules', 'bridge')
     const owned = join(f.profile.dir, '.dsh-module-fallback', 'node_modules', 'bridge')
@@ -1263,7 +1266,7 @@ describe('runtime resolution', { concurrent: false }, () => {
     pkg(bundleLib, 'bridge', 2)
     f.profile.layers.push({
       packageName: 'my-bundle', packageDir: bundleDir,
-      patchPath: join(bundleDir, 'cordis.patch.yml'), patches: [],
+      patchPaths: [join(bundleDir, 'cordis.patch.yml')], patches: [],
     })
     file(join(f.profile.dir, 'package.json'), JSON.stringify({
       name: 'dsh-profile-web', private: true, dependencies: { 'my-plugin': '*', 'my-bundle': '*' },
@@ -1293,10 +1296,18 @@ describe('runtime resolution', { concurrent: false }, () => {
     const importerDir = importer === 'plugin' ? pluginDir : f.profile.dir
     const require = createRequire(join(importerDir, 'entry.cjs'))
     const parent = pathToFileURL(join(importerDir, 'entry.mjs')).href
+    const explicitWinner = LOOKUP_LAYERS.find(layer => (
+      layers.includes(layer) && (layer !== 'private' || importer === 'plugin')
+    ))
+    if (explicitWinner === undefined) {
+      expect(thrownError(() => require.resolve(name, { paths: [importerDir] })))
+        .toMatchObject({ code: 'MODULE_NOT_FOUND' })
+    } else {
+      expect(require.resolve(name, { paths: [importerDir] })).toBe(join(real[explicitWinner], 'index.cjs'))
+    }
     const winner = lookupWinner(matrixCase)
     if (winner === 'missing') {
       expect(thrownError(() => require(name))).toMatchObject({ code: 'MODULE_NOT_FOUND' })
-      expect(thrownError(() => require.resolve(name, { paths: [importerDir] }))).toMatchObject({ code: 'MODULE_NOT_FOUND' })
       await expect(importFrom(name, parent)).rejects.toMatchObject({ code: 'ERR_MODULE_NOT_FOUND' })
       expect(registration.packageDir(name, parent)).toBeUndefined()
       return
@@ -1308,7 +1319,6 @@ describe('runtime resolution', { concurrent: false }, () => {
     const marker = winner === 'interception' ? (kind === 'installation' ? 1 : 2) : LOOKUP_MARKERS[winner]
     expect(require(name)).toEqual({ marker })
     expect(require.resolve(name)).toBe(join(realDir, 'index.cjs'))
-    expect(require.resolve(name, { paths: [importerDir] })).toBe(join(realDir, 'index.cjs'))
     expect(resolveFrom(name, parent)).toBe(pathToFileURL(join(realDir, 'index.js')).href)
     expect(await importFrom(name, parent)).toMatchObject({ marker })
     expect(registration.packageDir(name, parent)).toBe(packageDir)
@@ -1332,6 +1342,7 @@ describe('runtime resolution', { concurrent: false }, () => {
       profilesDir,
       profileDir: join(profilesDir, 'web'),
       localPackageNames: [],
+      linkedRoots: [],
       entries: [],
     })
     registrations.push(registration)
@@ -1595,6 +1606,14 @@ describe('runtime resolution', { concurrent: false }, () => {
     registration.replace({ ...first, localPackageNames: ['new-local'] })
     registration.replace({ ...first, localPackageNames: ['new-local'] })
     expect(() => { registration.replace(first) }).toThrow(/removing local package/u)
+    const linked = { name: 'linked-plugin', realPath: join(f.root, 'work', 'a') }
+    const withLocal = { ...first, localPackageNames: ['new-local'] }
+    registration.replace({ ...withLocal, linkedRoots: [linked] })
+    registration.replace({ ...withLocal, linkedRoots: [] })
+    registration.replace({ ...withLocal, linkedRoots: [linked] })
+    expect(() => {
+      registration.replace({ ...withLocal, linkedRoots: [{ ...linked, realPath: join(f.root, 'work', 'b') }] })
+    }).toThrow(/relinking "linked-plugin" requires a process restart/u)
     expect(registration.packageDir(
       '@deepseek-ai/dsh-core', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href,
     )).toBe(f.installed)
@@ -1661,6 +1680,827 @@ describe('runtime resolution', { concurrent: false }, () => {
     expect(getEnvironmentData(key)).toBe(previous)
   })
 
+  it('records active profile links to external directories with or without manifests', async () => {
+    const f = fixture()
+    const modules = join(f.profile.dir, 'node_modules')
+    const outside = join(f.root, 'work', 'my-plugin')
+    pkg(outside, 'my-plugin', 5)
+    const scopedOutside = join(f.root, 'work', 'scoped')
+    pkg(scopedOutside, '@scope/linked', 6)
+    const inside = join(f.root, 'profiles', 'node_modules', 'inside-lib')
+    pkg(inside, 'inside-lib', 7)
+    const bare = join(f.root, 'work', 'bare')
+    mkdirSync(bare, { recursive: true })
+    const dangling = join(f.root, 'work', 'dangling')
+    mkdirSync(dangling, { recursive: true })
+    const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+    mkdirSync(join(modules, '@scope'), { recursive: true })
+    symlinkSync(outside, join(modules, 'my-plugin'), linkType)
+    symlinkSync(scopedOutside, join(modules, '@scope', 'linked'), linkType)
+    symlinkSync(inside, join(modules, 'inside-lib'), linkType)
+    symlinkSync(join(f.root, 'profiles'), join(modules, 'profiles-root'), linkType)
+    symlinkSync(bare, join(modules, 'bare-dir'), linkType)
+    symlinkSync(dangling, join(modules, 'dangling'), linkType)
+    rmSync(dangling, { recursive: true })
+    pkg(join(modules, 'installed'), 'installed', 8)
+    const resolution = await resolutionOf(f)
+    expect(resolution.linkedRoots).toEqual([
+      { name: '@scope/linked', realPath: scopedOutside },
+      { name: 'bare-dir', realPath: bare },
+      { name: 'my-plugin', realPath: outside },
+    ])
+    expect(Object.isFrozen(resolution.linkedRoots)).toBe(true)
+    expect(Object.isFrozen(resolution.linkedRoots[0])).toBe(true)
+    const withoutProfile = await createRuntimeResolution({ installAnchor: f.installAnchor, home: f.root })
+    expect(withoutProfile.linkedRoots).toEqual([])
+    const unmaterialized = await createRuntimeResolution({
+      installAnchor: f.installAnchor,
+      profile: { ...f.profile, dir: join(f.root, 'later', 'profiles', 'web') },
+      home: join(f.root, 'later'),
+    })
+    expect(unmaterialized.linkedRoots).toEqual([])
+  })
+
+  it.each([
+    { layout: 'directory', sharedTree: 'present' },
+    { layout: 'symlink', sharedTree: 'present' },
+    { layout: 'directory', sharedTree: 'missing' },
+    { layout: 'symlink', sharedTree: 'missing' },
+  ])(
+    'excludes a $layout application-owned profile and its pnpm packages from linked roots ($sharedTree shared tree)', async ({ layout, sharedTree }) => {
+      const f = fixture()
+      const realProfile = join(f.root, 'application-profile')
+      const profileDir = layout === 'symlink' ? join(f.root, 'application-profile-alias') : realProfile
+      file(join(realProfile, 'package.json'), JSON.stringify({ name: 'application-profile', private: true }))
+      const local = join(realProfile, 'node_modules', '.pnpm', 'local@1.0.0', 'node_modules', 'local')
+      pkg(local, 'local', 2)
+      const outside = join(f.root, 'external-plugin')
+      pkg(outside, 'external-plugin', 3)
+      const shared = join(f.root, 'profiles', 'node_modules', 'shared-package')
+      pkg(shared, 'shared-package', 4)
+      const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+      const links: string[] = []
+      try {
+        if (layout === 'symlink') {
+          symlinkSync(realProfile, profileDir, linkType)
+          links.push(profileDir)
+        }
+        for (const [name, target] of [
+          ['local', join(profileDir, 'node_modules', '.pnpm', 'local@1.0.0', 'node_modules', 'local')],
+          ['profile-self', profileDir],
+          ['profile-real', realProfile],
+          ['external-plugin', outside],
+          ['shared-package', shared],
+        ] as const) {
+          const link = join(profileDir, 'node_modules', name)
+          symlinkSync(target, link, linkType)
+          links.push(link)
+        }
+        if (sharedTree === 'missing') rmSync(join(f.root, 'profiles'), { recursive: true })
+        const resolution = await createRuntimeResolution({
+          installAnchor: f.installAnchor,
+          profile: { ...f.profile, dir: profileDir, patchPath: join(profileDir, 'cordis.patch.yml') },
+          home: f.root,
+        })
+        expect(resolution.linkedRoots).toEqual([{ name: 'external-plugin', realPath: outside }])
+      } finally {
+        for (const link of links.reverse()) unlinkSync(link)
+      }
+    },
+  )
+
+  it.each(['unmaterialized', 'empty'] as const)(
+    'leaves an %s application-owned profile without linked roots', async (state) => {
+      const f = fixture()
+      const dir = join(f.root, 'application-profile')
+      if (state === 'empty') mkdirSync(join(dir, 'node_modules'), { recursive: true })
+      const resolution = await createRuntimeResolution({
+        installAnchor: f.installAnchor,
+        profile: { ...f.profile, dir, patchPath: join(dir, 'cordis.patch.yml') },
+        home: f.root,
+      })
+      expect(resolution.linkedRoots).toEqual([])
+    },
+  )
+
+  it('excludes profile symlinks to files from linked roots', async () => {
+    const f = fixture()
+    const modules = join(f.profile.dir, 'node_modules')
+    const target = join(f.root, 'work', 'file.cjs')
+    file(target, 'module.exports = { marker: 5 }\n')
+    mkdirSync(join(modules, '@scope'), { recursive: true })
+    symlinkSync(target, join(modules, 'file-link'), 'file')
+    symlinkSync(target, join(modules, '@scope', 'file-link'), 'file')
+
+    const resolution = await resolutionOf(f)
+    expect(resolution.linkedRoots).toEqual([])
+  })
+
+  it.each(['linked target', 'profiles directory'] as const)(
+    'reports a cyclic %s with the original Node error and path', async (location) => {
+      const f = fixture()
+      const home = location === 'profiles directory' ? join(f.root, 'cycle-home') : f.root
+      const modules = join(f.profile.dir, 'node_modules')
+      const outside = join(f.root, 'external-directory')
+      mkdirSync(outside, { recursive: true })
+      mkdirSync(modules, { recursive: true })
+      const cycle = location === 'profiles directory' ? join(home, 'profiles') : join(modules, 'cycle')
+      mkdirSync(dirname(cycle), { recursive: true })
+      const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+      const links: string[] = []
+      try {
+        const ordinaryLink = join(modules, 'external-directory')
+        symlinkSync(outside, ordinaryLink, linkType)
+        links.push(ordinaryLink)
+        symlinkSync(cycle, cycle, linkType)
+        links.push(cycle)
+        const nativeError = thrownError(() => realpathSync.native(cycle))
+        expect(nativeError.code).toBe('ELOOP')
+        expect(nativeError.path).toBe(cycle)
+        await expect(createRuntimeResolution({
+          installAnchor: f.installAnchor, profile: f.profile, home,
+        })).rejects.toMatchObject({
+          code: 'ELOOP', path: cycle, message: nativeError.message,
+        })
+      } finally {
+        for (const link of links.reverse()) unlinkSync(link)
+      }
+    },
+  )
+
+  /** A plugin repository linked into the profile, with the manifest a plugin developer keeps for type checking. */
+  function linkedPluginFixture(peerDependencies: Record<string, string> | undefined = { '@deepseek-ai/dsh-core': '*' }): {
+    f: ReturnType<typeof fixture>
+    linkedRoot: string
+    helper: string
+    writeManifest: (peers: Record<string, string> | undefined) => void
+  } {
+    const f = fixture()
+    const installDir = dirname(f.installAnchor)
+    pkg(installDir, '@deepseek-ai/dsh', 0, { '@deepseek-ai/dsh-core': '*', '@deepseek-ai/dsh-util': '*' })
+    pkg(join(installDir, 'node_modules', '@deepseek-ai', 'dsh-util'), '@deepseek-ai/dsh-util', 2)
+    const linkedRoot = join(f.root, 'work', 'my-plugin')
+    const writeManifest = (peers: Record<string, string> | undefined): void => {
+      file(join(linkedRoot, 'package.json'), JSON.stringify({
+        name: 'my-plugin',
+        version: '30.0.0',
+        type: 'module',
+        exports: { import: './index.js', require: './index.cjs' },
+        imports: { '#core': '@deepseek-ai/dsh-core' },
+        dependencies: { 'zod': '*', '@deepseek-ai/dsh-util': '*', 'helper': '*' },
+        ...(peers === undefined ? {} : { peerDependencies: peers }),
+        devDependencies: { '@deepseek-ai/dsh-core': '*' },
+      }))
+    }
+    writeManifest(peerDependencies)
+    file(join(linkedRoot, 'index.js'), 'export const marker = 30\n')
+    file(join(linkedRoot, 'index.cjs'), 'module.exports = { marker: 30 }\n')
+    // The devDependency copy a type checker needs, the plugin's own third-party version, and a dsh package
+    // declared as a plain dependency.
+    pkg(join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-core'), '@deepseek-ai/dsh-core', 21)
+    pkg(join(linkedRoot, 'node_modules', 'zod'), 'zod', 22)
+    pkg(join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-util'), '@deepseek-ai/dsh-util', 23)
+    pkg(join(f.root, 'work', 'node_modules', 'left-pad'), 'left-pad', 24)
+    // A transitive dependency in pnpm's isolated layout, with a sibling of its own.
+    const helper = join(linkedRoot, 'node_modules', '.pnpm', 'helper@1.0.0', 'node_modules', 'helper')
+    pkg(helper, 'helper', 25, { sibling: '*' }, { '@deepseek-ai/dsh-core': '*' })
+    pkg(join(dirname(helper), 'sibling'), 'sibling', 26)
+    const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+    symlinkSync(helper, join(linkedRoot, 'node_modules', 'helper'), linkType)
+    const modules = join(f.profile.dir, 'node_modules')
+    mkdirSync(modules, { recursive: true })
+    symlinkSync(linkedRoot, join(modules, 'my-plugin'), linkType)
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'dsh-profile-web', private: true, dependencies: { 'my-plugin': '*' },
+    }))
+    return { f, linkedRoot, helper, writeManifest }
+  }
+
+  describe('linked root generations', () => {
+    const peer = '@deepseek-ai/dsh-core'
+
+    function unsavedFixture(): ReturnType<typeof linkedPluginFixture> {
+      const result = linkedPluginFixture()
+      file(join(result.f.profile.dir, 'package.json'), JSON.stringify({
+        name: 'dsh-profile-web', private: true, dependencies: {},
+      }))
+      return result
+    }
+
+    function expectPeerLookup(
+      registration: RuntimeInterception, require: NodeJS.Require, parent: string, selected: string,
+    ): void {
+      expect(require.resolve(peer)).toBe(join(selected, 'index.cjs'))
+      expect(resolveFrom(peer, parent)).toBe(pathToFileURL(join(selected, 'index.js')).href)
+      expect(registration.packageDir(peer, parent)).toBe(selected)
+    }
+
+    it('returns an unlinked importer to native lookup without changing its first generation', async () => {
+      const { f, linkedRoot } = unsavedFixture()
+      const link = join(f.profile.dir, 'node_modules', 'my-plugin')
+      const local = join(linkedRoot, 'node_modules', peer)
+      const require = createRequire(join(linkedRoot, 'entry.cjs'))
+      const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+      const first = await resolutionOf(f)
+      expect(first.localPackageNames).toEqual([])
+      expect(first.linkedRoots).toEqual([{ name: 'my-plugin', realPath: linkedRoot }])
+      const registration = installRuntimeInterception(first)
+      registrations.push(registration)
+      try {
+        expectPeerLookup(registration, require, parent, f.installed)
+        unlinkSync(link)
+        const second = await resolutionOf(f)
+        expect(second.localPackageNames).toEqual([])
+        expect(second.linkedRoots).toEqual([])
+        registration.replace(second)
+        expectPeerLookup(registration, require, parent, local)
+        expect(first.linkedRoots).toEqual([{ name: 'my-plugin', realPath: linkedRoot }])
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+    })
+
+    it('reports native misses after unlinking when no physical peer remains', async () => {
+      const { f, linkedRoot } = unsavedFixture()
+      rmSync(join(linkedRoot, 'node_modules', peer), { recursive: true })
+      const require = createRequire(join(linkedRoot, 'entry.cjs'))
+      const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+      const first = await resolutionOf(f)
+      expect(first.localPackageNames).toEqual([])
+      const registration = installRuntimeInterception(first)
+      registrations.push(registration)
+      try {
+        expectPeerLookup(registration, require, parent, f.installed)
+        unlinkSync(join(f.profile.dir, 'node_modules', 'my-plugin'))
+        const second = await resolutionOf(f)
+        expect(second.linkedRoots).toEqual([])
+        registration.replace(second)
+        expect(thrownError(() => require.resolve(peer))).toMatchObject({ code: 'MODULE_NOT_FOUND' })
+        expect(thrownError(() => require(peer))).toMatchObject({ code: 'MODULE_NOT_FOUND' })
+        expect(thrownError(() => resolveFrom(peer, parent))).toMatchObject({ code: 'ERR_MODULE_NOT_FOUND' })
+        await expect(importFrom(peer, parent)).rejects.toMatchObject({ code: 'ERR_MODULE_NOT_FOUND' })
+        expect(registration.packageDir(peer, parent)).toBeUndefined()
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+    })
+
+    it('restores the same link target and admits an additional root name', async () => {
+      const { f, linkedRoot } = unsavedFixture()
+      const link = join(f.profile.dir, 'node_modules', 'my-plugin')
+      const require = createRequire(join(linkedRoot, 'entry.cjs'))
+      const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+      const first = await resolutionOf(f)
+      expect(first.localPackageNames).toEqual([])
+      const registration = installRuntimeInterception(first)
+      registrations.push(registration)
+      try {
+        expectPeerLookup(registration, require, parent, f.installed)
+        unlinkSync(link)
+        registration.replace(await resolutionOf(f))
+        expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+        symlinkSync(linkedRoot, link, linkType)
+        registration.replace(await resolutionOf(f))
+        expectPeerLookup(registration, require, parent, f.installed)
+
+        const additional = join(f.root, 'work', 'another-plugin')
+        pkg(additional, 'another-plugin', 0, {}, { [peer]: '*' })
+        pkg(join(additional, 'node_modules', peer), peer, 31)
+        symlinkSync(additional, join(f.profile.dir, 'node_modules', 'another-plugin'), linkType)
+        const successor = await resolutionOf(f)
+        expect(successor.localPackageNames).toEqual([])
+        expect(successor.linkedRoots).toEqual([
+          { name: 'another-plugin', realPath: additional },
+          { name: 'my-plugin', realPath: linkedRoot },
+        ])
+        registration.replace(successor)
+        expectPeerLookup(registration, require, parent, f.installed)
+        expectPeerLookup(registration, createRequire(join(additional, 'entry.cjs')),
+          pathToFileURL(join(additional, 'entry.mjs')).href, f.installed)
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+    })
+
+    it.each(['inner', 'outer'] as const)(
+      'keeps an overlapping importer proxied after removing the %s root until the last root is removed', async (removed) => {
+        const { f, linkedRoot } = unsavedFixture()
+        const innerLink = join(f.profile.dir, 'node_modules', 'my-plugin')
+        const outer = dirname(linkedRoot)
+        const outerLink = join(f.profile.dir, 'node_modules', 'workspace')
+        symlinkSync(outer, outerLink, process.platform === 'win32' ? 'junction' : 'dir')
+        const require = createRequire(join(linkedRoot, 'entry.cjs'))
+        const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+        const first = await resolutionOf(f)
+        expect(first.localPackageNames).toEqual([])
+        expect(first.linkedRoots).toEqual([
+          { name: 'my-plugin', realPath: linkedRoot },
+          { name: 'workspace', realPath: outer },
+        ])
+        const registration = installRuntimeInterception(first)
+        registrations.push(registration)
+        try {
+          expectPeerLookup(registration, require, parent, f.installed)
+          unlinkSync(removed === 'inner' ? innerLink : outerLink)
+          const second = await resolutionOf(f)
+          expect(second.linkedRoots).toEqual(removed === 'inner'
+            ? [{ name: 'workspace', realPath: outer }]
+            : [{ name: 'my-plugin', realPath: linkedRoot }])
+          registration.replace(second)
+          expectPeerLookup(registration, require, parent, f.installed)
+          unlinkSync(removed === 'inner' ? outerLink : innerLink)
+          const third = await resolutionOf(f)
+          expect(third.linkedRoots).toEqual([])
+          registration.replace(third)
+          expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+        } finally {
+          registration.dispose()
+          registrations.pop()
+        }
+      },
+    )
+
+    it('uses native fresh subpaths from a loaded caller while held modules keep their values', async () => {
+      const { f, linkedRoot } = unsavedFixture()
+      const local = join(linkedRoot, 'node_modules', peer)
+      for (const [dir, marker] of [[f.installed, 1], [local, 21]] as const) {
+        file(join(dir, 'package.json'), JSON.stringify({
+          name: peer, version: `${String(marker)}.0.0`, type: 'module',
+          exports: {
+            '.': { import: './index.js', require: './index.cjs' },
+            './fresh': { import: './fresh.js', require: './fresh.cjs' },
+          },
+        }))
+        file(join(dir, 'fresh.js'), `export const marker = ${String(marker)}\n`)
+        file(join(dir, 'fresh.cjs'), `module.exports = { marker: ${String(marker)} }\n`)
+      }
+      // The fresh subpath has no completed Node resolution; root removal does not replace held module references.
+      file(join(linkedRoot, 'caller.js'), `import * as held from '${peer}'\nexport { held }\n`
+        + `export async function fresh() { return await import('${peer}/fresh') }\n`)
+      file(join(linkedRoot, 'caller.cjs'), `module.exports = { held: require('${peer}'), `
+        + `fresh: () => require('${peer}/fresh') }\n`)
+      const require = createRequire(join(linkedRoot, 'entry.cjs'))
+      const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+      const first = await resolutionOf(f)
+      expect(first.localPackageNames).toEqual([])
+      const registration = installRuntimeInterception(first)
+      registrations.push(registration)
+      try {
+        const cjsCaller = require('./caller.cjs') as { held: { marker: number }; fresh(): { marker: number } }
+        const esmCaller = await importFrom('./caller.js', parent) as {
+          held: { marker: number }
+          fresh(): Promise<{ marker: number }>
+        }
+        const heldCjs = cjsCaller.held
+        const heldEsm = esmCaller.held
+        expect(heldCjs).toEqual({ marker: 1 })
+        expect(heldEsm).toMatchObject({ marker: 1 })
+        unlinkSync(join(f.profile.dir, 'node_modules', 'my-plugin'))
+        const second = await resolutionOf(f)
+        expect(second.linkedRoots).toEqual([])
+        registration.replace(second)
+        expect(cjsCaller.fresh()).toEqual({ marker: 21 })
+        await expect(esmCaller.fresh()).resolves.toMatchObject({ marker: 21 })
+        expect(cjsCaller.held).toBe(heldCjs)
+        expect(esmCaller.held).toBe(heldEsm)
+        expect(heldCjs).toEqual({ marker: 1 })
+        expect(heldEsm).toMatchObject({ marker: 1 })
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+    })
+
+    it.each(['initial', 'added'] as const)(
+      'rejects a removed %s root retarget without reactivating either directory', async (generation) => {
+        const { f, linkedRoot } = unsavedFixture()
+        const link = join(f.profile.dir, 'node_modules', 'my-plugin')
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+        const require = createRequire(join(linkedRoot, 'entry.cjs'))
+        const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+        if (generation === 'added') unlinkSync(link)
+        const first = await resolutionOf(f)
+        expect(first.localPackageNames).toEqual([])
+        expect(first.linkedRoots).toEqual(generation === 'added'
+          ? [] : [{ name: 'my-plugin', realPath: linkedRoot }])
+        const registration = installRuntimeInterception(first)
+        registrations.push(registration)
+        try {
+          if (generation === 'added') {
+            symlinkSync(linkedRoot, link, linkType)
+            registration.replace(await resolutionOf(f))
+          }
+          expectPeerLookup(registration, require, parent, f.installed)
+          unlinkSync(link)
+          const removed = await resolutionOf(f)
+          expect(removed.linkedRoots).toEqual([])
+          registration.replace(removed)
+          expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+
+          const target = join(f.root, 'work', 'retargeted-plugin')
+          pkg(target, 'my-plugin', 0, {}, { [peer]: '*' })
+          pkg(join(target, 'node_modules', peer), peer, 22)
+          symlinkSync(target, link, linkType)
+          const successor = await resolutionOf(f)
+          expect(successor.localPackageNames).toEqual([])
+          expect(successor.linkedRoots).toEqual([{ name: 'my-plugin', realPath: target }])
+          expect(() => { registration.replace(successor) })
+            .toThrow(/^profile resolution: relinking "my-plugin" requires a process restart$/u)
+          expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+          expectPeerLookup(registration, createRequire(join(target, 'entry.cjs')),
+            pathToFileURL(join(target, 'entry.mjs')).href, join(target, 'node_modules', peer))
+        } finally {
+          registration.dispose()
+          registrations.pop()
+        }
+      },
+    )
+
+    it('does not retain targets from a rejected successor', async () => {
+      const { f, linkedRoot } = unsavedFixture()
+      const modules = join(f.profile.dir, 'node_modules')
+      const originalLink = join(modules, 'my-plugin')
+      const newLink = join(modules, 'a-new-plugin')
+      const replacement = join(f.root, 'work', 'replacement')
+      const rejectedTarget = join(f.root, 'work', 'rejected-target')
+      const acceptedTarget = join(f.root, 'work', 'accepted-target')
+      for (const [dir, name, marker] of [
+        [replacement, 'my-plugin', 22],
+        [rejectedTarget, 'a-new-plugin', 31],
+        [acceptedTarget, 'a-new-plugin', 32],
+      ] as const) {
+        pkg(dir, name, 0, {}, { [peer]: '*' })
+        pkg(join(dir, 'node_modules', peer), peer, marker)
+      }
+      const require = createRequire(join(linkedRoot, 'entry.cjs'))
+      const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+      const first = await resolutionOf(f)
+      expect(first.localPackageNames).toEqual([])
+      const registration = installRuntimeInterception(first)
+      registrations.push(registration)
+      try {
+        expectPeerLookup(registration, require, parent, f.installed)
+        unlinkSync(originalLink)
+        const removed = await resolutionOf(f)
+        expect(removed.linkedRoots).toEqual([])
+        registration.replace(removed)
+        expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+        symlinkSync(replacement, originalLink, linkType)
+        symlinkSync(rejectedTarget, newLink, linkType)
+        const rejected = await resolutionOf(f)
+        expect(rejected.linkedRoots).toEqual([
+          { name: 'a-new-plugin', realPath: rejectedTarget },
+          { name: 'my-plugin', realPath: replacement },
+        ])
+        expect(() => { registration.replace(rejected) })
+          .toThrow(/^profile resolution: relinking "my-plugin" requires a process restart$/u)
+        expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+        expectPeerLookup(registration, createRequire(join(rejectedTarget, 'entry.cjs')),
+          pathToFileURL(join(rejectedTarget, 'entry.mjs')).href, join(rejectedTarget, 'node_modules', peer))
+
+        unlinkSync(originalLink)
+        unlinkSync(newLink)
+        symlinkSync(acceptedTarget, newLink, linkType)
+        const accepted = await resolutionOf(f)
+        expect(accepted.linkedRoots).toEqual([{ name: 'a-new-plugin', realPath: acceptedTarget }])
+        registration.replace(accepted)
+        expectPeerLookup(registration, createRequire(join(acceptedTarget, 'entry.cjs')),
+          pathToFileURL(join(acceptedTarget, 'entry.mjs')).href, f.installed)
+        expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer))
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+    })
+  })
+
+  it.each(['src', 'dist'] as const)(
+    'keeps intermediate %s/node_modules ahead of linked-root peers and ancestor packages', async (directory) => {
+      const { f, linkedRoot } = linkedPluginFixture()
+      const intermediate = join(linkedRoot, directory)
+      const queries = [
+        ['@deepseek-ai/dsh-core', 41],
+        ['@deepseek-ai/dsh-util', 42],
+        ['left-pad', 43],
+      ] as const
+      for (const [name, marker] of queries) pkg(join(intermediate, 'node_modules', name), name, marker)
+      const require = createRequire(join(intermediate, 'nested', 'entry.cjs'))
+      const parent = pathToFileURL(join(intermediate, 'nested', 'entry.mjs')).href
+      const registration = installRuntimeInterception(await resolutionOf(f))
+      registrations.push(registration)
+      try {
+        for (const [name, marker] of queries) {
+          const selected = join(intermediate, 'node_modules', name)
+          expect(require.resolve(name), name).toBe(join(selected, 'index.cjs'))
+          expect(require(name), name).toEqual({ marker })
+          expect(resolveFrom(name, parent), name).toBe(pathToFileURL(join(selected, 'index.js')).href)
+          expect(await importFrom(name, parent), name).toMatchObject({ marker })
+          expect(registration.packageDir(name, parent), name).toBe(selected)
+        }
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+    },
+  )
+
+  it.each([
+    { names: 'outer-first', reverse: false },
+    { names: 'outer-first', reverse: true },
+    { names: 'inner-first', reverse: false },
+    { names: 'inner-first', reverse: true },
+  ])('resolves overlapping linked roots independently of names and order ($names, reverse=$reverse)', async ({ names, reverse }) => {
+    const f = fixture('inner-peer')
+    const installDir = dirname(f.installAnchor)
+    const outer = join(f.root, 'work', 'repo')
+    const inner = join(outer, 'packages', 'plugin')
+    pkg(outer, 'outer-repo', 0, {}, { 'shadowed-outer-peer': '*', 'outer-peer': '*' })
+    pkg(inner, 'inner-plugin', 0, {}, { 'inner-peer': '*' })
+    const queries = [
+      {
+        name: 'inner-peer', nativeDir: join(inner, 'node_modules', 'inner-peer'), nativeMarker: 11,
+        selected: join(installDir, 'node_modules', 'inner-peer'), marker: 1,
+      },
+      {
+        name: 'shadowed-outer-peer', nativeDir: join(inner, 'node_modules', 'shadowed-outer-peer'), nativeMarker: 12,
+        selected: join(inner, 'node_modules', 'shadowed-outer-peer'), marker: 12,
+      },
+      {
+        name: 'outer-peer', nativeDir: join(outer, 'node_modules', 'outer-peer'), nativeMarker: 13,
+        selected: join(installDir, 'node_modules', 'outer-peer'), marker: 3,
+      },
+    ]
+    pkg(installDir, '@deepseek-ai/dsh', 0, Object.fromEntries(queries.map(({ name }) => [name, '*'])))
+    for (const [index, query] of queries.entries()) {
+      pkg(join(installDir, 'node_modules', query.name), query.name, index + 1)
+      pkg(query.nativeDir, query.name, query.nativeMarker)
+    }
+    const outerName = names === 'outer-first' ? 'a-repo' : 'z-repo'
+    const innerName = names === 'outer-first' ? 'z-plugin' : 'a-plugin'
+    const modules = join(f.profile.dir, 'node_modules')
+    mkdirSync(modules, { recursive: true })
+    const links: string[] = []
+    try {
+      for (const [name, target] of [[outerName, outer], [innerName, inner]] as const) {
+        const link = join(modules, name)
+        symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir')
+        links.push(link)
+      }
+      const resolution = await resolutionOf(f)
+      expect(resolution.linkedRoots.map(root => root.realPath))
+        .toEqual(names === 'outer-first' ? [outer, inner] : [inner, outer])
+      const linkedRoots = reverse ? [...resolution.linkedRoots].reverse() : resolution.linkedRoots
+      const require = createRequire(join(inner, 'entry.cjs'))
+      const parent = pathToFileURL(join(inner, 'entry.mjs')).href
+      for (const query of queries) expect(require.resolve(query.name)).toBe(join(query.nativeDir, 'index.cjs'))
+      const registration = installRuntimeInterception({ ...resolution, linkedRoots })
+      registrations.push(registration)
+      try {
+        for (const { name, selected, marker } of queries) {
+          expect(require.resolve(name), name).toBe(join(selected, 'index.cjs'))
+          expect(require(name), name).toEqual({ marker })
+          expect(resolveFrom(name, parent), name).toBe(pathToFileURL(join(selected, 'index.js')).href)
+          expect(await importFrom(name, parent), name).toMatchObject({ marker })
+          expect(registration.packageDir(name, parent), name).toBe(selected)
+        }
+      } finally {
+        registration.dispose()
+        registrations.pop()
+      }
+      for (const query of queries) expect(require.resolve(query.name)).toBe(join(query.nativeDir, 'index.cjs'))
+    } finally {
+      for (const link of links.reverse()) unlinkSync(link)
+    }
+  })
+
+  it.each(['host', 'dependency', 'workspace-logical', 'workspace-real'] as const)(
+    'keeps %s importers native inside a wide linked root', async (importer) => {
+      const name = '@deepseek-ai/dsh-core'
+      const f = fixture(name)
+      const installDir = dirname(f.installAnchor)
+      pkg(installDir, '@deepseek-ai/dsh', 0, {
+        [name]: '*', 'host-consumer': '*', 'workspace-consumer': '*',
+      })
+      const hostSource = join(installDir, 'src')
+      const dependency = join(installDir, 'node_modules', 'host-consumer')
+      const workspace = join(f.root, 'workspace-consumer')
+      const workspaceLink = join(installDir, 'node_modules', 'workspace-consumer')
+      const external = join(f.root, 'external-plugin')
+      for (const [dir, packageName, marker] of [
+        [hostSource, 'host-source', 11],
+        [dependency, 'host-consumer', 21],
+        [workspace, 'workspace-consumer', 22],
+        [external, 'external-plugin', 31],
+      ] as const) {
+        pkg(dir, packageName, 0, {}, { [name]: '*' })
+        pkg(join(dir, 'node_modules', name), name, marker)
+      }
+      const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+      const wideLink = join(f.profile.dir, 'node_modules', 'wide-workspace')
+      mkdirSync(dirname(wideLink), { recursive: true })
+      const links: string[] = []
+      try {
+        symlinkSync(workspace, workspaceLink, linkType)
+        links.push(workspaceLink)
+        symlinkSync(f.root, wideLink, linkType)
+        links.push(wideLink)
+        const importers = {
+          host: { dir: hostSource, marker: 11 },
+          dependency: { dir: dependency, marker: 21 },
+          'workspace-logical': { dir: workspaceLink, marker: 22 },
+          'workspace-real': { dir: workspace, marker: 22 },
+        }
+        const { dir, marker } = importers[importer]
+        const expectedDir = join(dir, 'node_modules', name)
+        const realDir = realpathSync.native(expectedDir)
+        const require = createRequire(join(dir, 'entry.cjs'))
+        const parent = pathToFileURL(join(dir, 'entry.mjs')).href
+        const nativeCjs = require.resolve(name)
+        const nativeEsm = resolveFrom(name, parent)
+        expect(nativeCjs).toBe(join(realDir, 'index.cjs'))
+        expect(nativeEsm).toBe(pathToFileURL(join(realDir, 'index.js')).href)
+        const resolution = await resolutionOf(f)
+        expect(resolution.entries.find(entry => entry.name === 'workspace-consumer'))
+          .toMatchObject({ scope: 'installation', packageDir: workspaceLink })
+        expect(resolution.linkedRoots).toEqual([
+          { name: 'wide-workspace', realPath: f.root },
+        ])
+        const registration = installRuntimeInterception(resolution)
+        registrations.push(registration)
+        try {
+          const externalRequire = createRequire(join(external, 'entry.cjs'))
+          const externalParent = pathToFileURL(join(external, 'entry.mjs')).href
+          expect(externalRequire.resolve(name)).toBe(join(f.installed, 'index.cjs'))
+          expect(externalRequire(name)).toEqual({ marker: 1 })
+          expect(resolveFrom(name, externalParent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+          expect(await importFrom(name, externalParent)).toMatchObject({ marker: 1 })
+          expect(registration.packageDir(name, externalParent)).toBe(f.installed)
+          expect(require.resolve(name)).toBe(nativeCjs)
+          expect(require(name)).toEqual({ marker })
+          expect(resolveFrom(name, parent)).toBe(nativeEsm)
+          expect(await importFrom(name, parent)).toMatchObject({ marker })
+          expect(registration.packageDir(name, parent)).toBe(expectedDir)
+        } finally {
+          registration.dispose()
+          registrations.pop()
+        }
+      } finally {
+        for (const link of links.reverse()) unlinkSync(link)
+      }
+    },
+  )
+
+  it('occupies only the peer names of a linked plugin at its own node_modules', async () => {
+    const { f, linkedRoot, helper } = linkedPluginFixture()
+    const registration = installRuntimeInterception(await resolutionOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(linkedRoot, 'entry.cjs'))
+    const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+    const expectResolution = async (
+      name: string, dir: string, marker: number, from: { require: NodeJS.Require; parent: string } = { require, parent },
+    ): Promise<void> => {
+      expect(from.require(name), name).toEqual({ marker })
+      expect(from.require.resolve(name), name).toBe(join(dir, 'index.cjs'))
+      expect(resolveFrom(name, from.parent), name).toBe(pathToFileURL(join(dir, 'index.js')).href)
+      expect(await importFrom(name, from.parent), name).toMatchObject({ marker })
+      expect(registration.packageDir(name, from.parent), name).toBe(dir)
+    }
+    // The peer comes from the running installation; its devDependency copy is never read.
+    await expectResolution('@deepseek-ai/dsh-core', f.installed, 1)
+    // A cache-busting query on the importer, as hot module replacement re-imports it, changes nothing.
+    expect(resolveFrom('@deepseek-ai/dsh-core', `${parent}?t=1`)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(resolveFrom('zod', `${parent}?t=1`)).toBe(pathToFileURL(join(linkedRoot, 'node_modules', 'zod', 'index.js')).href)
+    // Plain dependencies keep the plugin's own copies, including a dsh package declared as one.
+    await expectResolution('zod', join(linkedRoot, 'node_modules', 'zod'), 22)
+    await expectResolution('@deepseek-ai/dsh-util', join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-util'), 23)
+    // An undeclared name without an entry follows the real ancestor chain.
+    await expectResolution('left-pad', join(f.root, 'work', 'node_modules', 'left-pad'), 24)
+    // Package imports and self-references keep their Node semantics inside the linked package.
+    expect(require.resolve('#core')).toBe(join(f.installed, 'index.cjs'))
+    expect(resolveFrom('#core', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(require('my-plugin')).toEqual({ marker: 30 })
+    expect(resolveFrom('my-plugin', parent)).toBe(pathToFileURL(join(linkedRoot, 'index.js')).href)
+    // A transitive dependency sees its own local layer first and the linked package's peers at the layer above.
+    const helperImporter = { require: createRequire(join(helper, 'entry.cjs')), parent: pathToFileURL(join(helper, 'entry.mjs')).href }
+    await expectResolution('sibling', join(dirname(helper), 'sibling'), 26, helperImporter)
+    await expectResolution('@deepseek-ai/dsh-core', f.installed, 1, helperImporter)
+    // The profile still reaches the linked plugin through Node's own symlink handling.
+    const profileRequire = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(profileRequire.resolve('my-plugin')).toBe(join(linkedRoot, 'index.cjs'))
+    expect(resolveFrom('my-plugin', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href))
+      .toBe(pathToFileURL(join(linkedRoot, 'index.js')).href)
+  })
+
+  it('continues above a linked plugin after a CommonJS subpath miss in an occupied peer', async () => {
+    const { f, linkedRoot } = linkedPluginFixture()
+    file(join(f.installed, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '1.0.0', main: './index.cjs' }))
+    const above = join(f.root, 'work', 'node_modules', '@deepseek-ai', 'dsh-core')
+    file(join(above, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '3.0.0' }))
+    file(join(above, 'sub.cjs'), 'module.exports = { marker: 3 }\n')
+    file(join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-core', 'sub.cjs'), 'module.exports = { marker: 21 }\n')
+    const registration = installRuntimeInterception(await resolutionOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(linkedRoot, 'entry.cjs'))
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs'))
+    // The occupied name never falls back to the devDependency copy at the same layer.
+    expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs')).toBe(join(above, 'sub.cjs'))
+    expect(require('@deepseek-ai/dsh-core/sub.cjs')).toEqual({ marker: 3 })
+  })
+
+  it('preserves the native require stack for a missing linked legacy subpath', async () => {
+    const { f, linkedRoot } = linkedPluginFixture()
+    const name = '@deepseek-ai/dsh-core'
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name, version: '1.0.0', type: 'module', main: './index.cjs',
+    }))
+    rmSync(join(linkedRoot, 'node_modules', name), { recursive: true })
+    const importer = join(linkedRoot, 'entry.cjs')
+    const require = createRequire(importer)
+    const request = `${name}/missing.cjs`
+    const nativeError = thrownError(() => require.resolve(request))
+    expect(nativeError.code).toBe('MODULE_NOT_FOUND')
+    expect(nativeError.requireStack).toEqual([importer])
+
+    const registration = installRuntimeInterception(await resolutionOf(f))
+    registrations.push(registration)
+    try {
+      const runtimeError = thrownError(() => require.resolve(request))
+      expect(runtimeError.code).toBe(nativeError.code)
+      expect(runtimeError.requireStack).toEqual(nativeError.requireStack)
+      expect(runtimeError.message).toBe(nativeError.message)
+    } finally {
+      registration.dispose()
+      registrations.pop()
+    }
+  })
+
+  it('reads a linked plugin manifest at every resolution', async () => {
+    const { f, linkedRoot, writeManifest } = linkedPluginFixture({})
+    const registration = installRuntimeInterception(await resolutionOf(f))
+    registrations.push(registration)
+    const devCopy = join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-core')
+    const require = createRequire(join(linkedRoot, 'entry.cjs'))
+    const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs'))
+    expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(devCopy, 'index.js')).href)
+    expect(registration.packageDir('@deepseek-ai/dsh-core', parent)).toBe(devCopy)
+
+    writeManifest({ '@deepseek-ai/dsh-core': '*' })
+    // No memo holds for a linked importer, and the occupied name delegates from the entry's declaring manifest,
+    // a parent Node has never resolved this request from.
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs'))
+    expect(registration.packageDir('@deepseek-ai/dsh-core', parent)).toBe(f.installed)
+    expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(await importFrom('@deepseek-ai/dsh-core', parent)).toMatchObject({ marker: 1 })
+
+    writeManifest({})
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs'))
+    expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(devCopy, 'index.js')).href)
+    expect(registration.packageDir('@deepseek-ai/dsh-core', parent)).toBe(devCopy)
+    writeManifest(undefined)
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs'))
+    // Without a manifest the linked package occupies nothing.
+    rmSync(join(linkedRoot, 'package.json'))
+    expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs'))
+  })
+
+  it('reads ancestor peer declarations at every linked resolution', async () => {
+    const { f, linkedRoot } = linkedPluginFixture({})
+    const name = '@deepseek-ai/dsh-core'
+    rmSync(join(linkedRoot, 'node_modules', name), { recursive: true })
+    const ancestor = dirname(linkedRoot)
+    const ancestorCopy = join(ancestor, 'node_modules', name)
+    pkg(ancestorCopy, name, 31)
+    const manifestPath = join(ancestor, 'package.json')
+    const manifest = { name: 'plugin-workspace', private: true }
+    file(manifestPath, JSON.stringify(manifest))
+    const require = createRequire(join(linkedRoot, 'entry.cjs'))
+    const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href
+    const registration = installRuntimeInterception(await resolutionOf(f))
+    registrations.push(registration)
+    try {
+      for (const [peerDependencies, expectedDir] of [
+        [undefined, ancestorCopy],
+        [{ [name]: '*' }, f.installed],
+        [undefined, ancestorCopy],
+      ] as const) {
+        file(manifestPath, JSON.stringify({ ...manifest, peerDependencies }))
+        expect(require.resolve(name)).toBe(join(expectedDir, 'index.cjs'))
+        expect(resolveFrom(name, parent)).toBe(pathToFileURL(join(expectedDir, 'index.js')).href)
+        expect(registration.packageDir(name, parent)).toBe(expectedDir)
+      }
+    } finally {
+      registration.dispose()
+      registrations.pop()
+    }
+  })
+
   it('restores CommonJS resolution when the registration is disposed', async () => {
     const f = fixture()
     const registration = installRuntimeInterception(await resolutionOf(f))
diff --git a/packages/boot/app-boot/tests/profile.spec.ts b/packages/boot/app-boot/tests/profile.spec.ts
index fa6de1ddaf..3aec80e6e9 100644
--- a/packages/boot/app-boot/tests/profile.spec.ts
+++ b/packages/boot/app-boot/tests/profile.spec.ts
@@ -84,7 +84,7 @@ function stageProfile(home: string, name: string, bundleAnchor: string): Profile
     layers: [{
       packageName,
       packageDir: join(bundleAnchor, '..'),
-      patchPath: join(bundleAnchor, '..', 'cordis.patch.yml'),
+      patchPaths: [join(bundleAnchor, '..', 'cordis.patch.yml')],
       patches: [],
     }],
     patchPath: join(dir, PROFILE_PATCH_FILENAME),
@@ -302,6 +302,40 @@ describe('loadProfile', () => {
     expect(bare.layers).toEqual([])
   })
 
+  it('applies a dsh.bundle.patch list in order, anchoring inserted paths beside each file', () => {
+    const anchor = stageInstallation({ 'multi': { patch: '[]\n' }, 'broken': { patch: '[]\n' } })
+    const bundleDir = join(anchor, '..', 'node_modules', 'multi')
+    mkdirSync(join(bundleDir, 'layers'), { recursive: true })
+    writeFileSync(join(bundleDir, 'package.json'), JSON.stringify({
+      name: 'multi', version: '0.0.0', type: 'module', main: './index.js',
+      dsh: { bundle: { patch: ['./first.patch.yml', './layers/second.patch.yml'] } },
+    }))
+    writeFileSync(join(bundleDir, 'first.patch.yml'), '- insert:\n    - id: a\n      name: ./local.js\n      config: { v: 1 }\n')
+    writeFileSync(join(bundleDir, 'layers', 'second.patch.yml'), '- id: a\n  config: { v: 2 }\n- insert:\n    - id: b\n      name: ./local.js\n')
+    const brokenManifest = join(anchor, '..', 'node_modules', 'broken', 'package.json')
+    writeFileSync(brokenManifest, JSON.stringify({ name: 'broken', version: '0.0.0', dsh: { bundle: { patch: [1] } } }))
+    const home = tmp()
+    const dir = resolveProfileDir('demo', home)
+    initProfile(dir, ['multi', 'broken'])
+    const warn = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    onTestFinished(() => { warn.mockRestore() })
+
+    const profile = loadProfile('t', 'demo', anchor, home)
+    expect(profile.layers.map(layer => ({ ...layer, patches: layer.patches.length }))).toEqual([{
+      packageName: 'multi',
+      packageDir: bundleDir,
+      patchPaths: [join(bundleDir, 'first.patch.yml'), join(bundleDir, 'layers', 'second.patch.yml')],
+      patches: 3,
+    }])
+    expect(composeEntries(profile.layers.map(layer => layer.patches))).toEqual([
+      { id: 'a', name: pathToFileURL(join(bundleDir, 'local.js')).href, config: { v: 2 } },
+      { id: 'b', name: pathToFileURL(join(bundleDir, 'layers', 'local.js')).href },
+    ])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(
+      'skipping profile bundle "broken": Error: dsh.bundle.patch must be a file path or a list of file paths',
+    ))
+  })
+
   it('auto-initializes only shipped templates and fails loud otherwise', () => {
     const anchor = stageInstallation({})
     const home = tmp()
@@ -502,7 +536,7 @@ describe('createRuntimeResolution', () => {
       layers: [{
         packageName: 'selected-bundle',
         packageDir: bundleLink,
-        patchPath: join(bundleLink, 'cordis.patch.yml'),
+        patchPaths: [join(bundleLink, 'cordis.patch.yml')],
         patches: [],
       }],
       patchPath: join(dir, PROFILE_PATCH_FILENAME),
@@ -552,7 +586,7 @@ describe('createRuntimeResolution', () => {
       layers: ([['bundle-a', bundleA], ['bundle-b', bundleB]] as const).map(([packageName, packageDir]) => ({
         packageName,
         packageDir,
-        patchPath: join(packageDir, 'cordis.patch.yml'),
+        patchPaths: [join(packageDir, 'cordis.patch.yml')],
         patches: [],
       })),
       patchPath: join(dir, PROFILE_PATCH_FILENAME),
diff --git a/packages/boot/hmr/README.i18n.yaml b/packages/boot/hmr/README.i18n.yaml
index bb50a0f843..2a8a9c45e5 100644
--- a/packages/boot/hmr/README.i18n.yaml
+++ b/packages/boot/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/boot/hmr/README.md
-README.md: 735b37c41e50c6a1f663cbfa0cde42f7250ec415
-README.zh.md: b0d3196913cb11e434b397350c81ad1bb45dc0c6
+README.md: 9e2c62c739c420ceae3db3fd5ade58d6eeadacec
+README.zh.md: fa926d5998f7f4b784fe2f848b5acc3047b91b77
diff --git a/packages/boot/hmr/README.md b/packages/boot/hmr/README.md
index 735b37c41e..9e2c62c739 100644
--- a/packages/boot/hmr/README.md
+++ b/packages/boot/hmr/README.md
@@ -54,7 +54,7 @@ Chokidar options, including polling, retain their existing meaning. Exact config
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-`watchConfig()` registers an awaited configuration handler. `runExclusive()` serializes configuration changes and Loader updates with automatic reloads and rejects nested transactions. Package installation and removal run outside this queue. HMR does not acquire the package writer lock; manifest notifications reload only when the ordered `dsh.profile.bundles` list changes. Profile and home patch changes also trigger recomposition. File events received during a configuration transaction are processed afterward.
+`watchConfig()` registers an awaited configuration handler. `runExclusive()` serializes configuration changes and Loader updates with automatic reloads and rejects nested transactions. Package installation and removal run outside this queue. HMR does not acquire the package writer lock; manifest notifications reload only when the ordered `dsh.profile.bundles` list changes. Profile and home patch changes also trigger recomposition. File events received during a configuration transaction are processed afterward. Include refreshes and profile reconciliation reach plugins through ordinary Loader entry updates; Loader commits volatile-only changes in place.
 
 App-boot owns profile parsing and patch precedence. HMR reads the launcher’s data-only `profileContext`, registers the profile manifest and both user patch watches during initialization, and waits for application readiness before processing changes. Its disposal closes the watchers and cancels reloads waiting for startup. HMR also owns module-cache replacement and reload scheduling. Configuration watchers start outside the active transaction context so later notifications can enter the queue. No invariant companion is published because the queue and watcher registrations have no independent persisted projection.
 
diff --git a/packages/boot/hmr/README.zh.md b/packages/boot/hmr/README.zh.md
index b0d3196913..fa926d5998 100644
--- a/packages/boot/hmr/README.zh.md
+++ b/packages/boot/hmr/README.zh.md
@@ -54,7 +54,7 @@ Chokidar 选项（包括轮询）保持原有含义。精确配置监听同时
 <details>
 <summary>实现细节——点击展开</summary>
 
-`watchConfig()` 注册会被等待的配置处理器。`runExclusive()` 将配置变更、Loader 更新与自动重载串行化，并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁；manifest 通知仅在有序的 `dsh.profile.bundles` 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。
+`watchConfig()` 注册会被等待的配置处理器。`runExclusive()` 将配置变更、Loader 更新与自动重载串行化，并拒绝嵌套事务。包安装和删除在该队列之外执行。HMR 不获取包操作写锁；manifest 通知仅在有序的 `dsh.profile.bundles` 列表变化时触发重载。profile 与 home patch 变化也会触发重新组合。配置事务期间收到的文件事件在事务结束后处理。 Include 刷新和 profile 重载都通过普通的 Loader 条目更新到达插件；仅 volatile 变化由 Loader 就地提交。
 
 App-boot 负责 profile 解析和 patch 优先级规则。HMR 读取启动器提供的纯数据 `profileContext`，在初始化时注册 profile manifest 和两份用户 patch 的监听，并等待应用就绪后处理更改。销毁 HMR 时会关闭监听器并取消等待启动的重载。HMR 也负责模块缓存替换和重载调度。配置监听器在当前事务上下文之外启动，使后续通知可以进入队列。不发布 invariant 伴生入口，因为队列和监听注册没有独立的持久投影。
 
diff --git a/packages/boot/hmr/tests/modules.spec.ts b/packages/boot/hmr/tests/modules.spec.ts
index 6e2a7e12a9..93b96a007c 100644
--- a/packages/boot/hmr/tests/modules.spec.ts
+++ b/packages/boot/hmr/tests/modules.spec.ts
@@ -7,6 +7,7 @@ import NodeModule, { createRequire } from 'node:module'
 import { Context, type Plugin } from '@deepseek-ai/cordis'
 import Loader, { type ModuleJob, type ModuleLoader } from '@deepseek-ai/cordis-plugin-loader'
 import Timer from '@deepseek-ai/cordis-plugin-timer'
+import z from '@deepseek-ai/schemastery'
 import { expect, it, onTestFinished, vi } from 'vitest'
 import Hmr from '../src/index.ts'
 
@@ -87,6 +88,31 @@ it.each(['v1', 'v2'] as const)('replaces a %s module and retains the latest Load
   expect(mounted.at(-1)).toBe('after:next')
 })
 
+it('replaces volatile references on code HMR after an in-place config update', async () => {
+  const { ctx, module, imports, reload } = await fixture()
+  const Config = z.object({ value: z.string().volatile() })
+  const configs: ReturnType<typeof Config>[] = []
+  const before = { Config, apply(_ctx: Context, config: ReturnType<typeof Config>) { configs.push(config) } }
+  const after = { Config, apply(_ctx: Context, config: ReturnType<typeof Config>) { configs.push(config) } }
+  const job = module('volatile.mjs', before)
+  const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url, config: { value: 'initial' } }))
+  await ctx.loader.await()
+  await entry.update({ config: { value: 'current' } })
+  await ctx.loader.await()
+  expect(configs).toHaveLength(1)
+  const old = configs[0]!.value
+  expect(old.get()).toBe('current')
+  imports.set(job.url, after)
+  reload.stashed.add(job.url)
+  await reload.partialReload()
+  expect(configs).toHaveLength(2)
+  expect(configs[1]!.value).not.toBe(old)
+  expect(configs[1]!.value.get()).toBe('current')
+  await entry.update({ config: { value: 'after-reload' } })
+  expect(configs[1]!.value.get()).toBe('after-reload')
+  expect(old.get()).toBe('current')
+})
+
 it('reactivates a source-replaced consumer after provider and consumer configuration changes', async () => {
   const { ctx, module, imports, reload } = await fixture()
   const mounted: string[] = []
diff --git a/packages/boot/plugin-manager/src/index.ts b/packages/boot/plugin-manager/src/index.ts
index e03b361dc7..43fedca432 100644
--- a/packages/boot/plugin-manager/src/index.ts
+++ b/packages/boot/plugin-manager/src/index.ts
@@ -13,7 +13,7 @@ import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol'
 import { pluginEntryId, readPluginInventory } from '@deepseek-ai/dsh-host-plugin-inventory'
 import {
   readPluginMeta, readProfileManifest, resolveBundleDir, loadOverlayPatches, composeEntries,
-  reconcileProfilePatches, readProfilePatches, OPTIONAL_BUNDLES,
+  reconcileProfilePatches, readProfilePatches, OPTIONAL_BUNDLES, bundlePatchPaths,
 } from '@deepseek-ai/dsh-app-boot'
 import type {} from '@deepseek-ai/dsh-hmr'
 import type { ProfileContext, ProfileManifest } from '@deepseek-ai/dsh-app-boot'
@@ -475,8 +475,8 @@ export class PluginManager extends TypertRemoteService {
         name = target
         const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir)
         const manifest = bundleManifest(name, this.profile.dir, this.profile.installAnchor)
-        if (manifest?.dsh?.bundle?.patch === undefined) throw new ManagementFailure('not-bundle')
-        loadOverlayPatches('dsh', join(dir, manifest.dsh.bundle.patch))
+        if (manifest?.dsh?.bundle === undefined) throw new ManagementFailure('not-bundle')
+        for (const file of bundlePatchPaths(dir, manifest.dsh.bundle)) loadOverlayPatches('dsh', file)
       } catch (error) {
         // pnpm has exited by now, so the files it rewrote go back as they were.
         await this.restoreFiles(files)
@@ -556,11 +556,11 @@ export class PluginManager extends TypertRemoteService {
 
   /** The rows a bundle's patch inserts and the existing rows it changes; an unreadable patch throws. */
   private declaredRows(name: string, info: ProfileManifest): Pick<BundleInfo, 'rows' | 'overrides'> {
-    const patch = info.dsh?.bundle?.patch
+    const bundle = info.dsh?.bundle
     /* v8 ignore next -- bundleManifest answers only manifests that declare a patch */
-    if (patch === undefined) return { rows: [], overrides: [] }
+    if (bundle === undefined) return { rows: [], overrides: [] }
     const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir)
-    const patches: PatchOptions[] = loadOverlayPatches('dsh', join(dir, patch))
+    const patches: PatchOptions[] = bundlePatchPaths(dir, bundle).flatMap(file => loadOverlayPatches('dsh', file))
     // One entry per row id: the Loader keeps a single entry for an id, whichever layer declared it last.
     const live = new Map<string, { entryId: PluginEntryId; baseUrl: string | undefined }>()
     for (const entry of this.ctx.loader.entries()) {
@@ -656,7 +656,7 @@ export class PluginManager extends TypertRemoteService {
     const info = bundleManifest(name, this.profile.dir, this.profile.installAnchor)
     if (info?.dsh?.bundle === undefined) return []
     const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir)
-    return flatten(composeEntries([loadOverlayPatches('dsh', join(dir, info.dsh.bundle.patch))]))
+    return flatten(composeEntries([bundlePatchPaths(dir, info.dsh.bundle).flatMap(file => loadOverlayPatches('dsh', file))]))
   }
 
   private protectsManager(name: string): boolean {
diff --git a/packages/boot/plugin-manager/src/operations.ts b/packages/boot/plugin-manager/src/operations.ts
index 984a9d99cf..883e79713e 100644
--- a/packages/boot/plugin-manager/src/operations.ts
+++ b/packages/boot/plugin-manager/src/operations.ts
@@ -5,7 +5,7 @@ import { join, resolve } from 'node:path'
 import { execa } from 'execa'
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import {
-  DEFAULT_PROFILE_BUNDLES, initProfile, PROFILE_TEMPLATES, readProfileManifest,
+  DEFAULT_PROFILE_BUNDLES, bundlePatchPaths, initProfile, PROFILE_TEMPLATES, readProfileManifest,
   resolveBundleDir, resolveProfileDir, loadOverlayPatches, type ProfileManifest,
 } from '@deepseek-ai/dsh-app-boot'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
@@ -86,7 +86,7 @@ async function reconcile(before: ProfileManifest, dir: string, anchor: string, o
       options.onOutput?.(`dsh: warning: ${name} declares no dsh.bundle — installed as a plain dependency, not a profile layer\n`, 'stderr')
       continue
     }
-    loadOverlayPatches('dsh', join(resolveBundleDir('dsh', name, anchor, dir), metadata.dsh.bundle.patch))
+    for (const file of bundlePatchPaths(resolveBundleDir('dsh', name, anchor, dir), metadata.dsh.bundle)) loadOverlayPatches('dsh', file)
     if (!bundles.includes(name)) {
       bundles.push(name)
     }
diff --git a/packages/boot/plugin-manager/tests/manager.spec.ts b/packages/boot/plugin-manager/tests/manager.spec.ts
index 19966e47b8..16fbed9650 100644
--- a/packages/boot/plugin-manager/tests/manager.spec.ts
+++ b/packages/boot/plugin-manager/tests/manager.spec.ts
@@ -217,6 +217,7 @@ it.each(['native', 'runtime'] as const)('reads a disabled bundle and its indepen
   const resolution: RuntimeResolution = {
     profilesDir: join(profile.home, 'profiles'), profileDir: dir,
     localPackageNames: Object.keys(manifest.dependencies),
+    linkedRoots: [],
     entries: [{ name: 'local-child', packageDir: child, version: undefined,
       declarer: join(child, 'package.json'), scope: 'installation' }],
   }
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index 1aaf9da6b4..079942f1d1 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -449,7 +449,7 @@
     # preset; products with a stricter network policy override tool-web. 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
+    # endpoint is configured independently from the model route, so it takes its own
     # base-URL override. Anonymous fetch accepts only public HTTP(S) destinations,
     # resolves and validates every destination, and pins every actual connection.
     # Search is a full auxiliary model request with server-side retrieval, so this
diff --git a/packages/bundle/sdk-app/README.i18n.yaml b/packages/bundle/sdk-app/README.i18n.yaml
index ac62ef092e..1563c25b1f 100644
--- a/packages/bundle/sdk-app/README.i18n.yaml
+++ b/packages/bundle/sdk-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/sdk-app/README.md
-README.md: 0bac09b5a7e355434e35b04f4e9abd3e816505af
-README.zh.md: e0e0d7e1e147c0a2dfaed7014ea0b3a0a9028f2b
+README.md: 6d6106e6dd803cee5c51cee0a38f80705986ddfa
+README.zh.md: 9de1fb6e17f3f83b7d8c2acbf87154b1cdfea38f
diff --git a/packages/bundle/sdk-app/README.md b/packages/bundle/sdk-app/README.md
index 0bac09b5a7..6d6106e6dd 100644
--- a/packages/bundle/sdk-app/README.md
+++ b/packages/bundle/sdk-app/README.md
@@ -33,6 +33,8 @@ The startup provider binds stdin EOF to the launcher's bounded successful shutdo
 
 The SDK uses the base `read`, `write`, and `edit` defaults. To add `str_replace_editor`, use the explicit insertion patch in the [base configuration guide](../base/README.md#use-this-package). The standalone `sdk-minimal` profile owns its separate tool selection.
 
+The packaged Python runtime enables the [Office runtime query and skills](../../skill/tool-workspace-dependencies/README.md#use-this-package) by default. `DSH_PRIMARY_RUNTIME` overrides its bundled payload; an empty value disables both rows. Source launches without a carrier default remain opt-in. The tool reads the payload in place. Profile patches can disable `skill-office` or replace its `assetRoot` independently of `workspace-dependencies`; filesystem skills with the same name take precedence over bundled skills. See the [runtime package](../../../python/sdk-runtime/README.md) for packaging and configuration.
+
 -----
 
 <a id="model-experience"></a>
diff --git a/packages/bundle/sdk-app/README.zh.md b/packages/bundle/sdk-app/README.zh.md
index e0e0d7e1e1..9de1fb6e17 100644
--- a/packages/bundle/sdk-app/README.zh.md
+++ b/packages/bundle/sdk-app/README.zh.md
@@ -33,6 +33,8 @@ kind: "package-bundle"
 
 SDK 使用 base 默认提供的 `read`、`write` 和 `edit`。要添加 `str_replace_editor`，请使用 [base 配置指南](../base/README.zh.md#use-this-package)中的显式插入 patch。独立的 `sdk-minimal` profile 自行决定其工具选择。
 
+打包的 Python runtime 默认启用 [Office 运行时查询与 skills](../../skill/tool-workspace-dependencies/README.zh.md#use-this-package)。`DSH_PRIMARY_RUNTIME` 覆盖随包 payload；空值禁用两行。没有载体默认路径的源码启动仍需显式启用。工具原位读取 payload。profile patch 可独立于 `workspace-dependencies` 禁用 `skill-office` 或替换其 `assetRoot`；同名文件系统 skills 优先于随包 skills。打包与配置见 [runtime 包](../../../python/sdk-runtime/README.zh.md)。
+
 -----
 
 <a id="model-experience"></a>
diff --git a/packages/bundle/sdk-app/cordis.patch.yml b/packages/bundle/sdk-app/cordis.patch.yml
index 91c67debc1..2abfbc952d 100644
--- a/packages/bundle/sdk-app/cordis.patch.yml
+++ b/packages/bundle/sdk-app/cordis.patch.yml
@@ -23,3 +23,18 @@
 
 - id: hmr
   disabled: true
+
+# The packaged carrier supplies a default; DSH_PRIMARY_RUNTIME overrides it,
+# including an empty-string opt-out. Each row can be patched independently.
+- insert:
+    - id: workspace-dependencies
+      name: '@deepseek-ai/dsh-tool-workspace-dependencies'
+      disabled: !!js "!(process.env.DSH_PRIMARY_RUNTIME ?? process.env.DSH_BUNDLED_PRIMARY_RUNTIME)"
+      config:
+        source: !!js "process.getBuiltinModule('node:path').resolve(process.env.DSH_PRIMARY_RUNTIME ?? process.env.DSH_BUNDLED_PRIMARY_RUNTIME ?? '')"
+
+    - id: skill-office
+      name: '@deepseek-ai/dsh-skill-office'
+      disabled: !!js "!(process.env.DSH_PRIMARY_RUNTIME ?? process.env.DSH_BUNDLED_PRIMARY_RUNTIME)"
+      config:
+        assetRoot: !!js "process.getBuiltinModule('node:path').resolve(process.env.DSH_PRIMARY_RUNTIME ?? process.env.DSH_BUNDLED_PRIMARY_RUNTIME ?? '', '..', 'office-skills')"
diff --git a/packages/bundle/sdk-app/package.json b/packages/bundle/sdk-app/package.json
index 45e484464f..bdc3bd2c84 100644
--- a/packages/bundle/sdk-app/package.json
+++ b/packages/bundle/sdk-app/package.json
@@ -37,7 +37,9 @@
     "@deepseek-ai/dsh-cmdline": "workspace:^",
     "@deepseek-ai/dsh-sdk-jsonrpc-server": "workspace:^",
     "@deepseek-ai/schemastery": "workspace:^",
-    "commander": "^15.0.0"
+    "commander": "^15.0.0",
+    "@deepseek-ai/dsh-skill-office": "workspace:^",
+    "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:^"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "workspace:^"
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index 705ff4a9a4..ad5bbccf32 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: 00f523098ada6646a2cf22ce57ca5fef6c6d9afb
-README.zh.md: 2a3ea0d7d480ab2a29aa1d4adcb01836a9b70007
+README.md: 8fea1287610a0a71f2a351a1b8e00af87b20ba44
+README.zh.md: 603108991cd74ba379b3b9d8de9a2ff11bf7e101
diff --git a/packages/bundle/web-app/README.md b/packages/bundle/web-app/README.md
index 00f523098a..8fea128761 100644
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -36,9 +36,9 @@ dsh --profile web --no-open --port 8080
 
 After startup you see a `dsh web:` line whose root URL carries a fresh process token. Unless `--no-open` or an SSH session suppresses it, the default browser opens that URL, receives a signed cookie, and redirects to the same directory without the token. You know it worked when the page loads and you can chat with the agent. Two failures to expect: if the frontend is not built, startup stops with a build hint (`pnpm run build` in a checkout); if the browser cannot be opened, a credential-free diagnostic prints to stderr while the server keeps running — open the printed startup URL yourself.
 
-**Settings → Models** displays **DeepSeek**, using `DEEPSEEK_API_KEY`. The default is `deepseek-official` / `deepseek-flash` (DeepSeek-V41-Flash). The [DeepSeek plugin](../../llm/llm-deepseek/README.md#choose-a-protocol) defaults to Messages; set `protocol: chat-completions` in Cordis YAML to select Chat Completions. Web has no protocol selector.
+**Settings → Models** displays **DeepSeek**, using `DEEPSEEK_API_KEY`. The default is `deepseek-official` / `deepseek-flash` (DeepSeek-V41-Flash). The [DeepSeek plugin](../../llm/llm-deepseek/README.md#endpoint-and-wire-format) uses the Messages API.
 
-Saved model selections override the composition default. Both protocols share `deepseek-official` and `llm-deepseek` settings, so switching preserves model selections and credential references. Endpoint overrides retain their values; the settings card lets users supply a compatible API address.
+Saved model selections override the composition default. The settings card accepts a Messages-compatible API address and a credential reference.
 
 ### Configuration
 
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index 2a3ea0d7d4..603108991c 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -36,9 +36,9 @@ dsh --profile web --no-open --port 8080
 
 启动后你会看到 `dsh web:` 行，其根 URL 携带新的进程 token。除非 `--no-open` 或 SSH 会话抑制，否则默认浏览器会打开该 URL、取得签名 cookie，再重定向到不含认证参数的同一目录。页面加载且你可以与 agent 对话，就说明成功了。两种可预期的失败：前端未构建时，启动会以构建提示停止（checkout 中运行 `pnpm run build`）；浏览器无法打开时，stderr 会打印不含凭据的诊断，但服务器会继续运行——请自行打开已打印的启动 URL。
 
-**设置 → 模型**显示 **DeepSeek**，使用 `DEEPSEEK_API_KEY`。默认模型为 `deepseek-official` / `deepseek-flash`（DeepSeek-V41-Flash）。[DeepSeek 插件](../../llm/llm-deepseek/README.zh.md#choose-a-protocol)默认使用 Messages；在 Cordis YAML 中设置 `protocol: chat-completions` 可选择 Chat Completions。Web 不提供协议选择器。
+**设置 → 模型**显示 **DeepSeek**，使用 `DEEPSEEK_API_KEY`。默认模型为 `deepseek-official` / `deepseek-flash`（DeepSeek-V41-Flash）。[DeepSeek 插件](../../llm/llm-deepseek/README.zh.md#endpoint-and-wire-format)使用 Messages API。
 
-已保存的模型选择优先于组合默认值。两种协议共用 `deepseek-official` 与 `llm-deepseek` 设置，因此切换协议不改变模型选择或复制凭据。端点覆盖保持原值；设置卡片允许用户填写兼容的 API 地址。
+已保存的模型选择覆盖组合默认值。设置卡接受兼容 Messages 的 API 地址与凭据引用。
 
 ### 配置
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 1f4d203152..b069c9bba2 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -102,6 +102,10 @@
     - id: session-controller
       name: '@deepseek-ai/dsh-api-session-controller'
 
+    # One background job's observation record streamed over Typert Remote;
+    # the roster rides the session control stream above.
+    - id: job-controller
+      name: '@deepseek-ai/dsh-api-job-controller'
     # Workspace file service: bounded read, directory listing, and the
     # agent-write change feed inside the session workspace root.
     - id: terminal-controller
@@ -121,6 +125,12 @@
     - id: cordis-host-runner
       name: '@deepseek-ai/dsh-cordis-host-runner'
 
+    # The Host inspect providers are process-global: the registry rejects a
+    # duplicate id, so they register here once and every preset's `tool-cordis`
+    # row reads them.
+    - id: cordis-inspect-providers
+      name: '@deepseek-ai/dsh-tool-cordis/host'
+
     # Ordinary provider for the parsed Web flags. Its plugin-level injection
     # waits for cmdlineArgs; no launcher metadata or special row kind is needed.
     - id: web-startup
@@ -233,9 +243,10 @@
     - id: ui-sidebar-documentpreview
       name: '@deepseek-ai/dsh-client-ui-sidebar-documentpreview'
 
-    # Sandboxed HTTP(S) Browser tabs, including loopback targets.
+    # Web profiles opt in; Desktop retains sandboxed HTTP(S) Browser tabs.
     - id: ui-sidebar-browser
       name: '@deepseek-ai/dsh-client-ui-sidebar-browser'
+      disabled: !!js "ctx.get('profileContext')?.name !== 'desktop'"
 
     - id: ui-sidebar-terminal
       name: '@deepseek-ai/dsh-client-ui-sidebar-terminal'
@@ -323,6 +334,12 @@
     - id: ui-reference
       name: '@deepseek-ai/dsh-client-ui-reference'
 
+
+    # Background jobs: the session-header roster with on-demand streaming
+    # record panels over the session job-output service.
+    - id: ui-jobs
+      name: '@deepseek-ai/dsh-client-ui-jobs'
+
     # Read-only active Schedule catalog. The shipped Web graph resolves the
     # client package but leaves it disabled; the explicit Schedule overlay
     # enables this same row together with the host Schedule services.
@@ -330,10 +347,6 @@
       name: '@deepseek-ai/dsh-client-ui-schedule'
       disabled: true
 
-    # Background jobs: the session-header list over the jobsBySession mirror.
-    - id: ui-jobs
-      name: '@deepseek-ai/dsh-client-ui-jobs'
-
     # Goal surface: GoalBar in the input dock over the goal session projection.
     - id: ui-goal
       name: '@deepseek-ai/dsh-client-ui-goal'
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index cc00c61d15..049587c941 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -40,6 +40,7 @@
   },
   "dependencies": {
     "@deepseek-ai/dsh-agent-presets": "workspace:^",
+    "@deepseek-ai/dsh-api-job-controller": "workspace:^",
     "@deepseek-ai/dsh-api-remotes": "workspace:^",
     "@deepseek-ai/dsh-api-session-controller": "workspace:^",
     "@deepseek-ai/dsh-api-settings-controller": "workspace:^",
@@ -115,6 +116,7 @@
     "@deepseek-ai/dsh-session-stats": "workspace:^",
     "@deepseek-ai/dsh-session-turn-outline": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-tool-cordis": "workspace:^",
     "@deepseek-ai/dsh-tool-subagent": "workspace:^",
     "@deepseek-ai/dsh-web-frontend": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
diff --git a/packages/bundle/web-app/tests/browser-defaults.spec.ts b/packages/bundle/web-app/tests/browser-defaults.spec.ts
new file mode 100644
index 0000000000..73ee9b1a82
--- /dev/null
+++ b/packages/bundle/web-app/tests/browser-defaults.spec.ts
@@ -0,0 +1,41 @@
+/** Profile defaults and explicit overrides for the shipped Browser entry. */
+import { fileURLToPath } from 'node:url'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import { applyEntryPatches } from '@deepseek-ai/cordis-plugin-include'
+import { loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import * as Browser from '@deepseek-ai/dsh-client-ui-sidebar-browser'
+import { expect, it, onTestFinished } from 'vitest'
+
+it.each([
+  { profile: 'web', override: undefined, disabled: true },
+  { profile: 'custom-web', override: undefined, disabled: true },
+  { profile: undefined, override: undefined, disabled: true },
+  { profile: 'desktop', override: undefined, disabled: false },
+  { profile: 'web', override: false, disabled: false },
+  { profile: 'desktop', override: true, disabled: true },
+])('applies Browser availability for $profile with override $override', async ({ profile, override, disabled }) => {
+  const rows = loadOverlayPatches('browser-defaults', fileURLToPath(new URL('../cordis.patch.yml', import.meta.url)))
+    .flatMap(patch => patch.insert ?? []).filter(row => row.id === 'ui-sidebar-browser')
+  expect(rows).toHaveLength(1)
+  expect(rows[0]!.name).toBe('@deepseek-ai/dsh-client-ui-sidebar-browser')
+  const configured = applyEntryPatches(rows, override === undefined ? [] : [{ id: 'ui-sidebar-browser', disabled: override }],
+    (message) => { throw new Error(message) })
+  const ctx = new Context()
+  onTestFinished(() => ctx.fiber.dispose())
+  if (profile !== undefined) {
+    ctx.provide('profileContext', {
+      name: profile, dir: '/profile', patchPath: '/profile/cordis.patch.yml', installAnchor: '/profile/package.json',
+      cwd: '/workspace', home: '/home', startedBundles: [], overlays: [], telemetryDisabledEnv: undefined,
+    })
+  }
+  ctx.baseUrl = 'file:///'
+  await ctx.plugin(Loader).await()
+  // Keep the real companion in the source-plane loader without native package resolution.
+  ctx.loader.builtins.browser = Browser
+  await ctx.loader.root.update([{ ...configured[0]!, name: 'cordis:browser' }])
+  await ctx.loader.await()
+  const entry = ctx.loader.resolve('ui-sidebar-browser')
+  expect(entry.disabled).toBe(disabled)
+  expect(entry.fiber !== undefined).toBe(!disabled)
+})
diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml
index f77acedd8d..f968140311 100644
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/README.md
-README.md: 3d8e52fe6dfc3e517c09f772e63c073957e41cd9
-README.zh.md: 4a547889b9a12af7e65a671bef9176075d55ebc1
+README.md: a7e1397b4b62d883cbe02c4ec23afe35b9f7be9e
+README.zh.md: 01be68b480626aa77bfb361f4dda28c2d1cdfbd9
diff --git a/packages/client/README.md b/packages/client/README.md
index 3d8e52fe6d..a7e1397b4b 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -62,8 +62,8 @@ The kernel packages boot and serve the page; the UI feature packages present it.
 | [`ui-skill/`](ui-skill/README.md) | Adds skill references to inline suggestions | — |
 | [`ui-reference/`](ui-reference/README.md) | Unified Web `@file` / `@session` reference source | — |
 | [`ui-subagent/`](ui-subagent/README.md) | Provides subagent navigation, child transcript states, and inline references | — |
+| [`ui-jobs/`](ui-jobs/README.md) | Lists this session's background jobs with on-demand streaming record panels | — |
 | [`ui-schedule/`](ui-schedule/README.md) | Lists the current Session's active reminders in a read-only header catalog | — |
-| [`ui-jobs/`](ui-jobs/README.md) | Lists this session's background jobs in the conversation header | — |
 | [`ui-model-selection/`](ui-model-selection/README.md) | Provides model selection in conversation surfaces | — |
 | [`ui-permission-presets/`](ui-permission-presets/README.md) | Configures default permissions and switches the current session's access | — |
 | [`ui-plan/`](ui-plan/README.md) | Presents active plan-mode status and its exit control | — |
diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md
index 4a547889b9..01be68b480 100644
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -62,8 +62,8 @@ kind: "package-group"
 | [`ui-skill/`](ui-skill/README.zh.md) | 向内联建议添加 skill（技能）引用 | — |
 | [`ui-reference/`](ui-reference/README.zh.md) | 统一的 Web `@file` / `@session` 引用 source | — |
 | [`ui-subagent/`](ui-subagent/README.zh.md) | 提供 subagent 导航、子级 transcript（文本记录）状态与内联引用 | — |
+| [`ui-jobs/`](ui-jobs/README.zh.md) | 列出本会话的后台任务，并提供按需展开的流式输出面板 | — |
 | [`ui-schedule/`](ui-schedule/README.zh.md) | 在只读标题栏目录中列出当前会话中生效的提醒 | — |
-| [`ui-jobs/`](ui-jobs/README.zh.md) | 在会话标题栏列出当前会话的后台任务 | — |
 | [`ui-model-selection/`](ui-model-selection/README.zh.md) | 在对话界面中提供模型选择 | — |
 | [`ui-permission-presets/`](ui-permission-presets/README.zh.md) | 配置默认权限并切换当前会话的访问模式 | — |
 | [`ui-plan/`](ui-plan/README.zh.md) | 展示生效中的 plan mode 状态及其退出控件 | — |
diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml
index 3077a60252..fbc282a42b 100644
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/connection/README.md
-README.md: 17bcb9940286b91433273cef2fcda3147249133b
-README.zh.md: 6a090709414007ddb7fe7ca3fdd8c29b737a39dc
+README.md: e50f4fb6838ae27b545bd2b3c4683224f7eb37c9
+README.zh.md: 1bf0733bd660049a5b99a7e7966d65121b0dea3f
diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md
index 17bcb99402..e50f4fb683 100644
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -27,7 +27,9 @@ The package carries browser-to-Host Remote calls, exact Fetch responses, and con
 
 A static desktop page can provide `__DSH_TRANSPORT__.streamBaseUrl` for the HTTP origin of its owned Host. The Gateway uses that origin for its WebSocket while HTTP transport remains independently selected. The desktop carrier owns authentication; setting the origin alone grants no access.
 
-The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams through `connection.rpc.open` without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to `installConnection(ctx, options)`. A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
+Unary RPC requests use JSON. A Host handler may return byte attachments that it has already separated from the JSON-compatible result value, with each attachment naming its result-relative path. Connection writes these values as multipart parts. The JSON `metadata` part contains the RPC response envelope with `null` placeholders and an attachment table recording each path, codec, and part identifier. Paths use string keys and numeric array indices; no business field name is reserved. The Client validates the envelope, `rpcId`, attachment table, and parts, then restores each byte value as an `ArrayBuffer`-backed view. Results without attachments, including base64 strings, and failures remain JSON. Logical RPC carriers return decoded native values directly. Connection does not discover binary fields or depend on Typert; the handler that owns a result protocol performs any type-directed or runtime projection before returning. Binary parameters, events, and streamed binary results are unsupported.
+
+The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams, including a stream's uplink, through `connection.rpc.open` without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to `installConnection(ctx, options)`. A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
 
 -----
 
@@ -40,7 +42,9 @@ The cookie signing secret is the owner-scoped `client-connection/browser-session
 
 Before authentication, every request still passes `src/api-request-trust.ts`. Its `Host` must be loopback or match a `trustedHosts` entry: exact on `host:port`, any port on port-less entries, both sides WHATWG-normalized. An attached `Origin` must equal that Host and `sec-fetch-site: cross-site` is refused. Malformed configured authorities fail plugin load. These checks defend DNS rebinding and cross-site browser requests; they never establish identity. A failed Host/Origin check returns 403, while a trusted but unauthenticated request returns 401. `dsh web --host 0.0.0.0` remains unsupported. Decision records: [browser request trust](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md) and [browser token authentication](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.md).
 
-Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. WebSocket stream ownership remains with API Gateway.
+Every admitted request speaks for one Peer, the operator. `ctx.connection.operator` is that `PeerScope`: its `ctx` is a Cordis scope that owns connection-lifetime registrations and is disposed with the Connection. `ctx.connection.admit(request)` runs the trust and authentication checks and answers with the rejection status or the operator; the `/api` route and the Gateway's WebSocket upgrade admit through it, and every RPC handler receives the Peer of its call. `OperatorPeer` is exported so a composition without Connection, such as the Gateway's in-process carrier, owns an operator scope with the same contract.
+
+Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. Client disconnection aborts the handler signal; the bridge stops socket writes and drains any remaining response chunks. WebSocket stream ownership remains with API Gateway.
 
 <a id="connection-generation"></a>
 ## Connection generation
diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md
index 6a09070941..1bf0733bd6 100644
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -27,7 +27,9 @@ kind: "package-reference"
 
 静态桌面页面可以通过 `__DSH_TRANSPORT__.streamBaseUrl` 提供其所拥有 Host 的 HTTP origin。Gateway 将该 origin 用于 WebSocket，HTTP 传输仍独立选择。桌面载体负责认证；仅设置 origin 不会授予访问权限。
 
-浏览器通过 HTTP POST 执行 Remote 一元调用；API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流，不打开 WebSocket。浏览器插件读取页面 transport、恢复设置与 location，再委托 `installConnection(ctx, options)`。持有自身载体的组合可以直接调用同一个安装函数；整机客户端测试档就是这一消费者。每次调用都会创建一个归所属 Context 的服务，因此同一 realm 中的多棵 Client 树可以使用不同载体。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时，它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验；由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
+一元 RPC 请求使用 JSON。Host handler 可以返回已经从 JSON 兼容结果值中分离的字节附件，每个附件标明其相对于结果的路径。Connection 将这些值写为 multipart 部分。JSON `metadata` 部分包含带 `null` 占位值的 RPC 响应信封，以及记录各路径、codec 和部分标识符的附件表。路径使用字符串键与数字数组下标，不保留任何业务字段名。Client 校验信封、`rpcId`、附件表和各部分，再将每个字节值恢复为以 `ArrayBuffer` 为底层缓冲区的视图。没有附件的结果（包括 base64 字符串）与失败仍使用 JSON。逻辑 RPC 载体直接返回解码后的原生值。Connection 不识别二进制字段，也不依赖 Typert；拥有结果协议的 handler 在返回前执行按类型或按运行时值的投影。不支持二进制参数、事件和二进制流式结果。
+
+浏览器通过 HTTP POST 执行 Remote 一元调用；API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流（包括流的上行），不打开 WebSocket。浏览器插件读取页面 transport、恢复设置与 location，再委托 `installConnection(ctx, options)`。持有自身载体的组合可以直接调用同一个安装函数；整机客户端测试档就是这一消费者。每次调用都会创建一个归所属 Context 的服务，因此同一 realm 中的多棵 Client 树可以使用不同载体。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时，它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验；由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
 
 -----
 
@@ -40,7 +42,9 @@ cookie 签名密钥是 `ctx.credentials` 中由 `client-connection/browser-sessi
 
 认证之前，每个请求仍经过 `src/api-request-trust.ts`。其 `Host` 必须是 loopback，或与 `trustedHosts` 条目匹配：带端口的 `host:port` 精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化。若附带 `Origin`，它必须等于该 Host；`sec-fetch-site: cross-site` 一律拒绝。畸形配置 authority 会让插件加载失败。这些检查防御 DNS rebinding 与跨站浏览器请求，绝不建立身份。Host/Origin 校验失败返回 403；Host 可信但未认证的请求返回 401。`dsh web --host 0.0.0.0` 仍不受支持。决策记录：[浏览器请求信任](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md)与[浏览器令牌认证](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.zh.md)。
 
-通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求，或等待 `next()` 直到响应完成；释放所属 fiber 会移除准入行为。Desktop 使用此扩展点，在已批准的安装期间锁住新的 API 工作，而不取消已接纳的工作。WebSocket 流仍由 API Gateway 负责。
+每个被接纳的请求都代表同一个 Peer——操作者。`ctx.connection.operator` 就是这个 `PeerScope`：其 `ctx` 是拥有连接期注册的 Cordis scope，随 Connection 一起释放。`ctx.connection.admit(request)` 执行信任与认证检查，以拒绝状态或操作者作答；`/api` 路由与 Gateway 的 WebSocket 升级都经它接纳，每个 RPC 处理器都收到本次调用的 Peer。`OperatorPeer` 对外导出，供没有 Connection 的组合（例如 Gateway 的进程内载体）以同一约定拥有一个操作者 scope。
+
+通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求，或等待 `next()` 直到响应完成；释放所属 fiber 会移除准入行为。Desktop 使用此扩展点，在已批准的安装期间锁住新的 API 工作，而不取消已接纳的工作。客户端断开会中止处理函数的信号；桥接器停止写入 socket，并排空剩余响应块。WebSocket 流仍由 API Gateway 负责。
 
 <a id="connection-generation"></a>
 ## Connection generation
diff --git a/packages/client/connection/package.json b/packages/client/connection/package.json
index ea8af1e498..8b95205a05 100644
--- a/packages/client/connection/package.json
+++ b/packages/client/connection/package.json
@@ -44,7 +44,8 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-scope": "workspace:^"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
@@ -52,6 +53,8 @@
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^"
+    "@deepseek-ai/dsh-scope": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^"
   }
 }
diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts
index fef3b234bb..c5d5c9b394 100644
--- a/packages/client/connection/src/client/rpc.ts
+++ b/packages/client/connection/src/client/rpc.ts
@@ -17,11 +17,12 @@ const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
  */
 export type RpcFetch = (input: string | URL, init: RequestInit) => Promise<Response>
 
-/** Worker-local opener for decoded Gateway Remote streams. */
+/** Worker-local opener for decoded Gateway Remote streams; `uplink` carries the Client's items for the stream. */
 export type RpcStreamOpen = (
   endpoint: string,
   payload: unknown,
   signal: AbortSignal,
+  uplink?: AsyncIterable<unknown>,
 ) => AsyncIterable<unknown>
 
 /**
@@ -57,24 +58,86 @@ export function createWebConnectionRpc(doFetch?: RpcFetch, openStream?: RpcStrea
       if (!response.ok) {
         throw new Error(`transport failure for ${channel}/${endpoint}: HTTP ${response.status}`)
       }
-      const full = parseConnectionResponse(await response.json())
+      const mediaType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+      const full = mediaType === 'multipart/form-data'
+        ? await parseBinaryResponse(response)
+        : parseConnectionResponse(await response.json())
+      signal?.throwIfAborted()
       if (full.rpcId !== rpcId) {
         throw new Error(`rpcId mismatch for ${endpoint}: sent ${rpcId}, got ${full.rpcId}`)
       }
       return full.result
     },
     ...openStream === undefined ? {} : {
-      open(channel, endpoint, payload, signal) {
+      open(channel, endpoint, payload, signal, uplink) {
         assertTarget(channel, endpoint)
         if (channel !== '/api') {
           throw new Error(`connection: worker-local streams require the /api channel, got ${JSON.stringify(channel)}`)
         }
-        return openStream(endpoint, payload, signal)
+        return openStream(endpoint, payload, signal, uplink)
       },
     },
   }
 }
 
+async function parseBinaryResponse(response: Response): Promise<ReturnType<typeof parseConnectionResponse>> {
+  const body = await response.formData()
+  const fields = new Map<string, string | Blob>()
+  for (const [name, value] of body) {
+    if (fields.has(name)) throw new TypeError('connection: invalid binary response fields')
+    fields.set(name, value)
+  }
+  const metadata = fields.get('metadata')
+  fields.delete('metadata')
+  if (typeof metadata !== 'string') {
+    throw new TypeError('connection: invalid binary response fields')
+  }
+  const envelope: unknown = JSON.parse(metadata)
+  const full = parseConnectionResponse(envelope)
+  if (!full.result.ok || !isRecord(envelope) || !Array.isArray(envelope.attachments) || envelope.attachments.length === 0) {
+    throw new TypeError('connection: invalid binary response result')
+  }
+  const root = { value: full.result.value }
+  for (const attachment of envelope.attachments) {
+    if (!isRecord(attachment) || attachment.codec !== 'bytes' || typeof attachment.part !== 'string'
+      || !Array.isArray(attachment.path)) {
+      throw new TypeError('connection: invalid binary response attachment')
+    }
+    const data = fields.get(attachment.part)
+    fields.delete(attachment.part)
+    if (!(data instanceof Blob)) {
+      throw new TypeError('connection: invalid binary response fields')
+    }
+    let parent: object = root
+    let key: string | number = 'value'
+    for (const segment of attachment.path) {
+      const value: unknown = Reflect.get(parent, key)
+      if (typeof value !== 'object' || value === null) {
+        throw new TypeError('connection: invalid binary response path')
+      }
+      if (Array.isArray(value)) {
+        if (typeof segment !== 'number' || !Number.isSafeInteger(segment) || segment < 0 || segment >= value.length) {
+          throw new TypeError('connection: invalid binary response path')
+        }
+      } else if (typeof segment !== 'string') {
+        throw new TypeError('connection: invalid binary response path')
+      }
+      if (!Object.hasOwn(value, segment)) throw new TypeError('connection: invalid binary response path')
+      parent = value
+      key = segment
+    }
+    if (Reflect.get(parent, key) !== null) throw new TypeError('connection: invalid binary response placeholder')
+    Object.defineProperty(parent, key, {
+      value: new Uint8Array(await data.arrayBuffer()), enumerable: true, writable: true, configurable: true,
+    })
+  }
+  if (fields.size !== 0) throw new TypeError('connection: invalid binary response fields')
+  return {
+    rpcId: full.rpcId,
+    result: { ok: true, value: root.value },
+  }
+}
+
 function parseConnectionResponse(value: unknown): {
   readonly rpcId: RpcIdType
   readonly result: ConnectionRpcResult<unknown>
diff --git a/packages/client/connection/src/http-bridge.ts b/packages/client/connection/src/http-bridge.ts
index ff6042d117..713f53dcea 100644
--- a/packages/client/connection/src/http-bridge.ts
+++ b/packages/client/connection/src/http-bridge.ts
@@ -3,7 +3,7 @@
  * web carrier; the fetch-shaped handler itself is transport-agnostic).
  */
 
-import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { IncomingMessage } from 'node:http'
 import { Readable } from 'node:stream'
 import type { ConnectionFetchHandler } from './rpc.ts'
 
@@ -13,9 +13,20 @@ import type { ConnectionFetchHandler } from './rpc.ts'
  * each body in memory, so this cap is also the per-request resident bound. */
 export const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024
 
+interface BridgeServerResponse {
+  readonly destroyed: boolean
+  readonly writableEnded: boolean
+  on(event: 'close', listener: () => void): this
+  off(event: 'close' | 'drain', listener: () => void): this
+  once(event: 'close' | 'drain', listener: () => void): this
+  writeHead(statusCode: number, headers?: Record<string, string>): unknown
+  write(chunk: Uint8Array): boolean
+  end(): unknown
+}
+
 /**
  * Bridge one node:http request to the fetch-shaped handler (client close
- * aborts; response bodies stream out chunk by chunk).
+ * aborts; response writes respect backpressure and stop on disconnect).
  * @param req - incoming node:http request.
  * @param res - node:http response the bridge writes and owns to completion.
  * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
@@ -23,7 +34,7 @@ export const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024
  */
 export async function bridge(
   req: IncomingMessage,
-  res: ServerResponse,
+  res: BridgeServerResponse,
   apiHandler: ConnectionFetchHandler,
   maxRequestBodyBytes = DEFAULT_MAX_REQUEST_BODY_BYTES,
 ): Promise<void> {
@@ -90,11 +101,13 @@ export async function bridge(
     return
   }
   for await (const chunk of response.body) {
+    // Drain without writing after disconnect: cancelling Node multipart bodies
+    // can race their producer and reject with ERR_INVALID_STATE.
+    if (abort.signal.aborted) continue
     // Backpressure: a false return means the socket buffer is full — wait for drain
     // instead of buffering unboundedly (slow or suspended consumers). 'close' also
-    // resolves so a mid-wait disconnect can't park this loop forever; the close
-    // handler above aborts the handler stream, which then ends the iteration.
-    if (!res.write(chunk)) {
+    // resolves so a mid-wait disconnect cannot park this loop forever.
+    if (!res.write(chunk) && !res.destroyed) {
       await new Promise<void>((resolve) => {
         const done = (): void => {
           res.off('drain', done)
diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts
index 7a4457e375..647174f743 100644
--- a/packages/client/connection/src/index.ts
+++ b/packages/client/connection/src/index.ts
@@ -14,14 +14,17 @@ import { HostConnectionService } from './rpc-host.ts'
 import { ConnectionRecoveryConfigSchema, resolveConnectionConfig, type ConnectionRecoveryConfig } from './recovery-config.ts'
 
 export type {
+  PeerAdmission,
   ConnectionFetchMethod,
   ConnectionFetchHandler,
   ConnectionFetchRoute,
   ConnectionIndexRequest,
   ConnectionIndexResponse,
   ConnectionRpcEndpointMatcher,
+  ConnectionRpcAttachment,
   ConnectionRpcFailure,
   ConnectionRpcHandler,
+  ConnectionRpcHandlerResult,
   ConnectionRequestRejection,
   ConnectionRpcResult,
   ConnectionRequestBodyMode,
@@ -33,7 +36,9 @@ export type {
   RpcMessage,
   ServerResponse,
 } from './rpc.ts'
+export type { PeerId, PeerScope, RemoteInvocation } from '@deepseek-ai/dsh-typert-protocol'
 export { RpcId, transportError } from './rpc.ts'
+export { OperatorPeer } from './operator-peer.ts'
 export {
   clientRequestSchema,
   rpcErrorSchema,
@@ -141,10 +146,10 @@ export async function apply(ctx: Context, config?: ConnectionConfig): Promise<vo
       kind: 'prefix',
       path: API_PATH,
       handler: async (req, res) => {
-        const rejection = connection.requestRejection(req)
-        if (rejection !== undefined) {
-          res.writeHead(rejection)
-          res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+        const admission = connection.admit(req)
+        if ('rejection' in admission) {
+          res.writeHead(admission.rejection)
+          res.end(admission.rejection === 401 ? 'unauthorized' : 'forbidden')
           return
         }
         await webCtx.waterfall('connection/request', req, res, () => bridge(req, res, fetchHandler, maxRequestBodyBytes))
diff --git a/packages/client/connection/src/operator-peer.ts b/packages/client/connection/src/operator-peer.ts
new file mode 100644
index 0000000000..83325f78e7
--- /dev/null
+++ b/packages/client/connection/src/operator-peer.ts
@@ -0,0 +1,33 @@
+/**
+ * The operator Peer: the one party this Host answers to. Connection owns it
+ * for its own lifetime, admits every request as it, and hands it to each
+ * Remote call as `invocation.peer`.
+ * @module @deepseek-ai/dsh-client-connection/src/operator-peer
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import { createScope, type Scope } from '@deepseek-ai/dsh-scope'
+import type { PeerId, PeerScope } from '@deepseek-ai/dsh-typert-protocol'
+
+/**
+ * The operator's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
+ * returns it and events dispatched with `scopeTarget(subject, peer)` reach
+ * listeners registered through `peer.ctx` and nobody else.
+ */
+export class OperatorPeer implements PeerScope {
+  readonly id: PeerId = randomUUID() as PeerId
+  readonly ctx: Context
+  private readonly scope: Scope
+
+  /** @param owner - Connection plugin context the scope fiber hangs under. */
+  constructor(owner: Context) {
+    this.scope = createScope(owner, this)
+    this.ctx = this.scope.ctx
+  }
+
+  /** Tear down every connection-lifetime registration; racing calls share one completion. */
+  dispose(): Promise<void> {
+    return this.scope.dispose()
+  }
+}
diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts
index d74734e132..0f98bc1f19 100644
--- a/packages/client/connection/src/rpc-host.ts
+++ b/packages/client/connection/src/rpc-host.ts
@@ -2,6 +2,7 @@
 
 import { Context, Service } from '@deepseek-ai/cordis'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { PeerScope } from '@deepseek-ai/dsh-typert-protocol'
 import {
   RpcId,
   type ClientRequest,
@@ -12,7 +13,9 @@ import { bridge } from './http-bridge.ts'
 import { isTrustedApiRequest } from './api-request-trust.ts'
 import { API_PATH } from './api-path.ts'
 import type { BrowserAuth } from './browser-auth.ts'
+import { OperatorPeer } from './operator-peer.ts'
 import type {
+  PeerAdmission,
   ConnectionIndexRequest,
   ConnectionIndexResponse,
   ConnectionFetchRoute,
@@ -58,6 +61,8 @@ declare module '@deepseek-ai/cordis' {
 
 /** Host Connection service whose channel registrations belong to the caller fiber. */
 export class HostConnectionService extends Service implements HostConnectionHandle {
+  /** The operator Peer every admitted request speaks for. */
+  readonly operator: PeerScope
   private readonly interceptors = new Map<string, ConnectionRpcInterceptor>()
   private readonly fetchRoutes = new Map<string, RegisteredFetchRoute>()
 
@@ -73,6 +78,8 @@ export class HostConnectionService extends Service implements HostConnectionHand
     private readonly browserAuth: BrowserAuth,
   ) {
     super(ctx, 'connection')
+    this.operator = new OperatorPeer(ctx)
+    ctx.effect(() => () => this.operator.dispose(), 'client-connection: operator Peer')
   }
 
   /** Generic channel registry scoped to the Context reading this service. */
@@ -99,6 +106,12 @@ export class HostConnectionService extends Service implements HostConnectionHand
     return this.browserAuth.isAuthenticated(request) ? undefined : 401
   }
 
+  /** A request that passes the fence and authentication speaks for the operator. */
+  admit(request: ConnectionTrustRequest): PeerAdmission {
+    const rejection = this.requestRejection(request)
+    return rejection === undefined ? { peer: this.operator } : { rejection }
+  }
+
   /** Authenticate an index request through the process-token exchange or cookie. */
   authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean {
     return this.browserAuth.authorizeIndex(request, response)
@@ -161,15 +174,15 @@ export class HostConnectionService extends Service implements HostConnectionHand
     handler: ConnectionRpcHandler,
   ): () => Promise<void> {
     assertChannel(channel)
-    const fetchHandler = rpcFetchHandler(channel, handler)
+    const fetchHandler = rpcFetchHandler(channel, handler, this.operator)
     const route: WebRoute = {
       kind: 'prefix',
       path: channel,
       handler: async (req, res) => {
-        const rejection = this.requestRejection(req)
-        if (rejection !== undefined) {
-          res.writeHead(rejection)
-          res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+        const admission = this.admit(req)
+        if ('rejection' in admission) {
+          res.writeHead(admission.rejection)
+          res.end(admission.rejection === 401 ? 'unauthorized' : 'forbidden')
           return
         }
         await bridge(req, res, fetchHandler)
@@ -192,7 +205,7 @@ export class HostConnectionService extends Service implements HostConnectionHand
     }
     const interceptor: ConnectionRpcInterceptor = {
       matches,
-      fetchHandler: rpcFetchHandler(channel, handler),
+      fetchHandler: rpcFetchHandler(channel, handler, this.operator),
     }
     return owner.effect(() => {
       if (this.interceptors.has(channel)) {
@@ -209,6 +222,7 @@ export class HostConnectionService extends Service implements HostConnectionHand
 function rpcFetchHandler(
   channel: string,
   handler: ConnectionRpcHandler,
+  peer: PeerScope,
 ): ConnectionFetchHandler {
   return {
     requestBodyMode: () => 'buffered',
@@ -244,7 +258,7 @@ function rpcFetchHandler(
       }
 
       try {
-        const result = await handler(endpoint, message.payload, request.signal)
+        const result = await handler(endpoint, message.payload, request.signal, peer)
         return fullResponse(message.rpcId, result)
       } catch (error) {
         return new Response(`handler failure: ${String(error)}`, { status: 500 })
@@ -278,9 +292,23 @@ function errorResponse(rpcId: RpcIdType, error: ConnectionRpcFailure): Response
   return fullResponse(rpcId, { ok: false, error })
 }
 
-function fullResponse(rpcId: RpcIdType, result: ConnectionRpcResult<unknown>): Response {
-  const body: ConnectionServerResponse = { type: 'server-response', rpcId, result }
-  return Response.json(body)
+function fullResponse(rpcId: RpcIdType, result: Awaited<ReturnType<ConnectionRpcHandler>>): Response {
+  if (!result.ok) {
+    const body: ConnectionServerResponse = { type: 'server-response', rpcId, result }
+    return Response.json(body)
+  }
+  const { attachments, ...success } = result
+  const body: ConnectionServerResponse = { type: 'server-response', rpcId, result: success }
+  if (attachments === undefined || attachments.length === 0) return Response.json(body)
+  const parts = new FormData()
+  const attachmentMetadata = attachments.map((attachment, index) => {
+    const part = `bytes-${index}`
+    // FileSystem bytes may have SharedArrayBuffer backing, which BlobPart excludes.
+    parts.set(part, new Blob([new Uint8Array(attachment.bytes)]))
+    return { path: [...attachment.path], codec: 'bytes' as const, part }
+  })
+  parts.set('metadata', JSON.stringify({ ...body, attachments: attachmentMetadata }))
+  return new Response(parts)
 }
 
 function assertChannel(channel: string): void {
diff --git a/packages/client/connection/src/rpc.ts b/packages/client/connection/src/rpc.ts
index 5d4a4db957..0b8755bf71 100644
--- a/packages/client/connection/src/rpc.ts
+++ b/packages/client/connection/src/rpc.ts
@@ -1,6 +1,7 @@
 /** Generic unary RPC contracts shared by the Host and Client Connection halves. */
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { PeerScope } from '@deepseek-ai/dsh-typert-protocol'
 
 /** Correlation id minted by a caller and echoed by the Connection response. */
 export type RpcId = Branded<'rpc-id'>
@@ -26,6 +27,24 @@ export type ConnectionRpcResult<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly error: ConnectionRpcFailure }
 
+/** One binary value separated from a successful RPC result before transport framing. */
+export interface ConnectionRpcAttachment {
+  /** Result-relative path occupied by the attachment's `null` placeholder. */
+  readonly path: readonly (string | number)[]
+  /** Byte view carried outside the JSON response metadata. */
+  readonly bytes: Uint8Array
+}
+
+/** Successful or failed handler result ready for Connection transport framing. */
+export type ConnectionRpcHandlerResult =
+  | {
+    readonly ok: true
+    readonly value: unknown
+    /** Binary fields already projected by the handler that owns the result protocol. */
+    readonly attachments?: readonly ConnectionRpcAttachment[]
+  }
+  | { readonly ok: false; readonly error: ConnectionRpcFailure }
+
 /** Historical short name for a generic Connection result. */
 export type RpcResult<T> = ConnectionRpcResult<T>
 
@@ -96,12 +115,21 @@ export interface ConnectionIndexResponse {
   end(body?: string): unknown
 }
 
-/** Handler invoked after Connection has decoded the transport envelope. */
+/** Outcome of admitting one request: the operator Peer it speaks for, or the status refusing it. */
+export type PeerAdmission =
+  | { readonly peer: PeerScope }
+  | { readonly rejection: 401 | 403 }
+
+/**
+ * Handler invoked after Connection has decoded the transport envelope.
+ * `peer` is the Peer the request was admitted as: the operator.
+ */
 export type ConnectionRpcHandler = (
   endpoint: string,
   payload: unknown,
   signal: AbortSignal,
-) => Promise<ConnectionRpcResult<unknown>>
+  peer: PeerScope,
+) => Promise<ConnectionRpcHandlerResult>
 
 /** Synchronous ownership test for one endpoint on a shared RPC channel. */
 export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean
@@ -161,12 +189,14 @@ export interface HostConnectionRpc {
   ): () => Promise<void>
 }
 
-/** Host `ctx.connection` shape consumed by transport-independent adapters. */
+/** Host `ctx.connection` members consumed by transport-independent adapters. */
 export interface HostConnectionHandle {
   /** Generic RPC channel registry. */
   readonly rpc: HostConnectionRpc
   /** Exact Fetch routes for streaming or browser-native responses. */
   readonly fetch: HostConnectionFetch
+  /** The operator Peer every admitted request speaks for; its scope lives as long as Connection. */
+  readonly operator: PeerScope
 
   /**
    * Compose exact Fetch routes and the shared-channel RPC interceptor.
@@ -183,6 +213,14 @@ export interface HostConnectionHandle {
    */
   requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection
 
+  /**
+   * Admit one request: it passes {@link requestRejection} and speaks for the
+   * operator, or it is refused with that status.
+   * @param request - request headers from the HTTP or upgrade request.
+   * @returns the operator Peer, or the rejection status.
+   */
+  admit(request: ConnectionTrustRequest): PeerAdmission
+
   /**
    * Authenticate one frontend index request, owning a token redirect or 401.
    * @param request - root or configured-index HTTP request.
@@ -240,6 +278,7 @@ export interface ClientConnectionRpc {
    * @param endpoint - channel-relative endpoint such as `session/follow`.
    * @param payload - channel-owned request payload.
    * @param signal - caller cancellation for this logical stream.
+   * @param uplink - Client uplink items the Host method reads through `invocation.uplink()`.
    * @returns decoded stream values from the in-process carrier.
    */
   readonly open?: (
@@ -247,5 +286,6 @@ export interface ClientConnectionRpc {
     endpoint: string,
     payload: unknown,
     signal: AbortSignal,
+    uplink?: AsyncIterable<unknown>,
   ) => AsyncIterable<unknown>
 }
diff --git a/packages/client/connection/tests/binary-rpc.host.spec.ts b/packages/client/connection/tests/binary-rpc.host.spec.ts
new file mode 100644
index 0000000000..05ec270545
--- /dev/null
+++ b/packages/client/connection/tests/binary-rpc.host.spec.ts
@@ -0,0 +1,285 @@
+import { request } from 'node:http'
+import { gunzipSync } from 'node:zlib'
+import { Context } from '@deepseek-ai/cordis'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { describe, expect, it } from 'vitest'
+import type { BrowserAuth } from '../src/browser-auth.ts'
+import { createWebConnectionRpc } from '../src/client/rpc.ts'
+import { bridge } from '../src/http-bridge.ts'
+import type { ConnectionRpcHandlerResult, ConnectionRpcResult } from '../src/rpc.ts'
+import { HostConnectionService } from '../src/rpc-host.ts'
+
+function binaryResponse(rpcId: string, mutate: (parts: FormData) => void = () => {}): Response {
+  const parts = new FormData()
+  parts.set('metadata', JSON.stringify({
+    type: 'server-response', rpcId, result: { ok: true, value: { offset: 7, data: null } },
+    attachments: [{ path: ['data'], codec: 'bytes', part: 'bytes-0' }],
+  }))
+  parts.set('bytes-0', new Blob([new Uint8Array([0, 128, 255])]))
+  mutate(parts)
+  return new Response(parts)
+}
+
+describe('Connection binary RPC', () => {
+  it.each(['gzip', 'none'] as const)('preserves %s configuration through the HTTP bridge', async (compression) => {
+    const ctx = new Context()
+    try {
+      await ctx.plugin(WebServer, { host: '127.0.0.1', port: 0, compression })
+      await ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) })
+      const connection = ctx.get('connection') as HostConnectionService
+      const data = new Uint8Array(1024 * 1024).fill(65)
+      data.set([0, 128, 255])
+      connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => ({
+        ok: true,
+        value: { data: null, bytes: data.length },
+        attachments: [{ path: ['data'], bytes: data }],
+      }))
+      const handler = connection.createSharedFetchHandler('/api')
+      ctx.webServer.register({ kind: 'prefix', path: '/api', handler: (req, res) => bridge(req, res, handler) })
+      let transferred = 0
+      let encoding: string | undefined
+      const rpc = createWebConnectionRpc((path, init) => new Promise((resolve, reject) => {
+        const req = request(new URL(path, `http://127.0.0.1:${ctx.webServer.port}`), {
+          method: init.method,
+          headers: { ...Object.fromEntries(new Headers(init.headers)), 'accept-encoding': 'gzip' },
+        }, (response) => {
+          void (async () => {
+            const chunks: Buffer[] = []
+            for await (const chunk of response) chunks.push(chunk as Buffer)
+            const body = Buffer.concat(chunks)
+            transferred = body.length
+            encoding = response.headers['content-encoding']
+            return new Response(encoding === 'gzip' ? gunzipSync(body) : body, {
+              status: response.statusCode!,
+              headers: { 'content-type': response.headers['content-type']! },
+            })
+          })().then(resolve, reject)
+        })
+        req.once('error', reject)
+        req.end(init.body as string)
+      }))
+      expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { data, bytes: data.length } })
+      if (compression === 'gzip') {
+        expect(encoding).toBe('gzip')
+        expect(transferred).toBeLessThan(data.length / 10)
+      } else {
+        expect(encoding).toBeUndefined()
+        expect(transferred).toBeGreaterThan(data.length)
+      }
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('roundtrips raw bytes and metadata on the existing channel while JSON results and errors stay JSON', async () => {
+    const ctx = new Context()
+    const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) })
+    await fiber.await()
+    try {
+      const connection = ctx.get('connection') as HostConnectionService
+      const byteValues = [
+        new Uint8Array([9, 0, 128, 255, 9]).subarray(1, 4),
+        new Uint8Array(new SharedArrayBuffer(3)).fill(255),
+        new Uint8Array(),
+      ]
+      const cases: readonly {
+        readonly sent: ConnectionRpcHandlerResult
+        readonly expected: ConnectionRpcResult<unknown>
+      }[] = [
+        ...byteValues.map((data, index) => ({
+          sent: {
+            ok: true as const,
+            value: { data: null, offset: index === 0 ? 7 : 0, eof: index !== 0, bytes: index === 0 ? 42 : data.length },
+            attachments: [{ path: ['data'], bytes: data }],
+          },
+          expected: {
+            ok: true as const,
+            value: { data, offset: index === 0 ? 7 : 0, eof: index !== 0, bytes: index === 0 ? 42 : data.length },
+          },
+        })),
+        { sent: { ok: true, value: { data: 'AID/', encoding: 'base64' } }, expected: { ok: true, value: { data: 'AID/', encoding: 'base64' } } },
+        { sent: { ok: true, value: { count: 4 } }, expected: { ok: true, value: { count: 4 } } },
+        { sent: { ok: true, value: null }, expected: { ok: true, value: null } },
+        { sent: { ok: true, value: 'plain' }, expected: { ok: true, value: 'plain' } },
+        {
+          sent: { ok: false, error: { code: 'fixture/denied', message: 'denied', details: { path: 'private' } } },
+          expected: { ok: false, error: { code: 'fixture/denied', message: 'denied', details: { path: 'private' } } },
+        },
+      ]
+      let next: ConnectionRpcHandlerResult = cases[0]!.sent
+      connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => next)
+      const shared = connection.createSharedFetchHandler('/api')
+      const mediaTypes: (string | null)[] = []
+      const rpc = createWebConnectionRpc(async (url, init) => {
+        const response = await shared.fetch(new Request(new URL(url, 'http://host'), init))
+        mediaTypes.push(response.headers.get('content-type'))
+        return response
+      })
+      for (const { sent, expected } of cases) {
+        next = sent
+        const received = await rpc.call('/api', 'fixture/read', { args: {} })
+        expect(received).toEqual(expected)
+        if (received.ok && typeof received.value === 'object' && received.value !== null
+          && 'data' in received.value && received.value.data instanceof Uint8Array) {
+          expect(received.value.data.buffer).toBeInstanceOf(ArrayBuffer)
+        }
+      }
+      expect(mediaTypes.slice(0, 3).every(type => type?.startsWith('multipart/form-data;'))).toBe(true)
+      expect(mediaTypes.slice(3)).toEqual(Array(5).fill('application/json'))
+    } finally {
+      await fiber.dispose()
+    }
+  })
+
+  it('frames attachments already projected by the result owner', async () => {
+    const ctx = new Context()
+    const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) })
+    await fiber.await()
+    try {
+      const connection = ctx.get('connection') as HostConnectionService
+      const content = Buffer.from([9, 0, 128, 255, 9]).subarray(1, 4)
+      connection.rpc.intercept('/api', () => true, async () => ({
+        ok: true,
+        value: { content: null, metadata: { count: 1 } },
+        attachments: [{ path: ['content'], bytes: content }],
+      }))
+      const handler = connection.createSharedFetchHandler('/api')
+      const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init)))
+      expect(await rpc.call('/api', 'fixture/read', {})).toEqual({
+        ok: true, value: { content: new Uint8Array([0, 128, 255]), metadata: { count: 1 } },
+      })
+    } finally {
+      await fiber.dispose()
+    }
+  })
+
+  it.each([
+    ['missing bytes', (p: FormData) => { p.delete('bytes-0') }],
+    ['text bytes', (p: FormData) => { p.set('bytes-0', 'AID/') }],
+    ['missing metadata', (p: FormData) => { p.delete('metadata') }],
+    ['file metadata', (p: FormData) => { p.set('metadata', new Blob(['{}'])) }],
+    ['duplicate metadata', (p: FormData) => { p.append('metadata', '{}') }],
+    ['duplicate bytes', (p: FormData) => { p.append('bytes-0', new Blob()) }],
+    ['extra part', (p: FormData) => { p.set('extra', 'unclaimed') }],
+    ['invalid JSON', (p: FormData) => { p.set('metadata', '{') }],
+    ['invalid envelope', (p: FormData) => { p.set('metadata', '{}') }],
+    ...[
+      { ok: false, error: { code: 'fixture/error', message: 'failed', details: {} } },
+      { ok: true, value: null },
+      { ok: true, value: [] },
+      { ok: true, value: { data: 'duplicate' } },
+    ].map(result => ['invalid result', (p: FormData) => { p.set('metadata', JSON.stringify({
+      type: 'server-response', rpcId: 'fixture', result,
+    })) }] as const),
+  ] satisfies readonly (readonly [string, (parts: FormData) => void])[])('rejects malformed multipart: %s', async (_name, mutate) => {
+    const rpc = createWebConnectionRpc(async (_url, init) => {
+      const message = JSON.parse(init.body as string) as { rpcId: string }
+      return binaryResponse(message.rpcId, mutate)
+    })
+    await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow(/invalid binary response|invalid server-response|JSON/)
+  })
+
+  it('rejects a binary response for another request', async () => {
+    const rpc = createWebConnectionRpc(async () => binaryResponse('unrelated'))
+    await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('rpcId mismatch')
+  })
+
+  it('roundtrips nested, optional and root attachment paths without reserving field names', async () => {
+    const ctx = new Context()
+    const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) })
+    await fiber.await()
+    try {
+      const data = new Uint8Array([0, 128, 255])
+      const second = Buffer.from([9, 2, 3, 9]).subarray(1, 3)
+      let next: ConnectionRpcHandlerResult = {
+        ok: true,
+        value: {
+          files: [{ name: 'a.png', content: null }, { name: 'b.png', content: null }, { name: 'empty' }],
+          'dots./[]': [null, null, [null]],
+          metadata: { attachments: { content: null } },
+          ...JSON.parse('{"__proto__":null,"constructor":null}') as object,
+        },
+        attachments: [
+          { path: ['files', 0, 'content'], bytes: data },
+          { path: ['files', 1, 'content'], bytes: second },
+          { path: ['dots./[]', 0], bytes: new Uint8Array() },
+          { path: ['dots./[]', 2, 0], bytes: data },
+          { path: ['metadata', 'attachments', 'content'], bytes: data },
+          { path: ['__proto__'], bytes: data },
+        ],
+      }
+      const connection = ctx.get('connection') as HostConnectionService
+      connection.rpc.intercept('/api', () => true, async () => next)
+      const handler = connection.createSharedFetchHandler('/api')
+      const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init)))
+      const expected = {
+        files: [{ name: 'a.png', content: data }, { name: 'b.png', content: new Uint8Array([2, 3]) }, { name: 'empty' }],
+        'dots./[]': [new Uint8Array(), null, [data]],
+        metadata: { attachments: { content: data } },
+        ...JSON.parse('{"__proto__":null,"constructor":null}') as object,
+      }
+      Object.defineProperty(expected, '__proto__', { value: data, enumerable: true })
+      expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: expected })
+      for (const bytes of [data, Buffer.from([0, 128, 255]), new Uint8Array(new SharedArrayBuffer(3))]) {
+        next = { ok: true, value: null, attachments: [{ path: [], bytes }] }
+        const response = await rpc.call('/api', 'fixture/read', {})
+        expect(response).toEqual({ ok: true, value: new Uint8Array(bytes) })
+        if (!response.ok || !(response.value instanceof Uint8Array)) throw new Error('expected root bytes')
+        expect(response.value.buffer).toBeInstanceOf(ArrayBuffer)
+        expect(Object.isFrozen(response.value)).toBe(false)
+      }
+      next = {
+        ok: true,
+        value: [null, [null]],
+        attachments: [{ path: [0], bytes: data }, { path: [1, 0], bytes: data }],
+      }
+      expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: [data, [data]] })
+    } finally {
+      await fiber.dispose()
+    }
+  })
+
+  it.each([
+    ['absent table', { attachments: undefined }],
+    ['non-array table', { attachments: {} }],
+    ['empty table', { attachments: [] }],
+    ...[
+      null, {}, { path: ['data'], codec: 'numpy', part: 'bytes-0' },
+      { path: ['data'], codec: 'bytes', part: 0 },
+      { path: ['data'], codec: 'bytes', part: 'metadata' },
+      { path: 'data', codec: 'bytes', part: 'bytes-0' },
+      ...[['missing'], ['offset', 'child'], ['constructor', 'prototype'], [0], ['files', '0'], ['files', -1], ['files', 0.5], ['files', 1], ['files', false], ['files', null]].map(path => ({ path, codec: 'bytes', part: 'bytes-0' })),
+    ].map(attachment => ['invalid attachment', { attachments: [attachment] }] as const),
+    ['duplicate part', { attachments: [0, 1].map(() => ({ path: ['data'], codec: 'bytes', part: 'bytes-0' })) }],
+    ['duplicate path', { attachments: [0, 1].map(i => ({ path: ['data'], codec: 'bytes', part: `bytes-${i}` })) }],
+    ['overlapping path', { attachments: [
+      { path: ['data'], codec: 'bytes', part: 'bytes-0' },
+      { path: ['data', '0'], codec: 'bytes', part: 'bytes-1' },
+    ] }],
+    ['occupied placeholder', { result: { ok: true, value: { data: 'AID/' } } }],
+  ] satisfies readonly (readonly [string, Record<string, unknown>])[])('rejects malformed attachment metadata: %s', async (_name, overrides) => {
+    const rpc = createWebConnectionRpc(async (_url, init) => {
+      const { rpcId } = JSON.parse(init.body as string) as { rpcId: string }
+      return binaryResponse(rpcId, (parts) => {
+        const metadata = JSON.parse(parts.get('metadata') as string) as Record<string, unknown>
+        parts.set('metadata', JSON.stringify({ ...metadata, result: { ok: true, value: { data: null, offset: 7, files: [null] } }, ...overrides }))
+        if (_name === 'duplicate path' || _name === 'overlapping path') parts.set('bytes-1', new Blob())
+      })
+    })
+    await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('invalid binary response')
+  })
+
+  it('rejects truncated multipart and late bytes after caller cancellation', async () => {
+    const broken = createWebConnectionRpc(async () => new Response('truncated', {
+      headers: { 'content-type': 'multipart/form-data; boundary=fixture' },
+    }))
+    await expect(broken.call('/api', 'fixture/read', {})).rejects.toThrow()
+    const abort = new AbortController()
+    const rpc = createWebConnectionRpc(async (_url, init) => {
+      const message = JSON.parse(init.body as string) as { rpcId: string }
+      abort.abort(new Error('caller left'))
+      return binaryResponse(message.rpcId)
+    })
+    await expect(rpc.call('/api', 'fixture/read', {}, abort.signal)).rejects.toThrow('caller left')
+  })
+})
diff --git a/packages/client/connection/tests/client-apply.client.spec.ts b/packages/client/connection/tests/client-apply.client.spec.ts
index 8ff914bef4..4588382d9e 100644
--- a/packages/client/connection/tests/client-apply.client.spec.ts
+++ b/packages/client/connection/tests/client-apply.client.spec.ts
@@ -495,9 +495,10 @@ describe('connection client apply', () => {
   it('exposes a worker-local Gateway stream through connection.rpc.open', async () => {
     ;(globalThis as Win).location = { hostname: 'preview.example' }
     const openStream = vi.fn<NonNullable<ClientTransportHooks['openStream']>>(
-      (endpoint, payload, signal) => (async function *(): AsyncGenerator {
+      (endpoint, payload, signal, uplink) => (async function *(): AsyncGenerator {
         signal.throwIfAborted()
         yield { endpoint, payload }
+        if (uplink !== undefined) yield* uplink
       })(),
     )
     ;(globalThis as Win).__DSH_TRANSPORT__ = {
@@ -521,7 +522,14 @@ describe('connection client apply', () => {
       'session/follow',
       { args: { sessionId: 'session-1' } },
       abort.signal,
+      undefined,
     )
+
+    const uplink = (async function *(): AsyncGenerator<string> { yield 'typed' })()
+    const echoed = []
+    for await (const value of open('/api', 'job/attach', { args: {} }, abort.signal, uplink)) echoed.push(value)
+    expect(echoed).toEqual([{ endpoint: 'job/attach', payload: { args: {} } }, 'typed'])
+    expect(openStream).toHaveBeenLastCalledWith('job/attach', { args: {} }, abort.signal, uplink)
     expect(handle.isLoopback).toBe(true)
     expect(() => open('/rpc', 'session/follow', {}, abort.signal))
       .toThrow('worker-local streams require the /api channel')
diff --git a/packages/client/connection/tests/http-bridge.host.spec.ts b/packages/client/connection/tests/http-bridge.host.spec.ts
index 9dc6df8405..e9fa9df364 100644
--- a/packages/client/connection/tests/http-bridge.host.spec.ts
+++ b/packages/client/connection/tests/http-bridge.host.spec.ts
@@ -75,6 +75,73 @@ describe('HTTP bridge abort', () => {
     expect(carrierSignal?.aborted).toBe(true)
   })
 
+  it.each(['write', 'backpressure'])('finishes a multipart response without further writes when the client closes during %s', async (phase) => {
+    const request = Readable.from([]) as IncomingMessage
+    Object.assign(request, { url: '/api/workspaceFiles/readBytes', method: 'GET', headers: {} })
+    const body = new FormData()
+    body.set('metadata', '{}')
+    body.set('data', new Blob([new Uint8Array(16 * 1024 * 1024)]))
+    let writes = 0
+    let cleaningUp = false
+    const response = Object.assign(new EventEmitter(), {
+      destroyed: false,
+      writableEnded: false,
+      writeHead() { return this },
+      write() {
+        writes++
+        if (writes === 1) {
+          const close = (): void => { response.destroyed = true; response.emit('close') }
+          if (phase === 'write') close()
+          else queueMicrotask(close)
+        }
+        return cleaningUp
+      },
+      end() { this.writableEnded = true; return this },
+    })
+    let settled = false
+    const pending = bridge(request, response, {
+      requestBodyMode: () => 'buffered',
+      fetch: async () => new Response(body),
+    }).then(() => { settled = true })
+    try {
+      await expect.poll(() => settled).toBe(true)
+      expect(writes).toBe(1)
+      expect(response.listenerCount('drain')).toBe(0)
+    } finally {
+      // Release a regressed bridge parked after the one close event.
+      cleaningUp = true
+      response.emit('drain')
+      await pending
+    }
+  })
+
+  it('discards bytes returned after the client disconnects', async () => {
+    const request = Readable.from([]) as IncomingMessage
+    Object.assign(request, { url: '/api/workspaceFiles/readBytes', method: 'GET', headers: {} })
+    const response = Object.assign(new EventEmitter(), {
+      destroyed: false,
+      writableEnded: false,
+      writeHead() { return this },
+      write() { throw new Error('a disconnected response must not receive bytes') },
+      end() { this.writableEnded = true; return this },
+    })
+    const started = Promise.withResolvers<undefined>()
+    let controller!: ReadableStreamDefaultController<Uint8Array>
+    const body = new ReadableStream<Uint8Array>({
+      start(value) { controller = value },
+      pull() { started.resolve(undefined) },
+    })
+    const pending = bridge(request, response, {
+      requestBodyMode: () => 'buffered',
+      fetch: async () => new Response(body),
+    })
+    await started.promise
+    response.emit('close')
+    controller.enqueue(Uint8Array.of(1))
+    controller.close()
+    await pending
+  })
+
   it('streams a declared 2.19 GiB request before the body ends and bypasses the JSON buffer cap', async () => {
     const request = new Readable({ read() {} }) as IncomingMessage
     Object.assign(request, {
diff --git a/packages/client/connection/tests/node-half.host.spec.ts b/packages/client/connection/tests/node-half.host.spec.ts
index b2d4ce11d5..51a0bbbf67 100644
--- a/packages/client/connection/tests/node-half.host.spec.ts
+++ b/packages/client/connection/tests/node-half.host.spec.ts
@@ -8,7 +8,16 @@ import type { AddressInfo } from 'node:net'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
 import type { IndexInjection, WebServer, WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
-import { API_PATH, RpcId, apply, inject, type ClientRequest, type ConnectionConfig, type HostConnectionHandle } from '../src/index.ts'
+import {
+  API_PATH,
+  RpcId,
+  apply,
+  inject,
+  type ClientRequest,
+  type ConnectionConfig,
+  type HostConnectionHandle,
+  type PeerScope,
+} from '../src/index.ts'
 import { DEFAULT_MAX_REQUEST_BODY_BYTES } from '../src/http-bridge.ts'
 import { provideBrowserCredentials } from './browser-credentials.ts'
 
@@ -469,6 +478,47 @@ describe('connection node half', () => {
     await fiber.dispose()
   })
 
+  it('admits every trusted, authenticated request as the operator Peer and hands each call that Peer', async () => {
+    const { connection, routes, dispose } = await mounted({ trustedHosts: ['harness.example'] })
+    const peers: PeerScope[] = []
+    const remove = connection.rpc.intercept(
+      '/api',
+      () => true,
+      async (_endpoint, _payload, _signal, peer) => {
+        peers.push(peer)
+        return { ok: true, value: null }
+      },
+    )
+    expect(connection.admit(fakeRequest({ host: 'other.example' }))).toEqual({ rejection: 403 })
+    expect(connection.admit(fakeRequest({ host: '127.0.0.1:3080' }))).toEqual({ rejection: 401 })
+    const cookie = browserCookie(connection, '127.0.0.1:3080')
+    expect(connection.admit(fakeRequest({ host: '127.0.0.1:3080', cookie }))).toEqual({ peer: connection.operator })
+
+    const route = routes.find(candidate => candidate.path === API_PATH)!
+    const request: ClientRequest = {
+      type: 'client-request',
+      rpcId: RpcId('rpc-peer'),
+      method: 'goals/create',
+      payload: { args: {} },
+    }
+    const answered = fakeResponse()
+    await route.handler(fakePost({ host: '127.0.0.1:3080', cookie }, '/api/goals/create', request), answered.response)
+    expect(JSON.parse(String(answered.state.body))).toMatchObject({ result: { ok: true, value: null } })
+    // A shell-owned carrier dispatches the shared handler without the bridge and speaks for the operator too.
+    const direct = await connection.createSharedFetchHandler('/api').fetch(new Request('http://127.0.0.1:3080/api/goals/create', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(request),
+    }))
+    expect(direct.status).toBe(200)
+    expect(peers).toEqual([connection.operator, connection.operator])
+
+    // Racing disposals share one completion, and the scope goes with the Connection.
+    await Promise.all([connection.operator.dispose(), connection.operator.dispose()])
+    await remove()
+    await dispose()
+  })
+
   it('applies the configured trust fence and JSON envelope checks to generic channels', async () => {
     const ctx = new Context()
     const routes: WebRoute[] = []
diff --git a/packages/client/connection/tsconfig.client.json b/packages/client/connection/tsconfig.client.json
index ffc18472c2..a9c558d29b 100644
--- a/packages/client/connection/tsconfig.client.json
+++ b/packages/client/connection/tsconfig.client.json
@@ -35,6 +35,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../typert/protocol"
+    },
     {
       "path": "../../util/brand"
     }
diff --git a/packages/client/connection/tsconfig.host.json b/packages/client/connection/tsconfig.host.json
index f58ca85848..66d9844f17 100644
--- a/packages/client/connection/tsconfig.host.json
+++ b/packages/client/connection/tsconfig.host.json
@@ -9,9 +9,12 @@
     "src/api-path.ts",
     "src/api-request-trust.ts",
     "src/browser-auth.ts",
+    "src/client/random-uuid.ts",
+    "src/client/rpc.ts",
     "src/http-bridge.ts",
     "src/index.ts",
     "src/loopback-hostname.ts",
+    "src/operator-peer.ts",
     "src/recovery-config.ts",
     "src/rpc-host.ts",
     "src/rpc-schema.ts",
@@ -28,14 +31,20 @@
       "path": "../../attachment/attachment"
     },
     {
-      "path": "../../credentials/credentials"
+      "path": "../../core/scope"
     },
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../credentials/credentials"
+    },
     {
       "path": "../../host/webserver"
     },
+    {
+      "path": "../../typert/protocol"
+    },
     {
       "path": "../../util/brand"
     }
diff --git a/packages/client/hmr/README.i18n.yaml b/packages/client/hmr/README.i18n.yaml
index 07ad3d545d..f6861208ea 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: e459da10332ffdb3af422b75f639ce25df512487
-README.zh.md: 54e2f3af63472dedbfc75c5b4400b5d93e14f311
+README.md: 5dae1463ceed315c3409bf97de80649f10e83fa8
+README.zh.md: a77befcf63cd78be66b7e5b636d86367af6fdcdf
diff --git a/packages/client/hmr/README.md b/packages/client/hmr/README.md
index e459da1033..5dae1463ce 100644
--- a/packages/client/hmr/README.md
+++ b/packages/client/hmr/README.md
@@ -29,7 +29,7 @@ The shipped Web composition mounts this transport for live plugin changes. Durin
 
 ### Starting the reload chain
 
-Run `pnpm run dev:web` (or a watch process using the shared Client tsdown preset) against the same host; rebuilt plugins are then swapped into the running browser automatically, one at a time. The preset stamps `lib/client.js` after all package-local chunks are written, so a chunk-only rebuild also advances the package revision without Host-side chunk scanning.
+Run `pnpm run dev:web`, which starts the host and the rebuild watchers together (`--no-serve` attaches only the watchers to a host started elsewhere, as does any watch process using the shared Client tsdown preset); rebuilt plugins are then swapped into the running browser automatically, one at a time. The preset stamps `lib/client.js` after all package-local chunks are written, so a chunk-only rebuild also advances the package revision without Host-side chunk scanning.
 
 ### What a reload does
 
diff --git a/packages/client/hmr/README.zh.md b/packages/client/hmr/README.zh.md
index 54e2f3af63..a77befcf63 100644
--- a/packages/client/hmr/README.zh.md
+++ b/packages/client/hmr/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 启动重载链路
 
-对同一个宿主运行 `pnpm run dev:web`（或使用共享 Client tsdown 预设的 watch 进程）；重建后的插件随后会被自动逐个替换进运行中的浏览器。该预设会在所有包内 chunk 写完后标记 `lib/client.js`，因此仅 chunk 发生重建也会推进包 revision，无需 Host 扫描 chunk。
+运行 `pnpm run dev:web`，它会同时启动宿主与重建 watcher（`--no-serve` 则只把 watcher 接到别处启动的宿主上，使用共享 Client tsdown 预设的任何 watch 进程亦然）；重建后的插件随后会被自动逐个替换进运行中的浏览器。该预设会在所有包内 chunk 写完后标记 `lib/client.js`，因此仅 chunk 发生重建也会推进包 revision，无需 Host 扫描 chunk。
 
 ### 一次重载做什么
 
diff --git a/packages/client/locale/tests/language-row.client.spec.tsx b/packages/client/locale/tests/language-row.client.spec.tsx
index 5068b90218..776542c0f2 100644
--- a/packages/client/locale/tests/language-row.client.spec.tsx
+++ b/packages/client/locale/tests/language-row.client.spec.tsx
@@ -20,7 +20,7 @@ const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
 
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
-    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {} })
+    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {} })
   return bindSnapshotSelector(store)
 }
 function emptyWorkspaces() {
diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts
index b8468c0957..5e9592ba70 100644
--- a/packages/client/tsdown.client.ts
+++ b/packages/client/tsdown.client.ts
@@ -61,7 +61,7 @@ function styleInjectionModule(
  * Everything else under @deepseek-ai/* is either a module-table entry
  * (external) or a leak the purity gate rejects.
  */
-export const INLINE_SAFE = /^(?:@deepseek-ai\/dsh-(?:file-reference|session|llm|tools|brand|deque|output-retention|typert-protocol|util-crypto|util-values|util-workspace-path)(?:\/|$)|@deepseek-ai\/dsh-token-meter\/client$|@deepseek-ai\/dsh-host-open-in-app\/shared$|@deepseek-ai\/dsh-plugin-manager\/registry$|@deepseek-ai\/dsh-agent-presets\/display$|@deepseek-ai\/dsh-spill-policy\/notice$)/
+export const INLINE_SAFE = /^(?:@deepseek-ai\/dsh-(?:file-reference|session|llm|tools|brand|deque|output-retention|typert-protocol|util-crypto|util-values|util-workspace-path)(?:\/|$)|@deepseek-ai\/dsh-token-meter\/client$|@deepseek-ai\/dsh-native-command\/types$|@deepseek-ai\/dsh-host-open-in-app\/shared$|@deepseek-ai\/dsh-plugin-manager\/registry$|@deepseek-ai\/dsh-agent-presets\/display$|@deepseek-ai\/dsh-spill-policy\/notice$)/
 
 /**
  * Vendored framework libraries: rescoped into @deepseek-ai, so the gate below
diff --git a/packages/client/ui-agent-preset/README.i18n.yaml b/packages/client/ui-agent-preset/README.i18n.yaml
index 2ed6513974..de88b1368c 100644
--- a/packages/client/ui-agent-preset/README.i18n.yaml
+++ b/packages/client/ui-agent-preset/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-agent-preset/README.md
-README.md: c7a87da591c1cafc433fbb3bb5fa216d94ab85ef
-README.zh.md: a54b47baed132e790fc4f44ad1155f48a19c430b
+README.md: f2c24e0b406c8c53bd49a1c72050f2f9c72c2300
+README.zh.md: 1b728834a35dcd756e9a044a4fb8274b7ea4c2ad
diff --git a/packages/client/ui-agent-preset/README.md b/packages/client/ui-agent-preset/README.md
index c7a87da591..f2c24e0b40 100644
--- a/packages/client/ui-agent-preset/README.md
+++ b/packages/client/ui-agent-preset/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use this package to choose the agent preset for a new Web GUI session, see the active preset in the session header, and manage available presets in Settings. The Agent mode picker is shown by default; Settings can hide it without changing running or historical sessions. A preset is fixed when a session is created, so changing the selection or default affects only later sessions. If the deployment provides no presets, these controls stay hidden and every session uses the host composition.
+Use this package to choose the agent preset for a new Web GUI session, see the active preset in the session header, and manage available presets in Settings. The Agent mode picker is shown by default while Developer tools is enabled; Settings can hide it without changing running or historical sessions. A preset is fixed when a session is created, so changing the selection or default affects only later sessions. If the deployment provides no presets, these controls stay hidden and every session uses the host composition.
 
 ## Table of Contents
 
@@ -25,14 +25,16 @@ Use this package to choose the agent preset for a new Web GUI session, see the a
 <a id="use-this-package"></a>
 ## Use this package
 
-The new-session picker additionally requires Developer tools to be enabled in General Settings. This presentation preference does not alter the selected preset, saved default, Host composition, or the management section’s independent picker policy.
+The new-session picker and the management section’s “Choose a mode for new tasks” row are visible only while Developer tools is enabled in General Settings. This presentation preference does not alter the selected preset, saved default, Host composition, or the management section’s independent picker policy.
 
-Mount this plugin alongside the settings and conversation packages; the management section then shows a visibility switch that is on by default. While it is off, the new-session chip is absent and the Host composes an unnamed session from the deployment default (`standard` in the shipped Web bundle). Turning it on restores the saved user default, or uses the deployment default when none has been saved, and carries that default to the current blank task; a chip pick itself is staged only once for the next blank session. Turning the picker off again returns the current blank task to the deployment default the same way and discards an unconsumed stage; started and historical sessions keep their labels, compositions, and recorded history.
+Mount this plugin alongside the settings and conversation packages; once Developer tools is enabled, the management section shows a visibility switch that is on by default. While it is off, the new-session chip is absent and the Host composes an unnamed session from the deployment default (`standard` in the shipped Web bundle). Turning it on restores the saved user default, or uses the deployment default when none has been saved, and carries that default to the current blank task; a chip pick itself is staged only once for the next blank session. Turning the picker off again returns the current blank task to the deployment default the same way and discards an unconsumed stage; started and historical sessions keep their labels, compositions, and recorded history.
 
 ### Managing the roster
 
 The settings section shows the roster as cards: a copy dialog is the only way a preset is created — the browser edits no composition text — and every custom card keeps a location action that opens the preset's own files. The visibility switch changes only whether the saved user default is active: the Host uses the deployment default while hidden and restores the saved default when the picker is shown again. While the picker is enabled, choosing a healthy non-default card writes a new user default for later sessions; if the current new-task surface already reuses a blank session, that explicit Settings action carries the same preset to that exact blank session through the existing selection path. Started and historical sessions remain unchanged. The switch is disabled while saving, and a failed write keeps the prior preference and shows an error. Hiding the picker disables default selection and the Creator launch but leaves roster viewing, copying, location, and deletion available. Deleting removes the preset directory while sessions already composed from it keep running. A shipped preset opens in a read-only viewer and offers no location or delete. A roster row carrying `broken` renders as a marked card whose body and duplication are disabled, because a copy of a broken preset is another broken preset; broken custom rows keep their location and delete actions so the files can be fixed and ghost directories cleared. The card face still shows the preset's own description — a chooser cannot act on a package specifier there — and the host's reason rides the badge as a tooltip, plus a visually hidden alert that carries it to assistive technology, which a disabled card body cannot.
 
+Known shipped presets offer mode details and usage examples in a read-only dialog. Its tabs preserve each page's scroll position; closing returns focus to the opening action. Help does not change the new-task default. The default badge replaces the card's source badge, and the preset id appears beside the title. Guide copy and examples belong to this package; the tab control comes from `ui-primitives`.
+
 ### The conversational entry
 
 When the roster carries the self-referential `cordis` preset, its dashed add-card stays disabled until the picker is enabled. It then stages `cordis` and starts a new session — the section closes the settings panel and the new-session chip's own applier composes the blank session the workspace flow produces.
diff --git a/packages/client/ui-agent-preset/README.zh.md b/packages/client/ui-agent-preset/README.zh.md
index a54b47baed..1b728834a3 100644
--- a/packages/client/ui-agent-preset/README.zh.md
+++ b/packages/client/ui-agent-preset/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用本包可以为新的 Web GUI 会话选择 agent preset、在会话标题中查看当前 preset，并在设置中管理可用 preset。Agent 模式选择器默认显示；设置可以隐藏它，而不会改变运行中或历史会话。preset 在会话创建时即固定，因此更改选择或默认值只影响此后创建的会话。如果部署未提供任何 preset，这些控件保持隐藏，每个会话都使用宿主组装。
+使用本包可以为新的 Web GUI 会话选择 agent preset、在会话标题中查看当前 preset，并在设置中管理可用 preset。Agent 模式选择器在通用设置开启开发者工具时默认显示；设置可以隐藏它，而不会改变运行中或历史会话。preset 在会话创建时即固定，因此更改选择或默认值只影响此后创建的会话。如果部署未提供任何 preset，这些控件保持隐藏，每个会话都使用宿主组装。
 
 ## 目录
 
@@ -25,14 +25,16 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-新会话选择器还要求在通用设置中开启开发者工具。此展示偏好不会改变已选预设、保存的默认值、Host 组合或管理区域独立的选择器策略。
+新会话选择器和管理区域中的「新任务可选择模式」整行设置仅在通用设置中开启开发者工具时显示。此展示偏好不会改变已选预设、保存的默认值、Host 组合或管理区域独立的选择器策略。
 
-与设置和对话包一起挂载本插件；管理分区随后显示一个默认开启的可见性开关。关闭期间，新建会话 chip 不出现，宿主会依据部署默认值（随附 Web bundle 中为 `standard`）组装未指名会话。开启时会恢复已保存的用户默认值；尚未保存时则使用部署默认值；该默认值会同时带到当前空白任务上。chip 中的选择本身只为下一个空白会话暂存一次。再次关闭选择器会以同样方式把当前空白任务带回部署默认值，并丢弃尚未使用的暂存选择；已开始及历史会话的标签、组装与已记录历史均保持不变。
+与设置和对话包一起挂载本插件；通用设置开启开发者工具后，管理分区会显示一个默认开启的可见性开关。关闭期间，新建会话 chip 不出现，宿主会依据部署默认值（随附 Web bundle 中为 `standard`）组装未指名会话。开启时会恢复已保存的用户默认值；尚未保存时则使用部署默认值；该默认值会同时带到当前空白任务上。chip 中的选择本身只为下一个空白会话暂存一次。再次关闭选择器会以同样方式把当前空白任务带回部署默认值，并丢弃尚未使用的暂存选择；已开始及历史会话的标签、组装与已记录历史均保持不变。
 
 ### 管理名单
 
 设置分区把名单呈现为卡片：复制对话框是创建 preset 的唯一入口——浏览器不编辑任何组装文本——每张自定义卡片都保留一个打开 preset 自身文件的位置动作。可见性开关只决定已保存的用户默认值是否生效：宿主在隐藏期间使用部署默认值，再次显示选择器时恢复已保存的默认值。选择器开启期间，选择健康且非默认的卡片会为后续会话写入新的用户默认值；如果当前新任务页已经复用一个空白会话，这次在设置中的明确选择也会通过既有选择链路把同一 preset 带到这个精确的空白会话。已开始及历史会话保持不变。保存期间开关会被禁用；写入失败时，界面保留先前的偏好并显示错误。隐藏选择器会禁用默认值选择与 Creator 启动，但名单查看、复制、位置和删除仍然可用。删除会移除 preset 目录，而已据其组装的会话继续运行。随附 preset 在只读查看器中打开，不提供位置或删除。名单行携带 `broken` 时渲染为标记卡片，其主体与复制均被禁用，因为损坏 preset 的副本只是另一个损坏 preset；损坏的自定义行保留位置与删除动作，以便修复文件、清掉幽灵目录。卡片正面仍显示 preset 自己的描述——在选择器里，一个包说明符不足以让人采取行动——宿主给出的原因作为工具提示附在徽标上，另有一个视觉隐藏的 alert 将该原因传达给辅助技术，而被禁用的卡片主体无法做到这一点。
 
+已知的内置预设提供模式说明与使用示例，通过只读弹窗展示。标签切换保留各页的滚动位置，关闭后焦点回到打开入口。查看帮助不会改变新任务默认模式。默认标签替换卡片的来源标签，预设标识显示在标题旁。说明文案和案例由本包维护，标签切换控件来自 `ui-primitives`。
+
 ### 对话式入口
 
 名单携带自指的 `cordis` preset 时，其虚线添加卡在选择器开启前保持禁用。开启后，它会暂存 `cordis` 并启动新会话——分区关闭设置面板，新建会话 chip 自己的应用器负责组装工作区流程产出的空白会话。
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css b/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
index 91111b0682..76e6b536e3 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css
@@ -84,9 +84,7 @@
   padding: 0;
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(268px, 1fr));
-  /* Every row the same height, so a short description does not make its card
-     shorter than the one beside it. */
-  grid-auto-rows: 1fr;
+  /* Match neighboring cards within a row, without stretching shorter rows. */
   gap: 12px;
 }
 
@@ -214,7 +212,7 @@
   cursor: pointer;
   display: flex;
   flex-direction: column;
-  gap: 8px;
+  gap: 12px;
   padding: 14px 16px 12px;
   border-radius: 12px 12px 0 0;
 }
@@ -230,38 +228,45 @@
 
 .cardHead {
   display: flex;
-  align-items: center;
-  gap: 8px;
+  align-items: flex-start;
+  gap: 12px;
   /* Anchors the broken badge's tooltip: the badge itself stays unpositioned so
-     its `::after` resolves against the card's own width instead of against a
+     the tooltip resolves against the card's own width instead of against a
      badge that sits partway across it. A tooltip grown from the badge would
      run past the card, and past the section for a card in the last column. */
   position: relative;
 }
 
+.cardIdentity {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
 .cardName {
+  min-width: 0;
   font-size: 15px;
   font-weight: 600;
   line-height: 1.4;
-}
-
-/* Placement only: the capsule geometry and palette come from `Tag`. */
-.inUse {
-  margin-left: auto;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 /* Bounded to four lines. A preset publishes its own description, so one long
-   one would otherwise stretch every card in its grid row (`.cards` sizes rows
-   1fr). Clamping is CSS alone: the whole text stays in the DOM for assistive
+   one would otherwise stretch every card in its grid row. Clamping is CSS
+   alone: the whole text stays in the DOM for assistive
    tech, and the card offers it on hover when it is actually cut off. The
    description does not grow to fill the card — `-webkit-line-clamp` on a
    flex-stretched box leaves the clamp height and the box height disagreeing,
-   so `.cardId` takes the free space with an auto margin instead. */
+   so auto margins center the text between the header and footer instead. */
 .cardDesc {
+  margin-block: auto;
   font-size: 13px;
   line-height: 1.55;
   color: var(--dsw-alias-label-secondary);
-  min-height: 42px;
   display: -webkit-box;
   -webkit-box-orient: vertical;
   -webkit-line-clamp: 4;
@@ -271,20 +276,47 @@
 }
 
 .cardId {
-  margin-top: auto;
+  flex-shrink: 0;
+  max-width: 35%;
   font-family: var(--dsw-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
+  line-height: 21px;
   color: var(--dsw-alias-label-tertiary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .cardFoot {
   display: flex;
+  align-items: center;
+  flex-wrap: wrap;
   justify-content: flex-end;
   gap: 2px;
   padding: 6px 10px;
   border-top: 0.5px solid var(--dsw-alias-border-l2);
 }
 
+.cardHelp {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-right: auto;
+}
+
+.helpButton {
+  padding: 5px 6px;
+  min-height: 28px;
+  font-size: 12px;
+  font-weight: 400;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.helpButton:hover,
+.helpButton:focus-visible {
+  color: var(--dsw-alias-label-primary);
+}
+
 /* Icon-only actions: the label rides `title` so the row stays quiet until
    someone reaches for it. */
 .iconButton {
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
index 5738a1fa36..cc3e9157ff 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
@@ -16,10 +16,11 @@ import {
   Button, IconBrowseOutlineRegular, IconCopyOutlineRegular, IconFolderOpenOutlineRegular,
   IconPlusOutlineRegular, IconTrashOutlineRegular, Modal, Switch, Tag, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import { draftBlocker, type AgentPresetSectionState } from './section-store.ts'
 import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts'
+import { PresetGuideDialog, presetGuide, type PresetGuidePage } from './PresetGuideDialog.tsx'
 import css from './AgentPresetSection.module.css'
 
 /** Registration-side business face for the management section. */
@@ -27,6 +28,8 @@ export interface AgentPresetSectionInjected {
   hooks: {
     /** Page snapshot bound by the renderer as useAgentPresetSection. */
     agentPresetSection: SnapshotStore<AgentPresetSectionState>
+    /** Shared preference controlling the picker-policy row. */
+    developerTools: ObservableSnapshot<boolean>
   }
   /** Read the roster; called once when the section first renders. */
   load: () => Promise<void>
@@ -181,6 +184,11 @@ function CardDescription({ text }: { text: string }): ReactNode {
 export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
   const { useAgentPresetSection, t, load } = props
   const state = useAgentPresetSection(snapshot => snapshot)
+  const developerTools = props.useDeveloperTools(enabled => enabled)
+  const [guide, setGuide] = useState<{
+    content: NonNullable<ReturnType<typeof presetGuide>>
+    page: PresetGuidePage
+  } | null>(null)
   const viewedId = state.view?.id
   const viewedRow = viewedId === undefined ? undefined : state.rows.find(row => row.id === viewedId)
   const viewedTitle = state.view === null
@@ -236,21 +244,23 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
     <div className={css.section}>
       <h2 className={css.title}>{t('nav')}</h2>
       <p className={css.intro}>{t('sectionIntro')}</p>
-      <div className={css.pickerPreference}>
-        <div className={css.pickerPreferenceCopy}>
-          <span className={css.pickerPreferenceTitleRow}>
-            <span className={css.pickerPreferenceTitle}>{t('showPicker')}</span>
-            <Tag>{t('showPickerBeta')}</Tag>
-          </span>
-          <p className={css.pickerPreferenceDescription}>{t('showPickerDescription')}</p>
+      {developerTools && (
+        <div className={css.pickerPreference}>
+          <div className={css.pickerPreferenceCopy}>
+            <span className={css.pickerPreferenceTitleRow}>
+              <span className={css.pickerPreferenceTitle}>{t('showPicker')}</span>
+              <Tag>{t('showPickerBeta')}</Tag>
+            </span>
+            <p className={css.pickerPreferenceDescription}>{t('showPickerDescription')}</p>
+          </div>
+          <Switch
+            checked={state.showPicker}
+            label={t('showPicker')}
+            disabled={state.status !== 'ready' || state.policySaving}
+            onChange={(next) => { void props.setPickerVisible(next) }}
+          />
         </div>
-        <Switch
-          checked={state.showPicker}
-          label={t('showPicker')}
-          disabled={state.status !== 'ready' || state.policySaving}
-          onChange={(next) => { void props.setPickerVisible(next) }}
-        />
-      </div>
+      )}
       {state.error === null ? null : <p className={css.error} role="alert">{state.error}</p>}
       {([['system', t('builtInGroup')], ['user', t('customGroup')]] as const).map(([trust, heading]) => {
         const group = state.rows
@@ -258,6 +268,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
           .map(row => ({
             row,
             text: presetDisplayText(row, t),
+            help: presetGuide(row.id, row.trust),
             selectionAction: row.broken !== undefined
               ? t('brokenBadge')
               : row.isDefault
@@ -273,7 +284,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
             <h3 className={css.groupHead}>{heading}</h3>
             {group.length === 0 ? null : (
               <ul className={css.cards}>
-                {group.map(({ row, text, selectionAction }) => (
+                {group.map(({ row, text, selectionAction, help }) => (
                   <li
                     key={row.id}
                     className={[
@@ -317,29 +328,27 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
                       }}
                     >
                       <span className={css.cardHead}>
-                        <span className={css.cardName}>{text.name}</span>
-                        {row.broken !== undefined
-                          ? (
-                            <span className={css.brokenBadge}>
-                              {t('brokenBadge')}
-                              {/* Pointer-only, hence `aria-hidden`: the same
-                                reason reaches assistive technology through the
-                                alert below, and a second copy inside the card's
-                                own text would be read out twice. */}
-                              <span className={css.brokenTip} aria-hidden="true">{row.broken}</span>
-                            </span>
-                          )
-                          : null}
-                        <Tag>
-                          {row.trust === 'user' ? t('userTrust') : t('builtIn')}
-                        </Tag>
-                        {row.isDefault
-                          ? (
-                            <Tag tone="solid" className={css.inUse}>
-                              {state.showPicker ? t('inUse') : t('selectionOffDefault')}
-                            </Tag>
-                          )
-                          : null}
+                        <span className={css.cardIdentity}>
+                          <span className={css.cardName} title={text.name}>{text.name}</span>
+                          {row.broken !== undefined
+                            ? (
+                              <span className={css.brokenBadge}>
+                                {t('brokenBadge')}
+                                {/* Pointer-only, hence `aria-hidden`: the same
+                                  reason reaches assistive technology through the
+                                  alert below, and a second copy inside the card's
+                                  own text would be read out twice. */}
+                                <span className={css.brokenTip} aria-hidden="true">{row.broken}</span>
+                              </span>
+                            )
+                            : null}
+                          <Tag tone={row.isDefault ? 'solid' : 'outline'}>
+                            {row.isDefault
+                              ? state.showPicker ? t('inUse') : t('selectionOffDefault')
+                              : row.trust === 'user' ? t('userTrust') : t('builtIn')}
+                          </Tag>
+                        </span>
+                        <code className={css.cardId} title={row.id}>{row.id}</code>
                       </span>
                       <CardDescription text={text.description ?? t('noDescription')} />
                       {/* Visually hidden, deliberately: the pointer path is the
@@ -349,9 +358,28 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
                       {row.broken === undefined
                         ? null
                         : <span className={css.cardBrokenReason} role="alert">{row.broken}</span>}
-                      <code className={css.cardId}>{row.id}</code>
                     </button>
                     <div className={css.cardFoot}>
+                      {help === undefined ? null : (
+                        <div className={css.cardHelp}>
+                          <Button
+                            variant="ghost"
+                            className={css.helpButton}
+                            aria-label={`${t('modeExplanation')}: ${text.name}`}
+                            onClick={() => { setGuide({ content: help, page: 'explanation' }) }}
+                          >
+                            {t('modeExplanation')}
+                          </Button>
+                          <Button
+                            variant="ghost"
+                            className={css.helpButton}
+                            aria-label={`${t('howToUse')}: ${text.name}`}
+                            onClick={() => { setGuide({ content: help, page: 'usage' }) }}
+                          >
+                            {t('howToUse')}
+                          </Button>
+                        </div>
+                      )}
                       {/* Shipped presets are the compositions a copy starts
                         from, so READING one is the point; a custom preset is
                         edited in its files instead, which the location action
@@ -426,6 +454,14 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
           </section>
         )
       })}
+      {guide === null ? null : (
+        <PresetGuideDialog
+          guide={guide.content}
+          initialPage={guide.page}
+          t={t}
+          onClose={() => { setGuide(null) }}
+        />
+      )}
       <CopyDialog
         state={state}
         t={t}
diff --git a/packages/client/ui-agent-preset/src/client/PresetGuideDialog.module.css b/packages/client/ui-agent-preset/src/client/PresetGuideDialog.module.css
new file mode 100644
index 0000000000..165614e16e
--- /dev/null
+++ b/packages/client/ui-agent-preset/src/client/PresetGuideDialog.module.css
@@ -0,0 +1,146 @@
+.guideDialog {
+  box-sizing: border-box;
+  width: min(640px, 100%);
+  height: min(600px, 100%);
+  max-height: 100%;
+  padding: 0;
+  gap: 0;
+}
+
+.guideLayout {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  height: 100%;
+}
+
+.guideHeader {
+  flex: none;
+  padding: 24px 24px 20px 28px;
+}
+
+.guideTitleRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.guideTitle {
+  margin: 0;
+  font-size: 20px;
+  line-height: 28px;
+  font-weight: 600;
+}
+
+.guideIntro {
+  margin: 8px 0 0;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.guideClose {
+  width: 32px;
+  height: 32px;
+  min-height: 32px;
+  padding: 0;
+  border-radius: 10px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.guideTabs {
+  flex: none;
+  margin: 0 28px 22px;
+}
+
+.guidePanel {
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
+  padding: 0 24px 24px 28px;
+  font-size: 16px;
+  color: var(--dsw-alias-label-primary);
+  overflow-wrap: anywhere;
+}
+
+.guidePanel:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: -2px;
+}
+
+.guidePanel h3 {
+  margin: 28px 0 10px;
+  font-size: 16px;
+  line-height: 24px;
+  font-weight: 600;
+}
+
+.guidePanel h3:first-child {
+  margin-top: 0;
+}
+
+.guidePanel p {
+  margin: 0 0 16px;
+  font-size: 16px;
+  line-height: 1.625;
+  color: var(--dsw-alias-label-primary);
+}
+
+.guidePanel blockquote {
+  margin: 10px 0 14px;
+  padding: 14px 16px;
+  border: 0;
+  border-radius: 12px;
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+.guidePanel blockquote p {
+  margin: 0;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* Usage pages emphasize the example input, with expected results as supporting copy. */
+.guidePanel[data-guide-page='usage'] p {
+  margin-bottom: 12px;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.guidePanel[data-guide-page='usage'] h3 {
+  margin: 0;
+}
+
+.guideExample + .guideExample {
+  margin-top: 28px;
+}
+
+.guideExampleHeader {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px 10px;
+  margin-bottom: 8px;
+}
+
+.guideExampleTag {
+  flex-shrink: 0;
+  gap: 4px;
+}
+
+.guidePanel[data-guide-page='usage'] blockquote {
+  margin: 8px 0;
+  padding: 12px 16px;
+}
+
+.guidePanel[data-guide-page='usage'] blockquote p {
+  margin: 0;
+  font-size: 16px;
+  line-height: 26px;
+  color: var(--dsw-alias-label-primary);
+}
diff --git a/packages/client/ui-agent-preset/src/client/PresetGuideDialog.tsx b/packages/client/ui-agent-preset/src/client/PresetGuideDialog.tsx
new file mode 100644
index 0000000000..6ecb534f02
--- /dev/null
+++ b/packages/client/ui-agent-preset/src/client/PresetGuideDialog.tsx
@@ -0,0 +1,157 @@
+/** Read-only help stays local to Settings and never changes the selected preset. */
+import { useId, useLayoutEffect, useRef, useState } from 'react'
+import type { KeyboardEvent, ReactNode } from 'react'
+import { Button, IconCloseOutlineRegular, IconListPenOutlineRegular, MarkdownText, Modal, SegmentedTabs, Tag } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { AgentPresetSettingsKey } from './locales.ts'
+import css from './PresetGuideDialog.module.css'
+
+export type PresetGuidePage = 'explanation' | 'usage'
+
+/** Locale references for one known, shipped preset. */
+interface PresetGuide {
+  name: AgentPresetSettingsKey
+  intro: AgentPresetSettingsKey
+  explanation: AgentPresetSettingsKey
+  usage: AgentPresetSettingsKey
+}
+
+const guides = new Map<string, PresetGuide>([
+  ['standard', { name: 'presetStandardName', intro: 'guideStandardIntro', explanation: 'guideStandardExplanation', usage: 'guideStandardUsage' }],
+  ['ptc', { name: 'presetPtcName', intro: 'guidePtcIntro', explanation: 'guidePtcExplanation', usage: 'guidePtcUsage' }],
+  ['minimal', { name: 'presetMinimalName', intro: 'guideMinimalIntro', explanation: 'guideMinimalExplanation', usage: 'guideMinimalUsage' }],
+  ['cordis', { name: 'presetCordisName', intro: 'guideCordisIntro', explanation: 'guideCordisExplanation', usage: 'guideCordisUsage' }],
+])
+
+/**
+ * Look up help only for known, shipped presets.
+ * @param id - preset identifier from the roster.
+ * @param trust - roster source; custom presets own their capability claims.
+ * @returns the shipped guide, or undefined for unknown and custom presets.
+ */
+export function presetGuide(id: string, trust: string): PresetGuide | undefined {
+  return trust === 'system' ? guides.get(id) : undefined
+}
+
+/** Curated usage dictionaries contain only level-three example sections. */
+function GuideUsage({ text, t }: {
+  text: string
+  t: (key: AgentPresetSettingsKey) => string
+}): ReactNode {
+  const labels = {
+    code: { copyLabel: t('guideCopy'), copiedLabel: t('guideCopied') },
+    footnotes: t('guideFootnotes'),
+  }
+  return text.split(/(?=^### )/m).map((section) => {
+    const headingEnd = section.indexOf('\n')
+    const title = section.slice(4, headingEnd)
+    return (
+      <section key={title} className={css.guideExample}>
+        <div className={css.guideExampleHeader}>
+          <h3>{title}</h3>
+          <Tag tone="neutral" className={css.guideExampleTag}>
+            <IconListPenOutlineRegular size={12} />
+            {t('guideExampleTask')}
+          </Tag>
+        </div>
+        <MarkdownText text={section.slice(headingEnd + 1)} labels={labels} />
+      </section>
+    )
+  })
+}
+
+/**
+ * Open read-only help without changing the selected preset.
+ * @param props - localized guide, initial page, and close callback.
+ * @returns the modal reader with independent scroll positions for each page.
+ */
+export function PresetGuideDialog({ guide, initialPage, t, onClose }: {
+  guide: PresetGuide
+  initialPage: PresetGuidePage
+  t: (key: AgentPresetSettingsKey) => string
+  onClose: () => void
+}): ReactNode {
+  const [page, setPage] = useState(initialPage)
+  const guideId = useId()
+  const content = useRef<HTMLDivElement>(null)
+
+  useLayoutEffect(() => {
+    const previous = document.activeElement
+    content.current?.querySelector<HTMLButtonElement>('[role="tab"][aria-selected="true"]')?.focus()
+    return () => {
+      if (previous instanceof HTMLElement) previous.focus()
+    }
+  }, [])
+
+  // This reader sits above Settings. Keep keyboard navigation in the reader,
+  // and let Escape dismiss only this layer before returning to its trigger.
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      event.stopPropagation()
+      onClose()
+    } else if (event.key === 'Tab') {
+      const targets = Array.from(event.currentTarget.querySelectorAll<HTMLElement>(
+        'button:not([disabled]):not([tabindex="-1"]), [tabindex="0"]',
+      )).filter(element => !element.closest('[hidden]'))
+      const first = targets[0]
+      const last = targets[targets.length - 1]
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault()
+        last?.focus()
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault()
+        first?.focus()
+      }
+    }
+  }
+
+  return (
+    <Modal open headless onClose={onClose} title={t(guide.name)} className={css.guideDialog as string}>
+      <div ref={content} className={css.guideLayout} role="presentation" onKeyDownCapture={onKeyDown}>
+        <div className={css.guideHeader}>
+          <div className={css.guideTitleRow}>
+            <h2 className={css.guideTitle}>{t(guide.name)}</h2>
+            <Button variant="ghost" className={css.guideClose} aria-label={t('close')} onClick={onClose}>
+              <IconCloseOutlineRegular size={18} />
+            </Button>
+          </div>
+          <p className={css.guideIntro}>{t(guide.intro)}</p>
+        </div>
+        <SegmentedTabs<PresetGuidePage>
+          className={css.guideTabs}
+          label={t('guideSections')}
+          value={page}
+          onChange={setPage}
+          items={[
+            { value: 'explanation', label: t('modeExplanation'), id: `${guideId}-explanation-tab`, panelId: `${guideId}-explanation-panel` },
+            { value: 'usage', label: t('howToUse'), id: `${guideId}-usage-tab`, panelId: `${guideId}-usage-panel` },
+          ]}
+        />
+        {(['explanation', 'usage'] as const).map(section => (
+          <div
+            key={section}
+            id={`${guideId}-${section}-panel`}
+            role="tabpanel"
+            aria-labelledby={`${guideId}-${section}-tab`}
+            className={css.guidePanel}
+            data-guide-page={section}
+            hidden={page !== section}
+            tabIndex={0}
+          >
+            {section === 'usage'
+              ? <GuideUsage text={t(guide.usage)} t={t} />
+              : (
+                <MarkdownText
+                  text={t(guide.explanation)}
+                  labels={{
+                    code: { copyLabel: t('guideCopy'), copiedLabel: t('guideCopied') },
+                    footnotes: t('guideFootnotes'),
+                  }}
+                />
+              )}
+          </div>
+        ))}
+      </div>
+    </Modal>
+  )
+}
diff --git a/packages/client/ui-agent-preset/src/client/guide-locales.ts b/packages/client/ui-agent-preset/src/client/guide-locales.ts
new file mode 100644
index 0000000000..c41b55aef7
--- /dev/null
+++ b/packages/client/ui-agent-preset/src/client/guide-locales.ts
@@ -0,0 +1,152 @@
+/** Curated help for shipped presets, kept separate from their short picker copy. */
+export const guideEn = {
+  modeExplanation: 'Mode details',
+  howToUse: 'How to use',
+  guideSections: 'Guide sections',
+  guideExampleTask: 'Example task',
+  guideCopy: 'Copy',
+  guideCopied: 'Copied',
+  guideFootnotes: 'Footnotes',
+  guideStandardIntro: 'Choose Standard mode when starting a new task. Describe what you want to accomplish, point to the relevant files, and explain how to check the result.',
+  guideStandardExplanation: [
+    '### How it works',
+    'The agent calls tools directly to read and edit files, search, and run terminal commands. It includes Skills, planning, goals, subagents, workflows, and context compaction.',
+    '### When to choose it',
+    'Start here for everyday coding, file work, and research. Standard mode can also write scripts and process files in batches. PTC changes how tool calls are organized; it is not required for batch tasks.',
+  ].join('\n\n'),
+  guideStandardUsage: [
+    '### Fix a bug',
+    '> Find out why submitting the search form twice makes the results disappear. Fix it and run the relevant tests. Explain the cause and what changed.',
+    'Expected output: a code change, the relevant test results, and an explanation of the cause.',
+    '### Organize project notes',
+    '> Read the Markdown notes in this project. Summarize the agreed decisions and open questions, with links to the source files.',
+    'Expected output: a summary with references that you can check against the original notes.',
+  ].join('\n\n'),
+  guidePtcIntro: 'Choose PTC mode when starting a new task. Specify the input files, processing rules, and output format. The agent writes the code.',
+  guidePtcExplanation: [
+    '### How tools are called',
+    'PTC means Programmatic Tool Calling. In this built-in preset, the agent uses run_code to write a TypeScript program that calls tools through a generated SDK. The program can use loops, conditions, error handling, and concurrent calls where appropriate.',
+    '### What reaches the model',
+    'Tool results first reach the program, which can filter and combine them. The model receives what the program prints or returns; image results are attached separately. Nested tool calls are still recorded and remain subject to tool permissions.',
+    '### Compared with Standard mode',
+    'Both modes can handle coding and batch tasks. Standard mode exposes individual tools directly; PTC organizes tool calls in code. The current PTC preset leaves the workflow tool disabled. Speed and token use depend on the task and how the program handles its results.',
+  ].join('\n\n'),
+  guidePtcUsage: [
+    '### Check a set of configuration files',
+    '> Check all JSON files in configs/. List missing required fields and invalid values against schema.json. Save a CSV with one row per issue. Include unreadable files in the report and keep checking the rest. Leave the original files unchanged.',
+    'Expected output: an issue summary and a CSV report. The program can repeat the same checks, handle individual failures, and collect the results.',
+    '### Summarize error logs',
+    '> Analyze the log files in logs/. Group errors by service and error type. Show the ten most frequent groups and one example from each. Save the full counts to a CSV.',
+    'Expected output: the top error groups and a complete count table. Intermediate data can be aggregated in the program before the summary reaches the model.',
+  ].join('\n\n'),
+  guideMinimalIntro: 'Choose Minimal mode for a new task. For a comparison, hold the model, permissions, input, and starting workspace state constant across runs.',
+  guideMinimalExplanation: [
+    '### What is included',
+    'One persistent shell tool and a fixed system prompt. The built-in preset does not load Skills, planning, context compaction, or the standard runtime context.',
+    '### When to choose it',
+    'Use it as a baseline for experiments and comparisons. It can still read files and execute scripts through shell commands, but offers fewer built-in ways to manage a long task. Fewer tools does not necessarily make it easier for a beginner.',
+  ].join('\n\n'),
+  guideMinimalUsage: [
+    '### Compare performance on a small bug fix',
+    '> Run the tests for this project, find the cause of the failure, and make the smallest fix. Run the relevant tests again and report the result.',
+    'Run the same task separately in Standard and Minimal modes from the same starting state. Compare task completion, tool calls, and the resulting changes. Minimal mode performs the work through terminal commands.',
+  ].join('\n\n'),
+  guideCordisIntro: 'Choose Creator mode for a new task. Describe the capability you want, where it should appear, and how you will verify it.',
+  guideCordisExplanation: [
+    '### What you can create',
+    'Creator mode includes the standard task tools plus runtime inspection, persistent plugin management, and guidance for authoring Cordis plugins and agent presets. It can create a plugin that adds a capability or UI, or a preset that combines tools and prompts for a particular job.',
+    '### Plugins and modes',
+    'A plugin adds capabilities to DSH, such as a tool, a service connection, or a UI entry. A mode is an agent preset that selects tools and defines how the agent works in a task. A plugin can be included in a custom preset.',
+    '### How the result takes effect',
+    'Ask the agent to install and verify the result, not just generate source code. A plugin may load immediately or require a restart, depending on what it changes. A newly created preset is selected when starting a new task.',
+  ].join('\n\n'),
+  guideCordisUsage: [
+    '### Add a UI',
+    '> Create a DSH plugin that adds a project notes entry to the sidebar. Let me browse the Markdown files in this workspace and preview a selected note. Install it and verify that the page opens.',
+    'Expected output: an installed plugin with a working entry and preview page, plus any remaining activation steps.',
+    '### Add a tool',
+    '> Create a plugin with a tool that reads this project’s test report and summarizes the failed tests. Register it and verify it with a sample report.',
+    'Expected output: a plugin with a callable tool and a verified sample call.',
+    '### Create my own mode',
+    '> Create a “Code review” mode based on Standard mode. Have it prioritize potential bugs and test gaps, cite file paths and lines, and ask before modifying files. Save it as a selectable preset.',
+    'Expected output: a custom preset for new tasks. These review instructions guide the agent; permission settings determine which actions it can execute.',
+  ].join('\n\n'),
+}
+
+/** Keys merged into the feature’s ordinary locale seat. */
+export type PresetGuideKey = keyof typeof guideEn
+
+/** Simplified Chinese help. Examples describe suggested tasks, not recorded runs. */
+export const guideZh: Record<PresetGuideKey, string> = {
+  modeExplanation: '模式说明',
+  howToUse: '如何使用',
+  guideSections: '帮助内容',
+  guideExampleTask: '示例任务',
+  guideCopy: '复制',
+  guideCopied: '已复制',
+  guideFootnotes: '脚注',
+  guideStandardIntro: '新建任务时选择「标准模式」，说明要完成什么、相关文件在哪里，以及怎样判断任务完成。',
+  guideStandardExplanation: [
+    '### 工作方式',
+    'Agent 直接调用工具来读写文件、检索资料和执行终端命令。包含 Skills、计划、目标、子 Agent、工作流和上下文压缩等能力。',
+    '### 什么时候选',
+    '日常编程、文件处理和资料整理可以从这里开始。标准模式也能编写脚本、批量处理文件；PTC 改变的是工具调用方式，批量任务并不必须使用 PTC。',
+  ].join('\n\n'),
+  guideStandardUsage: [
+    '### 修复一个问题',
+    '> 搜索表单连续提交两次后，结果会消失。请定位原因、修复问题并运行相关测试，最后说明原因和修改内容。',
+    '预期产出：代码修改、相关测试结果，以及问题原因说明。',
+    '### 整理项目资料',
+    '> 阅读项目中的 Markdown 记录，整理已经达成的结论和仍待确认的问题，并附上对应文件链接。',
+    '预期产出：一份带来源引用的总结，方便回到原文核对。',
+  ].join('\n\n'),
+  guidePtcIntro: '新建任务时选择「PTC 模式」，说明输入文件、处理规则和输出格式。代码由 Agent 编写。',
+  guidePtcExplanation: [
+    '### 怎样调用工具',
+    'PTC 是 Programmatic Tool Calling，即通过程序调用工具。当前内置预设让 Agent 通过 run_code 编写 TypeScript 程序，使用生成的工具 SDK 发起调用。程序可以组织循环、条件判断、错误处理，以及适合并发执行的调用。',
+    '### 哪些结果交给模型',
+    '工具返回的数据先交给程序，经过筛选、计算或合并，再通过输出或返回值交给模型；图片结果会另行附加。程序中的工具调用仍会被记录，也仍受工具权限约束。',
+    '### 与标准模式的区别',
+    '两种模式都能编程、批量处理文件。标准模式直接向模型提供各个工具；PTC 让模型用代码组织工具调用。当前 PTC 预设未启用 workflow 工具。速度和 token 用量取决于具体任务与结果处理方式。',
+  ].join('\n\n'),
+  guidePtcUsage: [
+    '### 批量检查配置文件',
+    '> 检查 configs/ 下所有 JSON 文件，按照 schema.json 找出缺失字段和不合法的值。每个问题写成 CSV 中的一行；读取失败的文件也记入报告，继续检查其余文件。保留原文件。',
+    '预期产出：问题汇总和一份 CSV 报告。程序可以对多份文件执行相同检查，处理单个文件的失败，再汇总结果。',
+    '### 汇总错误日志',
+    '> 分析 logs/ 下的日志，按服务和错误类型统计次数，列出出现最多的十类错误，每类保留一条示例。完整统计另存为 CSV。',
+    '预期产出：高频错误摘要和完整统计表。中间数据可以先在程序中聚合，再把汇总交给模型。',
+  ].join('\n\n'),
+  guideMinimalIntro: '新建任务时选择「极简模式」。做对照测试时，保持模型、权限、任务输入和工作区起始状态一致。',
+  guideMinimalExplanation: [
+    '### 保留哪些能力',
+    '仅提供一个持久 Shell 工具，并使用固定系统提示词。内置预设不加载 Skills、计划、上下文压缩，也不注入标准运行时上下文。',
+    '### 什么时候选',
+    '适合作为实验和对照测试的基线。Agent 仍能通过终端命令读写文件、运行脚本，但缺少管理长任务的内置辅助能力。工具少，不代表对新手更容易。',
+  ].join('\n\n'),
+  guideMinimalUsage: [
+    '### 对比基础修复表现',
+    '> 运行这个项目的测试，找出失败原因，做最小修复，再运行相关测试并报告结果。',
+    '分别用标准模式和极简模式，从相同的工作区状态执行这条任务，对比完成情况、工具调用和最终修改。极简模式会通过终端命令完成这些操作。',
+  ].join('\n\n'),
+  guideCordisIntro: '新建任务时选择「创造模式」，说明希望增加什么能力、从哪里使用，以及怎样验证效果。',
+  guideCordisExplanation: [
+    '### 可以创造什么',
+    '创造模式具备标准任务工具，并增加运行时检查、持久化插件管理，以及 Cordis 插件和 Agent 预设的开发指引。可以编写插件来添加功能或界面，也可以组合工具和提示词，创建适合特定任务的模式。',
+    '### 插件与模式的关系',
+    '插件为 DSH 增加能力，例如工具、服务连接或界面入口。模式是一份 Agent 预设，用来选择任务可用的工具，并约定 Agent 的工作方式。自定义模式中也可以使用自己开发的插件。',
+    '### 怎样让成果生效',
+    '可以要求 Agent 完成安装并验证实际效果。插件可能即时加载，也可能需要重启，取决于修改内容；新建的模式在创建新任务时选择。',
+  ].join('\n\n'),
+  guideCordisUsage: [
+    '### 添加一个界面',
+    '> 帮我写一个 DSH 插件，在侧栏增加「项目笔记」入口，列出当前工作区的 Markdown 文件，点击后能预览内容。完成安装并验证页面能打开。',
+    '预期产出：带侧栏入口和预览页的插件，以及仍需完成的生效步骤。',
+    '### 添加一个工具',
+    '> 写一个插件，提供读取项目测试报告、汇总失败用例的工具。注册工具，并用一份示例报告验证调用结果。',
+    '预期产出：可调用的新工具，以及一次示例调用的验证结果。',
+    '### 创建自己的模式',
+    '> 基于标准模式创建「代码审查」模式，优先检查潜在错误和测试缺口，指出文件与行号，修改文件前先询问我。保存成可选择的预设。',
+    '预期产出：可在新任务中选择的自定义模式。审查要求用于指导 Agent，实际可执行的操作仍由权限设置决定。',
+  ].join('\n\n'),
+}
diff --git a/packages/client/ui-agent-preset/src/client/index.ts b/packages/client/ui-agent-preset/src/client/index.ts
index c335518aff..0838fd89aa 100644
--- a/packages/client/ui-agent-preset/src/client/index.ts
+++ b/packages/client/ui-agent-preset/src/client/index.ts
@@ -203,7 +203,7 @@ export function apply(ctx: ClientContext): void {
   }
 
   const sectionInjected = (): AgentPresetSectionInjected => ({
-    hooks: { agentPresetSection: section.store },
+    hooks: { agentPresetSection: section.store, developerTools: ctx.settingsScope.developerTools.enabled },
     load: () => section.load(),
     view: (id: string) => section.view(id),
     closeView: () => { section.closeView() },
diff --git a/packages/client/ui-agent-preset/src/client/locales.ts b/packages/client/ui-agent-preset/src/client/locales.ts
index 39ac4ed537..4d15827ecc 100644
--- a/packages/client/ui-agent-preset/src/client/locales.ts
+++ b/packages/client/ui-agent-preset/src/client/locales.ts
@@ -1,7 +1,10 @@
 /** Locale bundles for the agent-preset hero chip, header label, and management section. */
 
+import { guideEn, guideZh, type PresetGuideKey } from './guide-locales.ts'
+
 /** Locale keys these surfaces render. */
 export type AgentPresetSettingsKey =
+  | PresetGuideKey
   | 'error' | 'userTrust' | 'seatHint' | 'headerHint'
   | 'nav' | 'sectionIntro' | 'builtIn' | 'setDefault' | 'view'
   | 'presetStandardName' | 'presetStandardDescription'
@@ -22,38 +25,39 @@ export type AgentPresetSettingsKey =
 
 /** English copy. */
 export const en: Record<AgentPresetSettingsKey, string> = {
+  ...guideEn,
   error: 'Could not load agent presets.',
   userTrust: 'Custom',
-  seatHint: 'Agent preset for the session you are about to start',
-  headerHint: 'The agent preset this session runs, fixed when it started',
+  seatHint: 'Choose the agent preset for your new task',
+  headerHint: 'The agent preset chosen when this task started',
   nav: 'Agent presets',
   sectionIntro:
-    'A preset is the plugin composition one session\'s agent runs — its tools, prompt, and capabilities. '
-    + 'Duplicate an existing one and make it yours, or let the agent draft one for you in Creator mode.',
+    'Choose the agent\'s tools and how it works. Use Standard mode for everyday tasks, '
+    + 'or Creator mode to add capabilities to DSH.',
   builtIn: 'Built-in',
-  setDefault: 'Set as default',
-  view: 'View',
+  setDefault: 'Set as new task default',
+  view: 'View configuration',
   presetStandardName: 'Standard mode',
   presetStandardDescription:
-    'Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.',
+    'Work with code, files, and information. Suitable for most tasks, with search, editing, terminal commands, and other tools available as needed.',
   presetPtcName: 'PTC mode',
   presetPtcDescription:
-    'Full coding agent without the workflow tool; other tools are exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program.',
+    'Includes all Standard mode capabilities. Better suited to tasks that call tools in batches and then filter, organize, deduplicate, count, or summarize the results.',
   presetMinimalName: 'Minimal mode',
   presetMinimalDescription:
-    'Single-tool coding agent with a persistent shell.',
+    'The agent works using only a terminal tool. Useful for testing and comparing its basic performance.',
   presetCordisName: 'Creator mode',
   presetCordisDescription:
-    'Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, persistent plugin management, and preset-authoring guidance.',
-  duplicate: 'Duplicate',
+    'Customize DSH through conversation. Let the agent write plugins that add features or UI, or combine tools and prompts to create your own mode.',
+  duplicate: 'Duplicate preset',
   duplicateUnavailable: 'This deployment has no writable preset directory',
   delete: 'Delete',
   presetId: 'Identifier',
   presetIdPlaceholder: 'my-agent',
   displayName: 'Name',
-  displayNamePlaceholder: 'Shown in the picker; defaults to the identifier',
+  displayNamePlaceholder: 'Name shown in the mode menu; leave blank to use the identifier',
   inUse: 'New task default',
-  selectionOffDefault: 'Default',
+  selectionOffDefault: 'Application default',
   builtInGroup: 'Built-in',
   customGroup: 'Custom',
   noDescription: 'No description.',
@@ -61,17 +65,17 @@ export const en: Record<AgentPresetSettingsKey, string> = {
   brokenNoCopy: 'A preset that failed to load cannot be duplicated',
   switchRefused: 'Could not switch to {name}: {reason}',
   copyOf: 'Copied from',
-  composition: 'Composition (agent.cordis.yml)',
+  composition: 'Preset configuration (agent.cordis.yml)',
   cancel: 'Cancel',
   close: 'Close',
   retry: 'Retry',
   copyTitle: 'Duplicate preset',
   copyIntro:
-    'The whole preset is copied on this machine. The identifier becomes its directory name and cannot '
-    + 'be changed later; everything else is edited in the preset\'s own files.',
+    'Save a copy on this machine, then open its folder to edit the configuration. '
+    + 'The identifier becomes the folder name and cannot be changed after creation.',
   create: 'Create',
   creating: 'Creating…',
-  creatorDraft: 'Draft a custom preset with Creator mode',
+  creatorDraft: 'Let the agent help me create a preset',
   openLocation: 'Open folder',
   showLocation: 'Show location',
   revealedPathLabel: 'Preset files:',
@@ -83,42 +87,43 @@ export const en: Record<AgentPresetSettingsKey, string> = {
     'The preset directory is deleted. Sessions already running on it keep working; new sessions cannot select it.',
   deleteConfirm: 'Delete',
   deleting: 'Deleting…',
-  showPicker: 'Allow switching Agent modes',
+  showPicker: 'Choose a mode for new tasks',
   showPickerBeta: 'Beta',
   showPickerDescription:
-    'When enabled, new tasks can choose Standard, PTC, Creator, Minimal, and custom modes. When disabled, all new tasks use the default mode (Standard by default; configurable). Only affects new tasks.',
-  enablePickerToSetDefault: 'Turn on Agent mode selection to choose a default',
-  enablePickerToCreate: 'Turn on Agent mode selection to start Creator mode',
+    'When enabled, choose a mode for each new task and set a default here. When disabled, new tasks use the application\'s configured default. Existing tasks are unaffected.',
+  enablePickerToSetDefault: 'Enable mode selection for new tasks before setting a default',
+  enablePickerToCreate: 'Enable mode selection for new tasks before starting Creator mode',
 }
 
 /** Simplified Chinese copy. */
 export const zh: Record<AgentPresetSettingsKey, string> = {
+  ...guideZh,
   error: '无法加载 Agent 预设。',
   userTrust: '自定义',
-  seatHint: '即将开始的这个会话所用的 Agent 预设',
-  headerHint: '本会话运行的 Agent 预设，开始时即固定',
+  seatHint: '选择新任务使用的 Agent 预设',
+  headerHint: '本任务的 Agent 预设，在任务开始时确定',
   nav: 'Agent 预设',
-  sectionIntro: '预设即一个会话的 Agent 所运行的插件组装 —— 它的工具、提示词与能力。复制一份既有预设改成自己的，或用「创造模式」让 Agent 帮你创建。',
+  sectionIntro: '选择 Agent 的工具和工作方式。日常任务用「标准模式」，扩展 DSH 的能力用「创造模式」。',
   builtIn: '内置',
-  setDefault: '设为默认',
-  view: '查看',
+  setDefault: '设为新任务默认',
+  view: '查看配置',
   presetStandardName: '标准模式',
-  presetStandardDescription: '功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。',
+  presetStandardDescription: '处理代码、文件和资料，适合大多数任务。Agent 会按需使用检索、编辑和终端等工具。',
   presetPtcName: 'PTC 模式',
-  presetPtcDescription: '功能完整的编码 Agent，但默认不提供 workflow 工具；其他工具通过 PTC 模式 SDK 呈现，让模型用一个 TypeScript 程序组合多步操作。',
+  presetPtcDescription: '包含标准模式的所有能力，更适合批量调用工具，并对结果进行筛选、整理、去重、统计或汇总的任务。',
   presetMinimalName: '极简模式',
-  presetMinimalDescription: '仅提供持久 shell 的单工具编码 Agent。',
+  presetMinimalDescription: 'Agent 仅使用终端工具完成任务，适合测试和对比其基础表现。',
   presetCordisName: '创造模式',
-  presetCordisDescription: '用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、持久化插件管理和 preset 创作指导。',
-  duplicate: '复制',
+  presetCordisDescription: '用对话定制 DSH：让 Agent 编写插件，添加新功能或界面；也能组合工具和提示词，创建自己的模式。',
+  duplicate: '复制预设',
   duplicateUnavailable: '此部署未配置可写的预设目录',
   delete: '删除',
   presetId: '标识符',
   presetIdPlaceholder: 'my-agent',
   displayName: '名称',
-  displayNamePlaceholder: '选择器中显示的名字，缺省用标识符',
+  displayNamePlaceholder: '在模式列表中显示的名称，不填则使用标识符',
   inUse: '新任务默认',
-  selectionOffDefault: '默认',
+  selectionOffDefault: '应用默认',
   builtInGroup: '内置',
   customGroup: '自定义',
   noDescription: '暂无描述。',
@@ -126,15 +131,15 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
   brokenNoCopy: '预设加载失败，不能复制',
   switchRefused: '无法切换到「{name}」：{reason}',
   copyOf: '复制自',
-  composition: '组装（agent.cordis.yml）',
+  composition: '预设配置（agent.cordis.yml）',
   cancel: '取消',
   close: '关闭',
   retry: '重试',
   copyTitle: '复制预设',
-  copyIntro: '整个预设会在本机复制一份。标识符将成为目录名，事后无法更改；其余内容之后直接在预设自己的文件里编辑。',
+  copyIntro: '复制后会在本机保存一份预设，你可以打开目录修改配置。标识符用作目录名，创建后不能修改。',
   create: '创建',
   creating: '正在创建…',
-  creatorDraft: '用「创造模式」创作自定义预设',
+  creatorDraft: '让 Agent 帮我创建预设模式',
   openLocation: '打开目录',
   showLocation: '查看路径',
   revealedPathLabel: '预设文件：',
@@ -145,11 +150,11 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
   deleteDescription: '预设目录将被删除。已在其上运行的会话不受影响；新会话将无法再选择它。',
   deleteConfirm: '删除',
   deleting: '正在删除…',
-  showPicker: '允许切换agent模式',
-  showPickerBeta: 'beta',
-  showPickerDescription: '开启后，新任务可选择标准、PTC、创造、极简及自定义模式；关闭后统一使用默认模式（默认为标准模式，可自定义）。仅影响新任务。',
-  enablePickerToSetDefault: '请先开启 Agent 模式选择，再设置默认模式',
-  enablePickerToCreate: '请先开启 Agent 模式选择，再启动创造模式',
+  showPicker: '新任务可选择模式',
+  showPickerBeta: 'Beta',
+  showPickerDescription: '开启后，可为每个新任务选择模式，并在这里设置默认值。关闭后，新任务使用应用配置的默认预设。已有任务不受影响。',
+  enablePickerToSetDefault: '请先开启新任务模式选择，再设置默认值',
+  enablePickerToCreate: '请先开启新任务模式选择，再启动创造模式',
 }
 
 // The resolution itself is the shared fold in `dsh-agent-presets/display`,
diff --git a/packages/client/ui-agent-preset/tests/section.client.spec.tsx b/packages/client/ui-agent-preset/tests/section.client.spec.tsx
index d67dc98529..4bf77e08bb 100644
--- a/packages/client/ui-agent-preset/tests/section.client.spec.tsx
+++ b/packages/client/ui-agent-preset/tests/section.client.spec.tsx
@@ -17,6 +17,8 @@ import { en } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
+const translations: ReadonlyMap<string, string> = new Map(Object.entries(en))
+
 const READY: AgentPresetSectionState = {
   status: 'ready',
   error: null,
@@ -35,6 +37,10 @@ const READY: AgentPresetSectionState = {
   revealedPaths: {},
 }
 
+function unusedHook(): never {
+  throw new Error('This section does not read global slot sources')
+}
+
 /**
  * Render the section over a fixed snapshot, with every action a spy.
  * @param state - the snapshot to render.
@@ -42,7 +48,7 @@ const READY: AgentPresetSectionState = {
  */
 function renderSection(
   state: Partial<AgentPresetSectionState> = {},
-  options: { creator?: boolean } = {},
+  options: { creator?: boolean; developerTools?: boolean } = {},
 ) {
   const store = createSnapshotStore<AgentPresetSectionState>({ ...READY, ...state })
   const actions = {
@@ -63,11 +69,18 @@ function renderSection(
     makeDefault: vi.fn(() => Promise.resolve()),
     setPickerVisible: vi.fn(() => Promise.resolve()),
   }
-  const props = {
+  const props: AgentPresetSectionProps = {
     ...actions,
+    usePanelInfo: unusedHook,
+    useSessions: unusedHook,
+    useSessionStatus: unusedHook,
+    useSessionRetainInfo: unusedHook,
+    useWorkspaces: unusedHook,
+    useResource: unusedHook,
     useAgentPresetSection: bindSnapshotSelector(store),
-    t: (key: keyof typeof en) => en[key],
-  } as unknown as AgentPresetSectionProps
+    useDeveloperTools: bindSnapshotSelector(createSnapshotStore(options.developerTools ?? true)),
+    t: key => translations.get(key) ?? key,
+  }
   render(<AgentPresetSection {...props} />)
   return actions
 }
@@ -82,6 +95,13 @@ function rowFor(id: string): HTMLElement {
 }
 
 describe('the preset list', () => {
+  it('hides the complete picker-policy row while developer tools are off', () => {
+    renderSection({}, { developerTools: false })
+    expect(screen.queryByRole('switch', { name: en.showPicker })).toBeNull()
+    expect(screen.queryByText(en.showPickerDescription)).toBeNull()
+    expect(screen.queryByText(en.showPickerBeta)).toBeNull()
+  })
+
   it('reads the roster once when it first renders', async () => {
     const actions = renderSection()
 
@@ -100,11 +120,11 @@ describe('the preset list', () => {
     expect(within(mine).getByText(en.noDescription)).toBeTruthy()
   })
 
-  it('marks trust and the one in use, and offers no "set default" on it', () => {
+  it('replaces the default preset trust tag with its new-task default status', () => {
     renderSection()
 
     const standard = rowFor('standard')
-    expect(within(standard).getByText(en.builtIn)).toBeTruthy()
+    expect(within(standard).queryByText(en.builtIn)).toBeNull()
     expect(within(standard).getByText(en.inUse)).toBeTruthy()
     expect(within(standard).queryByText(en.setDefault)).toBeNull()
     expect(within(rowFor('mine')).getByText(en.userTrust)).toBeTruthy()
@@ -348,14 +368,8 @@ describe('the preset list', () => {
   })
 
   it('renders nothing when the deployment composes no presets', () => {
-    const { container } = render(<AgentPresetSection {...({
-      useAgentPresetSection: bindSnapshotSelector(
-        createSnapshotStore<AgentPresetSectionState>({ ...READY, status: 'unavailable', rows: [] })),
-      t: (key: keyof typeof en) => en[key],
-      load: vi.fn(() => Promise.resolve()),
-    } as unknown as AgentPresetSectionProps)} />)
-
-    expect(container.firstChild).toBeNull()
+    renderSection({ status: 'unavailable', rows: [] })
+    expect(screen.queryByRole('heading')).toBeNull()
   })
 
   it('offers a retry when the roster could not be read', () => {
@@ -368,6 +382,108 @@ describe('the preset list', () => {
   })
 })
 
+describe('preset help', () => {
+  it.each([
+    ['standard', en.presetStandardName, 'How it works', 'Fix a bug'],
+    ['ptc', en.presetPtcName, 'How tools are called', 'Check a set of configuration files'],
+    ['minimal', en.presetMinimalName, 'What is included', 'Compare performance on a small bug fix'],
+    ['cordis', en.presetCordisName, 'What you can create', 'Add a UI'],
+  ])('opens both help sections for %s without changing the default', (id, name, heading, exampleTitle) => {
+    const actions = renderSection({ rows: [{ id, trust: 'system', isDefault: false }] })
+    const trigger = within(rowFor(id)).getByRole('button', { name: `${en.modeExplanation}: ${name}` })
+    trigger.focus()
+    fireEvent.click(trigger)
+
+    const dialog = screen.getByRole('dialog', { name })
+    expect(within(dialog).getByRole('heading', { name: heading })).toBeTruthy()
+    const usage = within(dialog).getByRole('tab', { name: en.howToUse })
+    fireEvent.click(usage)
+    expect(usage.getAttribute('aria-selected')).toBe('true')
+    expect(within(dialog).getByRole('heading', { name: exampleTitle })).toBeTruthy()
+    expect(within(dialog).getAllByText(en.guideExampleTask).length).toBeGreaterThan(0)
+    fireEvent.click(within(dialog).getByRole('tab', { name: en.modeExplanation }))
+    expect(within(dialog).getByRole('heading', { name: heading })).toBeTruthy()
+    fireEvent.click(within(dialog).getByRole('button', { name: en.close }))
+    expect(document.activeElement).toBe(trigger)
+
+    fireEvent.click(within(rowFor(id)).getByRole('button', { name: `${en.howToUse}: ${name}` }))
+    expect(within(screen.getByRole('dialog')).getByRole('tab', { name: en.howToUse }).getAttribute('aria-selected')).toBe('true')
+    expect(actions.makeDefault).not.toHaveBeenCalled()
+    expect(actions.view).not.toHaveBeenCalled()
+    expect(actions.startCreatorDraft).not.toHaveBeenCalled()
+  })
+
+  it('keeps keyboard focus in help and dismisses only the reader on Escape', () => {
+    const actions = renderSection()
+    const trigger = within(rowFor('standard')).getByRole('button', { name: `${en.modeExplanation}: ${en.presetStandardName}` })
+    trigger.focus()
+    fireEvent.click(trigger)
+    const dialog = screen.getByRole('dialog')
+    const details = within(dialog).getByRole('tab', { name: en.modeExplanation })
+    const panel = within(dialog).getByRole('tabpanel', { name: en.modeExplanation })
+    const close = within(dialog).getByRole('button', { name: en.close })
+    expect(document.activeElement).toBe(details)
+    expect(fireEvent.keyDown(details, { key: 'Tab' })).toBe(true)
+    panel.focus()
+    fireEvent.keyDown(panel, { key: 'Tab' })
+    expect(document.activeElement).toBe(close)
+    fireEvent.keyDown(close, { key: 'Tab', shiftKey: true })
+    expect(document.activeElement).toBe(panel)
+    fireEvent.keyDown(panel, { key: 'Escape' })
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(document.activeElement).toBe(trigger)
+    expect(actions.close).not.toHaveBeenCalled()
+  })
+
+  it('closes even when the browser reports no previously focused element', () => {
+    const activeElement = vi.spyOn(document, 'activeElement', 'get').mockReturnValue(null)
+    try {
+      renderSection()
+      fireEvent.click(within(rowFor('standard')).getByRole('button', { name: `${en.modeExplanation}: ${en.presetStandardName}` }))
+      fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: en.close }))
+      expect(screen.queryByRole('dialog')).toBeNull()
+    } finally {
+      activeElement.mockRestore()
+    }
+  })
+
+  it('connects keyboard selection to the visible guide panel', () => {
+    renderSection()
+    fireEvent.click(within(rowFor('standard')).getByRole('button', { name: `${en.modeExplanation}: ${en.presetStandardName}` }))
+    const dialog = screen.getByRole('dialog')
+    const details = within(dialog).getByRole('tab', { name: en.modeExplanation })
+    const usage = within(dialog).getByRole('tab', { name: en.howToUse })
+    expect(details.tabIndex).toBe(0)
+    expect(usage.tabIndex).toBe(-1)
+    fireEvent.keyDown(details, { key: 'ArrowRight' })
+    const panel = within(dialog).getByRole('tabpanel', { name: en.howToUse })
+    expect(panel.id).toBe(usage.getAttribute('aria-controls'))
+    expect(document.activeElement).toBe(usage)
+    expect(usage.getAttribute('aria-selected')).toBe('true')
+    expect(details.tabIndex).toBe(-1)
+    expect(usage.tabIndex).toBe(0)
+    expect(within(dialog).queryByRole('tabpanel', { name: en.modeExplanation })).toBeNull()
+  })
+
+  it('does not attach built-in claims to custom or unknown presets', () => {
+    renderSection({
+      rows: [
+        { id: 'ptc', trust: 'user', isDefault: false },
+        { id: 'third-party', trust: 'system', isDefault: false },
+      ],
+    })
+    expect(screen.queryByRole('button', { name: new RegExp(en.modeExplanation) })).toBeNull()
+    expect(screen.queryByRole('button', { name: new RegExp(en.howToUse) })).toBeNull()
+  })
+
+  it('leaves help usable when mode selection is disabled', () => {
+    const actions = renderSection({ showPicker: false })
+    fireEvent.click(within(rowFor('standard')).getByRole('button', { name: `${en.howToUse}: ${en.presetStandardName}` }))
+    expect(screen.getByRole('dialog', { name: en.presetStandardName })).toBeTruthy()
+    expect(actions.setPickerVisible).not.toHaveBeenCalled()
+  })
+})
+
 describe('the copy dialog', () => {
   const draft: CopyDraft = {
     from: 'standard', fromTitle: '标准模式', id: '', name: '', saving: false, error: null,
diff --git a/packages/client/ui-approval/src/client/contract/slots.ts b/packages/client/ui-approval/src/client/contract/slots.ts
index 99296e0c92..875fe5ea36 100644
--- a/packages/client/ui-approval/src/client/contract/slots.ts
+++ b/packages/client/ui-approval/src/client/contract/slots.ts
@@ -65,6 +65,9 @@ export type ApprovalDecision = 'allowed-once' | 'rejected'
 
 let nextApprovalKey = 0
 
+/** Domain discriminator literal carried by {@link PendingApproval.kind}. */
+export type ApprovalInteractionKind = 'approval'
+
 /** One answerable Client presentation of a pending Host waterfall. */
 export class PendingApproval {
   /** Domain discriminator used by Session pending-interaction consumers. */
diff --git a/packages/client/ui-attachment/README.i18n.yaml b/packages/client/ui-attachment/README.i18n.yaml
index 5ce716a2ae..0fad5492e0 100644
--- a/packages/client/ui-attachment/README.i18n.yaml
+++ b/packages/client/ui-attachment/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-attachment/README.md
-README.md: 0765068c73c8ca3cf79b8b23a54629669625ca2e
-README.zh.md: 5976acfda5b605dd85ba3d43e18a83af4d9d58e0
+README.md: 5a3e697189936a79df19ff9b976f06e0dd6191fb
+README.zh.md: 4168650770f42e7b94146041f37ffc440a5ec52e
diff --git a/packages/client/ui-attachment/README.md b/packages/client/ui-attachment/README.md
index 0765068c73..5a3e697189 100644
--- a/packages/client/ui-attachment/README.md
+++ b/packages/client/ui-attachment/README.md
@@ -39,7 +39,7 @@ Trajectory attachment rows request 48px square thumbnails that contain the compl
 
 ### Drop overlay
 
-While a file drag is over the page, the full-viewport overlay announces the drop: illustration, title, and a limits line when drops are accepted. The overlay only shows state — the owner's document-level listeners decide accept or reject.
+While a file drag is over the page, the full-viewport overlay announces the drop: illustration, title, and a limits line when drops are accepted. The overlay only shows state — the owner's document-level listeners decide accept or reject, and the drop handler reports which dropped members are directories through the entry API so the owner can cite or refuse them.
 
 -----
 
diff --git a/packages/client/ui-attachment/README.zh.md b/packages/client/ui-attachment/README.zh.md
index 5976acfda5..4168650770 100644
--- a/packages/client/ui-attachment/README.zh.md
+++ b/packages/client/ui-attachment/README.zh.md
@@ -39,7 +39,7 @@ Trajectory 附件行使用 48px 方形缩略图，完整缩放图片而不裁剪
 
 ### 拖放遮罩
 
-文件拖到页面上方时，全视口遮罩显示拖放提示，包括插画和标题；接受拖放时还会显示一行限制说明。遮罩只呈现状态——是否接受由持有方的文档级监听器决定。
+文件拖到页面上方时，全视口遮罩显示拖放提示，包括插画和标题；接受拖放时还会显示一行限制说明。遮罩只呈现状态，是否接受由持有方的文档级监听器决定，拖放处理器通过 entry API 报告放下的成员中哪些是文件夹，以便持有方引用或拒绝它们。
 
 -----
 
diff --git a/packages/client/ui-attachment/src/client/drop-events.ts b/packages/client/ui-attachment/src/client/drop-events.ts
index e04cbd43d0..2f3da69372 100644
--- a/packages/client/ui-attachment/src/client/drop-events.ts
+++ b/packages/client/ui-attachment/src/client/drop-events.ts
@@ -1,6 +1,24 @@
 /** Document drag-and-drop listeners owned by one mounted attachment view. */
 import type { ComposerAttachmentsProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
+/**
+ * Members of a drop that are directories. The `File` a directory drop yields
+ * is indistinguishable from an empty file, so the entry API is the only
+ * source of that fact; browsers without it report no directories.
+ */
+function droppedDirectories(dataTransfer: DataTransfer, files: readonly File[]): ReadonlySet<File> {
+  const directories = new Set<File>()
+  let fileIndex = 0
+  for (const item of dataTransfer.items) {
+    if (item.kind !== 'file') continue
+    const file = files[fileIndex++]
+    if (typeof item.webkitGetAsEntry !== 'function') continue
+    if (item.webkitGetAsEntry()?.isDirectory !== true) continue
+    if (file !== undefined) directories.add(file)
+  }
+  return directories
+}
+
 /**
  * Install one attachment view's file-drop listeners.
  * @param canAcceptDrop - whether this view accepts the dropped files.
@@ -49,7 +67,10 @@ export function installDocumentDropEvents(
     if (dataTransfer === null) return
     event.preventDefault()
     reset()
-    if (canAcceptDrop) onAddFiles([...dataTransfer.files])
+    if (canAcceptDrop) {
+      const files = [...dataTransfer.files]
+      onAddFiles(files, droppedDirectories(dataTransfer, files))
+    }
   }
   document.addEventListener('dragenter', onDragEnter)
   document.addEventListener('dragover', onDragOver)
diff --git a/packages/client/ui-attachment/tests/composer-attachments.client.spec.tsx b/packages/client/ui-attachment/tests/composer-attachments.client.spec.tsx
index c0d0920c52..057e29dc9c 100644
--- a/packages/client/ui-attachment/tests/composer-attachments.client.spec.tsx
+++ b/packages/client/ui-attachment/tests/composer-attachments.client.spec.tsx
@@ -103,20 +103,49 @@ describe('ComposerAttachments', () => {
     expect(view.queryByRole('status')).toBeNull()
 
     const image = attachment('dropped').file
-    const dataTransfer = { types: ['Files'], files: [image], dropEffect: 'none' }
+    const dataTransfer = { types: ['Files'], files: [image], items: [], dropEffect: 'none' }
     expect(fireEvent.dragEnter(document.body, { dataTransfer })).toBe(false)
     expect(view.getByRole('status').textContent).toContain('文件或图片拖动到此处即可添加')
     expect(view.getByRole('status').textContent).toContain('图片限制：最多 20 张，每张 5MB')
     expect(fireEvent.dragOver(document.body, { dataTransfer })).toBe(false)
     expect(dataTransfer.dropEffect).toBe('copy')
     expect(fireEvent.drop(document.body, { dataTransfer })).toBe(false)
-    expect(onAddFiles).toHaveBeenCalledWith([image])
+    expect(onAddFiles).toHaveBeenCalledWith([image], new Set())
     expect(view.queryByRole('status')).toBeNull()
   })
 
+  it('reports dropped directories from the entry API beside the dropped files', () => {
+    const onAddFiles = vi.fn()
+    render(<ComposerAttachments {...props({ onAddFiles })} />)
+    const folder = new File([], 'project')
+    const note = new File([Uint8Array.of(1)], 'notes.md', { type: 'text/markdown' })
+    const entry = (isDirectory: boolean | null, file: File) => ({
+      kind: 'file', getAsFile: () => new File([], file.name), webkitGetAsEntry: () => (isDirectory === null ? null : { isDirectory }),
+    })
+    fireEvent.drop(document.body, {
+      dataTransfer: {
+        types: ['Files'],
+        files: [folder, note],
+        items: [entry(true, folder), entry(false, note), { kind: 'string', getAsFile: () => null }],
+        dropEffect: 'none',
+      },
+    })
+    expect(onAddFiles).toHaveBeenCalledWith([folder, note], new Set([folder]))
+    // An entry API that answers nothing, or a browser without it, reports no directories.
+    fireEvent.drop(document.body, {
+      dataTransfer: {
+        types: ['Files'],
+        files: [note],
+        items: [entry(null, note), { kind: 'file', getAsFile: () => note }, entry(true, folder)],
+        dropEffect: 'none',
+      },
+    })
+    expect(onAddFiles).toHaveBeenLastCalledWith([note], new Set())
+  })
+
   it('tracks nested file drags and clears an aborted drag', () => {
     const view = render(<ComposerAttachments {...props()} />)
-    const dataTransfer = { types: ['Files'], files: [], dropEffect: 'none' }
+    const dataTransfer = { types: ['Files'], files: [], items: [], dropEffect: 'none' }
     fireEvent.dragLeave(document.body, {
       dataTransfer: { types: ['text/plain'], files: [], dropEffect: 'none' },
     })
@@ -144,7 +173,7 @@ describe('ComposerAttachments', () => {
     const onAddFiles = vi.fn()
     const view = render(<ComposerAttachments {...props({ canAcceptDrop: false, onAddFiles })} />)
     const image = attachment('blocked').file
-    const dataTransfer = { types: ['Files'], files: [image], dropEffect: 'copy' }
+    const dataTransfer = { types: ['Files'], files: [image], items: [], dropEffect: 'copy' }
     fireEvent.dragEnter(document.body, { dataTransfer })
     expect(view.getByRole('status').textContent).toBe('当前无法添加文件或图片')
     fireEvent.dragOver(document.body, { dataTransfer })
diff --git a/packages/client/ui-attachment/tests/message-image.client.spec.tsx b/packages/client/ui-attachment/tests/message-image.client.spec.tsx
index ee14237ad5..21db2ee64e 100644
--- a/packages/client/ui-attachment/tests/message-image.client.spec.tsx
+++ b/packages/client/ui-attachment/tests/message-image.client.spec.tsx
@@ -327,6 +327,8 @@ describe('ImageGallery', () => {
       useTrajectory,
       useInput,
       inputActions: {
+        captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+        insertText: () => false,
         setDraft: vi.fn(),
         addAttachments: vi.fn(() => true),
         removeAttachment: vi.fn(),
diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml
index c42928d650..1eefd3ba94 100644
--- a/packages/client/ui-chat/README.i18n.yaml
+++ b/packages/client/ui-chat/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-chat/README.md
-README.md: b916802917bfdd406fb333174371507d466b8e19
-README.zh.md: 01de4d633cb1501a03200aa96f72e89622d0a7d8
+README.md: 2beb4dfadddec0c834c3ef6f4b56826be120baa6
+README.zh.md: 5d643f4e90b77d2b79ab1bb1c003b399c202e004
diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
index b916802917..2beb4dfadd 100644
--- a/packages/client/ui-chat/README.md
+++ b/packages/client/ui-chat/README.md
@@ -8,14 +8,14 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use this package to render a browser chat from recorded Session conversations, including historical images, localized actions, and restored scroll position. Compact display folds completed-turn process rows while keeping the final answer and independently useful context visible; packed historical Assistant runs remain collapsed. Local transcript and steering submissions appear immediately, remain in their original surface, and disappear atomically when authoritative Session records arrive, while queued submissions stay outside Chat. The package does not assemble or modify model requests.
+Use this package to render a browser chat from recorded Session conversations, including historical images, localized actions, and restored scroll position. Work-details modes control reasoning previews and fold eligible completed-turn process rows without hiding final answers. Local transcript and steering submissions appear immediately, remain in their original surface, and disappear atomically when authoritative Session records arrive, while queued submissions stay outside Chat. The package does not assemble or modify model requests.
 
 File-mention providers receive the viewed Session ID with the closing-turn owner, so links into inherited history can address the fork itself.
 
 ## Table of Contents
 
 - [Reference previews](#reference-previews)
-- [System prompt row](#system-prompt-row)
+- [Hidden Chat rows](#system-prompt-row)
 - [Command and failure rows](#command-and-failure-rows)
 - [Turn token usage](#turn-token-usage)
 - [Completed-turn footer](#completed-turn-footer)
@@ -32,12 +32,12 @@ File-mention providers receive the viewed Session ID with the closing-turn owner
 
 Chat supplies file and HTTP(S) navigation through one `MarkdownDelegateProvider` around its node list. Assistant Markdown file links open in the right Sidebar after the message settles, including references to unmodified files. Relative paths resolve in the viewed Session's workspace; absolute paths retain the same Session's filesystem access. `#L24` and `#L24-L30` navigate to the first specified line and reuse an existing file tab. Missing files show the preview's error state.
 
-HTTP(S) links in Assistant Markdown open a new right-Sidebar Browser tab on ordinary clicks when that type is registered, or the system browser otherwise; modified clicks retain the native external-link behavior. Sent file references and skills confirmed by the message’s logged invocation also open in the right Sidebar. File paths use the viewed Session; skill names resolve through its current input-trigger source. Both use the prose file-link dotted underline on hover or focus. Sessions, directories, and command labels remain non-navigating references.
+Settings → General → Open chat links in selects the destination for ordinary clicks on Chat HTTP(S) links: Built-in browser (default) opens a new right-Sidebar Browser tab, while New browser tab opens an external tab. The setting is shown only while the built-in browser is available. If the Sidebar Browser is not registered, both choices use the external browser; modified clicks retain native behavior. The `ui-chat.linkOpening` preference persists on loopback browsers and stays process-local when settings cannot persist writes. Sent file references and skills confirmed by the message’s logged invocation also open in the right Sidebar. File paths use the viewed Session; skill names resolve through its current input-trigger source. Both use the prose file-link dotted underline on hover or focus. Sessions, directories, and command labels remain non-navigating references.
 
 <a id="system-prompt-row"></a>
-## System prompt row
+## Hidden Chat rows
 
-Each nonempty appended `system/message` owns a collapsed prompt row, including a complete prompt at the start of a headerless window; the same-step header does not duplicate it. Chat also shows a collapsed `System prompt` row for a non-empty initial request, explicit message-series start, or `system/message` surface node replacement whose text differs, reading the last nonempty surviving system node in surface order at the `request/header`; a non-initial request whose preceding header is outside the loaded history window also shows one. A resume repeats the row even when its system text is unchanged, including after pagination supplies the preceding header and system node; same-series config-only or tool-only changes, tool steps, and retries create no repetition, and a `system/message` event is never rendered as a transcript message. The row appears before that request's user messages, matching the provider envelope, and expands to the exact model-visible text with its original line breaks. A request whose system node is empty or outside the loaded window creates no row until the page holding the node arrives.
+Chat omits system-prompt and `permission` command rows in every work-details mode. The filter changes neither recorded Session events nor Trajectory inspection. Ordinary Context injection and other command rows remain in Chat; Context injection can fold with the owning Turn's process content.
 
 <a id="command-and-failure-rows"></a>
 ## Command and failure rows
@@ -65,9 +65,23 @@ The completed-turn action footer starts 20px below the preceding prose or extens
 <a id="turn-process-folding"></a>
 ## Turn Process Folding
 
-Each reasoning row starts collapsed, including during streaming and in reasoning-only replies. Clicking the row opens or closes its complete Markdown; incoming answer text, Tool calls, and stream completion preserve that choice. Expanded reasoning uses compact secondary typography: headings add bold weight without changing text size, line height, or color. The collapsed summary stays on one line, follows the latest reasoning line while streaming, and shows the first line after settlement.
+Each reasoning row starts collapsed, including during streaming and in reasoning-only replies. Clicking the row opens or closes its complete Markdown; incoming answer text, Tool calls, and stream completion preserve that choice. Expanded reasoning uses compact secondary typography: headings add bold weight without changing text size, line height, or color. While streaming, all modes preview the latest paragraph whose first line ends with a newline. Further text in that paragraph does not change the preview; an unfinished single line has no preview. One or more blank lines separate paragraphs. The one-line preview fades at the right edge. After settlement, Compact hides the preview, while Detailed and Expanded show the full text's first line.
 
-Settings → General exposes a persisted, localized `Normal` / `Compact` conversation-display preference in the `ui-chat` namespace; `Compact` is the default. Normal leaves process rows visible and renders no Turn-process control. In Compact mode, the System prompt remains independently visible before the opening User throughout the Turn. Context injection, reasoning, Assistant material, Tool rows, and Retry rows remain expanded while a Turn is open. At `turn/end`, its latest Step becomes the final-answer boundary only when it contains non-blank text, an image, or an unknown visible block—and no Tool-call block; preceding Context injection, reasoning, earlier Assistant material, Tool rows, and Retry rows then collapse by default. The control reports Turn-wide durable counts for non-subagent Tool calls, reply-bearing Assistant messages before the final answer, and subagent delegation calls; zero-valued segments are omitted, the Tool and subagent figures are mutually exclusive, and neither System prompt nor Context injection contributes a count. When all three counts are zero, the process still folds and the control reads `Thought for a while`. A full-width divider below the summary separates it from the answer or expanded process rows. User and steering messages, System prompt, error, max-token, and turn-tail rows stay outside, and a closed Turn with no final answer keeps all process evidence visible. A newly available process control is inserted without changing the relative order of existing rows: opening human input precedes the control and process rows from their first projection, while System prompt remains above that input. While older history remains available through Load earlier, process controls stay absent and no members are hidden; once history is complete, every eligible closed Turn uses the collapsed default immediately. Stable Chat Node Seats keep every renderer mounted, hidden members add no flow spacing, and a closed control sits 8px above its answer only when no independent input intervenes. Completion collapse does not depend on tail-follow position, so a reader above the tail may see the transcript reflow. An automatic collapse that would hide keyboard focus keeps the group open and leaves focus in place; a manual close focuses the process control before hiding its members. The session-scoped store records only manually expanded Turn-and-answer-Step generations; a different answer generation starts collapsed.
+Reasoning rows retain the disclosure's callback, icon, and unchanged content references. Each reasoning row selects its preview visibility from the display policy; mode changes toggle CSS display without unmounting the collapsed summary or updating its parent Assistant renderer. Full Markdown elements are created only while expanded.
+
+Settings → General → Work details stores `ui-chat.transcriptView` as `compact` (default), `detailed`, or `expanded`. A saved legacy `normal` value reads as `detailed` without being written back; it is not offered as an option.
+
+| Behavior | Compact | Detailed | Expanded |
+|---|---|---|---|
+| Settled reasoning preview | Think title only | First line | First line |
+| Individual reasoning and tool bodies | Manual expansion | Manual expansion | Manual expansion |
+| Eligible completed-Turn process | Folded by default | Folded by default | Folded by default |
+
+While a Turn is open, its process rows remain in the transcript; individual reasoning and tool disclosures retain their own expansion state. At `turn/end`, its latest Step becomes the final-answer boundary only when it contains non-blank text, an image, or an unknown visible block—and no Tool-call block. If that Turn's `turn/start` is loaded, preceding Context injection, reasoning, earlier Assistant material, Tool rows, and Retry rows fold by default. Folding eligibility is per Turn: a complete Turn can fold while Load earlier remains available, and a Turn whose start is missing keeps its process content visible until that start arrives. A closed Turn with no final answer also keeps all process evidence visible.
+
+The control reports Turn-wide durable counts for non-subagent Tool calls, reply-bearing Assistant messages before the final answer, and subagent delegation calls. Zero-valued segments are omitted; the Tool and subagent figures are mutually exclusive, and Context injection contributes no count. When all three counts are zero, the process still folds and the control reads `Thought for a while`. A full-width divider below the summary separates it from the answer or expanded process rows. User and steering messages, error, max-token, and turn-tail rows stay outside. A newly available process control preserves existing row order, with opening human input before the control and process rows.
+
+Stable Chat Node Seats keep every renderer mounted, hidden members add no flow spacing, and a closed control sits 8px above its answer only when no independent input intervenes. Completion collapse does not depend on tail-follow position, so a reader above the tail may see the transcript reflow. An automatic collapse that would hide keyboard focus keeps the process open and leaves focus in place; a manual close focuses the process control before hiding its members. The session-scoped store records only manually expanded Turn-and-answer-Step generations; a different answer generation starts collapsed. Switching work-details modes preserves manual expansion.
 
 -----
 
@@ -102,6 +116,8 @@ None; Chat presentation does not assemble or mutate provider requests.
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- **Secondary process grouping is not implemented** — Detailed and Expanded currently display the same Chat content. Expanded retains whole-Turn folding and does not automatically open individual reasoning or tool bodies.
+
 - **Developer messages are not displayed** — presentation is intentionally deferred; encountering `developer/message` throws instead of rendering a fallback row.
 
 - **The transcript reflects the loaded Session window** — older transcript nodes become available only after Session Controller loads the preceding event page. Turn navigation is wider than the window: the rail merges the loaded Turns with the host `turnOutline` projection, so every started Turn gets a fixed-pitch mark (10px apart; a ladder taller than the frame scrolls inside it with gradient fades), and activating an unloaded mark pages history through the Turn's `turn/start` seq before landing on its row. Without the projection (assemblies not mounting `dsh-session-turn-outline`) the rail falls back to loaded Turns only.
diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
index 01de4d633c..5d643f4e90 100644
--- a/packages/client/ui-chat/README.zh.md
+++ b/packages/client/ui-chat/README.zh.md
@@ -8,14 +8,14 @@ kind: "package-reference"
 
 ## 概述
 
-使用本包可在浏览器中渲染已记录的 Session 对话，包括历史图片、本地化操作和滚动位置恢复。紧凑显示会收起已完成轮次的过程行，同时保持最终答案和独立有用的上下文可见；已打包的历史 Assistant 连续消息保持收起。本地 transcript（文本记录）与 steering（中途引导）提交会立即显示并保留在原区域，在权威会话记录到达时原子地消失，而排队中的提交始终不进入 Chat。本包不组装或修改模型请求。
+使用本包可在浏览器中渲染已记录的 Session 对话，包括历史图片、本地化操作和滚动位置恢复。工作过程展示模式控制思考预览，并收起符合条件的已完成轮次过程行，不隐藏最终答案。本地 transcript（文本记录）与 steering（中途引导）提交会立即显示并保留在原区域，在权威会话记录到达时原子地消失，而排队中的提交始终不进入 Chat。本包不组装或修改模型请求。
 
 文件提及提供方同时接收当前查看的会话 ID 与收尾轮次的属主信息，因此继承历史中的链接可以指向 fork 自身。
 
 ## 目录
 
 - [引用预览](#reference-previews)
-- [系统提示词行](#system-prompt-row)
+- [Chat 隐藏的行](#system-prompt-row)
 - [指令与失败行](#command-and-failure-rows)
 - [轮次 token 用量](#turn-token-usage)
 - [已完成轮次的页脚](#completed-turn-footer)
@@ -32,12 +32,12 @@ kind: "package-reference"
 
 Chat 在节点列表外通过一个 `MarkdownDelegateProvider` 提供文件及 HTTP(S) 导航。Assistant Markdown 文件链接在消息落定后可于右侧栏打开，包括未修改文件的引用。相对路径基于当前查看的 Session 工作区解析；绝对路径仍使用同一 Session 的文件系统访问。`#L24` 和 `#L24-L30` 定位到指定起始行，并复用现有文件标签。文件缺失时显示预览错误状态。
 
-Assistant Markdown 中的 HTTP(S) 链接在普通点击时会在该类型已注册时打开新的右侧 Sidebar Browser tab，否则改用系统浏览器；带修饰键的点击保留原生外部链接行为。已发送的文件引用及消息日志确认调用的 skill 也可在右侧栏打开预览。文件路径使用当前查看的 Session；skill 名称由该 Session 当前的输入触发源解析。两者悬停或聚焦时均使用正文文件链接的虚线下划线。会话、目录和命令标签仍只作为引用展示。
+设置 → 通用设置 → 聊天链接打开方式控制普通点击 Chat HTTP(S) 链接时的目标：「内置浏览器」（默认）打开新的右侧 Sidebar Browser tab，「浏览器新标签页」打开外部标签页。该设置项仅在内置浏览器可用时显示。若 Sidebar Browser 未注册，两种选择均使用外部浏览器；带修饰键的点击保留原生行为。`ui-chat.linkOpening` 偏好在回环地址浏览器中持久化，设置无法持久化写入时仅在当前进程内生效。已发送的文件引用及消息日志确认调用的 skill 也可在右侧栏打开预览。文件路径使用当前查看的 Session；skill 名称由该 Session 当前的输入触发源解析。两者悬停或聚焦时均使用正文文件链接的虚线下划线。会话、目录和命令标签仍只作为引用展示。
 
 <a id="system-prompt-row"></a>
-## 系统提示词行
+## Chat 隐藏的行
 
-每个非空追加的 `system/message` 都拥有一行折叠提示词，包括无 header 窗口起点的完整提示词；同一步骤的 header 不会重复它。Chat 也会为非空的初始请求、显式消息序列起点、文本发生变化的 `system/message` surface 节点替换（文本读取自 `request/header` 处 surface 顺序中最后一个非空存活系统节点），或前序 header 尚未进入已加载历史窗口的非初始请求显示一行默认折叠的 `系统提示词`。即使系统文本未变，恢复也会重复该行，包括分页补齐前序 header 和系统节点后；同一序列内仅配置或仅工具变化、工具步骤与重试不会重复，且 `system/message` 事件绝不会渲染为对话消息。该行位于请求的用户消息之前，与提供方 envelope 顺序一致；展开后显示模型所见的确切文本，并保留其原始换行。系统节点为空或位于已加载窗口之外的请求不创建该行，直到包含该节点的分页到达。
+Chat 在所有工作过程展示模式下都不显示系统提示词行和 `permission` 命令行。该过滤不改变已记录的 Session 事件或 Trajectory 查看能力。普通上下文注入和其他命令行仍保留在 Chat 中；上下文注入可随所属轮次的过程内容一起收起。
 
 <a id="command-and-failure-rows"></a>
 ## 指令与失败行
@@ -65,9 +65,23 @@ Assistant Markdown 中的 HTTP(S) 链接在普通点击时会在该类型已注
 <a id="turn-process-folding"></a>
 ## 轮次过程折叠
 
-每个思考行初始都折叠，包括流式输出期间和仅含思考的回复。点击该行可展开或收起完整 Markdown；后续回答文本、工具调用和流结束都保留用户的选择。展开的思考采用紧凑的次级排版：标题只加粗，不改变字号、行高或颜色。折叠摘要保持单行，在流式输出期间跟随最新思考行，结算后显示第一行。
+每个思考行初始都折叠，包括流式输出期间和仅含思考的回复。点击该行可展开或收起完整 Markdown；后续回答文本、工具调用和流结束都保留用户的选择。展开的思考采用紧凑的次级排版：标题只加粗，不改变字号、行高或颜色。流式输出期间，三档都预览最近一个首行以换行符结束的段落；该段落后续文本不会改变预览，未写完的单行不显示预览。一个或多个空行分隔段落。预览保持单行，右侧渐隐。结算后，「简洁」隐藏预览，「详细」和「完全展开」显示全文首行。
 
-「设置 → 通用设置」提供持久化到 `ui-chat` 命名空间的「标准」/「紧凑」对话显示偏好，默认使用「紧凑」。标准模式保持所有过程行可见且不渲染轮次过程控件。紧凑模式下，系统提示词在整个轮次中始终独立显示于开场 User 上方。轮次打开期间，上下文注入、推理、Assistant 内容、工具行与重试行始终展开。到 `turn/end` 时，最后一个步骤只有在包含非空文本、图片或未知可见块且不含工具调用块时才成为最终答案边界；边界之前的上下文注入、推理、较早 Assistant 内容、工具行与重试行随后默认收起。控件展示覆盖整个轮次的非 subagent 工具调用数、最终答案之前带回复内容的 Assistant 消息数和 subagent 委派数；值为 0 的分段省略，工具调用与 subagent 两项互斥，系统提示词与上下文注入都不增加计数。三项全为 0 时过程仍会收起，控件标题显示「已思考」（英文为 `Thought for a while`）。摘要下方的通栏分隔线将其与正文或展开后的过程行隔开。用户与 steering 消息、系统提示词、错误、最大 token 与 turn-tail 行留在过程组外；关闭时没有最终答案的轮次保留全部过程证据。新的过程控件插入时不会改变既有行的相对顺序：开场人工输入从首次投影起便位于控件和过程行之前，系统提示词则始终位于该输入上方。只要仍可通过「加载更早」获取历史，过程控件就不出现，也不会隐藏任何成员；历史加载完整后，每个合格的已关闭轮次立即使用默认收起状态。稳定 Chat Node Seat 会让每个 renderer 保持挂载，隐藏成员不产生消息流间距；只有中间没有独立输入时，收起控件才与正文相隔 8px。完成后的收起不依赖是否跟随尾部，因此正在上方阅读的用户可能看到 transcript 重排。若自动收起会隐藏当前键盘焦点，则过程组保持展开且焦点留在原处；手动收起会先把焦点移到过程控件，再隐藏成员。会话作用域存储只记录用户手动展开的「轮次 + 正文步骤」generation；不同正文 generation 默认收起。
+思考行保留折叠控件的回调、图标和未变化内容的引用。每个思考行从展示策略中选择预览可见性；模式切换只改变 CSS 显示状态，不卸载折叠摘要，也不更新其父级 Assistant 渲染器。完整 Markdown 元素仅在展开时创建。
+
+「设置 → 通用设置 → 工作过程展示」将 `ui-chat.transcriptView` 保存为 `compact`（默认）、`detailed` 或 `expanded`。已保存的旧值 `normal` 读取为 `detailed`，不自动回写，也不再作为选项提供。
+
+| 行为 | 简洁 | 详细 | 完全展开 |
+|---|---|---|---|
+| 已完成思考的预览 | 只显示「思考」标题 | 首行 | 首行 |
+| 单个思考与工具正文 | 手动展开 | 手动展开 | 手动展开 |
+| 符合条件的已完成轮次过程 | 默认收起 | 默认收起 | 默认收起 |
+
+轮次打开期间，过程行保留在 transcript 中，单个思考与工具控件各自保留开合状态。到 `turn/end` 时，最后一个步骤只有在包含非空文本、图片或未知可见块且不含工具调用块时才成为最终答案边界。若该轮次的 `turn/start` 已加载，边界之前的上下文注入、思考、较早 Assistant 内容、工具行与重试行默认收起。折叠资格逐轮判断：即使仍可「加载更早」，完整轮次也能收起；缺少起点的轮次则保持过程内容可见，直到该起点加载。关闭时没有最终答案的轮次也保留全部过程证据。
+
+控件展示覆盖整个轮次的非 subagent 工具调用数、最终答案之前带回复内容的 Assistant 消息数和 subagent 委派数。值为 0 的分段省略；工具调用与 subagent 两项互斥，上下文注入不增加计数。三项全为 0 时过程仍会收起，控件标题显示「已思考」（英文为 `Thought for a while`）。摘要下方的通栏分隔线将其与正文或展开后的过程行隔开。用户与 steering 消息、错误、最大 token 与 turn-tail 行留在过程之外。新的过程控件保留既有行的相对顺序，开场人工输入位于控件和过程行之前。
+
+稳定 Chat Node Seat 会让每个 renderer 保持挂载，隐藏成员不产生消息流间距；只有中间没有独立输入时，收起控件才与正文相隔 8px。完成后的收起不依赖是否跟随尾部，因此正在上方阅读的用户可能看到 transcript 重排。若自动收起会隐藏当前键盘焦点，则过程保持展开且焦点留在原处；手动收起会先把焦点移到过程控件，再隐藏成员。会话作用域存储只记录用户手动展开的「轮次 + 正文步骤」generation；不同正文 generation 默认收起。切换工作过程展示模式会保留手动展开状态。
 
 -----
 
@@ -102,6 +116,8 @@ Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点，并且
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- **二级过程分组尚未实现**——「详细」与「完全展开」目前展示相同的 Chat 内容。「完全展开」仍保留整轮折叠，不会自动打开单个思考或工具正文。
+
 - **不展示 developer 消息** — 展示能力有意留待后续实现；遇到 `developer/message` 时抛出错误，不渲染回退行。
 
 - **transcript 只反映已加载的 Session 窗口**——只有会话控制器加载前一页事件后，更早的 transcript node 才会出现。轮次导航比窗口更宽：轨道把已加载的轮次与宿主 `turnOutline` 投影合并，每个已开始的轮次都有固定间距刻度（相隔 10px；阶梯高于外框时在框内滚动并以渐变淡出标示可滚方向），激活未加载刻度会先把历史分页拉到该轮次的 `turn/start` seq 再落到它的行上。没有该投影时（未挂载 `dsh-session-turn-outline` 的装配），轨道回退到仅显示已加载轮次。
diff --git a/packages/client/ui-chat/src/chat-settings.ts b/packages/client/ui-chat/src/chat-settings.ts
index dbf9014320..ccc9bc55fd 100644
--- a/packages/client/ui-chat/src/chat-settings.ts
+++ b/packages/client/ui-chat/src/chat-settings.ts
@@ -5,15 +5,24 @@ import z from '@deepseek-ai/schemastery'
 /** Settings namespace owned by the Chat target. */
 export const CHAT_SETTINGS_NAMESPACE = 'ui-chat'
 
-/** Field carrying the completed-Turn transcript presentation mode. */
+/** Field carrying the work-details presentation mode. */
 export const TRANSCRIPT_VIEW_FIELD = 'transcriptView'
 
-/** Transcript presentation modes accepted at settings boundaries. */
-export const TRANSCRIPT_VIEW_MODES = ['normal', 'compact'] as const
+/** Work-details presentation modes a user can choose. */
+export const TRANSCRIPT_VIEW_MODES = ['compact', 'detailed', 'expanded'] as const
 
-/** Completed-Turn transcript presentation. */
+/** Work-details presentation mode. */
 export type TranscriptViewMode = typeof TRANSCRIPT_VIEW_MODES[number]
 
+/**
+ * Saved value from the two-mode generation of this setting. Read as `detailed`;
+ * never offered as a choice and never written back.
+ */
+export const LEGACY_TRANSCRIPT_VIEW_MODE = 'normal'
+
+/** Every value the durable field accepts: current modes plus the legacy saved value. */
+const TRANSCRIPT_VIEW_SETTING_VALUES = [...TRANSCRIPT_VIEW_MODES, LEGACY_TRANSCRIPT_VIEW_MODE] as const
+
 /** Default preserves the compact process disclosure introduced by Chat. */
 export const DEFAULT_TRANSCRIPT_VIEW_MODE: TranscriptViewMode = 'compact'
 
@@ -26,16 +35,25 @@ export type PerformanceUsageMode = typeof PERFORMANCE_USAGE_MODES[number]
 /** Preserve detailed accounting for users without an explicit preference. */
 export const DEFAULT_PERFORMANCE_USAGE: PerformanceUsageMode = 'detailed'
 
+/** Destinations for ordinary clicks on Chat HTTP(S) links. */
+export type LinkOpening = 'sidebar' | 'new-tab'
+
+/** Preserve the built-in browser for users without an explicit preference. */
+export const DEFAULT_LINK_OPENING: LinkOpening = 'sidebar'
+
 /** Durable Chat section shared by the Host schema and browser scope. */
 export interface ChatSettings {
-  /** Presentation mode for completed Turn process content. */
-  transcriptView: TranscriptViewMode
+  /** Work-details preference; the legacy value is accepted only from existing saved settings. */
+  transcriptView: TranscriptViewMode | typeof LEGACY_TRANSCRIPT_VIEW_MODE
   /** Detail level for composer statistics and completed-Turn usage. */
   performanceUsage: PerformanceUsageMode
+  /** Default destination for Chat HTTP(S) links. */
+  linkOpening: LinkOpening
 }
 
 /** Durable Chat schema; also the wire envelope the browser scope validates against. */
 export const ChatSettingsSchema: z<ChatSettings> = z.object({
+  linkOpening: z.union(['sidebar', 'new-tab']).default(DEFAULT_LINK_OPENING),
   performanceUsage: z.union([...PERFORMANCE_USAGE_MODES]).default(DEFAULT_PERFORMANCE_USAGE),
-  [TRANSCRIPT_VIEW_FIELD]: z.union([...TRANSCRIPT_VIEW_MODES]).default(DEFAULT_TRANSCRIPT_VIEW_MODE),
+  [TRANSCRIPT_VIEW_FIELD]: z.union([...TRANSCRIPT_VIEW_SETTING_VALUES]).default(DEFAULT_TRANSCRIPT_VIEW_MODE),
 })
diff --git a/packages/client/ui-chat/src/client/apply.ts b/packages/client/ui-chat/src/client/apply.ts
index 21a63ab782..70390ec889 100644
--- a/packages/client/ui-chat/src/client/apply.ts
+++ b/packages/client/ui-chat/src/client/apply.ts
@@ -3,7 +3,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type { SessionBinding } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-browser/client'
@@ -34,7 +34,9 @@ import { en, NS, zh } from './locale.ts'
 import { TranscriptViewRow, type TranscriptViewRowInjected } from './settings/TranscriptViewRow.tsx'
 import { createChatStore } from './stores.ts'
 import { TranscriptViewPolicy } from './transcript-view.ts'
-import { CHAT_SETTINGS_NAMESPACE, type ChatSettings } from '../chat-settings.ts'
+import { derivePresentationPolicy } from './presentation-policy.ts'
+import { CHAT_SETTINGS_NAMESPACE, DEFAULT_LINK_OPENING, type ChatSettings } from '../chat-settings.ts'
+import { LinkOpeningRow, type LinkOpeningRowInjected } from './settings/LinkOpeningRow.tsx'
 import { PerformanceUsageRow, type PerformanceUsageRowInjected } from './settings/PerformanceUsageRow.tsx'
 import { PerformanceUsagePolicy } from './performance-usage.ts'
 import { useTurnDataValue } from './chat/use-turn-data.ts'
@@ -82,10 +84,38 @@ export function apply(ctx: Context): void {
   const chatStore = createChatStore()
   const chatScrollPositions = new Map<SessionId, ChatScrollPosition>()
   const chatSettings = ctx.settingsScope.bind<ChatSettings>({ namespace: CHAT_SETTINGS_NAMESPACE })
+  const linkOpening = createSnapshotStore(chatSettings.getSnapshot().value?.linkOpening ?? DEFAULT_LINK_OPENING)
+  ctx.effect(() => chatSettings.subscribe(() => {
+    const accepted = chatSettings.getSnapshot().value?.linkOpening
+    if (accepted !== undefined) linkOpening.set(accepted)
+  }))
+  ctx.inject(['sidebarRightTabs'], (scope) => {
+    const tabs = scope.sidebarRightTabs
+    const browserAvailable: ObservableSnapshot<boolean> = {
+      getSnapshot: () => tabs.get('browser') !== undefined,
+      subscribe: listener => tabs.subscribe(listener),
+    }
+    scope.slots.inject('settings.general.item', () => scope.slots.register({
+      name: 'settings.general.item',
+      id: 'link-opening',
+      order: 14,
+      locale: NS,
+      inject: (): LinkOpeningRowInjected => ({
+        hooks: { linkOpening, browserAvailable },
+        setLinkOpening: (destination) => {
+          linkOpening.set(destination)
+          void chatSettings.set('linkOpening', destination).catch((_error: unknown) => {
+            // The local choice remains usable when persistence is unavailable.
+          })
+        },
+      }),
+    }, LinkOpeningRow))
+  })
   const transcriptView = new TranscriptViewPolicy(chatSettings)
+  const presentation = derivePresentationPolicy(transcriptView.mode)
   const performancePolicy = new PerformanceUsagePolicy(chatSettings)
   const performanceUsage = performancePolicy.mode
-  registerChatNodeRenderers(ctx, performanceUsage)
+  registerChatNodeRenderers(ctx, performanceUsage, presentation)
 
   ctx.slots.inject('settings.general.item', () => ctx.slots.register({
     name: 'settings.general.item',
@@ -127,7 +157,7 @@ export function apply(ctx: Context): void {
         const session = binding.session
         const chat = chatSource(binding)
         return {
-          hooks: { transcriptView: transcriptView.mode },
+          hooks: { presentation },
           keyedHooks: {
             chatNode: key => chat.getSnapshot().nodes.source(key),
             chatNodeProcess: key => chat.getSnapshot().nodes.processSource(key),
@@ -158,7 +188,7 @@ export function apply(ctx: Context): void {
             ctx.get('inputTriggers')?.sessionOf(scope).openReference('skill', { ref: `/${name}` })
           },
           openExternalLink: (url) => {
-            if (ctx.get('sidebarRightTabs')?.get('browser') !== undefined) {
+            if (linkOpening.getSnapshot() === 'sidebar' && ctx.get('sidebarRightTabs')?.get('browser') !== undefined) {
               ctx.sidebarRight.openTab('browser', { params: { url } })
             } else {
               window.open(url, '_blank', 'noopener,noreferrer')
diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
index 13ff7fae4b..da45e543a9 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
@@ -2,7 +2,7 @@ import { Fragment, memo, useMemo } from 'react'
 import type { ReactNode } from 'react'
 import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { MarkdownFileMentions, MarkdownPathImages } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatNodeOwnerProps, ChatViewSlotProps, UsePresentation } from '../contract/slots.ts'
 import type { AssistantBlock } from '../contract/snapshot.ts'
 import { markdownLabels } from '../markdown-labels.ts'
 import { ReasoningRow } from './ReasoningRow.tsx'
@@ -31,7 +31,9 @@ export interface AssistantMarkdownProps {
   renderMessageImages: ChatNodeOwnerProps['renderMessageImages']
   /** Hide reasoning that belongs to the Turn-level process disclosure. */
   reasoningHidden?: boolean | undefined
-  /** Reveal the owning Turn-level process disclosure. */
+  /** Live display policy for reasoning summaries. */
+  usePresentation: UsePresentation
+  /** Reveal the disclosure that hides this reasoning. */
   revealProcess?: (() => void) | undefined
   /** Resolved prose file mentions for this Assistant's closing turn. */
   mentions?: MarkdownFileMentions | undefined
@@ -42,7 +44,7 @@ export interface AssistantMarkdownProps {
 /** Reasoning block as the Think variant summary row (figma 39:28304). */
 export const AssistantMarkdown = memo(function AssistantMarkdown({
   blocks, streaming, interrupted, renderMessageImages,
-  reasoningHidden = false, revealProcess, mentions, t,
+  reasoningHidden = false, usePresentation, revealProcess, mentions, t,
 }: AssistantMarkdownProps) {
   // Stable per locale revision (t identity changes on switch): a fresh object
   // per render would rebuild MarkdownText's component table every chunk.
@@ -83,7 +85,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
             hidden={reasoningHidden}
             reveal={revealProcess}
           >
-            <ReasoningRow text={block.text} running={streaming && i === last} t={t} />
+            <ReasoningRow text={block.text} running={streaming && i === last} usePresentation={usePresentation} t={t} />
           </ProcessReasoning>,
         )
         break
diff --git a/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx b/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx
index 399897a9b5..9ef72941f5 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantNodeView.tsx
@@ -1,11 +1,14 @@
 import { memo, useCallback, useMemo } from 'react'
-import type { ChatNodeViewProps, TurnTailOwnerProps } from '../contract/slots.ts'
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ChatNodeViewProps, PresentationInjected, TurnTailOwnerProps } from '../contract/slots.ts'
 import { AssistantMarkdown } from './AssistantMarkdown.tsx'
 
+type AssistantNodeViewProps = ChatNodeViewProps<'assistant-step'> & InjectFace<PresentationInjected>
+
 /** Streaming, settled, and interrupted Assistant states share one keyed renderer instance. */
 export const AssistantNodeView = memo(function AssistantNodeView({
-  node, useTurnData, turnProcess, openFile, renderMessageImages, fileMentions, t,
-}: ChatNodeViewProps<'assistant-step'>) {
+  node, useTurnData, turnProcess, openFile, renderMessageImages, fileMentions, usePresentation, t,
+}: AssistantNodeViewProps) {
   const data = node.data
   const turn = node.location.kind === 'turn' || node.location.kind === 'step'
     ? node.location.turn
@@ -33,6 +36,7 @@ export const AssistantNodeView = memo(function AssistantNodeView({
       interrupted={data.status === 'interrupted'}
       renderMessageImages={renderMessageImages}
       reasoningHidden={reasoningHidden}
+      usePresentation={usePresentation}
       revealProcess={revealProcess}
       mentions={mentions}
       t={t}
diff --git a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
index 40e08dbaf7..3ed6f7b8d8 100644
--- a/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatNodeSeat.tsx
@@ -1,7 +1,7 @@
 import { memo, useCallback, useMemo } from 'react'
 import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ConversationLocationDataStore, ConversationTurnDataMap } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatNodeOwnerProps, ChatViewSlotProps, UsePresentation } from '../contract/slots.ts'
 import type { ChatNode } from '../contract/chat-nodes.ts'
 import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts'
 import { storedTurnProcessEntry } from '../stores.ts'
@@ -12,8 +12,7 @@ interface ChatNodeSeatProps extends ChatNodeOwnerProps {
   readonly nodeKey: string
   readonly useChatNode: ChatViewSlotProps['useChatNode']
   readonly useChatNodeProcess: ChatViewSlotProps['useChatNodeProcess']
-  readonly historyIncomplete: boolean
-  readonly compactTranscript: boolean
+  readonly usePresentation: UsePresentation
   readonly useStore: ChatViewSlotProps['useStore']
   readonly actions: ChatViewSlotProps['actions']
   readonly renderSlot: ChatViewSlotProps['renderSlot']
@@ -34,9 +33,13 @@ function turnOf(node: ChatNode | undefined): number | undefined {
   return location?.kind === 'turn' || location?.kind === 'step' ? location.turn.turn : undefined
 }
 
-/** Subscribe, apply Turn-process visibility, and dispatch one stable Context key. */
+/**
+ * Subscribe, apply Turn-process visibility, and dispatch one stable Context key.
+ * Policy reads select this seat's own conclusion, so a mode change re-renders
+ * only seats whose visibility actually changes.
+ */
 export const ChatNodeSeat = memo(function ChatNodeSeat({
-  nodeKey, useChatNode, useChatNodeProcess, historyIncomplete, compactTranscript,
+  nodeKey, useChatNode, useChatNodeProcess, usePresentation,
   cwd, openFile, openSkill, inspectCall, forkAt,
   loadImage, renderMessageImages, fileMentions, useStore, actions, renderSlot, t,
 }: ChatNodeSeatProps) {
@@ -59,13 +62,15 @@ export const ChatNodeSeat = memo(function ChatNodeSeat({
       actions.setTurnProcessOpen(processSpec.turn, processSpec.answerStep, open)
     }
   }, [actions, processSpec])
+  const foldCompleted = usePresentation(policy => policy.foldCompletedTurns)
+  // Folding is decided per Turn: the Turn is closed and its start is loaded.
   const processWindowReady = processSpec !== undefined
     && processPresentation !== undefined
-    && compactTranscript
+    && foldCompleted
     && processSpec.answerAnchorSeq !== null
     && processPresentation.turn === processSpec.turn
     && processPresentation.turnClosed
-    && !historyIncomplete
+    && processPresentation.turnStarted
   const processMember = routedNode !== undefined
     && processWindowReady
     && !TURN_PROCESS_INDEPENDENT_KINDS.has(routedNode.kind)
diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx
index 257dad64ab..bad68eb828 100644
--- a/packages/client/ui-chat/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx
@@ -113,7 +113,7 @@ const ChatNodeList = memo(function ChatNodeList({ order, ...seatProps }: ChatNod
 export function ChatView({
   useSession, useChat, useChatNode, useChatNodeProcess, useSessions, useStore, actions, renderSlot,
   sessionId, openFile, openSkill, openExternalLink, loadOlder, loadThrough, loadImage, inspectCall, chatScroll, forkAt, fileMentions,
-  useTranscriptView, useProjection, t,
+  usePresentation, useProjection, t,
 }: ChatViewSlotProps) {
   const order = useChat(s => s.order)
   const nodeStore = useChat(s => s.nodes)
@@ -137,7 +137,6 @@ export function ChatView({
   const openError = useSession(s => s.openError)
   const hasMore = useSession(s => s.hasMore)
   const loadingOlder = useSession(s => s.loadingOlder)
-  const compactTranscript = useTranscriptView(mode => mode === 'compact')
   const [fileOpenError, setFileOpenError] = useState<{ path: string; message: string } | null>(null)
   const [fileOpenBusy, setFileOpenBusy] = useState(false)
   // Close/retry must ignore a settlement that started before the latest
@@ -237,8 +236,7 @@ export function ChatView({
               order={order}
               useChatNode={useChatNode}
               useChatNodeProcess={useChatNodeProcess}
-              historyIncomplete={hasMore}
-              compactTranscript={compactTranscript}
+              usePresentation={usePresentation}
               useStore={useStore}
               actions={actions}
               cwd={cwd}
diff --git a/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css b/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css
index 513a826c46..a4bb6ef0cc 100644
--- a/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css
+++ b/packages/client/ui-chat/src/client/chat/GenericCommandCard.module.css
@@ -3,32 +3,6 @@
   flex-direction: column;
 }
 
-.row {
-  position: relative;
-  overflow: hidden;
-}
-
-.root[data-state='running'] .row::after {
-  content: '';
-  position: absolute;
-  inset-block: 0;
-  left: 0;
-  width: 300px;
-  background: linear-gradient(
-    90deg,
-    transparent 0%,
-    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
-    transparent 100%
-  );
-  animation: dsh-command-row-sweep 2.6s ease-out infinite;
-  pointer-events: none;
-}
-
-@keyframes dsh-command-row-sweep {
-  0% { left: -300px; }
-  90%, 100% { left: 100%; }
-}
-
 .leading {
   flex-shrink: 0;
 }
@@ -39,6 +13,7 @@
 
 .title {
   font-weight: 400;
+  transition: color 100ms ease;
 }
 
 .separator {
@@ -59,6 +34,12 @@
   line-height: calc(24px + var(--dsh-content-font-delta, 0px));
   text-overflow: ellipsis;
   white-space: nowrap;
+  transition: color 100ms ease;
+}
+
+.row:hover .title,
+.row:hover .summary:not([data-error]) {
+  color: var(--dsw-alias-label-primary);
 }
 
 .summary[data-error],
@@ -78,9 +59,3 @@
   font: var(--dsw-font-markdown-code-block-small);
   white-space: pre-wrap;
 }
-
-@media (prefers-reduced-motion: reduce) {
-  .root[data-state='running'] .row::after {
-    animation: none;
-  }
-}
diff --git a/packages/client/ui-chat/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-chat/src/client/chat/GenericCommandCard.tsx
index 2864836301..0b0749881b 100644
--- a/packages/client/ui-chat/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-chat/src/client/chat/GenericCommandCard.tsx
@@ -1,11 +1,13 @@
-import { useState } from 'react'
+import { memo, useCallback, useMemo, useState } from 'react'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
-import { DisclosureRow, IconApiOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
+import { DisclosureRow, IconApiOutlineRegular, TextShimmer } from '@deepseek-ai/dsh-client-ui-primitives'
 import a11yCss from './accessibility.module.css'
 import css from './GenericCommandCard.module.css'
 
 type CommandRowState = 'running' | 'ok' | 'error'
 
+const COMMAND_ICON = <IconApiOutlineRegular size={14} />
+
 /** Node state → row state semantic (running while unsettled; outcome kind after). */
 function stateOf(outcome: CommandRowOwnerProps['node']['outcome']): CommandRowState {
   if (outcome === null) return 'running'
@@ -19,7 +21,12 @@ export interface GenericCommandCardProps extends CommandRowOwnerProps {
   runningSummary?: string | undefined
 }
 
-export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCardProps) {
+/**
+ * Render a command summary and its lazily mounted multiline output.
+ * @param props - command, locale, and optional running label.
+ * @returns the command disclosure.
+ */
+export const GenericCommandCard = memo(function GenericCommandCard({ node, t, runningSummary }: GenericCommandCardProps) {
   const [expanded, setExpanded] = useState(false)
   const text = node.outcome?.text
   const summary = node.outcome === null
@@ -29,8 +36,21 @@ export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCa
   // command name.
   const title = node.name ?? t('command.title')
   const state = stateOf(node.outcome)
+  const running = state === 'running'
   const body = text !== undefined && text.includes('\n') ? text : null
   const open = expanded && body !== null
+  const toggle = useCallback(() => { setExpanded(value => !value) }, [])
+  const collapsedContent = useMemo(() => (
+    <>
+      <span className={css.separator} aria-hidden />
+      <span className={css.summary} data-error={state === 'error' || undefined}>
+        <TextShimmer active={running}>{summary}</TextShimmer>
+      </span>
+    </>
+  ), [running, state, summary])
+  const content = useMemo(() => open
+    ? <pre className={css.body} data-error={state === 'error' || undefined}>{body}</pre>
+    : undefined, [body, open, state])
   return (
     <div className={css.root} data-variant="others" data-state={state}>
       {state === 'running' && <span className={a11yCss.visuallyHidden}>{t('row.running')}</span>}
@@ -40,22 +60,18 @@ export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCa
         leadingClassName={css.leading}
         titleClassName={css.title}
         chevronClassName={css.chevron}
-        icon={<IconApiOutlineRegular size={14} />}
+        icon={COMMAND_ICON}
         title={title}
+        running={running}
         open={open}
         expandable={body !== null}
         expandOnRowClick
         keepContentWhenOpen
-        onToggle={() => { setExpanded(value => !value) }}
-        collapsedContent={(
-          <>
-            <span className={css.separator} aria-hidden />
-            <span className={css.summary} data-error={state === 'error' || undefined}>{summary}</span>
-          </>
-        )}
+        onToggle={toggle}
+        collapsedContent={collapsedContent}
       >
-        <pre className={css.body} data-error={state === 'error' || undefined}>{body}</pre>
+        {content}
       </DisclosureRow>
     </div>
   )
-}
+})
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
index 3ca51f8d85..f59c04e404 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
@@ -83,20 +83,20 @@
   text-overflow: ellipsis;
 }
 
-.summary[data-follow-end] {
-  display: flex;
-  justify-content: flex-end;
+.summary[data-streaming] {
+  mask-image: linear-gradient(to right, black calc(100% - 48px), transparent);
 }
 
-.summary[data-follow-end] .summaryText {
-  flex: 0 0 auto;
-  width: max-content;
-  min-width: 100%;
+.summary[data-streaming] .summaryText {
   overflow: visible;
-  text-align: start;
   text-overflow: clip;
 }
 
+.root:not([data-preview]) .separator,
+.root:not([data-preview]) .summary {
+  display: none;
+}
+
 .thinkBody {
   /* Indent under the title, which starts at leading (16 + delta) + gap 6. */
   padding: 4px 0 4px calc(22px + var(--dsh-content-font-delta, 0px));
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
index 4d484af95b..6e24934099 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
@@ -1,35 +1,74 @@
 /** Assistant reasoning disclosure, independent of Tool-call presentation. */
-import { useMemo, useState } from 'react'
+import { memo, useCallback, useMemo, useState } from 'react'
 import { DisclosureRow, IconThinkOutlineRegular, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { ChatViewSlotProps } from '../contract/slots.ts'
+import type { ChatViewSlotProps, UsePresentation } from '../contract/slots.ts'
 import { markdownLabels } from '../markdown-labels.ts'
 import a11yCss from './accessibility.module.css'
 import css from './ReasoningRow.module.css'
 
+const THINK_ICON = <IconThinkOutlineRegular size={14} />
+
 function firstLine(text: string): string {
   const newline = text.indexOf('\n')
   return newline === -1 ? text : text.slice(0, newline)
 }
 
-function latestLine(text: string): string {
-  const visible = text.trimEnd()
-  const newline = visible.lastIndexOf('\n')
-  return newline === -1 ? visible : visible.slice(newline + 1)
+function latestCompletedParagraphFirstLine(text: string): string {
+  let summary = ''
+  let paragraphStart = 0
+  const separator = /\r?\n(?:[\t ]*\r?\n)+/g
+  while (true) {
+    const nextParagraph = separator.exec(text)
+    const paragraphEnd = nextParagraph === null ? text.length
+      : nextParagraph.index + nextParagraph[0].indexOf('\n')
+    const newline = text.indexOf('\n', paragraphStart)
+    if (newline !== -1 && newline <= paragraphEnd) {
+      const candidate = text.slice(paragraphStart, newline).trim()
+      if (candidate !== '') summary = candidate
+    }
+    if (nextParagraph === null) return summary
+    paragraphStart = nextParagraph.index + nextParagraph[0].length
+  }
 }
 
 /**
  * Render one assistant reasoning block collapsed until the reader opens it. The
  * collapsed summary omits double-asterisk markers; expanded content renders
- * the complete Markdown with secondary typography.
+ * the complete Markdown with secondary typography. A streaming preview advances
+ * when a paragraph's first line completes. Mode changes toggle CSS display without unmounting
+ * collapsed summaries.
  * @param props.text - complete or streaming reasoning text.
  * @param props.running - whether this block is the streaming tail.
+ * @param props.usePresentation - live display-policy selector for this reasoning row.
  * @param props.t - conversation locale seat for status and Markdown actions.
  * @returns the reasoning disclosure.
  */
-export function ReasoningRow({ text, running, t }: { text: string; running: boolean; t: ChatViewSlotProps['t'] }) {
+export const ReasoningRow = memo(function ReasoningRow({ text, running, usePresentation, t }: {
+  text: string
+  running: boolean
+  usePresentation: UsePresentation
+  t: ChatViewSlotProps['t']
+}) {
   const [expanded, setExpanded] = useState(false)
   const labels = useMemo(() => markdownLabels(t), [t])
-  const summary = (running ? latestLine(text) : firstLine(text)).replaceAll('**', '')
+  const toggle = useCallback(() => { setExpanded(value => !value) }, [])
+  const summaryText = running ? latestCompletedParagraphFirstLine(text) : firstLine(text)
+  const summary = useMemo(() => summaryText.replaceAll('**', ''), [summaryText])
+  const preview = usePresentation(policy => !expanded && summary !== ''
+    && (running || policy.settledReasoningPreview))
+  const collapsedContent = useMemo(() => (
+    <>
+      <span className={css.separator} aria-hidden />
+      <span className={css.summary} data-streaming={running || undefined}>
+        <span className={css.summaryText}>{summary}</span>
+      </span>
+    </>
+  ), [running, summary])
+  const content = useMemo(() => expanded ? (
+    <div className={css.thinkBody}>
+      <MarkdownText text={text} streaming={running} labels={labels} variant="compact" />
+    </div>
+  ) : undefined, [expanded, labels, running, text])
 
   return (
     <div
@@ -37,6 +76,7 @@ export function ReasoningRow({ text, running, t }: { text: string; running: bool
       data-variant="think"
       data-state={running ? 'running' : 'ok'}
       data-expanded={expanded || undefined}
+      data-preview={preview || undefined}
     >
       {running && <span className={a11yCss.visuallyHidden}>{t('row.running')}</span>}
       <DisclosureRow
@@ -44,25 +84,16 @@ export function ReasoningRow({ text, running, t }: { text: string; running: bool
         leadingClassName={css.leading}
         titleClassName={css.title}
         chevronClassName={css.chevron}
-        icon={<IconThinkOutlineRegular size={14} />}
+        icon={THINK_ICON}
         title={t('message.think')}
         open={expanded}
         expandable
         expandOnRowClick
-        onToggle={() => { setExpanded(value => !value) }}
-        collapsedContent={(
-          <>
-            <span className={css.separator} aria-hidden />
-            <span className={css.summary} data-follow-end={running || undefined}>
-              <span className={css.summaryText}>{summary}</span>
-            </span>
-          </>
-        )}
+        onToggle={toggle}
+        collapsedContent={collapsedContent}
       >
-        <div className={css.thinkBody}>
-          <MarkdownText text={text} streaming={running} labels={labels} variant="compact" />
-        </div>
+        {content}
       </DisclosureRow>
     </div>
   )
-}
+})
diff --git a/packages/client/ui-chat/src/client/chat/register-node-renderers.ts b/packages/client/ui-chat/src/client/chat/register-node-renderers.ts
index f8f78000f1..9fa302992d 100644
--- a/packages/client/ui-chat/src/client/chat/register-node-renderers.ts
+++ b/packages/client/ui-chat/src/client/chat/register-node-renderers.ts
@@ -1,6 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { PerformanceUsageMode } from '../../chat-settings.ts'
+import type { ChatPresentationPolicy } from '../presentation-policy.ts'
 import { NS } from '../locale.ts'
 import { AssistantNodeView } from './AssistantNodeView.tsx'
 import { CommandNodeView, ManualCompactionNodeView } from './CommandNodeView.tsx'
@@ -14,10 +15,17 @@ import { TurnTailNodeView } from './TurnTailNodeView.tsx'
 
 /**
  * Register this package's business renderers behind the keyed Chat Node seat.
+ * Renderers whose output depends on the work-details mode receive the policy
+ * through their own registration; the seat and the other renderers do not.
  * @param ctx - owning UI Conversation context.
  * @param performanceUsage - live statistics detail preference.
+ * @param presentation - live presentation policy.
  */
-export function registerChatNodeRenderers(ctx: Context, performanceUsage: ObservableSnapshot<PerformanceUsageMode>): void {
+export function registerChatNodeRenderers(
+  ctx: Context,
+  performanceUsage: ObservableSnapshot<PerformanceUsageMode>,
+  presentation: ObservableSnapshot<ChatPresentationPolicy>,
+): void {
   ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
     { name: 'conversation.chat.node', key: 'user', locale: NS }, UserMessageNodeView))
   ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
@@ -26,8 +34,12 @@ export function registerChatNodeRenderers(ctx: Context, performanceUsage: Observ
     { name: 'conversation.chat.node', key: 'context', locale: NS }, ContextMessageNodeView))
   ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
     { name: 'conversation.chat.node', key: 'system-prompt', locale: NS }, SystemPromptNodeView))
-  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register(
-    { name: 'conversation.chat.node', key: 'assistant-step', locale: NS }, AssistantNodeView))
+  ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
+    name: 'conversation.chat.node',
+    key: 'assistant-step',
+    locale: NS,
+    inject: () => ({ hooks: { presentation } }),
+  }, AssistantNodeView))
   ctx.slots.inject('conversation.chat.node', () => ctx.slots.register({
     name: 'conversation.chat.node',
     key: 'command',
diff --git a/packages/client/ui-chat/src/client/contract/chat-visibility.ts b/packages/client/ui-chat/src/client/contract/chat-visibility.ts
new file mode 100644
index 0000000000..7e66c15ca5
--- /dev/null
+++ b/packages/client/ui-chat/src/client/contract/chat-visibility.ts
@@ -0,0 +1,13 @@
+/** Chat-only row visibility; durable events and trajectory inspection remain intact. */
+import type { ChatNode } from './chat-nodes.ts'
+
+/**
+ * Exclude system prompts and permission commands from visible Chat rows.
+ * @param node - projected Chat node.
+ * @returns whether the node contributes a visible Chat row.
+ */
+export function isVisibleChatNode(node: ChatNode): boolean {
+  return node.visibility === 'visible'
+    && node.kind !== 'system-prompt'
+    && !(node.kind === 'command' && node.data.name === 'permission')
+}
diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts
index d5b007b7cf..4086eb4d5b 100644
--- a/packages/client/ui-chat/src/client/contract/slots.ts
+++ b/packages/client/ui-chat/src/client/contract/slots.ts
@@ -9,17 +9,18 @@ import type {
   InjectFace, KeyedSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
   SlotHookFactory, SnapshotSelectorHook,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { createChatStore } from '../stores.ts'
+import type { ChatPresentationPolicy } from '../presentation-policy.ts'
 import type { ToolCallId } from './store.ts'
 import type { ChatConversationViewNode, ChatNode, ChatNodeKind } from './chat-nodes.ts'
 import type {
   ChatNodeProcessSource, ChatNodeSource, ChatSnapshot, ChatTurnProcessPresentation,
 } from './snapshot.ts'
 import type { TurnProcessSpec } from './turn-process.ts'
-import type { PerformanceUsageMode, TranscriptViewMode } from '../../chat-settings.ts'
+import type { PerformanceUsageMode } from '../../chat-settings.ts'
 
 /** Selector hook over the current Conversation binding's Chat target. */
 export type UseChat = SnapshotSelectorHook<ChatSnapshot>
@@ -30,6 +31,13 @@ export type UseChatNode = KeyedSnapshotSelectorHook<ChatConversationViewNode | u
 /** Per-key selector hook over one Chat Node's Turn-process presentation. */
 export type UseChatNodeProcess = KeyedSnapshotSelectorHook<ChatTurnProcessPresentation | undefined>
 
+/**
+ * Selector hook over the live presentation policy. Callers select one field or
+ * a derived conclusion, never the whole policy, so a mode change re-renders
+ * only components whose selected value changed.
+ */
+export type UsePresentation = SnapshotSelectorHook<ChatPresentationPolicy>
+
 /** Where in a file an open should land. */
 export interface OpenFileOptions {
   /** 1-based line to reveal; absent = the file's beginning. */
@@ -105,6 +113,14 @@ export interface TurnProcessOwnerProps {
   setOpen(open: boolean): void
 }
 
+/** Shared presentation policy source for renderers that depend on the work-details mode. */
+export interface PresentationInjected {
+  hooks: {
+    /** Live presentation policy derived from the accepted work-details mode. */
+    presentation: ObservableSnapshot<ChatPresentationPolicy>
+  }
+}
+
 /** Full props of one keyed Chat renderer. */
 export type ChatNodeViewProps<Kind extends ChatNodeKind = ChatNodeKind> =
   PropsRuntime<'conversation.chat.node', Kind> & PropsLocale<'chat'>
@@ -139,8 +155,8 @@ export interface PerformanceUsageInjected {
 /** Business callbacks injected into the Chat view. */
 export interface ChatViewInjected {
   hooks: {
-    /** Persisted completed-Turn transcript presentation. */
-    transcriptView: SnapshotStore<TranscriptViewMode>
+    /** Live presentation policy derived from the accepted work-details mode. */
+    presentation: ObservableSnapshot<ChatPresentationPolicy>
   }
   keyedHooks: {
     /** Resolve the stable source for one Chat Node key. */
@@ -150,7 +166,7 @@ export interface ChatViewInjected {
   }
   /** Open the current source file of a skill referenced by a sent message. */
   openSkill: (name: string) => void
-  /** Open one HTTP(S) message link in a Sidebar Browser tab. */
+  /** Open one HTTP(S) message link at the selected destination, using an external tab if Sidebar Browser is unavailable. */
   openExternalLink: (url: string) => void
   openFile: (path: string, options?: OpenFileOptions) => Promise<void>
   loadOlder: () => void
diff --git a/packages/client/ui-chat/src/client/contract/snapshot.ts b/packages/client/ui-chat/src/client/contract/snapshot.ts
index 80f8654e7c..86833382c0 100644
--- a/packages/client/ui-chat/src/client/contract/snapshot.ts
+++ b/packages/client/ui-chat/src/client/contract/snapshot.ts
@@ -74,6 +74,8 @@ export interface ChatLocationNodeIndex {
 export interface ChatTurnProcessPresentation {
   readonly turn: number
   readonly spec: TurnProcessSpec
+  /** Whether the loaded window contains this Turn's `turn/start`; folding is decided per Turn on this fact. */
+  readonly turnStarted: boolean
   readonly turnClosed: boolean
   readonly hasExternalProcess: boolean
   readonly compactAnswer: boolean
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
index fb91233786..8c805e6107 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts
@@ -6,6 +6,7 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ChatConversationViewNode, ChatNode } from '../contract/chat-nodes.ts'
 import { isRunningTool } from '../contract/chat-nodes.ts'
+import { isVisibleChatNode } from '../contract/chat-visibility.ts'
 import type {
   ChatLocationNodeIndex, ChatNodeProcessSource, ChatNodeSource, ChatNodeStore, ChatSnapshot,
   ChatTurnNavigationIndex, ChatTurnProcessPresentation, LegacyConversationSlice, TurnNavigationItem,
@@ -400,7 +401,7 @@ function presentationPosition(
 export function orderedVisibleChatNodes(
   nodes: readonly ChatConversationViewNode[],
 ): ChatConversationViewNode[] {
-  const visible = nodes.filter(node => node.visibility === 'visible')
+  const visible = nodes.filter(node => isVisibleChatNode(node as ChatNode))
   const presentations = turnProcessPresentations(visible)
   return visible.sort((left, right) => {
     const leftPosition = presentationPosition(left, presentations)
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-navigation.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-navigation.ts
index 331840e80c..d0f6c40798 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/turn-navigation.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-navigation.ts
@@ -1,3 +1,4 @@
+import { isVisibleChatNode } from '../contract/chat-visibility.ts'
 import type { ChatNode } from '../contract/chat-nodes.ts'
 import type { ChatLocationNodeIndex, ChatNodeStore, TurnNavigationItem } from '../contract/snapshot.ts'
 
@@ -82,7 +83,7 @@ export function turnNavigationItem(
 ): TurnNavigationItem | undefined {
   const loaded = locations.getTurn(turn)
     .map(key => nodes.get(key))
-    .filter((node): node is ChatNode => node !== undefined && node.visibility === 'visible')
+    .filter((node): node is ChatNode => node !== undefined && isVisibleChatNode(node as ChatNode))
   const user = loaded.find(node => node.kind === 'user')
   const anchor = user ?? loaded[0]
   if (anchor === undefined) return undefined
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
index a49ae6031b..d337954772 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-process-presentation.ts
@@ -1,3 +1,4 @@
+import { isVisibleChatNode } from '../contract/chat-visibility.ts'
 import type { ChatNode } from '../contract/chat-nodes.ts'
 import type {
   ChatLocationNodeIndex, ChatNodeStore, ChatTurnProcessPresentation,
@@ -16,6 +17,7 @@ function samePresentation(
   return left === right || (left !== undefined && right !== undefined
     && left.spec === right.spec
     && left.turn === right.turn
+    && left.turnStarted === right.turnStarted
     && left.turnClosed === right.turnClosed
     && left.hasExternalProcess === right.hasExternalProcess
     && left.compactAnswer === right.compactAnswer)
@@ -48,7 +50,7 @@ function derivePresentation(
   let compactAnswer = true
   for (const key of keys) {
     const node = nodes.get(key) as ChatNode | undefined
-    if (node === undefined || node.kind === 'turn-process') continue
+    if (node === undefined || !isVisibleChatNode(node) || node.kind === 'turn-process') continue
     if ((node.kind === 'user' || node.kind === 'steering')
       && (openingHumanAnchor === undefined || node.anchorSeq > openingHumanAnchor)
       && (spec.answerAnchorSeq === null || node.anchorSeq < spec.answerAnchorSeq)) {
@@ -64,6 +66,7 @@ function derivePresentation(
   return {
     turn,
     spec,
+    turnStarted: location.turn.start !== undefined,
     turnClosed: location.turn.status === 'closed',
     hasExternalProcess,
     compactAnswer,
diff --git a/packages/client/ui-chat/src/client/index.ts b/packages/client/ui-chat/src/client/index.ts
index 9c2fe3a5d0..20e33d8885 100644
--- a/packages/client/ui-chat/src/client/index.ts
+++ b/packages/client/ui-chat/src/client/index.ts
@@ -30,11 +30,12 @@ export type {
 export type { ChatStoreState, ToolCallId, TurnProcessViewEntry } from './contract/store.ts'
 export type { TranscriptViewRowInjected, TranscriptViewRowProps } from './settings/TranscriptViewRow.tsx'
 export type { TranscriptViewMode } from '../chat-settings.ts'
+export type { ChatPresentationPolicy } from './presentation-policy.ts'
 export type {
   AssistantActionOwnerProps, ChatFileMentions, ChatNodeOwnerProps, ChatNodeTurnDataInjected,
   ChatNodeViewProps, ChatScrollPosition, ChatStore, ChatViewInjected, ChatViewSlotProps,
-  CommandRowOwnerProps, CommandRowProps, MessageImagesProps, OpenFileOptions,
-  TurnProcessOwnerProps, TurnTailOwnerProps, UseChat, UseChatNodeTurnData,
+  CommandRowOwnerProps, CommandRowProps, MessageImagesProps, OpenFileOptions, PresentationInjected,
+  TurnProcessOwnerProps, TurnTailOwnerProps, UseChat, UseChatNodeTurnData, UsePresentation,
 } from './contract/slots.ts'
 export type {
   TurnProcessSpec,
diff --git a/packages/client/ui-chat/src/client/locale.ts b/packages/client/ui-chat/src/client/locale.ts
index 344fef13d0..a0440b4682 100644
--- a/packages/client/ui-chat/src/client/locale.ts
+++ b/packages/client/ui-chat/src/client/locale.ts
@@ -31,10 +31,15 @@ export const zh = {
   'settings.performance.description': '选择性能与用量信息展示的详细程度',
   'settings.performance.compact': '简洁',
   'settings.performance.detailed': '详细',
-  'settings.transcript.title': '对话显示',
-  'settings.transcript.description': '控制已完成轮次的过程内容',
-  'settings.transcript.normal': '标准',
-  'settings.transcript.compact': '紧凑',
+  'settings.links.title': '聊天链接打开方式',
+  'settings.links.description': '选择聊天中 HTTP(S) 链接的打开位置',
+  'settings.links.sidebar': '内置浏览器',
+  'settings.links.newTab': '浏览器新标签页',
+  'settings.transcript.title': '工作过程展示',
+  'settings.transcript.description': '控制轮次和步骤的默认展开方式',
+  'settings.transcript.compact': '简洁',
+  'settings.transcript.detailed': '详细',
+  'settings.transcript.expanded': '完全展开',
   'fileOpen.title': '无法打开文件',
   'fileOpen.unknown': '无法打开此文件',
   'message.extraBlock': '附加内容块',
@@ -141,10 +146,15 @@ export const en = {
   'settings.performance.description': 'Choose how much performance and usage information to show',
   'settings.performance.compact': 'Compact',
   'settings.performance.detailed': 'Detailed',
-  'settings.transcript.title': 'Conversation display',
-  'settings.transcript.description': 'Controls process content in completed turns',
-  'settings.transcript.normal': 'Normal',
+  'settings.links.title': 'Open chat links in',
+  'settings.links.description': 'Choose where HTTP(S) links in chat open',
+  'settings.links.sidebar': 'Built-in browser',
+  'settings.links.newTab': 'New browser tab',
+  'settings.transcript.title': 'Work details',
+  'settings.transcript.description': 'Controls how turns and steps expand by default',
   'settings.transcript.compact': 'Compact',
+  'settings.transcript.detailed': 'Detailed',
+  'settings.transcript.expanded': 'Expanded',
   'fileOpen.title': 'Couldn’t open file',
   'fileOpen.unknown': 'Couldn’t open this file',
   'message.extraBlock': 'Extra content block',
diff --git a/packages/client/ui-chat/src/client/presentation-policy.ts b/packages/client/ui-chat/src/client/presentation-policy.ts
new file mode 100644
index 0000000000..c1af53db51
--- /dev/null
+++ b/packages/client/ui-chat/src/client/presentation-policy.ts
@@ -0,0 +1,66 @@
+/**
+ * Runtime vocabulary derived from the persisted work-details mode. Renderers
+ * and seats select single fields of this policy; none of them compares the
+ * mode enum, so adding a mode changes only the table below.
+ */
+
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { TranscriptViewMode } from '../chat-settings.ts'
+
+/** Presentation capabilities that one work-details mode enables. */
+export interface ChatPresentationPolicy {
+  /** Mode this policy was derived from; for diagnostics, never for branching in renderers. */
+  readonly mode: TranscriptViewMode
+  /** Whether a normally completed Turn folds its process rows behind the whole-Turn control. */
+  readonly foldCompletedTurns: boolean
+  /** Reserved secondary-grouping preference; no renderer consumes this field yet. */
+  readonly stepGrouping: 'collapsed' | 'none'
+  /** Whether a settled reasoning row previews its first line beside the Think title. */
+  readonly settledReasoningPreview: boolean
+}
+
+const POLICIES: Readonly<Record<TranscriptViewMode, ChatPresentationPolicy>> = {
+  compact: {
+    mode: 'compact',
+    foldCompletedTurns: true,
+    stepGrouping: 'collapsed',
+    settledReasoningPreview: false,
+  },
+  detailed: {
+    mode: 'detailed',
+    foldCompletedTurns: true,
+    stepGrouping: 'collapsed',
+    settledReasoningPreview: true,
+  },
+  expanded: {
+    mode: 'expanded',
+    foldCompletedTurns: true,
+    stepGrouping: 'none',
+    settledReasoningPreview: true,
+  },
+}
+
+/**
+ * Resolve the policy constant for one mode. The same mode always yields the
+ * same object, so selectors over a policy see stable identities.
+ * @param mode - persisted work-details mode.
+ * @returns the mode's presentation policy.
+ */
+export function presentationPolicyFor(mode: TranscriptViewMode): ChatPresentationPolicy {
+  return POLICIES[mode]
+}
+
+/**
+ * Derive a policy observable from the mode observable without a subscription of
+ * its own: reads are a table lookup and change notifications are the mode's.
+ * @param mode - live work-details mode.
+ * @returns observable policy that changes exactly when the mode changes.
+ */
+export function derivePresentationPolicy(
+  mode: ObservableSnapshot<TranscriptViewMode>,
+): ObservableSnapshot<ChatPresentationPolicy> {
+  return {
+    getSnapshot: () => POLICIES[mode.getSnapshot()],
+    subscribe: listener => mode.subscribe(listener),
+  }
+}
diff --git a/packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx b/packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx
new file mode 100644
index 0000000000..b17a3e4929
--- /dev/null
+++ b/packages/client/ui-chat/src/client/settings/LinkOpeningRow.tsx
@@ -0,0 +1,47 @@
+/** General Settings row for Chat HTTP(S) link destinations. */
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { LinkOpening } from '../../chat-settings.ts'
+import { PreferenceRow } from './PreferenceRow.tsx'
+
+/** Registration-side link-opening preference. */
+export interface LinkOpeningRowInjected {
+  hooks: {
+    /** Current destination, bound as useLinkOpening. */
+    linkOpening: ObservableSnapshot<LinkOpening>
+    /** Whether the built-in browser is registered, bound as useBrowserAvailable. */
+    browserAvailable: ObservableSnapshot<boolean>
+  }
+  /** Change the default destination for Chat HTTP(S) links. */
+  setLinkOpening: (destination: LinkOpening) => void
+}
+
+/** Full Settings-row props. */
+export type LinkOpeningRowProps =
+  PropsRuntime<'settings.general.item'>
+  & PropsLocale<'chat'>
+  & InjectFace<LinkOpeningRowInjected>
+
+/**
+ * Render the link-opening destination selector.
+ * @param props - Composed Settings slot props.
+ * @returns The preference row.
+ */
+export function LinkOpeningRow({ useLinkOpening, useBrowserAvailable, setLinkOpening, t }: LinkOpeningRowProps) {
+  const destination = useLinkOpening(value => value)
+  const browserAvailable = useBrowserAvailable(value => value)
+  if (!browserAvailable) return null
+  return (
+    <PreferenceRow
+      title={t('settings.links.title')}
+      description={t('settings.links.description')}
+      value={destination}
+      selectedLabel={t(destination === 'sidebar' ? 'settings.links.sidebar' : 'settings.links.newTab')}
+      options={[
+        { id: 'sidebar', label: t('settings.links.sidebar') },
+        { id: 'new-tab', label: t('settings.links.newTab') },
+      ]}
+      onSelect={(value) => { setLinkOpening(value as LinkOpening) }}
+    />
+  )
+}
diff --git a/packages/client/ui-chat/src/client/settings/TranscriptViewRow.tsx b/packages/client/ui-chat/src/client/settings/TranscriptViewRow.tsx
index 7dc7df7363..2b29abacd9 100644
--- a/packages/client/ui-chat/src/client/settings/TranscriptViewRow.tsx
+++ b/packages/client/ui-chat/src/client/settings/TranscriptViewRow.tsx
@@ -1,18 +1,18 @@
-/** General Settings row for completed-Turn transcript presentation. */
+/** General Settings row for work-details presentation. */
 
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type { TranscriptViewMode } from '../../chat-settings.ts'
+import { TRANSCRIPT_VIEW_MODES, type TranscriptViewMode } from '../../chat-settings.ts'
 import type { ChatKey } from '../locale.ts'
 import { PreferenceRow } from './PreferenceRow.tsx'
 
-/** Registration-side transcript preference face. */
+/** Registration-side work-details preference face. */
 export interface TranscriptViewRowInjected {
   hooks: {
-    /** Persisted transcript preference bound as useTranscriptView. */
+    /** Persisted work-details preference bound as useTranscriptView. */
     transcriptView: SnapshotStore<TranscriptViewMode>
   }
-  /** Change the completed-Turn transcript presentation. */
+  /** Change the work-details presentation. */
   setTranscriptView: (mode: TranscriptViewMode) => void
 }
 
@@ -22,28 +22,26 @@ export type TranscriptViewRowProps =
   & PropsLocale<'chat'>
   & InjectFace<TranscriptViewRowInjected>
 
-const OPTIONS: readonly { id: TranscriptViewMode; label: ChatKey }[] = [
-  { id: 'normal', label: 'settings.transcript.normal' },
-  { id: 'compact', label: 'settings.transcript.compact' },
-]
+const LABELS = {
+  compact: 'settings.transcript.compact',
+  detailed: 'settings.transcript.detailed',
+  expanded: 'settings.transcript.expanded',
+} as const satisfies Record<TranscriptViewMode, ChatKey>
 
 /**
- * Render the completed-Turn transcript mode selector.
+ * Render the work-details mode selector.
  * @param props - composed Settings slot props.
  * @returns the preference row.
  */
 export function TranscriptViewRow({ useTranscriptView, setTranscriptView, t }: TranscriptViewRowProps) {
   const mode = useTranscriptView(value => value)
-  const selectedLabel = mode === 'normal'
-    ? 'settings.transcript.normal'
-    : 'settings.transcript.compact'
   return (
     <PreferenceRow
       title={t('settings.transcript.title')}
       description={t('settings.transcript.description')}
       value={mode}
-      selectedLabel={t(selectedLabel)}
-      options={OPTIONS.map(option => ({ id: option.id, label: t(option.label) }))}
+      selectedLabel={t(LABELS[mode])}
+      options={TRANSCRIPT_VIEW_MODES.map(id => ({ id, label: t(LABELS[id]) }))}
       onSelect={(value) => { setTranscriptView(value as TranscriptViewMode) }}
     />
   )
diff --git a/packages/client/ui-chat/src/client/transcript-view.ts b/packages/client/ui-chat/src/client/transcript-view.ts
index 5534a0139c..a97e17bda8 100644
--- a/packages/client/ui-chat/src/client/transcript-view.ts
+++ b/packages/client/ui-chat/src/client/transcript-view.ts
@@ -1,13 +1,13 @@
-/** Host-backed completed-Turn transcript presentation policy. */
+/** Host-backed work-details presentation policy. */
 
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
 import {
-  DEFAULT_TRANSCRIPT_VIEW_MODE, TRANSCRIPT_VIEW_FIELD,
+  DEFAULT_TRANSCRIPT_VIEW_MODE, LEGACY_TRANSCRIPT_VIEW_MODE, TRANSCRIPT_VIEW_FIELD,
   type ChatSettings, type TranscriptViewMode,
 } from '../chat-settings.ts'
 
-/** Live transcript preference consumed by Chat and its Settings row. */
+/** Live work-details preference consumed by Chat and its Settings row. */
 export class TranscriptViewPolicy {
   /** Reactive current mode; defaults to Compact before Host settings arrive. */
   readonly mode: SnapshotStore<TranscriptViewMode> = createSnapshotStore(DEFAULT_TRANSCRIPT_VIEW_MODE)
@@ -22,7 +22,7 @@ export class TranscriptViewPolicy {
 
   /**
    * Publish and persist one explicit user choice.
-   * @param mode - Normal or Compact transcript presentation.
+   * @param mode - Compact, Detailed, or Expanded work details.
    */
   setMode(mode: TranscriptViewMode): void {
     if (this.mode.getSnapshot() === mode) return
@@ -33,7 +33,8 @@ export class TranscriptViewPolicy {
   /** Adopt the latest accepted Host section without writing it back. */
   private adopt(): void {
     const section = this.host.getSnapshot().value
-    if (section === undefined || this.mode.getSnapshot() === section.transcriptView) return
-    this.mode.set(section.transcriptView)
+    if (section === undefined) return
+    const mode = section.transcriptView === LEGACY_TRANSCRIPT_VIEW_MODE ? 'detailed' : section.transcriptView
+    if (this.mode.getSnapshot() !== mode) this.mode.set(mode)
   }
 }
diff --git a/packages/client/ui-chat/src/index.ts b/packages/client/ui-chat/src/index.ts
index 6229537c23..cd0c89e5c5 100644
--- a/packages/client/ui-chat/src/index.ts
+++ b/packages/client/ui-chat/src/index.ts
@@ -5,7 +5,7 @@ import type {} from '@deepseek-ai/dsh-settings'
 import { CHAT_SETTINGS_NAMESPACE, ChatSettingsSchema } from './chat-settings.ts'
 
 export {
-  CHAT_SETTINGS_NAMESPACE, DEFAULT_TRANSCRIPT_VIEW_MODE, TRANSCRIPT_VIEW_FIELD,
+  CHAT_SETTINGS_NAMESPACE, DEFAULT_TRANSCRIPT_VIEW_MODE, LEGACY_TRANSCRIPT_VIEW_MODE, TRANSCRIPT_VIEW_FIELD,
   TRANSCRIPT_VIEW_MODES, type ChatSettings, type TranscriptViewMode,
 } from './chat-settings.ts'
 
diff --git a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
index 7977740640..dff3bbe376 100644
--- a/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-chat/tests/apply-inject.client.spec.tsx
@@ -19,6 +19,8 @@ import {
 import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 import { createChatStore } from '../src/client/stores.ts'
+import { CHAT_SETTINGS_NAMESPACE, type ChatSettings } from '../src/chat-settings.ts'
+import type { LinkOpeningRowInjected } from '../src/client/settings/LinkOpeningRow.tsx'
 
 usePinnedBrowserLanguages('zh-CN')
 
@@ -47,9 +49,16 @@ function sessionFakeFor() {
   } satisfies SessionBehaviorOverrides
 }
 
-async function bench() {
+async function bench(initialSettings?: ChatSettings, withBrowserRegistry = true) {
   const runtime = await SlotTestRuntime.create()
-  runtime.ctx.provide('settingsScope', { developerTools: { enabled: createSnapshotStore(true) }, bind: () => stubSettingsScope().scope } as never)
+  const chatSettings = stubSettingsScope<ChatSettings>()
+  if (initialSettings !== undefined) chatSettings.publish({ value: initialSettings })
+  runtime.ctx.provide('settingsScope', {
+    developerTools: { enabled: createSnapshotStore(true) },
+    bind: ({ namespace }: { namespace: string }) => namespace === CHAT_SETTINGS_NAMESPACE
+      ? chatSettings.scope
+      : stubSettingsScope().scope,
+  } as never)
   const layout = { closeRightbar: vi.fn(), openRightbar: vi.fn() }
   runtime.ctx.provide('layout', layout as never)
   const sidebarRight = {
@@ -57,11 +66,13 @@ async function bench() {
     openTab: vi.fn<(kind: string, options?: unknown) => void>(),
   }
   runtime.ctx.provide('sidebarRight', sidebarRight as never)
+  const browserAvailable = createSnapshotStore(true)
   const sidebarRightTabs = {
-    get: vi.fn<(kind: string) => object | undefined>(() => ({})),
+    get: vi.fn<(kind: string) => object | undefined>(() => browserAvailable.getSnapshot() ? {} : undefined),
+    subscribe: (listener: () => void) => browserAvailable.subscribe(listener),
     register: vi.fn(() => () => {}),
   }
-  runtime.ctx.provide('sidebarRightTabs', sidebarRightTabs as never)
+  if (withBrowserRegistry) runtime.ctx.provide('sidebarRightTabs', sidebarRightTabs as never)
   runtime.ctx.provide('resources', { register: vi.fn(() => () => {}) } as never)
   const openWorkspacePath = vi.fn<ClientRemote['session']['openWorkspacePath']>(
     () => Promise.resolve({ ok: true, value: { opened: true } }),
@@ -88,9 +99,10 @@ async function bench() {
   runtime.slots.installLocale(locale)
   await runtime.root.declare({
     'main': { kind: 'keyed', scope: 'root' },
+    'settings.general.item': { kind: 'list', scope: 'root' },
   }, (_props: { renderSlot?: unknown }) => null)
   await runtime.mount({ inject: [...injectConversation], apply: applyConversation })
-  await runtime.mount({ inject: [...injectChat], apply: applyChat })
+  const chat = await runtime.mount({ inject: [...injectChat], apply: applyChat })
   runtime.renderRoot()
 
   const chatViewApi = (reference: SessionReference) => {
@@ -104,7 +116,13 @@ async function bench() {
     return { instance, injected }
   }
   return {
-    runtime, layout, openWorkspacePath, sidebarRight, sidebarRightTabs, session, chatViewApi, rootReference, openSession,
+    get linkPreference() {
+      const row = runtime.slots.entries('settings.general.item').find(entry => entry.options.id === 'link-opening')!
+      const preference: object = row.inject!()
+      return preference as LinkOpeningRowInjected
+    },
+    runtime, chat, chatSettings, browserAvailable,
+    layout, openWorkspacePath, sidebarRight, sidebarRightTabs, session, chatViewApi, rootReference, openSession,
   }
 }
 
@@ -184,6 +202,106 @@ describe('Chat inject API', () => {
     }
   })
 
+  it('applies restored and live link destinations without remounting the Chat view', async () => {
+    const settings: ChatSettings = { transcriptView: 'compact', performanceUsage: 'detailed', linkOpening: 'new-tab' }
+    const b = await bench(settings)
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    try {
+      const { injected } = b.chatViewApi(b.rootReference)
+      const source = b.linkPreference.hooks.linkOpening
+      expect(source.getSnapshot()).toBe('new-tab')
+      injected.openExternalLink('https://example.test/restored')
+      expect(open).toHaveBeenLastCalledWith('https://example.test/restored', '_blank', 'noopener,noreferrer')
+      expect(b.sidebarRight.openTab).not.toHaveBeenCalled()
+
+      b.chatSettings.publish({ value: { ...settings, linkOpening: 'sidebar' } })
+      expect(source.getSnapshot()).toBe('sidebar')
+      injected.openExternalLink('http://example.test/live')
+      expect(b.sidebarRight.openTab).toHaveBeenLastCalledWith('browser', { params: { url: 'http://example.test/live' } })
+
+      b.linkPreference.setLinkOpening('new-tab')
+      expect(b.chatSettings.set).toHaveBeenCalledWith('linkOpening', 'new-tab')
+      injected.openExternalLink('http://example.test/selected')
+      expect(open).toHaveBeenLastCalledWith('http://example.test/selected', '_blank', 'noopener,noreferrer')
+
+      await b.chat.dispose()
+      expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(false)
+      b.chatSettings.publish({ value: { ...settings, linkOpening: 'sidebar' } })
+      expect(source.getSnapshot()).toBe('new-tab')
+    } finally {
+      open.mockRestore()
+      await b.runtime.dispose()
+    }
+  })
+
+  it('follows browser registration and routes absent browsers externally', async () => {
+    const b = await bench()
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    const available = b.linkPreference.hooks.browserAvailable
+    const changed = vi.fn()
+    const unsubscribe = available.subscribe(changed)
+    try {
+      const { injected } = b.chatViewApi(b.rootReference)
+      expect(available.getSnapshot()).toBe(true)
+      b.browserAvailable.set(false)
+      expect(available.getSnapshot()).toBe(false)
+      expect(changed).toHaveBeenCalledOnce()
+      injected.openExternalLink('https://example.test/disabled')
+      expect(open).toHaveBeenCalledWith('https://example.test/disabled', '_blank', 'noopener,noreferrer')
+      b.browserAvailable.set(true)
+      injected.openExternalLink('https://example.test/enabled')
+      expect(b.sidebarRight.openTab).toHaveBeenCalledWith('browser', { params: { url: 'https://example.test/enabled' } })
+      expect(b.linkPreference.hooks.linkOpening.getSnapshot()).toBe('sidebar')
+    } finally {
+      unsubscribe()
+      open.mockRestore()
+      await b.runtime.dispose()
+    }
+  })
+
+  it('keeps Chat available while the optional tab registry appears and leaves', async () => {
+    const b = await bench(undefined, false)
+    try {
+      expect(b.runtime.slots.entries('conversation.view')).toHaveLength(1)
+      expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(false)
+      const registry = await b.runtime.mount({
+        apply(ctx) { ctx.provide('sidebarRightTabs', b.sidebarRightTabs as never) },
+      })
+      await vi.waitFor(() => {
+        expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(true)
+      })
+      await registry.dispose()
+      expect(b.runtime.slots.entries('settings.general.item').some(row => row.options.id === 'link-opening')).toBe(false)
+      expect(b.runtime.slots.entries('conversation.view')).toHaveLength(1)
+    } finally {
+      await b.runtime.dispose()
+    }
+  })
+
+  it('keeps local link choices usable when settings cannot persist', async () => {
+    const b = await bench()
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    try {
+      const { injected } = b.chatViewApi(b.rootReference)
+      b.chatSettings.publish({ mode: 'memory', status: 'unavailable' })
+      b.chatSettings.set.mockResolvedValueOnce(false)
+      b.linkPreference.setLinkOpening('new-tab')
+      b.chatSettings.publish({ value: undefined })
+      injected.openExternalLink('https://example.test/local')
+      expect(open).toHaveBeenCalledWith('https://example.test/local', '_blank', 'noopener,noreferrer')
+      expect(b.sidebarRight.openTab).not.toHaveBeenCalled()
+
+      b.chatSettings.set.mockRejectedValueOnce(new Error('settings unavailable'))
+      b.linkPreference.setLinkOpening('sidebar')
+      await Promise.resolve()
+      injected.openExternalLink('https://example.test/local-sidebar')
+      expect(b.sidebarRight.openTab).toHaveBeenCalledWith('browser', { params: { url: 'https://example.test/local-sidebar' } })
+    } finally {
+      open.mockRestore()
+      await b.runtime.dispose()
+    }
+  })
+
   it('routes sent skill previews through the viewed Session source and tolerates an absent provider', async () => {
     const b = await bench()
     const { injected } = b.chatViewApi(b.rootReference)
diff --git a/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx b/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
index 55a02209ed..77bc597140 100644
--- a/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
+++ b/packages/client/ui-chat/tests/assistant-markdown-path-images.client.spec.tsx
@@ -2,6 +2,7 @@
 import { cleanup, render } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { AssistantMarkdown, localPathMediaUrl } from '../src/client/chat/AssistantMarkdown.tsx'
+import { useDetailedPresentation } from './presentation-fixture.client.ts'
 import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../src/client/contract/slots.ts'
 import type { AssistantBlock } from '../src/client/contract/snapshot.ts'
 
@@ -54,6 +55,7 @@ describe('AssistantMarkdown local-path images', () => {
   it('renders a local image path in closing prose through the same-origin API', () => {
     const { container } = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         blocks={[textBlock('See ![diagram](/tmp/graph.png) for the layout.')]}
         streaming={false}
         renderMessageImages={renderMessageImages}
@@ -70,6 +72,7 @@ describe('AssistantMarkdown local-path images', () => {
   it('keeps non-absolute destinations inert', () => {
     const { container } = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         blocks={[textBlock('See ![diagram](relative.png).')]}
         streaming={false}
         renderMessageImages={renderMessageImages}
diff --git a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
index 028752d24c..54d79ecb0d 100644
--- a/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-apply.client.spec.tsx
@@ -47,7 +47,11 @@ async function bench() {
   } as never)
   runtime.ctx.provide('layout', { openRightbar: vi.fn(), closeRightbar: vi.fn() } as never)
   runtime.ctx.provide('sidebarRight', { openResource: vi.fn(), openTab: vi.fn() } as never)
-  runtime.ctx.provide('sidebarRightTabs', { register: vi.fn(() => () => {}) } as never)
+  runtime.ctx.provide('sidebarRightTabs', {
+    register: vi.fn(() => () => {}),
+    get: vi.fn(() => ({})),
+    subscribe: vi.fn(() => () => {}),
+  } as never)
   runtime.ctx.provide('resources', { register: vi.fn(() => () => {}) } as never)
   const openSession = vi.fn<(id: SessionId) => void>()
   runtime.ctx.provide('uiWorkspace', {
@@ -84,6 +88,12 @@ function storeOf(runtime: SlotTestRuntime, key: 'conversation.session' | 'conver
 }
 
 describe('Chat apply wiring', () => {
+  it('keeps presentation-policy helpers out of the public browser entry', async () => {
+    const entry = await import('../src/client/index.ts')
+    expect(entry).not.toHaveProperty('derivePresentationPolicy')
+    expect(entry).not.toHaveProperty('presentationPolicyFor')
+  })
+
   it('contributes Chat View, node renderers, and stats', async () => {
     const b = await bench()
     const views = b.runtime.slots.entries('conversation.view')
@@ -94,7 +104,7 @@ describe('Chat apply wiring', () => {
     expect(b.runtime.slots.entries('conversation.composer.dock').map(row => row.options.id))
       .toEqual(['stats'])
     expect(b.runtime.slots.entries('settings.general.item').map(row => row.options.id))
-      .toEqual(['transcript-view', 'performance-usage', 'composer-enter'])
+      .toEqual(['transcript-view', 'performance-usage', 'link-opening', 'composer-enter'])
     await b.runtime.dispose()
   })
 
@@ -105,12 +115,12 @@ describe('Chat apply wiring', () => {
     const face = (row.inject as unknown as () => TranscriptViewRowInjected)()
 
     expect(face.hooks.transcriptView.getSnapshot()).toBe('compact')
-    face.setTranscriptView('normal')
-    expect(face.hooks.transcriptView.getSnapshot()).toBe('normal')
-    expect(b.chatSettings.set).toHaveBeenCalledWith('transcriptView', 'normal')
+    face.setTranscriptView('detailed')
+    expect(face.hooks.transcriptView.getSnapshot()).toBe('detailed')
+    expect(b.chatSettings.set).toHaveBeenCalledWith('transcriptView', 'detailed')
 
     b.chatSettings.publish({
-      status: 'ready', value: { transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 1, writable: true,
+      status: 'ready', value: { linkOpening: 'sidebar', transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 1, writable: true,
     })
     expect(face.hooks.transcriptView.getSnapshot()).toBe('compact')
     await b.runtime.dispose()
@@ -123,7 +133,7 @@ describe('Chat apply wiring', () => {
     expect(face.hooks.performanceUsage.getSnapshot()).toBe('detailed')
     face.setPerformanceUsage('compact')
     expect(b.chatSettings.set).toHaveBeenCalledWith('performanceUsage', 'compact')
-    b.chatSettings.publish({ value: { transcriptView: 'compact', performanceUsage: 'compact' } })
+    b.chatSettings.publish({ value: { linkOpening: 'sidebar', transcriptView: 'compact', performanceUsage: 'compact' } })
     expect(face.hooks.performanceUsage.getSnapshot()).toBe('compact')
     for (const entry of [
       b.runtime.slots.entries('conversation.composer.dock').find(entry => entry.options.id === 'stats')!,
diff --git a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
index 013ed04786..f389653c72 100644
--- a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
@@ -16,6 +16,7 @@ import {
   UserMessageNodeView,
 } from '../src/client/chat/MessageItem.tsx'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
+import { useDetailedPresentation } from './presentation-fixture.client.ts'
 import { StatsPills } from '../src/client/chat/StatsPills.tsx'
 import { zh } from '../src/client/locale.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
@@ -1044,6 +1045,7 @@ describe('small branch tails', () => {
   it('AssistantMarkdown single-line reasoning summary skips the newline cut', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text: 'one-liner' }]}
         streaming={false}
diff --git a/packages/client/ui-chat/tests/chat-settings.client.spec.ts b/packages/client/ui-chat/tests/chat-settings.client.spec.ts
index ad5ae6ab89..d2c146c40d 100644
--- a/packages/client/ui-chat/tests/chat-settings.client.spec.ts
+++ b/packages/client/ui-chat/tests/chat-settings.client.spec.ts
@@ -21,14 +21,20 @@ describe('ui-chat Host settings', () => {
     await fiber.await()
     const ns = CHAT_SETTINGS_NAMESPACE
 
-    expect(ctx.settings.get(ns)).toEqual({ transcriptView: DEFAULT_TRANSCRIPT_VIEW_MODE, performanceUsage: 'detailed' })
+    expect(ctx.settings.get(ns)).toEqual({ transcriptView: DEFAULT_TRANSCRIPT_VIEW_MODE, performanceUsage: 'detailed', linkOpening: 'sidebar' })
     await ctx.settings.update(ns, { transcriptView: 'normal' })
-    expect(ctx.settings.get(ns)).toEqual({ transcriptView: 'normal', performanceUsage: 'detailed' })
+    expect(ctx.settings.get(ns)).toEqual({ transcriptView: 'normal', performanceUsage: 'detailed', linkOpening: 'sidebar' })
     await expect(ctx.settings.update(ns, { transcriptView: 'dense' })).rejects.toThrow()
     await ctx.settings.update(ns, { performanceUsage: 'compact' })
     expect(ctx.settings.get(ns)).toMatchObject({ performanceUsage: 'compact' })
     await expect(ctx.settings.update(ns, { performanceUsage: 'hidden' })).rejects.toThrow()
 
+    await ctx.settings.update(ns, { linkOpening: 'new-tab' })
+    expect(ctx.settings.get(ns)).toMatchObject({ linkOpening: 'new-tab' })
+    await ctx.settings.update(ns, { linkOpening: 'sidebar' })
+    expect(ctx.settings.get(ns)).toMatchObject({ linkOpening: 'sidebar' })
+    await expect(ctx.settings.update(ns, { linkOpening: 'popup' })).rejects.toThrow()
+
     await fiber.dispose()
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
   })
diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
index 65f5f04e1d..db60f029a9 100644
--- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx
@@ -28,6 +28,7 @@ import { EMPTY_CONVERSATION_SNAPSHOT } from '@deepseek-ai/dsh-client-ui-conversa
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { createChatStore } from '../src/client/stores.ts'
+import { derivePresentationPolicy } from '../src/client/presentation-policy.ts'
 import { ChatView } from '../src/client/chat/ChatView.tsx'
 import { ChatNodeSeat } from '../src/client/chat/ChatNodeSeat.tsx'
 import { useTurnDataValue } from '../src/client/chat/use-turn-data.ts'
@@ -206,7 +207,7 @@ const compaction = (over: Partial<CompactionSummaryNode> = {}): CompactionSummar
 /** Empty sessions-list hook for the global standard-kit seat. */
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
-    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {} })
+    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {} })
   return bindSnapshotSelector(store)
 }
 
@@ -309,7 +310,7 @@ function makeHarness(
       case 'context':
         return <ContextMessageNodeView {...nodeProps<'context'>()} />
       case 'assistant-step':
-        return <AssistantNodeView {...nodeProps<'assistant-step'>()} />
+        return <AssistantNodeView {...nodeProps<'assistant-step'>()} usePresentation={props.usePresentation} />
       case 'command':
         return (
           <CommandNodeView
@@ -394,6 +395,8 @@ function makeHarness(
     },
     useInput: (() => { throw new Error('unused') }),
     inputActions: {
+      captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+      insertText: () => false,
       setDraft: () => {},
       addAttachments: () => true,
       removeAttachment: () => {},
@@ -402,7 +405,7 @@ function makeHarness(
     },
     useStore: bindSnapshotSelector(chat),
     actions: chat.actions,
-    useTranscriptView: bindSnapshotSelector(transcriptView),
+    usePresentation: bindSnapshotSelector(derivePresentationPolicy(transcriptView)),
     renderSlot,
     SessionProvider: SessionProviderStub,
     inspectCall: (callId: string) => { openView('trajectory', callId) },
@@ -1471,6 +1474,7 @@ describe('ChatView', () => {
         assistant(5, 'final answer', 1, 2),
       ],
       turnEnds: new Map([[1, 6]]),
+      turnTimings: new Map([[1, { startTime: 0, endTime: 6_000 }]]),
     })
     const view = render(<h.ChatView {...h.props} />)
     const contextRow = view.container.querySelector<HTMLElement>('[data-chat-flow-kind="context"]')
@@ -1484,18 +1488,16 @@ describe('ChatView', () => {
     expect(members.map(member => member.getAttribute('hidden'))).toEqual([null, null, null])
   })
 
-  it('keeps the first System prompt above User and outside Process through completion and expansion', () => {
+  it('omits the System prompt through Turn completion and process expansion', () => {
     const builder = new ChatSnapshotBuilder()
     const initial = withSystemPrompt(chatSnapshotFixture({
       nodes: [userInTurn(2, 'question', 1), context(3, 'runtime policy', 1)],
+      turnTimings: new Map([[1, { startTime: 0 }]]),
     }), builder)
     const h = makeHarness({ chat: initial }, { running: true })
     const view = render(<h.ChatView {...h.props} />)
-    const promptRow = view.container.querySelector<HTMLElement>('[data-chat-flow-kind="system-prompt"]')!
-
-    expect(renderedFlowKinds(view.container)).toEqual(['system-prompt', 'user', 'context'])
-    expect(promptRow.getAttribute('hidden')).toBeNull()
-    expect(promptRow.hasAttribute('data-turn-process-member')).toBe(false)
+    expect(renderedFlowKinds(view.container)).toEqual(['user', 'context'])
+    expect(view.container.querySelector('[data-chat-flow-kind="system-prompt"]')).toBeNull()
 
     act(() => {
       h.set({
@@ -1505,15 +1507,15 @@ describe('ChatView', () => {
             context(3, 'runtime policy', 1),
             reasoningAssistant(4, 'inspect', 1, 1),
           ],
+          turnTimings: new Map([[1, { startTime: 0 }]]),
         }), builder),
         running: true,
       })
     })
     expect(renderedFlowKinds(view.container)).toEqual([
-      'system-prompt', 'user', 'turn-process', 'context', 'assistant-step',
+      'user', 'turn-process', 'context', 'assistant-step',
     ])
-    expect(view.container.querySelector('[data-chat-flow-kind="system-prompt"]')).toBe(promptRow)
-    expect(promptRow.getAttribute('hidden')).toBeNull()
+    expect(view.container.querySelector('[data-chat-flow-kind="system-prompt"]')).toBeNull()
 
     act(() => {
       h.set({
@@ -1525,6 +1527,7 @@ describe('ChatView', () => {
             assistant(6, 'final answer', 1, 2),
           ],
           turnEnds: new Map([[1, 7]]),
+          turnTimings: new Map([[1, { startTime: 0, endTime: 7_000 }]]),
         }), builder),
         running: false,
       })
@@ -1532,19 +1535,18 @@ describe('ChatView', () => {
     const toggle = turnProcessControl(view.container)!
     const members = [...view.container.querySelectorAll<HTMLElement>('[data-turn-process-member]')]
     expect(renderedFlowKinds(view.container)).toEqual([
-      'system-prompt', 'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
+      'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
     ])
     expect(toggle.getAttribute('aria-expanded')).toBe('false')
-    expect(promptRow.getAttribute('hidden')).toBeNull()
-    expect(promptRow.hasAttribute('data-turn-process-member')).toBe(false)
+    expect(view.container.querySelector('[data-chat-flow-kind="system-prompt"]')).toBeNull()
     expect(members.map(member => member.dataset.chatFlowKind)).toEqual(['context', 'assistant-step'])
     expect(members.map(member => member.getAttribute('hidden'))).toEqual(['until-found', 'until-found'])
 
     fireEvent.click(toggle)
     expect(renderedFlowKinds(view.container)).toEqual([
-      'system-prompt', 'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
+      'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
     ])
-    expect(promptRow.getAttribute('hidden')).toBeNull()
+    expect(view.container.querySelector('[data-chat-flow-kind="system-prompt"]')).toBeNull()
     expect(members.map(member => member.getAttribute('hidden'))).toEqual([null, null])
   })
 
@@ -1552,6 +1554,7 @@ describe('ChatView', () => {
     const h = makeHarness({
       nodes: [user(1, 'question'), context(2, 'runtime policy', 1), assistant(3, 'final answer', 1, 1)],
       turnEnds: new Map([[1, 4]]),
+      turnTimings: new Map([[1, { startTime: 0, endTime: 4_000 }]]),
     })
     const view = render(<h.ChatView {...h.props} />)
     const toggle = view.getByRole('button', { name: '已思考' })
@@ -1606,6 +1609,7 @@ describe('ChatView', () => {
       nodes: [user(1, 'question'), process],
       partial: { turn: 1, step: 2, blocks: [{ kind: 'text', text: 'streaming answer' }] },
       running: true,
+      turnTimings: new Map([[1, { startTime: 0 }]]),
     })
     const view = render(<h.ChatView {...h.props} />)
     expect(turnProcessControl(view.container)).toBeNull()
@@ -1624,11 +1628,12 @@ describe('ChatView', () => {
     expect(processRow.getAttribute('hidden')).toBe('until-found')
   })
 
-  it('switches completed Turns between the persisted Normal and Compact modes', () => {
+  it('preserves whole-Turn folding and manual expansion across work-details modes', () => {
     const process = assistant(2, 'inspect', 1, 1)
     const h = makeHarness({
       nodes: [user(1, 'question'), process, assistant(4, 'final answer', 1, 2)],
       turnEnds: new Map([[1, 5]]),
+      turnTimings: new Map([[1, { startTime: 0, endTime: 5_000 }]]),
     })
     const view = render(<h.ChatView {...h.props} />)
     const processRow = view.getByText('inspect').closest('[data-chat-flow-kind="assistant-step"]') as HTMLElement
@@ -1636,13 +1641,20 @@ describe('ChatView', () => {
     expect(turnProcessControl(view.container)?.getAttribute('aria-expanded')).toBe('false')
     expect(processRow.getAttribute('hidden')).toBe('until-found')
 
-    act(() => { h.setTranscriptView('normal') })
-    expect(turnProcessControl(view.container)).toBeNull()
-    expect(processRow.getAttribute('hidden')).toBeNull()
-
-    act(() => { h.setTranscriptView('compact') })
-    expect(turnProcessControl(view.container)?.getAttribute('aria-expanded')).toBe('false')
-    expect(processRow.getAttribute('hidden')).toBe('until-found')
+    const toggle = turnProcessControl(view.container)!
+    for (const mode of ['detailed', 'expanded', 'compact'] as const) {
+      act(() => { h.setTranscriptView(mode) })
+      expect(turnProcessControl(view.container)).toBe(toggle)
+      expect(toggle.getAttribute('aria-expanded')).toBe('false')
+      expect(processRow.getAttribute('hidden')).toBe('until-found')
+    }
+    fireEvent.click(toggle)
+    for (const mode of ['detailed', 'expanded', 'compact'] as const) {
+      act(() => { h.setTranscriptView(mode) })
+      expect(turnProcessControl(view.container)).toBe(toggle)
+      expect(toggle.getAttribute('aria-expanded')).toBe('true')
+      expect(processRow.getAttribute('hidden')).toBeNull()
+    }
   })
 
   it('folds final-step reasoning under the fallback title when every summary count is zero', () => {
@@ -1653,7 +1665,11 @@ describe('ChatView', () => {
         { kind: 'text' as const, text: 'final answer' },
       ],
     }
-    const h = makeHarness({ nodes: [user(1, 'question'), final], turnEnds: new Map([[1, 4]]) })
+    const h = makeHarness({
+      nodes: [user(1, 'question'), final],
+      turnEnds: new Map([[1, 4]]),
+      turnTimings: new Map([[1, { startTime: 0, endTime: 4_000 }]]),
+    })
     const view = render(<h.ChatView {...h.props} />)
     const toggle = view.getByRole('button', { name: '已思考' })
     const reasoning = view.container.querySelector<HTMLElement>('[data-turn-process-inline]')
@@ -1666,7 +1682,10 @@ describe('ChatView', () => {
 
   it('folds a completed Turn even while the reader is away from the tail', () => {
     const first = assistant(2, 'first answer', 1, 1)
-    const h = makeHarness({ nodes: [user(1, 'question'), first], running: true })
+    const h = makeHarness({
+      nodes: [user(1, 'question'), first], running: true,
+      turnTimings: new Map([[1, { startTime: 0 }]]),
+    })
     const view = render(<h.ChatView {...h.props} />)
     const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
     Object.defineProperty(scroller, 'scrollHeight', { value: 1_000, writable: true })
@@ -1688,6 +1707,7 @@ describe('ChatView', () => {
     const h = makeHarness({
       nodes: [user(1, 'question'), context(2, 'runtime policy', 1)],
       running: true,
+      turnTimings: new Map([[1, { startTime: 0 }]]),
     })
     const view = render(<h.ChatView {...h.props} />)
     const scroller = view.container.querySelector('[class*="scroll"]') as HTMLDivElement
@@ -1715,6 +1735,7 @@ describe('ChatView', () => {
     const h = makeHarness({
       nodes: [user(1, 'question'), context(2, 'runtime policy', 1)],
       running: true,
+      turnTimings: new Map([[1, { startTime: 0 }]]),
     })
     const view = render(<h.ChatView {...h.props} />)
     const contextToggle = view.getByRole('button', { name: '上下文注入' })
@@ -1742,7 +1763,7 @@ describe('ChatView', () => {
     expect(contextRow?.getAttribute('hidden')).toBe('until-found')
   })
 
-  it('keeps a foldable closed Turn fully visible while history is partial', () => {
+  it('withholds folding until the Turn start arrives even when older history remains', () => {
     const h = makeHarness({
       nodes: [
         user(1, 'question'),
@@ -1761,6 +1782,13 @@ describe('ChatView', () => {
     expect(contextRow?.hasAttribute('data-turn-process-member')).toBe(false)
 
     act(() => { h.set({ hasMore: false }) })
+    expect(turnProcessControl(view.container)).toBeNull()
+    expect(contextRow?.getAttribute('hidden')).toBeNull()
+
+    act(() => { h.set({
+      hasMore: true,
+      turnTimings: new Map([[1, { startTime: 0, endTime: 5_000 }]]),
+    }) })
     const toggle = turnProcessControl(view.container)!
     expect(toggle.getAttribute('aria-expanded')).toBe('false')
     expect(contextRow?.getAttribute('hidden')).toBe('until-found')
@@ -1784,6 +1812,7 @@ describe('ChatView', () => {
           assistant(10, 'visible answer', 2),
         ],
         turnEnds: new Map([[1, 5]]),
+        turnTimings: new Map([[1, { startTime: 0, endTime: 5_000 }]]),
         hasMore: false,
       })
     })
@@ -1807,6 +1836,7 @@ describe('ChatView', () => {
         assistant(4, 'final answer', 1, 2),
       ],
       turnEnds: new Map([[1, 5]]),
+      turnTimings: new Map([[1, { startTime: 0, endTime: 5_000 }]]),
     })
     const process = source.nodes.values()
       .find((candidate): candidate is ChatNode<'turn-process'> => candidate.kind === 'turn-process')
@@ -1862,6 +1892,7 @@ describe('ChatView', () => {
       const h = makeHarness({
         nodes: [user(1, 'question'), first, assistant(4, 'new answer', 1, 2)],
         turnEnds: new Map([[1, 5]]),
+        turnTimings: new Map([[1, { startTime: 0, endTime: 5_000 }]]),
       })
       const view = render(<h.ChatView {...h.props} />, { container: host })
       fireEvent.click(turnProcessControl(view.container)!)
diff --git a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
index f116edab09..90c9c79b0a 100644
--- a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
+++ b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
@@ -166,6 +166,12 @@ function node(value: ChatSnapshot, kind: string): ChatConversationViewNode | und
   return value.nodes.values().find(candidate => candidate.kind === kind)
 }
 
+function promptNodes(value: ChatSnapshot): ChatConversationViewNode[] {
+  const prompts = value.nodes.values().filter(candidate => candidate.kind === 'system-prompt')
+  for (const prompt of prompts) expect(value.order).not.toContain(prompt.key)
+  return prompts.sort((left, right) => left.anchorSeq - right.anchorSeq)
+}
+
 function textMessage(id: string, text: string) {
   return {
     id,
@@ -319,6 +325,42 @@ describe('built-in conversation node Definitions', () => {
     expect(hasAssistantReplyContent([{ kind: 'other', block: { type: 'future' } }])).toBe(true)
   })
 
+  it.each(['replay', 'live', 'prepend'] as const)('hides permission commands but retains their data and ordinary Context (%s)', (mode) => {
+    const entries = [
+      at(1, 'command/run', { commandId: 'permission-1', name: 'permission', source: { kind: 'user' } }),
+      at(2, 'command/done', { commandId: 'permission-1', kind: 'success', text: 'Granted' }),
+      at(3, 'command/run', { commandId: 'plan-1', name: 'plan', source: { kind: 'user' } }),
+      at(4, 'command/done', { commandId: 'plan-1', kind: 'success', text: 'Plan mode' }),
+      at(5, 'turn/start', { turn: 1 }),
+      at(6, 'step/start', { turn: 1, step: 1 }),
+      at(7, 'user/message', {
+        ...textMessage('context-1', 'workspace context'),
+        source: { kind: 'context' },
+      }, { surfaceOp: 'append' }),
+    ]
+    const value = assembler(mode === 'replay' ? entries : [])
+    if (mode === 'live') {
+      for (const entry of entries) {
+        value.append(entry)
+        value.flush()
+      }
+    } else if (mode === 'prepend') {
+      value.replaceWindow(entries.slice(1), true)
+      value.flush()
+      expect(node(snapshot(value), 'command')?.data).toMatchObject({ name: null })
+      value.prepend(entries.slice(0, 1), false)
+      value.flush()
+    }
+    const current = snapshot(value)
+    const visible = current.order.map(key => current.nodes.get(key))
+    expect(visible.map(candidate => candidate?.kind)).toEqual(['command', 'context'])
+    expect(visible[0]?.data).toMatchObject({ name: 'plan' })
+    expect(current.nodes.values().filter(candidate => candidate.kind === 'command')).toHaveLength(2)
+    expect(node(current, 'command')?.data).toMatchObject({
+      name: 'permission', outcome: { kind: 'success', text: 'Granted' },
+    })
+  })
+
   it('projects one reversible process window before the finalized answer', () => {
     const value = assembler([
       at(1, 'turn/start', { turn: 1 }),
@@ -1543,7 +1585,7 @@ describe('built-in conversation node Definitions', () => {
     expect(current.nodes.values().filter(candidate => candidate.kind === 'unknown')).toEqual([])
   })
 
-  it('shows a complete appended prompt at the start of a headerless window', () => {
+  it('retains a complete appended prompt at the start of a headerless window', () => {
     const value = assembler([
       systemUpdateAt(10, '# Known prompt', 2, 1),
       at(11, 'user/message', textMessage('window-user', 'continue'), { surfaceOp: 'append' }),
@@ -1558,8 +1600,8 @@ describe('built-in conversation node Definitions', () => {
     ], false)
     value.flush()
     const restored = snapshot(value)
-    expect(restored.order.map(key => restored.nodes.get(key)).filter(candidate => candidate?.kind === 'system-prompt')
-      .map(candidate => candidate?.data)).toEqual([{ text: '# Original' }, { text: '# Known prompt', update: true }])
+    expect(promptNodes(restored).map(candidate => candidate.data))
+      .toEqual([{ text: '# Original' }, { text: '# Known prompt', update: true }])
   })
 
   it('withholds windowed replacement prompts until prepend resolves their positions', () => {
@@ -1595,10 +1637,7 @@ describe('built-in conversation node Definitions', () => {
     ]
     const promptTexts = (value: ConversationNodeAssembler) => {
       const restored = snapshot(value)
-      return restored.order.flatMap((key) => {
-        const candidate = restored.nodes.get(key)
-        return candidate?.kind === 'system-prompt' ? [candidate.data] : []
-      })
+      return promptNodes(restored).map(candidate => candidate.data)
     }
     windowed.prepend(older, false)
     windowed.flush()
@@ -1608,7 +1647,7 @@ describe('built-in conversation node Definitions', () => {
     expect(promptTexts(nodeless)).toEqual([{ text: '# Original prompt' }, { text: '# Original prompt' }])
   })
 
-  it('shows the system node text as the request prompt card before the request messages', () => {
+  it('retains the request prompt without adding it to visible Chat rows', () => {
     const value = assembler([
       at(1, 'turn/start', { turn: 1 }),
       at(2, 'step/start', { turn: 1, step: 1 }),
@@ -1626,7 +1665,6 @@ describe('built-in conversation node Definitions', () => {
 
     const current = snapshot(value)
     expect(current.order.map(key => current.nodes.get(key)?.kind)).toEqual([
-      'system-prompt',
       'user',
       'context',
     ])
@@ -1675,8 +1713,7 @@ describe('built-in conversation node Definitions', () => {
       }
     }
     const current = snapshot(value)
-    expect(current.order.map(key => current.nodes.get(key)).filter(candidate => candidate?.kind === 'system-prompt')
-      .map(candidate => candidate?.data)).toEqual([
+    expect(promptNodes(current).map(candidate => candidate.data)).toEqual([
       { text: 'A' }, { text: 'B', update: true }, { text: 'A' },
     ])
   })
@@ -1704,15 +1741,15 @@ describe('built-in conversation node Definitions', () => {
     ])
 
     const current = snapshot(value)
-    expect(current.order.map(key => current.nodes.get(key)?.kind)).toEqual(['system-prompt', 'user'])
+    expect(current.order.map(key => current.nodes.get(key)?.kind)).toEqual(['user'])
 
     value.append(systemAt(5, '# Replaced', 3))
     value.flush()
     const replaced = snapshot(value)
-    expect(replaced.order.map(key => replaced.nodes.get(key)?.kind)).toEqual(['system-prompt', 'user'])
+    expect(replaced.order.map(key => replaced.nodes.get(key)?.kind)).toEqual(['user'])
   })
 
-  it('presents an in-history prompt update as its own card and lets no same-step header repeat it', () => {
+  it('retains an in-history prompt update without duplicating it at the same-step header', () => {
     const value = assembler([
       at(1, 'turn/start', { turn: 1 }),
       at(2, 'step/start', { turn: 1, step: 1 }),
@@ -1731,19 +1768,14 @@ describe('built-in conversation node Definitions', () => {
     ])
     const cards = () => {
       const current = snapshot(value)
-      return current.order.flatMap((key) => {
-        const candidate = current.nodes.get(key)
-        return candidate?.kind === 'system-prompt' ? [[candidate.anchorSeq, candidate.data]] : []
-      })
+      return promptNodes(current).map(candidate => [candidate.anchorSeq, candidate.data])
     }
 
-    // The update is the model-visible change at its position; node 0 keeps its card.
     expect(cards()).toEqual([
       [1, { text: '# System' }],
       [10, { text: '# Updated', update: true }],
     ])
 
-    // A series header in the same step shows nothing more: the update card already carries the text.
     value.append(at(12, 'request/header', {
       reason: 'series',
       startsSeries: true,
@@ -1752,7 +1784,6 @@ describe('built-in conversation node Definitions', () => {
     value.flush()
     expect(cards()).toHaveLength(2)
 
-    // A later series header presents the effective prompt again, as any series start does.
     value.append(at(13, 'step/end', { turn: 2, step: 1 }))
     value.append(at(14, 'step/start', { turn: 2, step: 2 }))
     value.append(at(15, 'request/header', {
@@ -1784,10 +1815,11 @@ describe('built-in conversation node Definitions', () => {
     ])
 
     const current = snapshot(value)
-    expect(current.order.map(key => current.nodes.get(key)?.kind)).toEqual(['system-prompt', 'user'])
+    expect(current.order.map(key => current.nodes.get(key)?.kind)).toEqual(['user'])
+    expect(promptNodes(current).map(candidate => candidate.data)).toEqual([{ text: '# System' }])
   })
 
-  it('keeps the initial system prompt before the opening User as Turn process state changes', () => {
+  it('keeps the system prompt out of Chat order as Turn process state changes', () => {
     const value = assembler([
       at(1, 'turn/start', { turn: 1 }),
       at(2, 'step/start', { turn: 1, step: 1 }),
@@ -1808,14 +1840,14 @@ describe('built-in conversation node Definitions', () => {
     }
     const promptKey = node(snapshot(value), 'system-prompt')?.key
 
-    expect(kinds()).toEqual(['system-prompt', 'user', 'context'])
+    expect(kinds()).toEqual(['user', 'context'])
 
     value.append(at(7, 'assistant/live-chunk', {
       turn: 1, step: 1, chunk: { type: 'reasoning-delta', index: 0, text: 'thinking' },
     }))
     value.flush()
     expect(kinds()).toEqual([
-      'system-prompt', 'user', 'turn-process', 'context', 'assistant-step',
+      'user', 'turn-process', 'context', 'assistant-step',
     ])
 
     value.append(at(8, 'step/end', { turn: 1, step: 1 }))
@@ -1828,7 +1860,7 @@ describe('built-in conversation node Definitions', () => {
     value.flush()
 
     expect(kinds()).toEqual([
-      'system-prompt', 'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
+      'user', 'turn-process', 'context', 'assistant-step', 'assistant-step', 'turn-tail',
     ])
     expect(node(snapshot(value), 'system-prompt')?.key).toBe(promptKey)
   })
@@ -1855,7 +1887,8 @@ describe('built-in conversation node Definitions', () => {
       const candidate = current.nodes.get(key)
       return candidate?.kind === 'system-prompt' || candidate?.kind === 'user' ? [candidate] : []
     })
-    expect(ordered.map(candidate => candidate.kind)).toEqual(['system-prompt', 'user', 'user'])
+    expect(ordered.map(candidate => candidate.kind)).toEqual(['user', 'user'])
+    expect(promptNodes(current).map(candidate => candidate.data)).toEqual([{ text: '# System' }])
   })
 
   it('places a withheld replacement prompt after prepend supplies its original node', () => {
@@ -1892,10 +1925,7 @@ describe('built-in conversation node Definitions', () => {
       windowed.flush()
 
       const restored = snapshot(windowed)
-      const prompts = restored.order.flatMap((key) => {
-        const candidate = restored.nodes.get(key)
-        return candidate?.kind === 'system-prompt' ? [candidate] : []
-      })
+      const prompts = promptNodes(restored)
       expect(prompts.map(candidate => candidate.anchorSeq)).toEqual([1, 10])
       expect(prompts.at(-1)?.data).toEqual({ text: windowedSystem })
       expect(restored.nodes.get(user.key)).toBeDefined()
@@ -1936,11 +1966,8 @@ describe('built-in conversation node Definitions', () => {
       const candidate = current.nodes.get(key)
       return candidate?.kind === 'system-prompt' || candidate?.kind === 'user' ? [candidate] : []
     })
-    expect(ordered.map(candidate => candidate?.kind)).toEqual([
-      'system-prompt', 'user', 'system-prompt', 'system-prompt', 'user',
-    ])
-    expect(ordered.filter(candidate => candidate?.kind === 'system-prompt')
-      .map(candidate => candidate?.anchorSeq)).toEqual([1, 7, 10])
+    expect(ordered.map(candidate => candidate.kind)).toEqual(['user', 'user'])
+    expect(promptNodes(current).map(candidate => candidate.anchorSeq)).toEqual([1, 7, 10])
   })
 
   it('associates each direct message with its immediately following session recall', () => {
diff --git a/packages/client/ui-chat/tests/coverage-tails.client.spec.tsx b/packages/client/ui-chat/tests/coverage-tails.client.spec.tsx
index 2a2883ebb3..bc759ada20 100644
--- a/packages/client/ui-chat/tests/coverage-tails.client.spec.tsx
+++ b/packages/client/ui-chat/tests/coverage-tails.client.spec.tsx
@@ -5,6 +5,7 @@ import { cleanup, render } from '@testing-library/react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
+import { useDetailedPresentation } from './presentation-fixture.client.ts'
 import { zh } from '../src/client/locale.ts'
 
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
@@ -16,6 +17,7 @@ describe('tails', () => {
   it('AssistantMarkdown renders reasoning as a Think row and unknown blocks as JSON fallback', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[
           { kind: 'reasoning', text: 'thinking hard\nsecond line' },
@@ -31,6 +33,7 @@ describe('tails', () => {
     expect(view.getByText(/未知内容块/)).toBeTruthy()
     const stopped = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'text', text: 'partial words' }]}
         streaming={false}
@@ -46,6 +49,7 @@ describe('tails', () => {
     // groups is layout noise (no text, no pulse, no interrupted marker).
     const empty = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'tool-call', callId: 'c', name: 'todo_write', argsRaw: '{}' }]}
         streaming={false}
@@ -54,7 +58,9 @@ describe('tails', () => {
     )
     expect(empty.container.firstChild).toBeNull()
     const blank = render(
-      <AssistantMarkdown t={t} blocks={[]} streaming={false} renderMessageImages={renderMessageImages} />,
+      <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
+        t={t} blocks={[]} streaming={false} renderMessageImages={renderMessageImages} />,
     )
     expect(blank.container.firstChild).toBeNull()
   })
diff --git a/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx
index 8bfb4014b6..d97056af81 100644
--- a/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx
+++ b/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx
@@ -5,6 +5,7 @@ import { cleanup, render } from '@testing-library/react'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
+import { useDetailedPresentation } from './presentation-fixture.client.ts'
 import { StatsPills } from '../src/client/chat/StatsPills.tsx'
 import { zh } from '../src/client/locale.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
@@ -22,6 +23,7 @@ describe('render branch tails', () => {
   it('AssistantMarkdown reasoning row is ok-state when not the streaming tail', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text: 'done thinking' }, { kind: 'text', text: 'answer' }]}
         streaming
@@ -60,6 +62,7 @@ describe('render branch tails', () => {
   it('AssistantMarkdown reasoning as the streaming tail renders the running ring', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text: 'still thinking' }]}
         streaming
diff --git a/packages/client/ui-chat/tests/image-labels.client.spec.tsx b/packages/client/ui-chat/tests/image-labels.client.spec.tsx
index ffbde6bb29..0315bc2066 100644
--- a/packages/client/ui-chat/tests/image-labels.client.spec.tsx
+++ b/packages/client/ui-chat/tests/image-labels.client.spec.tsx
@@ -7,6 +7,7 @@ import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { RenderMessageImages } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { AssistantMarkdown } from '../src/client/chat/AssistantMarkdown.tsx'
+import { useDetailedPresentation } from './presentation-fixture.client.ts'
 import { zh } from '../src/client/locale.ts'
 
 afterEach(cleanup)
@@ -44,6 +45,7 @@ describe('assistant image slot handoff', () => {
     const calls: MessageImagesRenderOwner[] = []
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'image', attachment }]}
         streaming={false}
@@ -59,6 +61,7 @@ describe('assistant image slot handoff', () => {
     const calls: MessageImagesRenderOwner[] = []
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[
           { kind: 'image', attachment },
@@ -80,6 +83,7 @@ describe('assistant image slot handoff', () => {
     const calls: MessageImagesRenderOwner[] = []
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[
           { kind: 'text', text: 'before' },
diff --git a/packages/client/ui-chat/tests/performance-usage.client.spec.ts b/packages/client/ui-chat/tests/performance-usage.client.spec.ts
index 00e862cfe6..54ddfdd1de 100644
--- a/packages/client/ui-chat/tests/performance-usage.client.spec.ts
+++ b/packages/client/ui-chat/tests/performance-usage.client.spec.ts
@@ -21,10 +21,10 @@ describe('PerformanceUsagePolicy', () => {
 
   it('adopts accepted Host settings at construction and after updates', () => {
     const host = stubSettingsScope<ChatSettings>()
-    host.publish({ value: { transcriptView: 'normal', performanceUsage: 'compact' } })
+    host.publish({ value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'compact' } })
     const policy = new PerformanceUsagePolicy(host.scope)
     expect(policy.mode.getSnapshot()).toBe('compact')
-    host.publish({ value: { transcriptView: 'normal', performanceUsage: 'detailed' } })
+    host.publish({ value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'detailed' } })
     expect(policy.mode.getSnapshot()).toBe('detailed')
   })
 })
diff --git a/packages/client/ui-chat/tests/presentation-fixture.client.ts b/packages/client/ui-chat/tests/presentation-fixture.client.ts
new file mode 100644
index 0000000000..6cd56d4d57
--- /dev/null
+++ b/packages/client/ui-chat/tests/presentation-fixture.client.ts
@@ -0,0 +1,10 @@
+/** Fixed display policy for isolated Assistant Markdown fixtures. */
+import type { UsePresentation } from '../src/client/contract/slots.ts'
+import { presentationPolicyFor } from '../src/client/presentation-policy.ts'
+
+/**
+ * Select from a fixed policy that shows settled reasoning previews.
+ * @param selector - component's policy selection.
+ * @returns the selected Detailed policy value.
+ */
+export const useDetailedPresentation: UsePresentation = selector => selector(presentationPolicyFor('detailed'))
diff --git a/packages/client/ui-chat/tests/presentation-policy.client.spec.tsx b/packages/client/ui-chat/tests/presentation-policy.client.spec.tsx
new file mode 100644
index 0000000000..c7070e147c
--- /dev/null
+++ b/packages/client/ui-chat/tests/presentation-policy.client.spec.tsx
@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+import { act, cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
+import type { TranscriptViewMode } from '../src/chat-settings.ts'
+import { derivePresentationPolicy, presentationPolicyFor } from '../src/client/presentation-policy.ts'
+
+afterEach(cleanup)
+
+describe('Chat presentation policy', () => {
+  it.each([
+    ['compact', 'collapsed', false],
+    ['detailed', 'collapsed', true],
+    ['expanded', 'none', true],
+  ] as const)('maps %s to stable presentation capabilities', (mode, stepGrouping, settledReasoningPreview) => {
+    const policy = presentationPolicyFor(mode)
+    expect(policy).toEqual({ mode, foldCompletedTurns: true, stepGrouping, settledReasoningPreview })
+    expect(presentationPolicyFor(mode)).toBe(policy)
+  })
+
+  it('forwards mode notifications and removes the subscription on disposal', () => {
+    const mode = createSnapshotStore<TranscriptViewMode>('compact')
+    const policy = derivePresentationPolicy(mode)
+    const listener = vi.fn()
+    const dispose = policy.subscribe(listener)
+    expect(policy.getSnapshot()).toBe(presentationPolicyFor('compact'))
+    mode.set('detailed')
+    expect(listener).toHaveBeenCalledTimes(1)
+    expect(policy.getSnapshot()).toBe(presentationPolicyFor('detailed'))
+    dispose()
+    mode.set('expanded')
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders only consumers whose selected field changes', () => {
+    const mode = createSnapshotStore<TranscriptViewMode>('compact')
+    const usePresentation = bindSnapshotSelector(derivePresentationPolicy(mode))
+    const foldRender = vi.fn()
+    const previewRender = vi.fn()
+    function Fold() {
+      const fold = usePresentation(policy => policy.foldCompletedTurns)
+      foldRender(fold)
+      return <span>{String(fold)}</span>
+    }
+    function Preview() {
+      const preview = usePresentation(policy => policy.settledReasoningPreview)
+      previewRender(preview)
+      return <span>{String(preview)}</span>
+    }
+    render(<><Fold /><Preview /></>)
+    expect(foldRender).toHaveBeenCalledTimes(1)
+    expect(previewRender).toHaveBeenCalledTimes(1)
+    act(() => { mode.set('detailed') })
+    expect(foldRender).toHaveBeenCalledTimes(1)
+    expect(previewRender).toHaveBeenCalledTimes(2)
+    act(() => { mode.set('expanded') })
+    expect(foldRender).toHaveBeenCalledTimes(1)
+    expect(previewRender).toHaveBeenCalledTimes(2)
+    act(() => { mode.set('compact') })
+    expect(foldRender).toHaveBeenCalledTimes(1)
+    expect(previewRender).toHaveBeenCalledTimes(3)
+  })
+})
diff --git a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
index dedfa9198f..e0ce4a1b1e 100644
--- a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
@@ -1,10 +1,15 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, fireEvent, render } from '@testing-library/react'
-import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { zh } from '../src/client/locale.ts'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
+import { useDetailedPresentation } from './presentation-fixture.client.ts'
+import type { TranscriptViewMode } from '../src/chat-settings.ts'
+import { derivePresentationPolicy } from '../src/client/presentation-policy.ts'
+import { ReasoningRow } from '../src/client/chat/ReasoningRow.tsx'
 
 afterEach(() => {
   cleanup()
@@ -14,22 +19,87 @@ const t = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 
 describe('ReasoningRow', () => {
+  it.each([
+    ['', ''],
+    ['An unfinished line', ''],
+    ['A completed first line\nUnfinished continuation', 'A completed first line'],
+    ['First\nSecond\nThird\n', 'First'],
+    ['First\n\nNext unfinished', 'First'],
+    ['First\n\nNext complete\nDetails', 'Next complete'],
+    ['First\n\n\nNext complete\n', 'Next complete'],
+    ['First\n \n\t\nNext complete\nDetails', 'Next complete'],
+    ['First\r\n\r\n\r\nNext complete\r\n', 'Next complete'],
+    ['First\r\n \r\n\t\r\nNext complete\r\nDetails', 'Next complete'],
+    ['First\n\n\nNext unfinished', 'First'],
+    ['\n\n\nFirst complete\n', 'First complete'],
+    ['First\r\n \t\r\nNext complete\r\n', 'Next complete'],
+    ['First\n\n\n', 'First'],
+  ])('previews the completed paragraph first line for %j', (text, summary) => {
+    const view = render(<ReasoningRow text={text} running usePresentation={useDetailedPresentation} t={t} />)
+    const root = view.container.querySelector('[data-variant="think"]')!
+    expect(root.querySelector('[class*="summaryText"]')?.textContent).toBe(summary)
+    expect(root.hasAttribute('data-preview')).toBe(summary !== '')
+  })
+
+  it('retains summaries and expanded Markdown when the work-details mode changes', () => {
+    const mode = createSnapshotStore<TranscriptViewMode>('detailed')
+    const usePresentation = bindSnapshotSelector(derivePresentationPolicy(mode))
+    const view = render(<ReasoningRow
+      text={'First line\n\nDetailed body'} running={false} usePresentation={usePresentation} t={t} />)
+    const root = view.container.querySelector('[data-variant="think"]')!
+    const summary = view.getByText('First line')
+    const toggle = view.getByRole('button')
+    for (const next of ['compact', 'detailed', 'expanded', 'compact'] as const) {
+      act(() => { mode.set(next) })
+      expect(view.getByText('First line')).toBe(summary)
+      expect(root.hasAttribute('data-preview')).toBe(next !== 'compact')
+      expect(root.querySelector('[data-markdown-variant]')).toBeNull()
+    }
+    fireEvent.click(toggle)
+    const body = view.getByText('Detailed body')
+    for (const next of ['detailed', 'expanded', 'compact'] as const) {
+      act(() => { mode.set(next) })
+      expect(view.getByText('Detailed body')).toBe(body)
+      expect(toggle.getAttribute('aria-expanded')).toBe('true')
+      expect(root.hasAttribute('data-preview')).toBe(false)
+    }
+  })
+
+  it('keeps a running preview enabled in Compact and hides it on settlement without removing it', () => {
+    const mode = createSnapshotStore<TranscriptViewMode>('compact')
+    const usePresentation = bindSnapshotSelector(derivePresentationPolicy(mode))
+    const props = { text: 'First line\n', usePresentation, t }
+    const view = render(<ReasoningRow {...props} running />)
+    const summary = view.getByText('First line')
+    const root = view.container.querySelector('[data-variant="think"]')!
+    expect(root.hasAttribute('data-preview')).toBe(true)
+    view.rerender(<ReasoningRow {...props} running={false} />)
+    expect(root.hasAttribute('data-preview')).toBe(false)
+    expect(view.getByText('First line')).toBe(summary)
+  })
+
   it.each([
     { kind: 'text' as const, text: 'Answer' },
     { kind: 'tool-call' as const, callId: 'call-1', name: 'read', argsRaw: '{}' },
   ])('starts collapsed and preserves manual expansion when $kind arrives', (nextBlock) => {
     const reasoning = { kind: 'reasoning' as const, text: 'Inspect the session\nCheck persistence' }
     const view = render(
-      <AssistantMarkdown t={t} blocks={[reasoning]} streaming renderMessageImages={renderMessageImages} />,
+      <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
+        t={t} blocks={[reasoning]} streaming renderMessageImages={renderMessageImages} />,
     )
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
     fireEvent.click(view.getByText('思考'))
     view.rerender(
-      <AssistantMarkdown t={t} blocks={[reasoning, nextBlock]} streaming renderMessageImages={renderMessageImages} />,
+      <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
+        t={t} blocks={[reasoning, nextBlock]} streaming renderMessageImages={renderMessageImages} />,
     )
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
     view.rerender(
-      <AssistantMarkdown t={t} blocks={[reasoning, nextBlock]} streaming={false} renderMessageImages={renderMessageImages} />,
+      <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
+        t={t} blocks={[reasoning, nextBlock]} streaming={false} renderMessageImages={renderMessageImages} />,
     )
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
     expect(view.getByText(/Check persistence/)).toBeTruthy()
@@ -37,35 +107,52 @@ describe('ReasoningRow', () => {
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
   })
 
-  it('follows the latest streaming line, then restores the settled first line', () => {
+  it('advances on completed paragraph first lines, then restores the settled first line', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens' }]}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nDetails\n\nNewest reasoning tokens\n' }]}
         streaming
         renderMessageImages={renderMessageImages}
       />,
     )
     expect(view.getByText('运行中')).toBeTruthy()
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
-    expect(view.getByText('Newest reasoning tokens').parentElement?.getAttribute('data-follow-end'))
+    expect(view.getByText('Newest reasoning tokens').parentElement?.getAttribute('data-streaming'))
       .toBe('true')
 
     view.rerender(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens keep arriving' }]}
+        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nDetails\n\nNewest reasoning tokens\nMore details\n\nChecking boundaries' }]}
         streaming
         renderMessageImages={renderMessageImages}
       />,
     )
-    expect(view.getByText('Newest reasoning tokens keep arriving').parentElement
-      ?.getAttribute('data-follow-end')).toBe('true')
+    expect(view.getByText('Newest reasoning tokens').parentElement
+      ?.getAttribute('data-streaming')).toBe('true')
+    expect(view.queryByText('Checking boundaries')).toBeNull()
+
+    const text = 'Inspect the session\nDetails\n\nNewest reasoning tokens\nMore details\n\nChecking boundaries\n'
+    view.rerender(
+      <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
+        t={t}
+        blocks={[{ kind: 'reasoning', text }]}
+        streaming
+        renderMessageImages={renderMessageImages}
+      />,
+    )
+    expect(view.getByText('Checking boundaries')).toBeTruthy()
+    expect(view.queryByText('Newest reasoning tokens')).toBeNull()
 
     view.rerender(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
-        blocks={[{ kind: 'reasoning', text: 'Inspect the session\nNewest reasoning tokens keep arriving\n' }]}
+        blocks={[{ kind: 'reasoning', text }]}
         streaming={false}
         renderMessageImages={renderMessageImages}
       />,
@@ -73,12 +160,13 @@ describe('ReasoningRow', () => {
     const settledSummary = view.getByText('Inspect the session')
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
     expect(view.queryByText('运行中')).toBeNull()
-    expect(settledSummary.parentElement?.hasAttribute('data-follow-end')).toBe(false)
+    expect(settledSummary.parentElement?.hasAttribute('data-streaming')).toBe(false)
   })
 
   it('expands from either Think or the reasoning summary', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text: 'Inspect the session\nCheck persistence' }]}
         streaming={false}
@@ -103,12 +191,13 @@ describe('ReasoningRow', () => {
     },
     {
       label: 'streaming',
-      text: 'Inspect the session\n**Comparing checkout and merge bases**',
+      text: 'Inspect the session\n\n**Comparing checkout and merge bases**\n',
       streaming: true,
     },
   ])('strips double-asterisk markers from the $label summary and renders body emphasis', ({ text, streaming }) => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text }]}
         streaming={streaming}
@@ -129,6 +218,7 @@ describe('ReasoningRow', () => {
       .join('\n\n') + '\n\nReasoning body.'
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text }]}
         streaming={false}
@@ -154,6 +244,7 @@ describe('ReasoningRow', () => {
     const first = '## Investigation\n\n**Check persistence**\n\n'
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text: first }]}
         streaming
@@ -166,6 +257,7 @@ describe('ReasoningRow', () => {
     const text = first + Array.from({ length: 8 }, (_, index) => `Paragraph ${index}.`).join('\n\n')
     view.rerender(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text }]}
         streaming
@@ -180,6 +272,7 @@ describe('ReasoningRow', () => {
   it('expanded Think drops the inline summary and renders prose without an IN card', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[{ kind: 'reasoning', text: 'Inspect the session\nCheck persistence' }]}
         streaming={false}
@@ -196,6 +289,7 @@ describe('ReasoningRow', () => {
   it('anchors the sticky-header selector: only an open Think row nests the disclosure row under data-expanded and data-open', () => {
     const view = render(
       <AssistantMarkdown
+        usePresentation={useDetailedPresentation}
         t={t}
         blocks={[
           { kind: 'reasoning', text: 'Inspect the session\nCheck persistence' },
diff --git a/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts b/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts
index 84717bb5c0..ed4ee9f6e6 100644
--- a/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts
+++ b/packages/client/ui-chat/tests/transcript-view-policy.client.spec.ts
@@ -20,28 +20,28 @@ describe('TranscriptViewPolicy', () => {
     current = () => policy.mode.getSnapshot()
 
     expect(policy.mode.getSnapshot()).toBe('compact')
-    policy.setMode('normal')
-    expect(policy.mode.getSnapshot()).toBe('normal')
-    expect(observed).toEqual(['transcriptView=normal:normal'])
-    expect(host.set).toHaveBeenCalledWith('transcriptView', 'normal')
+    policy.setMode('detailed')
+    expect(policy.mode.getSnapshot()).toBe('detailed')
+    expect(observed).toEqual(['transcriptView=detailed:detailed'])
+    expect(host.set).toHaveBeenCalledWith('transcriptView', 'detailed')
   })
 
-  it('adopts Host state and ignores identical writes', () => {
+  it('adopts Host state, reads the legacy value as Detailed, and ignores identical writes', () => {
     const host = stubSettingsScope<ChatSettings>()
     const policy = new TranscriptViewPolicy(host.scope)
 
-    host.publish({ status: 'ready', value: { transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
-    expect(policy.mode.getSnapshot()).toBe('normal')
-    policy.setMode('normal')
+    host.publish({ status: 'ready', value: { linkOpening: 'sidebar', transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
+    expect(policy.mode.getSnapshot()).toBe('detailed')
+    policy.setMode('detailed')
     expect(host.set).not.toHaveBeenCalled()
 
-    host.publish({ value: { transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 2 })
+    host.publish({ value: { linkOpening: 'sidebar', transcriptView: 'compact', performanceUsage: 'detailed' }, revision: 2 })
     expect(policy.mode.getSnapshot()).toBe('compact')
   })
 
   it('adopts an accepted section standing at construction', () => {
     const host = stubSettingsScope<ChatSettings>()
-    host.publish({ status: 'ready', value: { transcriptView: 'normal', performanceUsage: 'detailed' }, revision: 1, writable: true })
-    expect(new TranscriptViewPolicy(host.scope).mode.getSnapshot()).toBe('normal')
+    host.publish({ status: 'ready', value: { linkOpening: 'sidebar', transcriptView: 'expanded', performanceUsage: 'detailed' }, revision: 1, writable: true })
+    expect(new TranscriptViewPolicy(host.scope).mode.getSnapshot()).toBe('expanded')
   })
 })
diff --git a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
index ca5aeb1e00..98154b74cc 100644
--- a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { WorkspaceSnapshot } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionStatusSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
@@ -9,14 +9,15 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { TranscriptViewRow, type TranscriptViewRowProps } from '../src/client/settings/TranscriptViewRow.tsx'
 import { PerformanceUsageRow } from '../src/client/settings/PerformanceUsageRow.tsx'
-import type { PerformanceUsageMode } from '../src/chat-settings.ts'
+import type { LinkOpening, PerformanceUsageMode, TranscriptViewMode } from '../src/chat-settings.ts'
+import { LinkOpeningRow } from '../src/client/settings/LinkOpeningRow.tsx'
 import { en, zh } from '../src/client/locale.ts'
 
 afterEach(cleanup)
 
 function emptySessions() {
   return bindSnapshotSelector(createSnapshotStore<SessionListState>({
-    ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+    ids: [], byId: {}, phase: 'ready', projectionsBySession: {},
   }))
 }
 
@@ -33,9 +34,9 @@ function noPendingInteraction() {
 // The resource hook the resources plugin merges into GlobalStandardProps; this row reads no address.
 const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined })) as GlobalStandardProps['useResource']
 
-function mount(mode: 'normal' | 'compact' = 'compact', dictionary: typeof en | typeof zh = en) {
-  const source = createSnapshotStore(mode)
-  const setTranscriptView = vi.fn((next: 'normal' | 'compact') => { source.set(next) })
+function mount(mode: TranscriptViewMode = 'compact', dictionary: typeof en | typeof zh = en) {
+  const source = createSnapshotStore<TranscriptViewMode>(mode)
+  const setTranscriptView = vi.fn((next: TranscriptViewMode) => { source.set(next) })
   const props: TranscriptViewRowProps = {
     usePanelInfo: selector => selector({ activePanelId: null }),
     useSessions: emptySessions(),
@@ -54,32 +55,85 @@ function mount(mode: 'normal' | 'compact' = 'compact', dictionary: typeof en | t
 describe('TranscriptViewRow', () => {
   it('explains the preference and shows Compact by default', () => {
     mount()
-    expect(screen.getByText('Conversation display')).toBeDefined()
-    expect(screen.getByText('Controls process content in completed turns')).toBeDefined()
+    expect(screen.getByText('Work details')).toBeDefined()
+    expect(screen.getByText('Controls how turns and steps expand by default')).toBeDefined()
     expect(screen.getByRole('button', { name: /Compact/ }).getAttribute('aria-expanded')).toBe('false')
   })
 
-  it('selects Normal and follows the mirrored value', () => {
+  it.each([
+    ['detailed', 'Detailed'],
+    ['expanded', 'Expanded'],
+  ] as const)('selects %s and follows the mirrored value', (mode, label) => {
     const b = mount()
     fireEvent.click(screen.getByRole('button', { name: /Compact/ }))
-    fireEvent.click(screen.getByRole('menuitem', { name: 'Normal' }))
-    expect(b.setTranscriptView).toHaveBeenCalledWith('normal')
-    const trigger = screen.getByRole('button', { name: /Normal/ })
+    expect(screen.queryByRole('menuitem', { name: 'Normal' })).toBeNull()
+    fireEvent.click(screen.getByRole('menuitem', { name: label }))
+    expect(b.setTranscriptView).toHaveBeenCalledWith(mode)
+    const trigger = screen.getByRole('button', { name: label })
     fireEvent.click(trigger)
     expect(screen.getByRole('menuitem', { name: 'Compact' })).toBeDefined()
     fireEvent.pointerDown(document.body)
     expect(screen.queryByRole('menuitem', { name: 'Compact' })).toBeNull()
   })
 
-  it('shows the conversation-display values in Chinese', () => {
-    mount('compact', zh)
-    fireEvent.click(screen.getByRole('button', { name: '紧凑' }))
-    fireEvent.click(screen.getByRole('menuitem', { name: '标准' }))
-    expect(screen.getByRole('button', { name: '标准' })).toBeDefined()
+  it('shows all three work-detail values in Chinese', () => {
+    const b = mount('compact', zh)
+    expect(screen.getByText('工作过程展示')).toBeDefined()
+    fireEvent.click(screen.getByRole('button', { name: '简洁' }))
+    fireEvent.click(screen.getByRole('menuitem', { name: '详细' }))
+    expect(b.setTranscriptView).toHaveBeenLastCalledWith('detailed')
+    fireEvent.click(screen.getByRole('button', { name: '详细' }))
+    fireEvent.click(screen.getByRole('menuitem', { name: '完全展开' }))
+    expect(b.setTranscriptView).toHaveBeenLastCalledWith('expanded')
+    expect(screen.getByRole('button', { name: '完全展开' })).toBeDefined()
   })
 })
 
 
+describe('LinkOpeningRow', () => {
+  it('follows browser availability without clearing the saved destination', () => {
+    const b = mount()
+    const browserAvailable = createSnapshotStore(false)
+    const source = createSnapshotStore<LinkOpening>('new-tab')
+    render(<LinkOpeningRow
+      {...b.props}
+      useLinkOpening={bindSnapshotSelector(source)}
+      useBrowserAvailable={bindSnapshotSelector(browserAvailable)}
+      setLinkOpening={vi.fn()}
+    />)
+    expect(screen.queryByText('Open chat links in')).toBeNull()
+    act(() => { browserAvailable.set(true) })
+    expect(screen.getByRole('button', { name: 'New browser tab' })).toBeDefined()
+    act(() => { browserAvailable.set(false) })
+    expect(screen.queryByText('Open chat links in')).toBeNull()
+    expect(source.getSnapshot()).toBe('new-tab')
+  })
+
+  it.each([
+    [en, 'Open chat links in', 'Built-in browser', 'New browser tab'],
+    [zh, '聊天链接打开方式', '内置浏览器', '浏览器新标签页'],
+  ] as const)('selects either destination using localized labels (%s)', (dictionary, title, sidebar, newTab) => {
+    const b = mount('compact', dictionary)
+    const source = createSnapshotStore<LinkOpening>('sidebar')
+    const setLinkOpening = vi.fn((destination: LinkOpening) => { source.set(destination) })
+    render(<LinkOpeningRow
+      {...b.props}
+      useLinkOpening={bindSnapshotSelector(source)}
+      useBrowserAvailable={bindSnapshotSelector(createSnapshotStore(true))}
+      setLinkOpening={setLinkOpening}
+    />)
+    expect(screen.getByText(title)).toBeDefined()
+    fireEvent.click(screen.getByRole('button', { name: sidebar }))
+    fireEvent.click(screen.getByRole('menuitem', { name: newTab }))
+    expect(setLinkOpening).toHaveBeenLastCalledWith('new-tab')
+    fireEvent.click(screen.getByRole('button', { name: newTab }))
+    fireEvent.click(screen.getByRole('menuitem', { name: sidebar }))
+    expect(setLinkOpening).toHaveBeenLastCalledWith('sidebar')
+    expect(screen.getByRole('button', { name: sidebar }).getAttribute('aria-expanded')).toBe('false')
+    expect(b.setTranscriptView).not.toHaveBeenCalled()
+  })
+})
+
 describe('PerformanceUsageRow', () => {
   it('selects compact statistics independently of conversation display', () => {
     const b = mount()
diff --git a/packages/client/ui-chat/tsconfig.json b/packages/client/ui-chat/tsconfig.json
index a004571d35..92dffe85b0 100644
--- a/packages/client/ui-chat/tsconfig.json
+++ b/packages/client/ui-chat/tsconfig.json
@@ -90,7 +90,7 @@
       "path": "../ui-session"
     },
     {
-      "path": "../ui-sidebar-browser"
+      "path": "../ui-sidebar-browser/tsconfig.client.json"
     },
     {
       "path": "../ui-sidebar-right"
diff --git a/packages/client/ui-commands/README.i18n.yaml b/packages/client/ui-commands/README.i18n.yaml
index eb6201046e..579f9d857b 100644
--- a/packages/client/ui-commands/README.i18n.yaml
+++ b/packages/client/ui-commands/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-commands/README.md
-README.md: f8cba29179f9960042a4a9e67e86496591a76d08
-README.zh.md: 1cea3ae7aea857f2b2d219abf0a7192c2f222792
+README.md: 7fada747562ff15a96997d8bffe9aeb6f9a18fb5
+README.zh.md: 2f532cbd0f3d33e304074644cc6cb02b7151d3e1
diff --git a/packages/client/ui-commands/README.md b/packages/client/ui-commands/README.md
index f8cba29179..7fada74756 100644
--- a/packages/client/ui-commands/README.md
+++ b/packages/client/ui-commands/README.md
@@ -49,6 +49,8 @@ When the composer submits with images or generic files, only a host command decl
 
 `src/client/contract.ts` defines contribution and decoration registration, plus `dismiss(name)`, which closes that command's open popups and confirmations: dismissal aborts pending option loads, prevents their late results from reopening the popup, and preserves composer drafts. `CommandDirectory` owns the per-session wire cache and resolves typed commands through `resolution.ts`; that module owns first-party identity matching and localized input spellings. `matchSpace` reads the ready cache synchronously, while `matchEnter` waits for readiness and rejects on warmup failure or cancellation. Forwarded catalog and connection events invalidate the cache. After a matched Host execution, this browser emits `command/executed`; other clients observe only the durable command events. `PopupSelectController` owns popup state, and `PopupSelectView` occupies the input overlay. `presentation.ts` owns row labels, icons, and sections; its helpers and the resolution helpers stay internal to the plugin.
 
+Each command-directory fetch requires an existing retained Client Session and waits for its initial history open to succeed before sending `commands.list`. A temporary `commandCatalog` reference holds that Session until the fetch settles. An unretained Session or a failed open rejects without sending the RPC, so background catalog refreshes do not reopen closed Sessions.
+
 </details>
 
 -----
diff --git a/packages/client/ui-commands/README.zh.md b/packages/client/ui-commands/README.zh.md
index 1cea3ae7ae..2f532cbd0f 100644
--- a/packages/client/ui-commands/README.zh.md
+++ b/packages/client/ui-commands/README.zh.md
@@ -49,6 +49,8 @@ composer 携带图片或通用文件提交时，只有声明了 `input.attachmen
 
 `src/client/contract.ts` 定义贡献项和装饰的注册接口，以及 `dismiss(name)`：它关闭该命令已打开的弹窗与确认对话框，中止待完成的选项加载，阻止晚到结果重新打开弹窗，并保留 composer 草稿。`CommandDirectory` 负责会话级协议缓存，并通过 `resolution.ts` 解析输入命令；该模块负责内置命令标识匹配和本地化输入写法。`matchSpace` 同步读取就绪缓存，`matchEnter` 等待缓存就绪，预热失败或取消时拒绝。转发的目录和连接事件使缓存失效。宿主执行匹配的命令后，本浏览器发布 `command/executed`，其他客户端只观察持久命令事件。`PopupSelectController` 负责弹窗状态，`PopupSelectView` 占据输入浮层。`presentation.ts` 负责行标题、图标和分节，展示与解析辅助函数均留在插件内部。
 
+每次命令目录拉取都要求客户端已持有该会话，并等待首次历史打开成功后才发送 `commands.list`。临时的 `commandCatalog` 引用持续持有会话，直到拉取结束。未被持有的会话或打开失败会直接拒绝，不发送 RPC，因此后台目录刷新不会重新打开已关闭的会话。
+
 </details>
 
 -----
diff --git a/packages/client/ui-commands/src/client/service.ts b/packages/client/ui-commands/src/client/service.ts
index 316474f354..7ae8c42c8b 100644
--- a/packages/client/ui-commands/src/client/service.ts
+++ b/packages/client/ui-commands/src/client/service.ts
@@ -9,6 +9,8 @@
  * `rankByName`). A host/contribution name collision fails loud. Every
  * execute addresses the session's agent by sessionId — sessions are always
  * agent-backed.
+ * Catalog RPCs retain an existing Client Session through completion and
+ * wait for its initial history open to succeed before contacting the Host.
  */
 import { Service } from '@deepseek-ai/cordis'
 import type { Context } from '@deepseek-ai/cordis'
@@ -34,6 +36,13 @@ import { builtinRowFace, sectionRows } from './presentation.ts'
 import { claimToken } from './resolution.ts'
 import type { TokenSegment } from './popup.ts'
 
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+  interface SessionReferenceSourceMap {
+    /** A command-catalog fetch waiting for initial history and its RPC result. */
+    commandCatalog: unknown
+  }
+}
+
 declare module '@deepseek-ai/cordis' {
   interface Events {
     /**
@@ -86,10 +95,20 @@ export class CommandUiRuntime extends Service implements CommandUiContract {
     if (locale === undefined) throw new Error('ui-commands: locale service unavailable')
     this.t = locale.bind('command')
     this.directory = new CommandDirectory(async (sessionId) => {
-      if (this.sessions().subagentAddress(sessionId) !== undefined) return []
-      const result = await ctx.remote.commands.list(sessionId)
-      if (!result.ok) throw new Error(`command.list failed: ${result.error.code}: ${result.error.message}`)
-      return result.value
+      const sessions = this.sessions()
+      if (sessions.subagentAddress(sessionId) !== undefined) return []
+      if (sessions.binding(sessionId) === undefined) {
+        throw new Error(`command catalog requires a retained session "${sessionId}"`)
+      }
+      return sessions.using(sessionId, { source: 'commandCatalog' }, async (reference) => {
+        const state = reference.binding.session.getSnapshot()
+        if (state.openState !== 'open') {
+          throw state.openError ?? new Error(`session "${sessionId}" is not open`)
+        }
+        const result = await ctx.remote.commands.list(sessionId)
+        if (!result.ok) throw new Error(`command.list failed: ${result.error.code}: ${result.error.message}`)
+        return result.value
+      })
     })
     const inputTriggers = ctx.get('inputTriggers')
     if (inputTriggers === undefined) throw new Error('ui-commands: slash service unavailable')
diff --git a/packages/client/ui-commands/tests/browser-plugin.client.spec.ts b/packages/client/ui-commands/tests/browser-plugin.client.spec.ts
index a53a161b14..7adee98b3e 100644
--- a/packages/client/ui-commands/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-commands/tests/browser-plugin.client.spec.ts
@@ -8,7 +8,7 @@
  */
 import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it, onTestFinished } from 'vitest'
-import { createScope, scopeOf } from '@deepseek-ai/dsh-api-session-controller/client'
+import { TestSessions } from '@deepseek-ai/dsh-client-test-runtime'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
@@ -28,21 +28,16 @@ async function bench() {
       return () => { sources.delete(`${src.trigger} ${src.name}`) }
     },
   })
-  const scopes = new Map<SessionId, Context>()
-  const bindings = new Map<SessionId, {
-    readonly sessionId: SessionId
-    readonly session: { readonly sessionId: SessionId }
-    readonly ctx: Context
-  }>()
-  ctx.provide('sessions', {
-    scope: (id: SessionId) => scopes.get(id),
-    scopeOf: (c: Context) => scopeOf(c),
-    sessionOf: (c: Context) => bindings.get(scopeOf(c)!)?.session,
-    binding: (id: SessionId) => bindings.get(id),
-    subagentAddress: (id: SessionId) => id === sid('child')
-      ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
-      : undefined,
+  const sessions = new TestSessions(async (action) => { await action() }, ctx)
+  onTestFinished(async () => {
+    await sessions.disposeScopes()
+    await ctx.fiber.dispose()
   })
+  ctx.provide('sessions', sessions)
+  await sessions.add({ id: 's1' })
+  await sessions.add({ id: 'child' })
+  sessions.retainFor(ctx, sid('s1'))
+  sessions.retainFor(ctx, { parentSessionId: sid('parent'), childSessionId: sid('child'), mode: 'continuable' })
   const commandsRemote = { list: () => Promise.resolve({ ok: true as const, value: [] }) }
   // The service subscribes its cache-invalidation events on construction, so
   // the Remote face needs `$on` even where this spec dispatches none.
@@ -57,10 +52,8 @@ async function bench() {
   await fiber.await()
   const mint = (key: string) => {
     const id = sid(key)
-    const handle = createScope(ctx, id)
-    scopes.set(id, handle.ctx)
-    bindings.set(id, { sessionId: id, session: { sessionId: id }, ctx: handle.ctx })
-    return handle
+    const binding = sessions.binding(id) ?? sessions.retainFor(ctx, id).binding
+    return { ctx: binding.ctx, fiber: binding.ctx.fiber }
   }
   return { ctx, fiber, sources, slots: ctx.slots, mint }
 }
diff --git a/packages/client/ui-commands/tests/service.client.spec.ts b/packages/client/ui-commands/tests/service.client.spec.ts
index f49ea80052..fcde326c59 100644
--- a/packages/client/ui-commands/tests/service.client.spec.ts
+++ b/packages/client/ui-commands/tests/service.client.spec.ts
@@ -1,6 +1,6 @@
 /**
  * CommandUiRuntime tests on a real cordis Context with fake slash/connection
- * faces and real session scopes (createScope): session-keyed candidate
+ * faces and retained TestSessions: session-keyed candidate
  * synthesis (host catalog by sessionId + contributions by availability,
  * collision fail-loud), the dispatch decision table cell by cell, matchSpace
  * hot-key policy, matchEnter strong-wait / reject, the sessionId execute
@@ -11,9 +11,10 @@ import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import type { CommandResult } from '@deepseek-ai/dsh-commands/types'
 import { CommandDefinitionId } from '@deepseek-ai/dsh-commands/brand'
-import { createScope, scopeOf } from '@deepseek-ai/dsh-api-session-controller/client'
+import { scopeOf } from '@deepseek-ai/dsh-api-session-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
+import { RemoteError, TestRemote, TestSessions } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionFixture } from '@deepseek-ai/dsh-client-test-runtime'
 import { IconGoalOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ClientSessionContext, ConsumeTokenRequest, InputTriggerPick, InputTriggerSource, SubmitAttachment } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
 import type { CommandContribution, CommandDecoration, PopupSelectSpec, SelectOption } from '../src/client/contract.ts'
@@ -44,6 +45,8 @@ interface BenchOptions {
   execute?: (payload: { sessionId: SessionId; line: string }) => Promise<ExecuteValue>
   translate?: (namespace: string, key: string, params?: Record<string, unknown>) => string
   addressed?: SessionId
+  initialOpen?: SessionFixture['initialOpen']
+  snapshot?: SessionFixture['snapshot']
 }
 
 /**
@@ -105,18 +108,30 @@ async function bench(opts: BenchOptions = {}) {
       opts.translate?.(ns, key, params)
       ?? `${ns}:${key}${params === undefined ? '' : JSON.stringify(params)}`,
   })
-  // Real scope tags behind a fake sessions face.
-  const scopes = new Map<SessionId, { ctx: Context; fiber: { dispose(): Promise<void> } }>()
-  const bindings = new Map<SessionId, { sessionId: SessionId; session: { sessionId: SessionId }; ctx: Context }>()
-  const removeSessions = ctx.provide('sessions', {
-    scope: (id: SessionId) => scopes.get(id)?.ctx,
-    scopeOf: (c: Context) => scopeOf(c),
-    sessionOf: (scopeCtx: Context) => [...bindings.values()].find(binding => binding.ctx === scopeCtx)?.session,
-    binding: (id: SessionId) => bindings.get(id),
-    subagentAddress: (id: SessionId) => id === opts.addressed
-      ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
-      : undefined,
+  const sessions = new TestSessions(async (action) => { await action() }, ctx)
+  onTestFinished(async () => {
+    await sessions.disposeScopes()
+    await ctx.fiber.dispose()
   })
+  const removeSessions = ctx.provide('sessions', sessions)
+  for (const id of new Set(['s1', 's2', 'other', 'ghost', ...opts.addressed === undefined ? [] : [opts.addressed]])) {
+    await sessions.add({
+      id,
+      ...opts.initialOpen === undefined ? {} : { initialOpen: opts.initialOpen },
+      ...opts.snapshot === undefined ? {} : { snapshot: opts.snapshot },
+    })
+  }
+  const mint = (key: string) => {
+    const id = sid(key)
+    const target = id === opts.addressed
+      ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
+      : id
+    const binding = sessions.binding(id) ?? sessions.retainFor(ctx, target).binding
+    return { ctx: binding.ctx, fiber: binding.ctx.fiber }
+  }
+  mint('s1')
+  mint('s2')
+  if (opts.addressed !== undefined) mint(opts.addressed)
   const remote = Object.assign(new TestRemote(ctx), { commands: commandsRemote })
   ctx.provide('remote.commands', commandsRemote)
   const executions: Array<{ sessionId: SessionId; name: string; result: CommandResult }> = []
@@ -142,24 +157,13 @@ async function bench(opts: BenchOptions = {}) {
   const command = ctx.get('commandUi') as CommandUiRuntime
   const source = registered.get('/ command')
   if (source === undefined) throw new Error('command source not registered')
-  const mint = (key: string) => {
-    const id = sid(key)
-    const handle = createScope(ctx, id)
-    const binding = { sessionId: id, session: { sessionId: id }, ctx: handle.ctx }
-    scopes.set(id, handle)
-    bindings.set(id, binding)
-    handle.ctx.effect(() => () => {
-      if (bindings.get(id) === binding) bindings.delete(id)
-    })
-    return handle
-  }
   /** Warm one session's catalog through the source's own candidate pull. */
   const warm = async (session: ClientSessionContext) => {
     await source.candidates(session, { query: '', position: 'leading', drilled: false, signal: new AbortController().signal })
   }
   return {
     ctx, fiber, command, source, mint, warm, listCalls, executeCalls, executions, registered, notices, focuses, remote,
-    removeSessions, removeConversation,
+    removeSessions, removeConversation, sessions,
   }
 }
 
@@ -215,15 +219,51 @@ describe('registration', () => {
   it('the warm hook prewarms the session key: one pull per session, no duplicate over pending', async () => {
     const { source, listCalls } = await bench()
     source.warm!(proj('s1'))
-    expect(listCalls).toEqual([{ sessionId: sid('s1') }])
+    await vi.waitFor(() => { expect(listCalls).toEqual([{ sessionId: sid('s1') }]) })
     source.warm!(proj('s2'))
-    expect(listCalls).toEqual([{ sessionId: sid('s1') }, { sessionId: sid('s2') }])
+    await vi.waitFor(() => { expect(listCalls).toEqual([{ sessionId: sid('s1') }, { sessionId: sid('s2') }]) })
     source.warm!(proj('s1')) // s1 already pending → no duplicate pull
     expect(listCalls).toHaveLength(2)
   })
 })
 
 describe('candidates', () => {
+  it('waits for initial history and retains the Session until the catalog RPC settles', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const response = Promise.withResolvers<{ commands: CommandDescriptor[] }>()
+    const b = await bench({ initialOpen: () => opened.promise, commands: () => response.promise })
+    try {
+      const pending = b.source.candidates(proj('s1'), req(''))
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().retainedBy.commandCatalog).toBe(1)
+      expect(b.listCalls).toEqual([])
+      opened.resolve(undefined)
+      await vi.waitFor(() => { expect(b.listCalls).toHaveLength(1) })
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(2)
+      response.resolve({ commands: S1_CMDS })
+      await pending
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      opened.resolve(undefined)
+      response.resolve({ commands: S1_CMDS })
+    }
+  })
+
+  it.each([true, false])('refuses an unsuccessful history open (reported error: %s)', async (reported) => {
+    const error = new RemoteError('gateway/internal', 'history unavailable', {})
+    const b = await bench({ snapshot: { openState: 'error', openError: reported ? error : null } })
+    await expect(b.source.candidates(proj('s1'), req(''))).rejects.toThrow(reported ? 'history unavailable' : 'is not open')
+    expect(b.listCalls).toEqual([])
+    expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+  })
+
+  it('does not reopen a Session released before catalog lookup', async () => {
+    const b = await bench()
+    await b.mint('s1').fiber.dispose()
+    await expect(b.source.candidates(proj('s1'), req(''))).rejects.toThrow('requires a retained session')
+    expect(b.sessions.binding(sid('s1'))).toBeUndefined()
+    expect(b.listCalls).toEqual([])
+  })
+
   it('does not fetch Agent-bound commands for an addressed child', async () => {
     const b = await bench({ addressed: sid('child') })
     await expect(b.warm(proj('child'))).resolves.toBeUndefined()
@@ -677,6 +717,7 @@ describe('matchEnter (enter column)', () => {
       commands: () => new Promise((resolve) => { release = resolve }),
     })
     const wait = source.matchEnter!(proj('s1'), '/goal args', signal(), { attachments: 0 })
+    await vi.waitFor(() => { expect(release).toBeTypeOf('function') })
     release({ commands: S1_CMDS })
     const outcome = await wait
     if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected claim')
@@ -906,10 +947,12 @@ describe('detached admission notices', () => {
   })
 
   it('a torn-down scope drops the failure notice', async () => {
-    const { source, warm, notices } = await bench({
+    const { source, warm, notices, mint } = await bench({
       execute: () => Promise.reject(new Error('orphan failure')),
     })
-    await warm(proj('ghost')) // never minted: scopeFor misses
+    const scope = mint('ghost')
+    await warm(proj('ghost'))
+    await scope.fiber.dispose()
     menuPick(source, 'plan', proj('ghost'))
     await flush()
     expect(notices).toEqual([])
@@ -1122,6 +1165,7 @@ describe('directory invalidation events', () => {
     ctx.emit('connection/reset')
     // Hard reset: silent until the rewarm lands.
     expect(source.matchSpace!(proj('s2'), '/attach')).toBeUndefined()
+    await vi.waitFor(() => { expect(release).toBeTypeOf('function') })
     release({ commands: S2_CMDS })
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(source.matchSpace!(proj('s2'), '/attach')).not.toBeUndefined()
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 74cd3168df..2f52a3e505 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: fef3a6551b517af2ac636687883864525aac70ee
-README.zh.md: e9ab08c686420c38c11ca2bede2fd00099a247a5
+README.md: 31b35ef7460c9fecd119e32ae5f696f55585a726
+README.zh.md: 1fb648bf9539cebc307e094c2fe46b1d1749edab
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index fef3a6551b..31b35ef746 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -40,7 +40,7 @@ The shared image slot props keep display choices separate from durable reference
 
 The context-occupancy button shows a ring and percentage below the input card, after the Session statistics. Clicking it opens the token breakdown in a panel kept inside the viewport, including when no statistics are shown; the button stays hidden until context usage and capacity are available.
 
-With Developer tools off, the shell exposes only Chat and hides the View tab bar. Turning it off while another View is active returns to Chat; stored View preferences and recorded Session data remain intact. Turning it on makes registered Views available again. View owners receive the available roster so their navigation actions can follow the same visibility.
+With Developer tools off, the shell hides only Trajectory; other plugin-contributed Views remain available. The View tab bar is hidden when fewer than two Views are available. Turning Developer tools off while Trajectory is active returns to Chat; stored View preferences and recorded Session data remain intact. Turning it on makes Trajectory available again. View owners receive the available roster so their navigation actions can follow the same visibility.
 
 The composer registers the File command action and owns its label, availability, and native file-dialog callback. Menu availability and invocation both consult the mounted composer's current attachment-intake policy. Unmounting or locking the composer disables that action; disposing the plugin removes its registration. The callback binding stays inside the input module.
 
@@ -62,7 +62,7 @@ Active transcripts in the main occurrence expose content-width drag handles in t
 
 The resident composer survives no-Session and Session transitions. Whitespace hides its placeholder; a whitespace-only draft without attachments cannot be sent. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. QueueDock reads `next-turn` directly from the Session `inbox` projection, including cold recovered messages. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label) and show local or durable images and files in original attachment order. Images use thumbnails; files use compact name-and-size cards. An edit exposes the literal sent text, and durable thumbnails resolve through the session image URL cache. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. The composer keymap arbitrates the trigger menu's keys through the slash pipeline — Tab settles the highlighted completion (or drills a drillable one), Escape and Shift+Tab leave the menu without settling — and leaves every other key to the editor. An overlay that takes the keyboard hands it back through `SessionInput.focus()`, which rides Lexical's own focus so the caret returns where the draft left it rather than at the start.
 
-Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) with the delivery mode before serializing, preserving selected image and file order in `pendingSubmissions`; Session derives the placement from that mode and its current running state, so idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint, encodes images through the browser's native `FileReader` data-URL path, and cites staged file receipts. Command submissions use the same receipts for generic files, so sending `/goal` or `/plan` never reads those browser files again. The prompt reuses the submission `requestId`; queue and history observation by that `rpcId` retires the echo once. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their attachment ids through admission and Session scope disposal. An observed retirement immediately exposes each image preview through the durable cache, replaces it with the canonical URL after fetching the admitted attachment, revokes each URL after its use ends, and releases file cards. Selected generic files enter one FIFO background-upload queue; `maxConcurrentFileUploads` defaults to two active Worker transports, the Conversation service retains queued and active operations plus byte progress across Session navigation, and removing a draft skips its queued transfer or aborts its active transport. Continuable subagents disable attachment intake and skip local echoes because their transport does not preserve the browser request id.
+Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) with the delivery mode before serializing, preserving selected image and file order in `pendingSubmissions`; Session derives the placement from that mode and its current running state, so idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint, encodes images through the browser's native `FileReader` data-URL path, and cites staged file receipts. Command submissions use the same receipts for generic files, so sending `/goal` or `/plan` never reads those browser files again. The prompt reuses the submission `requestId`; queue and history observation by that `rpcId` retires the echo once. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their attachment ids through admission and Session scope disposal. An observed retirement immediately exposes each image preview through the durable cache, replaces it with the canonical URL after fetching the admitted attachment, revokes each URL after its use ends, and releases file cards. Selected generic files enter one FIFO background-upload queue; `maxConcurrentFileUploads` defaults to two active Worker transports, the Conversation service retains queued and active operations plus byte progress across Session navigation, and removing a draft skips its queued transfer or aborts its active transport. Where the browser shell exposes `__DSH_HOST_PATHS__` (the Desktop application), dropped or pasted folders and dropped, picked, or pasted non-image files with a real path become `@path` chips; images keep uploading. Drag-and-drop and paste identify directories through the browser entry API; when that API is absent or returns no entry, pasted items retain ordinary file handling. The file picker cannot select directories. References require the `ui-reference` plugin and the original paths to remain readable by the model's file tools. Paths inside the workspace are relative; others remain absolute. The whole batch is validated before insertion, retains source order and selected text, and uses whitespace-separated, closed-quote mentions. A browser without the bridge refuses dropped or pasted folders; a Desktop folder without a reported path is rejected separately. Continuable subagents disable attachment intake and skip local echoes because their transport does not preserve the browser request id.
 
 Queued submission echoes show “Sending…” beside disabled edit, remove, and steer buttons; a collapsed dock keeps the sending status in its header. A matching Host queue row replaces the echo and enables each action according to its normal text-content and running-state requirements. Prompt acknowledgement alone does not enable queue actions. A failed submission removes its echo and displays an error; the composer restores the failed draft when it is empty or still contains the previous automatic restoration, preserving subsequently typed text.
 
@@ -120,6 +120,10 @@ try {
 
 The selector must be a pure function of the owner currency. Its non-null return is delivered to the component as `matched`; `PropsRuntime<'conversation.composer'>` supplies the standard Session and global props. Chain order remains ascending `priority`, then registration order, and the first non-null selector wins. The shell keeps the default composer mounted beneath a takeover. Request state, listeners, response encoding, and any request-specific child slots belong to the business package; they are not carried by `SessionSnapshot` or declared by this core package.
 
+`InputActions.captureInsertion()` captures the draft selection and revision; `insertText(text, span)` inserts one undoable plain-text edit only while that revision is current and the editor permits editing. Asynchronous consumers retain rejected results for user action.
+
+`conversation.input.activity` hosts one control between the model selector and Send. Its `onActiveChange` callback expands that control across the toolbar and hides ordinary accessory controls and the context meter while preserving the editor and submit action. Closing the activity restores those controls with context details closed. The empty hero dock remains collapsed when it has no content. The occupant releases expansion on unmount and owns any activity-specific feedback.
+
 <a id="model-experience"></a>
 ## Model Experience
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index e9ab08c686..1fb648bf95 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -40,7 +40,7 @@ target package 通过 declaration merge 扩展 snapshot 与 Location data map，
 
 上下文占用按钮在输入卡片下方、会话统计右侧显示圆环和百分比。点击按钮可在视口内的面板查看 token 构成，没有统计项时面板也不会越界；上下文用量和容量尚不可用时，按钮保持隐藏。
 
-关闭开发者工具时，外壳仅展示 Chat 并隐藏 View 标签栏。在其他 View 激活时关闭开关会返回 Chat；已保存的 View 偏好和 Session 记录保持不变。开启后，已注册的 View 恢复可用。View 所有者接收可用列表，使导航操作跟随相同的可见性。
+关闭开发者工具时，外壳仅隐藏 Trajectory；其他插件贡献的 View 仍然可用。可用 View 少于两个时隐藏 View 标签栏。在 Trajectory 激活时关闭开发者工具会返回 Chat；已保存的 View 偏好和 Session 记录保持不变。开启后，Trajectory 恢复可用。View 所有者接收可用列表，使导航操作跟随相同的可见性。
 
 输入框注册「文件」命令动作，负责其标题、可用性和原生文件选择器回调。菜单可用性与实际调用都读取已挂载输入框当前的附件接收策略。输入框卸载或锁定后该动作不可用，插件 dispose（资源释放）时移除注册。回调绑定留在输入模块内部。
 
@@ -62,7 +62,7 @@ Session 首次绑定或缓存的 Session 成为 current 时，shell 会在渲染
 
 常驻 composer 在无 Session 与有 Session 之间保持挂载。输入空白字符会隐藏占位提示；没有附件的纯空白草稿无法发送。无 Session 时，同一个编辑器表面保持 inert，Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器：引用 chip 是携带 owner 序列化身份的原子 decorator 节点（提交时经 owner codec 展开），已认领的 slash command 保持为带样式的行首文本，文件夹文本引用以图标前缀携带文件夹图形，草稿的剪贴板投影镜像到逐 Session Conversation store。QueueDock 直接从 Session 的 `inbox` 投影读取 `next-turn`，包含从冷状态恢复的消息。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence；queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本（wire 会话形式折叠为其标签），并按原始附件顺序展示本地或持久化的图片和文件。图片使用缩略图，文件使用紧凑的名称与大小卡片。编辑态展示字面发送文本，持久化缩略图通过会话图片 URL 缓存解析。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 composer 键盘映射经斜杠流水线裁决触发菜单的按键——Tab 确认高亮补全项（可下钻项则下钻），Escape 与 Shift+Tab 离开菜单且不选定——其余按键交给编辑器自身。 接管键盘的浮层通过 `SessionInput.focus()` 把键盘还回来，该路径走 Lexical 自己的 focus，因此光标回到草稿原来的位置而不是开头。
 
-默认发送采用乐观提交：Enter 在同一事务里清空草稿、occurrence 表和撤销历史，composer 保持 `plain`，发送作为 detached attempt 运行，发送期间可以继续输入和提交。`sendSession` 在序列化之前用投递模式注册 Session 提交回显（`session.beginSubmission`），并在 `pendingSubmissions` 中保留图片与文件的选择顺序；Session 根据该模式与当前运行状态推导位置，因此空闲发送进入 transcript（文本记录），繁忙时 Queue 进入 QueueDock，繁忙时 Steer 进入 pending-steering 区域。随后让出一帧，图片经浏览器原生 `FileReader` data-URL 路径编码，文件则引用已暂存凭证。命令提交也用同一凭证表示通用文件，因此发送 `/goal` 或 `/plan` 时不会再次读取这些浏览器文件。提示词复用提交 `requestId`；queue 或历史以同一 `rpcId` 被观察后，回显只退休一次。多个并发发送失败时，在用户编辑还原内容之前按提交顺序合并还原；命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有附件 id，直到 admission 完成或 Session scope 销毁。回显以 observed 退休时，durable 图片缓存立即公开每个预览 URL，读取 admitted 附件后用规范化 URL 替换预览，并在各 URL 停止使用后撤销，同时释放文件卡。选中的通用文件进入同一个先进先出的后台上传队列；`maxConcurrentFileUploads` 默认允许两个 Worker transport 同时运行，Conversation 服务在切换 Session 时继续持有排队和运行中的传输操作及字节进度，移除草稿会跳过排队中的传输或中止正在运行的传输。continuable 子代理禁用附件入口，也不创建本地回显，因为其 transport 不保留浏览器 request id。
+默认发送采用乐观提交：Enter 在同一事务里清空草稿、occurrence 表和撤销历史，composer 保持 `plain`，发送作为 detached attempt 运行，发送期间可以继续输入和提交。`sendSession` 在序列化之前用投递模式注册 Session 提交回显（`session.beginSubmission`），并在 `pendingSubmissions` 中保留图片与文件的选择顺序；Session 根据该模式与当前运行状态推导位置，因此空闲发送进入 transcript（文本记录），繁忙时 Queue 进入 QueueDock，繁忙时 Steer 进入 pending-steering 区域。随后让出一帧，图片经浏览器原生 `FileReader` data-URL 路径编码，文件则引用已暂存凭证。命令提交也用同一凭证表示通用文件，因此发送 `/goal` 或 `/plan` 时不会再次读取这些浏览器文件。提示词复用提交 `requestId`；queue 或历史以同一 `rpcId` 被观察后，回显只退休一次。多个并发发送失败时，在用户编辑还原内容之前按提交顺序合并还原；命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有附件 id，直到 admission 完成或 Session scope 销毁。回显以 observed 退休时，durable 图片缓存立即公开每个预览 URL，读取 admitted 附件后用规范化 URL 替换预览，并在各 URL 停止使用后撤销，同时释放文件卡。选中的通用文件进入同一个先进先出的后台上传队列；`maxConcurrentFileUploads` 默认允许两个 Worker transport 同时运行，Conversation 服务在切换 Session 时继续持有排队和运行中的传输操作及字节进度，移除草稿会跳过排队中的传输或中止正在运行的传输。浏览器 shell 暴露 `__DSH_HOST_PATHS__` 时（桌面应用），拖入或粘贴的文件夹以及拖入、选择或粘贴的带真实路径的非图片文件会成为 `@路径` chip；图片仍然上传。拖放和粘贴通过浏览器 entry API 识别目录；该 API 不可用或没有返回 entry 时，粘贴项沿用普通文件处理。文件选择器不能选择目录。引用需要启用 `ui-reference` 插件，原路径也必须仍可由模型的文件工具读取。工作区内的路径使用相对形式，其他路径保留绝对形式。整批文件先校验再插入，保留来源顺序和已选中的文字，引用之间有空白分隔，含空格的路径使用闭合引号。没有该桥的浏览器会拒绝拖入或粘贴的文件夹，桌面端无法获取文件夹路径时单独报错。continuable 子代理禁用附件入口，也不创建本地回显，因为其 transport 不保留浏览器 request id。
 
 排队提交的本地回显在禁用的编辑、删除、插话按钮旁显示“发送中…”；折叠后的队列在标题栏保留发送状态。匹配的 Host 队列行替换回显后，各操作按原有的纯文本内容和运行状态要求启用。仅收到提示词确认不会启用队列操作。提交失败会移除回显并显示错误；输入框为空或仍保留上一次自动恢复的内容时，composer 恢复失败草稿，保留用户随后输入的文字。
 
@@ -120,6 +120,10 @@ try {
 
 selector 必须是 owner currency 的纯函数。非 null 返回值作为 `matched` 传给组件；`PropsRuntime<'conversation.composer'>` 提供标准 Session 与 global props。Chain 顺序仍按 `priority` 升序，再按注册顺序；首个返回非 null 的 selector 获选。Shell 会在 takeover 下保持默认 composer 挂载。Request 状态、listener、response encoding 和任何 request-specific child slot 都属于业务 package，不进入 `SessionSnapshot`，也不由 core 包声明。
 
+`InputActions.captureInsertion()` 捕获草稿选区与版本；`insertText(text, span)` 仅在版本未变且编辑器允许编辑时，插入一次可撤销的纯文本编辑。异步消费者在插入被拒绝后负责保留结果，等待用户操作。
+
+`conversation.input.activity` 在模型选择器与发送按钮之间承载一个控件。其 `onActiveChange` 回调将控件展开至整条工具栏并隐藏普通辅助控件和上下文用量按钮，同时保留编辑器与提交按钮。关闭活动后恢复这些控件，上下文详情保持关闭。首页输入框下方没有内容时，该区域保持收起。占用者在卸载时释放展开状态，并拥有活动专属反馈。
+
 <a id="model-experience"></a>
 ## 模型体验
 
diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json
index 8a92b63714..e5b6bcdf2b 100644
--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -80,6 +80,7 @@
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-util-crypto": "workspace:^",
     "@deepseek-ai/dsh-workspace": "workspace:^",
+    "@deepseek-ai/dsh-file-reference": "workspace:^",
     "@deepseek-ai/dsh-util-workspace-path": "workspace:^",
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 3fef945990..760f7ac07b 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -18,8 +18,11 @@ import type {
   ConversationSessionInjected, DraftFileUploads,
 } from './contract/slots.ts'
 import type { InputNotice } from './contract/input.ts'
+import type { ReferenceInsert } from './contract/draft-editor.ts'
 import { createConversationStore, readConversationViewPreference } from './stores.ts'
-import { ConversationController, UnsupportedImageMediaTypeError } from './service.ts'
+import { formatFileMention } from '@deepseek-ai/dsh-file-reference/grammar'
+import { relativizeToCwd, workspaceTitleOf } from '@deepseek-ai/dsh-util-workspace-path'
+import { ConversationController, UnsupportedImageMediaTypeError, isImageMediaType } from './service.ts'
 import type { IConversation } from './service.ts'
 import { ComposerBlockRegistry } from './input/blocks.ts'
 import type { ComposerBlock } from './contract/composer-blocks.ts'
@@ -35,7 +38,7 @@ import { ConversationHeader } from './skeleton/ConversationHeader.tsx'
 import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { InputBar } from './skeleton/InputBar.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
-import { DEFAULT_VIEW_ID, resolveActiveView } from './view-selection.ts'
+import { DEVELOPER_TOOLS_VIEW_ID, resolveActiveView } from './view-selection.ts'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
 import { CONVERSATION_SETTINGS_NAMESPACE, type ConversationSettings } from '../submission-settings.ts'
 
@@ -87,6 +90,21 @@ const ABSENT_FILE_UPLOADS = {
   subscribe: () => () => {},
 }
 
+/**
+ * Browser-shell bridge reporting the harness-host path of a picked file. The
+ * Desktop preload exposes it on the application document; a served Web page
+ * has none, so every non-image file uploads there.
+ */
+interface HostPathBridge {
+  /** Absolute harness-host path of one picked file, or empty when the shell has none for it. */
+  pathFor(file: File): string
+}
+
+/** The shell-installed bridge, when this document runs inside the Desktop application. */
+function hostPathBridge(): HostPathBridge | undefined {
+  return (globalThis as { __DSH_HOST_PATHS__?: HostPathBridge }).__DSH_HOST_PATHS__
+}
+
 interface WorkspaceNavigation {
   openSession(sessionId: SessionId): void
   openWorkspace(
@@ -159,7 +177,7 @@ export function apply(ctx: Context, config: Config = Config({})): void {
     for (const entry of slots.entries('conversation.view')) {
       /* v8 ignore next -- list registration validates id at load. */
       if (entry.options.id === undefined) continue
-      if (!ctx.settingsScope.developerTools.enabled.getSnapshot() && entry.options.id !== DEFAULT_VIEW_ID) continue
+      if (!ctx.settingsScope.developerTools.enabled.getSnapshot() && entry.options.id === DEVELOPER_TOOLS_VIEW_ID) continue
       tabs.push({
         id: entry.options.id,
         label: resolveSlotLabel(entry.options.label) ?? entry.options.id,
@@ -368,6 +386,7 @@ export function apply(ctx: Context, config: Config = Config({})): void {
       'conversation.input.plan': { kind: 'single', scope: 'session' },
       'conversation.input.right': { kind: 'list', scope: 'session' },
       'conversation.input.model': { kind: 'single', scope: 'session' },
+      'conversation.input.activity': { kind: 'single', scope: 'session' },
       'conversation.composer.dock': { kind: 'list', scope: 'session' },
     },
     inject: (sessionId: SessionId | undefined): ComposerBarInjected => {
@@ -392,14 +411,41 @@ export function apply(ctx: Context, config: Config = Config({})): void {
       const conversation = concreteConversation(ctx)
       const shell = inputHub.shell(sessionId)
       const inputTriggers = inputHub.inputTriggers(sessionId)
+      const bridge = hostPathBridge()
       return {
         keyboard: shell,
-        addFiles: (files) => {
+        addFiles: (files, directories = new Set()) => {
           if (sessions.binding(sessionId) === undefined) return t('file.sessionUnavailable')
+          if (shell.snapshot.phase === 'adjudicating' || shell.snapshot.phase === 'submitting') {
+            return t('attachment.dropBlocked')
+          }
+          const uploads: File[] = []
+          const references: ReferenceInsert[] = []
+          const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd
+          for (const file of files) {
+            const directory = directories.has(file)
+            if (bridge === undefined && directory) return t('attachment.directoryDesktopOnly')
+            const path = bridge?.pathFor(file) ?? ''
+            if (directory && path === '') return t('attachment.pathUnavailable')
+            if (path === '' || (!directory && isImageMediaType(file.type))) {
+              uploads.push(file)
+              continue
+            }
+            const relative = relativizeToCwd(path, cwd)
+            // A completed directory chip needs closed quotes; the directory grammar keeps them open for drill.
+            const mention = formatFileMention({ path: directory ? `${relative}/` : relative, kind: 'file' }, false)
+            if (mention === undefined) return t('attachment.pathUnsupported')
+            const label = workspaceTitleOf(path) || file.name
+            references.push({
+              source: 'reference', ref: mention, label: directory ? `${label}/` : label,
+              appearance: directory ? 'folder' : 'file', clipboardText: mention,
+            })
+          }
           try {
-            const drafts = conversation.createDrafts(sessionId, files)
-            if (!shell.addAttachments(drafts.map(draft => draft.id))) {
+            const drafts = conversation.createDrafts(sessionId, uploads)
+            if (!shell.addFiles(references, drafts.map(draft => draft.id))) {
               conversation.releaseDraftAttachments(drafts)
+              return t('attachment.dropBlocked')
             }
             return null
           } catch (error: unknown) {
diff --git a/packages/client/ui-conversation/src/client/contract/input.ts b/packages/client/ui-conversation/src/client/contract/input.ts
index b4cd6b9bdf..4036736374 100644
--- a/packages/client/ui-conversation/src/client/contract/input.ts
+++ b/packages/client/ui-conversation/src/client/contract/input.ts
@@ -220,6 +220,15 @@ export interface SessionInputResolver {
  * paste/…) stay InputBar-private and never ride this face.
  */
 export interface InputActions {
+  /** @returns a revision-guarded copy of the current editor selection. */
+  captureInsertion(): TokenSpan
+  /**
+   * Insert asynchronous text without replacing subsequent edits or reference chips.
+   * @param text - plain text to insert in one undo step.
+   * @param span - captured selection and draft revision.
+   * @returns false when the draft changed or submission locked the editor.
+   */
+  insertText(text: string, span: TokenSpan): boolean
   /** Replace the whole draft (persisted-draft seed and programmatic writes). */
   setDraft(text: string): void
   /** Append ordered browser-owned attachment ids; busy admission phases refuse. */
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index 023babf26e..00f8db03b8 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -60,8 +60,12 @@ export interface ComposerAttachmentsOwnerProps {
   attachments: readonly ComposerAttachment[]
   /** Whether a document-level file drop may add attachments now. */
   canAcceptDrop: boolean
-  /** Add one dropped batch through the composer's validation path. */
-  onAddFiles: (files: readonly File[]) => void
+  /**
+   * Add one dropped batch through the composer's validation path.
+   * @param files - dropped, pasted, or picked browser files in source order.
+   * @param directories - members of `files` the drop source identified as directories.
+   */
+  onAddFiles: (files: readonly File[], directories?: ReadonlySet<File>) => void
   /** Remove one draft attachment through the Conversation service. */
   onRemoveAttachment: (id: DraftAttachmentId) => void
   /** Current per-draft upload states for file-kind attachments. */
@@ -197,6 +201,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
     'conversation.input.left': { kind: 'list'; scope: 'session' }
     /** Compact controls before the composer submit action. */
     'conversation.input.right': { kind: 'list'; scope: 'session' }
+    /** Compact action after the model selector; it can expand across the toolbar while retaining the editor and submit action. */
+    'conversation.input.activity': { kind: 'single'; scope: 'session'; owner: InputActivityOwnerProps }
     /** Resident composer body, including the no-Session inert state. */
     'conversation.composer.bar': { kind: 'single'; scope: 'session-maybe'; owner: ComposerBarOwnerProps }
     /** Optional draft-attachment rail and drop target. */
@@ -366,7 +372,14 @@ export interface ComposerBarOwnerProps {
 /** Package-private operations injected into the resident composer bar. */
 export interface ComposerBarInjected {
   keyboard: ComposerKeyboard | undefined
-  addFiles: ((files: readonly File[]) => string | null) | undefined
+  /**
+   * Register one picked batch; resolves to the rejection copy or null. Where
+   * the browser shell reports host paths (the Desktop application), files
+   * and folders with a real path become `@path` references in the draft
+   * instead of uploads; `directories` names the members the drop source
+   * identified as directories.
+   */
+  addFiles: ((files: readonly File[], directories?: ReadonlySet<File>) => string | null) | undefined
   removeAttachment: ((id: DraftAttachmentId) => void) | undefined
   resolveDraftAttachments: ((ids: readonly DraftAttachmentId[]) => readonly ComposerAttachment[]) | undefined
   /** Restart one failed file upload; absent without a session. */
@@ -393,6 +406,12 @@ export interface InputControlOwnerProps {
   locked: boolean
 }
 
+/** A toolbar activity hides ordinary accessory controls while expanded; its occupant must release expansion on unmount. */
+export interface InputActivityOwnerProps extends InputControlOwnerProps {
+  /** @param active - whether the occupant needs the toolbar width before the submit action. */
+  onActiveChange: (active: boolean) => void
+}
+
 /** Full props of the resident composer bar. */
 export type ComposerBarProps =
   PropsRuntime<'conversation.composer.bar'>
@@ -400,7 +419,7 @@ export type ComposerBarProps =
     | 'conversation.input.attachments' | 'conversation.input.overlay'
     | 'conversation.input.permission'
     | 'conversation.input.left' | 'conversation.input.plan'
-    | 'conversation.input.right' | 'conversation.input.model'
+    | 'conversation.input.right' | 'conversation.input.model' | 'conversation.input.activity'
     | 'conversation.composer.dock'
   >
   & InjectFace<ComposerBarInjected>
diff --git a/packages/client/ui-conversation/src/client/input/editor/keymap.ts b/packages/client/ui-conversation/src/client/input/editor/keymap.ts
index 42c217caa0..7291f2c25a 100644
--- a/packages/client/ui-conversation/src/client/input/editor/keymap.ts
+++ b/packages/client/ui-conversation/src/client/input/editor/keymap.ts
@@ -34,8 +34,12 @@ export interface ComposerKeymapHandlers {
   canSubmit(): boolean
   /** The Enter gesture after every guard passed; `accelerated` = Ctrl/Cmd held. */
   submit(accelerated: boolean): void
-  /** Pasted files (image intake). */
-  intakeFiles(files: readonly File[]): void
+  /**
+   * Pasted files with directory metadata supplied by the clipboard entry API.
+   * @param files - browser files in clipboard order.
+   * @param directories - known directory members; absent when no entry identifies a directory.
+   */
+  intakeFiles(files: readonly File[], directories?: ReadonlySet<File>): void
   /** Pasted plain text (sanitized insertion through the shell). */
   pasteText(text: string): void
 }
@@ -154,11 +158,18 @@ export function registerComposerKeymap(editor: LexicalEditor, handlers: Composer
       // deliver clipboardData on plain events.
       const clipboardData = (event as ClipboardEvent).clipboardData ?? null
       if (clipboardData === null) return false
-      const files = Array.from(clipboardData.items)
-        .filter(item => item.kind === 'file')
-        .map(item => item.getAsFile())
-        .filter((file): file is File => file !== null)
-      if (files.length > 0) handlers.intakeFiles(files)
+      const files: File[] = []
+      const directories = new Set<File>()
+      for (const item of clipboardData.items) {
+        if (item.kind !== 'file') continue
+        const file = item.getAsFile()
+        if (file === null) continue
+        files.push(file)
+        if (typeof item.webkitGetAsEntry === 'function' && item.webkitGetAsEntry()?.isDirectory === true) {
+          directories.add(file)
+        }
+      }
+      if (files.length > 0) handlers.intakeFiles(files, directories.size === 0 ? undefined : directories)
       const text = clipboardData.getData('text/plain')
       if (text === '') {
         if (files.length === 0) return false
diff --git a/packages/client/ui-conversation/src/client/input/editor/runtime.ts b/packages/client/ui-conversation/src/client/input/editor/runtime.ts
index 2054624342..f59a6d947d 100644
--- a/packages/client/ui-conversation/src/client/input/editor/runtime.ts
+++ b/packages/client/ui-conversation/src/client/input/editor/runtime.ts
@@ -210,6 +210,19 @@ export class DraftEditorRuntime {
     return applied
   }
 
+  /**
+   * Insert an asynchronous text result as one independent undo operation.
+   * @param span - owner-validated insertion range.
+   * @param text - text sanitized with the same rules as paste.
+   * @returns whether the range mapped and the edit applied.
+   */
+  insertAsyncText(span: DetectSpan, text: string): boolean {
+    let applied = false
+    const clean = text.replace(REFERENCE_PLACEHOLDER_RE, '')
+    this.applyEdit(() => { applied = $replaceDetectSpanWithText(span, clean) }, PASTE_TAG)
+    return applied
+  }
+
   /**
    * Insert a reference chip with the existing trailing-space rule.
    * @param span - detect-coordinate range.
@@ -228,6 +241,25 @@ export class DraftEditorRuntime {
     return applied
   }
 
+  /**
+   * Insert an ordered file-reference batch after the live selection without deleting it.
+   * @param references - validated references in source order.
+   * @returns whether the live insertion position accepted the batch.
+   */
+  insertFileReferences(references: readonly ReferenceInsert[]): boolean {
+    if (references.length === 0) return true
+    let applied = false
+    this.applyEdit(() => {
+      const projection = $projectComposer(key => this.occurrenceIdOf(key))
+      const at = projection.selection?.end ?? projection.detectText.length
+      const before = projection.detectText.slice(0, at)
+      const nodes = references.flatMap(ref => [$createReferenceChipNode(ref), $createTextNode(' ')])
+      if (before !== '' && !/\s$/u.test(before)) nodes.unshift($createTextNode(' '))
+      applied = $replaceDetectSpanWithNodes({ start: at, end: at }, nodes)
+    }, PASTE_TAG)
+    return applied
+  }
+
   /** Refresh claim-token decoration after the model's claim changes. */
   refreshClaimDecoration(): void {
     refreshClaimDecoration(this.editor)
diff --git a/packages/client/ui-conversation/src/client/input/editor/view-binding.ts b/packages/client/ui-conversation/src/client/input/editor/view-binding.ts
index 8dcd3d8c63..89218a887c 100644
--- a/packages/client/ui-conversation/src/client/input/editor/view-binding.ts
+++ b/packages/client/ui-conversation/src/client/input/editor/view-binding.ts
@@ -14,7 +14,7 @@ interface DraftViewGate {
   running: boolean
   steeringAvailable: boolean
   busyEnter: BusyEnterBehavior
-  intakeFiles: (files: readonly File[]) => void
+  intakeFiles: (files: readonly File[], directories?: ReadonlySet<File>) => void
   uploadsPending: boolean
   showToast: (text: string) => void
   t: ComposerBarProps['t']
@@ -136,7 +136,7 @@ export function installDraftKeymap(
         g.steeringAvailable,
       ))
     },
-    intakeFiles: (files) => { gate.current.intakeFiles(files) },
+    intakeFiles: (files, directories) => { gate.current.intakeFiles(files, directories) },
     pasteText: (text) => {
       if (gate.current.machineBusy || gate.current.locked) return
       keyboard.paste(text)
diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts
index 4f4d0aa300..3cd956bf76 100644
--- a/packages/client/ui-conversation/src/client/input/facade.ts
+++ b/packages/client/ui-conversation/src/client/input/facade.ts
@@ -117,6 +117,12 @@ export class SessionInputShell implements SessionInput {
   }
   /** The public provide-channel action face (one stable identity per session). */
   readonly actions: InputActions = {
+    captureInsertion: () => ({ ...this.caretSpan(), draftRev: this.rev }),
+    insertText: (text, span) => {
+      if (this.snapshot.phase === 'adjudicating' || this.snapshot.phase === 'submitting' || this.disposed) return false
+      if (span.draftRev !== this.rev) return false
+      return this.draftEditor.insertAsyncText(span, text)
+    },
     setDraft: (text) => { this.setDraft(text) },
     addAttachments: ids => this.addAttachments(ids),
     removeAttachment: (id) => { this.removeAttachment(id) },
@@ -215,6 +221,20 @@ export class SessionInputShell implements SessionInput {
     return true
   }
 
+  /**
+   * Add validated file references and attachment ids while admission is editable.
+   * @param references - reference chips in source order.
+   * @param ids - newly allocated attachment ids.
+   * @returns false when admission is locked or the editor refuses the insertion.
+   */
+  addFiles(references: readonly ReferenceInsert[], ids: readonly DraftAttachmentId[]): boolean {
+    if (this.snapshot.phase === 'adjudicating' || this.snapshot.phase === 'submitting') return false
+    if (!this.draftEditor.insertFileReferences(references)) return false
+    this.attachmentIds = [...this.attachmentIds, ...ids]
+    this.publish()
+    return true
+  }
+
   /**
    * Remove one attachment id from this draft. Busy admission phases refuse, like
    * {@link addAttachments}: a removal landing while a command submit serializes
diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts
index 464ff55e17..8ddad82052 100644
--- a/packages/client/ui-conversation/src/client/locales.ts
+++ b/packages/client/ui-conversation/src/client/locales.ts
@@ -31,6 +31,9 @@ export const zh = {
   'attachment.dropTitle': '文件或图片拖动到此处即可添加',
   'attachment.dropDesc': '图片限制：最多 {count} 张，每张 {size}',
   'attachment.dropBlocked': '当前无法添加文件或图片',
+  'attachment.directoryDesktopOnly': '只有桌面端支持添加文件夹，浏览器里请添加单个文件',
+  'attachment.pathUnavailable': '无法获取文件夹路径，请重新拖入',
+  'attachment.pathUnsupported': '路径含有无法引用的字符，请改名后再试',
   'image.pending': '待发送图片',
   'image.openOriginal': '查看原图',
   'image.openOriginalLabel': '{label}，点击查看原图',
@@ -286,7 +289,7 @@ export const zh = {
   'row.inspect': '查看',
   'tool.title.search': '搜索',
   'tool.title.read': '读取',
-  'tool.title.bash': 'Bash',
+  'tool.title.bash': '运行命令',
   'tool.title.write': '写入',
   'tool.title.edit': '编辑',
   'tool.title.code': '代码',
@@ -295,10 +298,10 @@ export const zh = {
   'tool.title.runCordis': '运行 Cordis 插件',
   'tool.title.stopCordis': '停止 Cordis 插件',
   'tool.title.removeCordis': '移除 Cordis 插件',
-  'tool.title.pwsh': 'Pwsh',
+  'tool.title.pwsh': '运行命令',
   'tool.title.readImage': '读取图片',
-  'tool.title.grep': 'Grep',
-  'tool.title.glob': 'Glob',
+  'tool.title.grep': '搜索文件内容',
+  'tool.title.glob': '查找文件',
   'tool.title.webSearch': '网页搜索',
   'tool.title.webFetch': '网页获取',
   'tool.autoReviewRejected': 'Auto review 已拒绝',
@@ -382,6 +385,9 @@ export const en = {
   'attachment.dropTitle': 'Drag files or images here to add them',
   'attachment.dropDesc': 'Image limit: up to {count} images, {size} each',
   'attachment.dropBlocked': 'Files and images cannot be added right now',
+  'attachment.directoryDesktopOnly': 'Folders can only be added in the desktop app; add individual files in the browser',
+  'attachment.pathUnavailable': 'Could not obtain the folder path; drag it in again',
+  'attachment.pathUnsupported': 'The path contains characters a reference cannot carry; rename it and try again',
   'image.pending': 'Pending images',
   'image.openOriginal': 'View original',
   'image.openOriginalLabel': '{label}, click to view original',
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts
index 367647658e..2ef2309ccf 100644
--- a/packages/client/ui-conversation/src/client/service.ts
+++ b/packages/client/ui-conversation/src/client/service.ts
@@ -594,8 +594,12 @@ function imageMediaType(value: string): ImageMediaType {
   }
 }
 
-/** Whether a browser-declared MIME selects the image draft path (all other files upload verbatim). */
-function isImageMediaType(value: string): boolean {
+/**
+ * Whether a browser-declared MIME selects the image draft path (all other files upload verbatim).
+ * @param value - the browser's declared MIME type.
+ * @returns whether the file is an accepted raster image.
+ */
+export function isImageMediaType(value: string): boolean {
   return value === 'image/png' || value === 'image/jpeg' || value === 'image/webp' || value === 'image/gif'
 }
 
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index 6226a18ffa..fbd07f2810 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -407,3 +407,10 @@
   font-size: 12px;
   cursor: pointer;
 }
+
+.standardControls { display: flex; align-items: center; gap: 12px; min-width: 0; }
+.tools[hidden], .standardControls[hidden] { display: none; }
+.trailingActive { flex: 1; margin-left: 0; }
+.activity { display: flex; align-items: center; flex: none; }
+.activity:empty { display: none; }
+.activityExpanded { flex: 1; min-width: 0; }
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index 6a4ea12740..7016ea8f9d 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -55,6 +55,8 @@ export const InputBar = memo(function InputBar({
   const busyEnter = useBusyEnter(s => s)
   void useLexicon // hook seat stays bound by the inject compartment; text-ref decoration rides the shell's editor transforms
   const commandMenuOpen = useMenuLauncher(source => source === 'command')
+  const [activity, setActivity] = useState(false)
+  useEffect(() => { setActivity(false) }, [sessionId])
   const promptError = useSession(s => s.promptError) ?? null
   const running = useSession(s => s.running) ?? false
   const subagent = useSession(s => s.subagent) ?? null
@@ -198,7 +200,7 @@ export const InputBar = memo(function InputBar({
   // client-side size or count limit and upload as soon as they are picked.
   // The host enforces the same image limits at submit for callers that bypass
   // this composer.
-  const intakeFiles = useCallback((files: readonly File[]): void => {
+  const intakeFiles = useCallback((files: readonly File[], directories?: ReadonlySet<File>): void => {
     if (subagent !== null || addFiles === undefined || files.length === 0) return
     const rejected = ((): string | null => {
       if (imageLimits !== undefined) {
@@ -217,7 +219,7 @@ export const InputBar = memo(function InputBar({
           return t('image.totalTooLarge', { size: imageSizeText(imageLimits.maxMessageImageBytes) })
         }
       }
-      return addFiles(files)
+      return addFiles(files, directories)
     })()
     if (rejected !== null) showToast(rejected)
   }, [subagent, addFiles, attachments, imageLimits, showToast, t])
@@ -406,7 +408,7 @@ export const InputBar = memo(function InputBar({
           showPlaceholder={draft === '' && attachments.length === 0 && !claimActive}
         />
         <div className={css.row}>
-          <div className={css.tools}>
+          <div className={css.tools} hidden={activity}>
             <Tooltip label={t('input.commands')} side="top" delayMs={500}>
               <button
                 type="button"
@@ -437,11 +439,16 @@ export const InputBar = memo(function InputBar({
               ? null
               : renderSlot('conversation.input.left', {})}
           </div>
-          <div className={css.trailing}>
-            {input === undefined || sessionId === undefined
-              ? null
-              : renderSlot('conversation.input.right', {})}
-            {sessionId === undefined ? null : renderSlot('conversation.input.model', { locked: modelSeatLocked })}
+          <div className={clsx(css.trailing, activity && css.trailingActive)}>
+            <div className={css.standardControls} hidden={activity}>
+              {input === undefined || sessionId === undefined
+                ? null
+                : renderSlot('conversation.input.right', {})}
+              {sessionId === undefined ? null : renderSlot('conversation.input.model', { locked: modelSeatLocked })}
+            </div>
+            {input === undefined || sessionId === undefined ? null : <div className={activity ? css.activityExpanded : css.activity}>
+              {renderSlot('conversation.input.activity', { locked, onActiveChange: setActivity })}
+            </div>}
             {interruptible && (
               <Tooltip label={t('input.stop')} side="top" delayMs={500} disabled={stop === undefined}>
                 <button
@@ -485,7 +492,7 @@ export const InputBar = memo(function InputBar({
         {variant === 'composer' && input !== undefined && sessionId !== undefined
           ? renderSlot('conversation.composer.dock', {})
           : null}
-        <ContextMeter useProjection={useProjection} t={t} />
+        {activity ? null : <ContextMeter useProjection={useProjection} t={t} />}
       </div>
     </div>
   )
diff --git a/packages/client/ui-conversation/src/client/view-selection.ts b/packages/client/ui-conversation/src/client/view-selection.ts
index 0d777c9b7d..6d0589759c 100644
--- a/packages/client/ui-conversation/src/client/view-selection.ts
+++ b/packages/client/ui-conversation/src/client/view-selection.ts
@@ -1,8 +1,11 @@
 import type { ViewTab } from './contract/views.ts'
 
-/** Chat remains available when developer tools are disabled. */
+/** Fallback View selected when no stored preference resolves to a registered View. */
 export const DEFAULT_VIEW_ID = 'chat'
 
+/** The one View the Developer tools preference gates; other Views stay registered by their owners. */
+export const DEVELOPER_TOOLS_VIEW_ID = 'trajectory'
+
 /**
  * Resolve a preferred registered View, then Chat, without choosing another View.
  * @param tabs - currently registered Views.
diff --git a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
index 6c12f28cfb..db7eb068ba 100644
--- a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
@@ -1,4 +1,8 @@
 // @vitest-environment jsdom
+import { render, cleanup } from '@testing-library/react'
+import { $getRoot, $isTextNode, PASTE_COMMAND } from 'lexical'
+import { projectUserText } from '@deepseek-ai/dsh-client-ui-primitives'
+import { registerComposerKeymap } from '../src/client/input/editor/keymap.ts'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import type { CommandContribution, CommandUiContract } from '@deepseek-ai/dsh-client-ui-commands/client'
@@ -201,24 +205,46 @@ describe('Conversation inject API', () => {
     const unsubscribe = source.subscribe(changed)
     expect(source.getSnapshot()).toBeUndefined()
     const removeDefinition = b.runtime.ctx.uiConversation.views.register({
-      target: 'custom-inspector',
+      target: 'trajectory',
       toolCallFocus: callId => `tool:${callId}`,
       create: () => ({ empty: null, replace: () => null, apply: () => null }),
     })
     expect(source.getSnapshot()).toBeUndefined()
     const removeView = b.slots.register(
-      { name: 'conversation.view', id: 'custom-inspector' }, (() => null) as never,
+      { name: 'conversation.view', id: 'trajectory' }, (() => null) as never,
     )
     await b.runtime.flush()
     const inspect = source.getSnapshot()!
     expect(inspect).toBeTypeOf('function')
     expect(source.getSnapshot()).toBe(inspect)
     inspect('call-1')
-    expect(body.instance.store.getSnapshot().viewRequest).toEqual({ view: 'custom-inspector', focus: 'tool:call-1' })
+    expect(body.instance.store.getSnapshot().viewRequest).toEqual({ view: 'trajectory', focus: 'tool:call-1' })
     await b.runtime.ctx.settingsScope.developerTools.setEnabled(false)
     expect(source.getSnapshot()).toBeUndefined()
     await b.runtime.ctx.settingsScope.developerTools.setEnabled(true)
     expect(source.getSnapshot()).toBe(inspect)
+    // Trajectory still owns inspection while both Views are visible; hiding
+    // it must leave a third-party View's inspection capability reachable.
+    const removePipelineDefinition = b.runtime.ctx.uiConversation.views.register({
+      target: 'pipeline',
+      toolCallFocus: callId => `stage:${callId}`,
+      create: () => ({ empty: null, replace: () => null, apply: () => null }),
+    })
+    const removePipelineView = b.slots.register(
+      { name: 'conversation.view', id: 'pipeline' }, (() => null) as never,
+    )
+    await b.runtime.flush()
+    expect(source.getSnapshot()).toBe(inspect)
+    await b.runtime.ctx.settingsScope.developerTools.setEnabled(false)
+    const pipelineInspect = source.getSnapshot()!
+    expect(pipelineInspect).toBeTypeOf('function')
+    pipelineInspect('call-2')
+    expect(body.instance.store.getSnapshot().viewRequest).toEqual({ view: 'pipeline', focus: 'stage:call-2' })
+    await b.runtime.ctx.settingsScope.developerTools.setEnabled(true)
+    removePipelineView()
+    removePipelineDefinition()
+    await b.runtime.flush()
+    expect(source.getSnapshot()).toBe(inspect)
     removeView()
     await b.runtime.flush()
     expect(source.getSnapshot()).toBeUndefined()
@@ -377,6 +403,90 @@ describe('Conversation inject API', () => {
     await b.runtime.dispose()
   })
 
+  it('cites shell-named files and folders as @ references and refuses folders without the shell bridge', async () => {
+    const browser = await bench()
+    const folder = new File([], 'project')
+    expect(browser.composerApi(ROOT).addFiles?.([folder], new Set([folder])))
+      .toBe('只有桌面端支持添加文件夹，浏览器里请添加单个文件')
+    expect(browser.inputApi(ROOT).state.getSnapshot().attachmentIds).toEqual([])
+    await browser.runtime.dispose()
+
+    const paths = new Map([['project', '/Users/me/my project'], ['notes.md', '/Users/me/notes.md'], ['shot.png', '/Users/me/shot.png']])
+    vi.stubGlobal('__DSH_HOST_PATHS__', { pathFor: (file: File) => paths.get(file.name) ?? '' })
+    try {
+      const desktop = await bench()
+      const composer = desktop.composerApi(ROOT)
+      const { state } = desktop.inputApi(ROOT)
+      const note = new File([Uint8Array.of(1)], 'notes.md', { type: 'text/markdown' })
+      const shot = new File([Uint8Array.of(2)], 'shot.png', { type: 'image/png' })
+      const pasted = new File([Uint8Array.of(3)], 'pasted.bin', { type: 'application/octet-stream' })
+      expect(composer.addFiles?.([folder, note, shot, pasted], new Set([folder]))).toBeNull()
+      // The folder and the file became references in the draft; the image and the pathless bytes stayed drafts.
+      expect(state.getSnapshot().draft).toBe('@"/Users/me/my project/" @/Users/me/notes.md ')
+      const drafts = composer.resolveDraftAttachments?.(state.getSnapshot().attachmentIds) ?? []
+      expect(drafts.map(draft => draft.kind)).toEqual(['image', 'file'])
+      await vi.waitFor(() => { expect(desktop.rootUpload).toHaveBeenCalledOnce() })
+      // A directory the shell cannot name is refused even with the bridge present.
+      const nameless = new File([], 'nameless')
+      expect(composer.addFiles?.([nameless], new Set([nameless])))
+        .toBe('无法获取文件夹路径，请重新拖入')
+      await desktop.runtime.dispose()
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('preserves selected text and file order and restores pasted directory chips from the draft', async () => {
+    vi.stubGlobal('__DSH_HOST_PATHS__', { pathFor: (file: File) => `/proj/${file.name}` })
+    onTestFinished(() => { vi.unstubAllGlobals(); cleanup() })
+    const b = await bench()
+    onTestFinished(() => b.runtime.dispose())
+    const composer = b.composerApi(ROOT)
+    const editor = composer.keyboard!.editor
+    const { state, actions } = b.inputApi(ROOT)
+    actions.setDraft('读取')
+    editor.update(() => {
+      const text = $getRoot().getAllTextNodes()[0]
+      if (text === undefined || !$isTextNode(text)) throw new Error('expected text selection')
+      text.select(0, 2)
+    }, { discrete: true })
+    const off = registerComposerKeymap(editor, {
+      arbitrate: () => 'pass', space: () => false, dismissPopup: () => {},
+      canSubmit: () => true, submit: () => {}, pasteText: (text) => { composer.keyboard!.paste(text) },
+      intakeFiles: (files, directories) => { expect(composer.addFiles?.(files, directories)).toBeNull() },
+    })
+    onTestFinished(off)
+    const folder = new File([], 'my project')
+    const files = [new File([], 'a.txt'), folder, new File([], 'b.txt')]
+    const event = new KeyboardEvent('paste', { cancelable: true })
+    Object.defineProperty(event, 'clipboardData', { value: {
+      items: files.map(file => ({
+        kind: 'file', getAsFile: () => file, webkitGetAsEntry: () => ({ isDirectory: file === folder }),
+      })), getData: () => '',
+    } })
+    editor.update(() => { editor.dispatchCommand(PASTE_COMMAND, event) }, { discrete: true })
+    expect(state.getSnapshot().draft).toBe('读取 @a.txt @"my project/" @b.txt ')
+    const view = render(<div>{projectUserText(state.getSnapshot().draft, [])}</div>)
+    expect(view.container.querySelector('[data-ref-chip="folder"]')?.textContent).toBe('my project')
+    expect(view.container.querySelector('[data-ref-chip="folder"]')?.getAttribute('title')).toBe('@"my project/"')
+  })
+
+  it('rejects the whole file batch before changing the draft when a later path is unrepresentable', async () => {
+    vi.stubGlobal('__DSH_HOST_PATHS__', { pathFor: (file: File) => `/proj/${file.name}` })
+    onTestFinished(() => { vi.unstubAllGlobals() })
+    const b = await bench()
+    onTestFinished(() => b.runtime.dispose())
+    const { state, actions } = b.inputApi(ROOT)
+    actions.setDraft('keep this text')
+    for (const name of ['bad"name', 'bad\nname']) {
+      const files = [new File([], 'good.txt'), new File([], name)]
+      expect(b.composerApi(ROOT).addFiles?.(files)).toBe('路径含有无法引用的字符，请改名后再试')
+      expect(state.getSnapshot().draft).toBe('keep this text')
+      expect(state.getSnapshot().attachmentIds).toEqual([])
+      expect(b.rootUpload).not.toHaveBeenCalled()
+    }
+  })
+
   it('fails loud for an unknown binding or an unloaded scoped service', async () => {
     const b = await bench()
     const entry = b.entryOf('conversation.composer.bar')
diff --git a/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx b/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx
index 32e2c1dcac..aca7780d30 100644
--- a/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-wiring.client.spec.tsx
@@ -44,18 +44,18 @@ function entry(
 }
 
 describe('target-neutral Conversation apply wiring', () => {
-  it('offers only Chat while developer tools are disabled and restores registered views when enabled', async () => {
+  it('hides only the Trajectory View while developer tools are disabled and restores it when enabled', async () => {
     const b = await bench()
     const header = b.runtime.slots.entries('conversation.session.header')[0]!
     const source = (header.inject!() as { hooks: { conversationViews: ObservableSnapshot<readonly ViewTab[]> } }).hooks.conversationViews
-    for (const id of ['chat', 'trajectory']) {
+    for (const id of ['chat', 'trajectory', 'probe']) {
       b.runtime.slots.register({ name: 'conversation.view', id, label: id }, (() => null) as never)
     }
-    await vi.waitFor(() => { expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory']) })
+    await vi.waitFor(() => { expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory', 'probe']) })
     b.developerTools.set(false)
-    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat'])
+    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'probe'])
     b.developerTools.set(true)
-    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory'])
+    expect(source.getSnapshot().map(tab => tab.id)).toEqual(['chat', 'trajectory', 'probe'])
     await b.runtime.dispose()
   })
   it('waits for the layout-owned conversation declaration before registering its subtree', async () => {
diff --git a/packages/client/ui-conversation/tests/async-insertion.client.spec.ts b/packages/client/ui-conversation/tests/async-insertion.client.spec.ts
new file mode 100644
index 0000000000..ef7cf1fcb9
--- /dev/null
+++ b/packages/client/ui-conversation/tests/async-insertion.client.spec.ts
@@ -0,0 +1,38 @@
+/** Late input insertions preserve references, subsequent edits, and undo ownership. */
+import { Context } from '@deepseek-ai/cordis'
+import { UNDO_COMMAND } from 'lexical'
+import { expect, it, vi } from 'vitest'
+import { SessionInputShell } from '../src/client/input/facade.ts'
+
+function shell(): SessionInputShell {
+  return new SessionInputShell({ actx: new Context(), defaultSink: vi.fn(), commandAttachments: {
+    serialize: async () => [], release: () => {}, unsupportedNotice: () => '',
+  } })
+}
+
+it('inserts text beside an existing reference and undoes only that insertion', async () => {
+  const input = shell()
+  try {
+    input.setDraft('@ref')
+    input.insertReference({ source: 'file', ref: 'src/main.ts', label: 'main.ts', clipboardText: '@[main.ts](src/main.ts)' },
+      { start: 0, end: 4, draftRev: input.state.getSnapshot().draftRev })
+    const original = input.state.getSnapshot()
+    expect(input.actions.insertText(' check types', input.actions.captureInsertion())).toBe(true)
+    expect(input.state.getSnapshot().draft).toContain('check types')
+    expect(input.state.getSnapshot().occurrences).toEqual(original.occurrences)
+    input.editor.dispatchCommand(UNDO_COMMAND, undefined)
+    await vi.waitFor(() => { expect(input.state.getSnapshot().draft).toBe(original.draft) })
+  } finally { input.dispose() }
+})
+
+it('refuses results captured before a user edit or after editor disposal', () => {
+  const input = shell()
+  input.setDraft('before')
+  const span = input.actions.captureInsertion()
+  input.setDraft('my newer text')
+  expect(input.actions.insertText('late voice', span)).toBe(false)
+  expect(input.state.getSnapshot().draft).toBe('my newer text')
+  const latest = input.actions.captureInsertion()
+  input.dispose()
+  expect(input.actions.insertText('late voice', latest)).toBe(false)
+})
diff --git a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
index 8a919e624c..2f57b05f27 100644
--- a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
+++ b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts
@@ -72,7 +72,6 @@ function fakeSessions(ctx: Context): { sessions: ISessions; binding: SessionBind
     byId: {},
     phase: 'ready',
     projectionsBySession: {},
-    jobsBySession: {},
   })
   const reference = {
     sessionId: SESSION_ID,
diff --git a/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx b/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx
index b5de7d3ade..3d1b833896 100644
--- a/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx
@@ -22,7 +22,7 @@ afterEach(() => {
 
 function emptySessions() {
   return bindSnapshotSelector(createSnapshotStore<SessionListState>({
-    ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+    ids: [], byId: {}, phase: 'ready', projectionsBySession: {},
   }))
 }
 
diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
index 9e0366952c..0e9349e51d 100644
--- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
@@ -19,6 +19,7 @@ import {
 } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { SessionListState, SessionSnapshot } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { ContextPressureProjection } from '@deepseek-ai/dsh-token-meter/client'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { Context } from '@deepseek-ai/cordis'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -26,7 +27,7 @@ import type { SubmitOutcome } from '../src/client/contract/input.ts'
 import { SessionInputShell } from '../src/client/input/facade.ts'
 import { $replaceDetectSpanWithText, $selectDetectSpan } from '../src/client/input/editor/span-map.ts'
 import type {
-  ComposerAttachment, ComposerAttachmentsOwnerProps, DraftFileUploads,
+  ComposerAttachment, ComposerAttachmentsOwnerProps, DraftFileUploads, InputActivityOwnerProps,
 } from '../src/client/contract/slots.ts'
 import type { DraftAttachmentId } from '../src/client/contract/input.ts'
 import { InputBar } from '../src/client/skeleton/InputBar.tsx'
@@ -92,11 +93,13 @@ interface BenchOptions {
   overlay?: React.ReactNode
   leftItems?: React.ReactNode
   rightItems?: React.ReactNode
+  activityEntry?: (owner: InputActivityOwnerProps) => React.ReactNode
+  contextPressure?: ContextPressureProjection
   footer?: React.ReactNode
   attachments?: readonly ComposerAttachment[]
   /** Upload states served for file-kind drafts (absent = every file is ready). */
   fileUploads?: DraftFileUploads
-  addFiles?: (files: readonly File[]) => string | null
+  addFiles?: (files: readonly File[], directories?: ReadonlySet<File>) => string | null
   commandMenuOpen?: boolean
   busyEnter?: 'queue' | 'steer'
   toggleCommandMenu?: (selection: { start: number; end: number }) => void
@@ -162,6 +165,7 @@ function bench(over?: BenchOptions) {
     if (key === 'conversation.input.plan') return over?.planEntry ?? null
     if (key === 'conversation.input.permission') return over?.permissionEntry ?? null
     if (key === 'conversation.input.model') return over?.modelEntry ?? null
+    if (key === 'conversation.input.activity') return over?.activityEntry?.(owner as InputActivityOwnerProps) ?? null
     return null
   }) as never
   const props: InputBarProps = {
@@ -175,7 +179,7 @@ function bench(over?: BenchOptions) {
     useResource,
     useSessions: bindSnapshotSelector(createSnapshotStore<SessionListState>({
       ids: [], byId: {}, phase: 'ready',
-      projectionsBySession: {}, jobsBySession: {},
+      projectionsBySession: {},
     })),
     useWorkspaces: bindSnapshotSelector(createSnapshotStore({
       items: [], archivedSessionIds: [], pinnedSessionIds: [], state: 'idle', phase: 'ready', error: null,
@@ -184,7 +188,8 @@ function bench(over?: BenchOptions) {
       (selector ?? (v => v))(key === 'plan'
         ? over?.plan
         : key === 'goal' ? over?.goal
-          : key === 'imageLimits' ? over?.imageLimits : undefined)),
+          : key === 'imageLimits' ? over?.imageLimits
+            : key === 'contextPressure' ? over?.contextPressure : undefined)),
     useInput: bindSnapshotSelector(shell.state),
     inputActions: shell.actions,
     keyboard: shell,
@@ -344,11 +349,34 @@ describe('image draft rail', () => {
         getData: () => '同时粘贴的文字',
       },
     })
-    expect(addFiles).toHaveBeenCalledWith([image])
+    expect(addFiles).toHaveBeenCalledWith([image], undefined)
     // The paste lands inside the PASTE_COMMAND update; its commit is a microtask away.
     await vi.waitFor(() => { expect(shell.snapshot.draft).toBe('同时粘贴的文字') })
   })
 
+  it('passes known clipboard directories and keeps files whose entry metadata is unavailable', () => {
+    const addFiles = vi.fn(() => null)
+    const { textarea } = bench({ addFiles })
+    const folder = new File([], 'folder with spaces')
+    const emptyFile = new File([], 'empty-file')
+    const withoutApi = new File([], 'without-api')
+    const withoutEntry = new File([], 'without-entry')
+    fireEvent.paste(textarea, {
+      clipboardData: {
+        items: [
+          { kind: 'string', getAsFile: () => null },
+          { kind: 'file', getAsFile: () => folder, webkitGetAsEntry: () => ({ isDirectory: true }) },
+          { kind: 'file', getAsFile: () => emptyFile, webkitGetAsEntry: () => ({ isDirectory: false }) },
+          { kind: 'file', getAsFile: () => withoutApi },
+          { kind: 'file', getAsFile: () => withoutEntry, webkitGetAsEntry: () => null },
+          { kind: 'file', getAsFile: () => null },
+        ],
+        getData: () => '',
+      },
+    })
+    expect(addFiles).toHaveBeenCalledWith([folder, emptyFile, withoutApi, withoutEntry], new Set([folder]))
+  })
+
   it('pre-checks projected limits at intake: whole-batch refusal with product copy, none added', () => {
     const limits = {
       maxImageBytes: 1024 * 1024,
@@ -386,7 +414,7 @@ describe('image draft rail', () => {
     const within = bench({ addFiles: vi.fn(() => null), imageLimits: limits })
     const fits = png(16, 'fits.png')
     intake(within, [fits])
-    expect(within.props.addFiles).toHaveBeenCalledWith([fits])
+    expect(within.props.addFiles).toHaveBeenCalledWith([fits], undefined)
     expect(within.view.queryByRole('alert')).toBeNull()
   })
 
@@ -409,7 +437,7 @@ describe('image draft rail', () => {
       new File([new ArrayBuffer(64)], 'b.pdf', { type: 'application/pdf' }),
     ]
     act(() => { attachmentOwner(result.slotCalls).onAddFiles(files) })
-    expect(addFiles).toHaveBeenCalledWith(files)
+    expect(addFiles).toHaveBeenCalledWith(files, undefined)
     expect(result.view.getByRole('alert').textContent).toContain('仅支持 PNG、JPG、WebP、GIF 格式的图片')
   })
 
@@ -428,6 +456,17 @@ describe('image draft rail', () => {
     expect(attachmentOwner(result.slotCalls).dropLimits).toEqual({ count: 20, size: '5MB' })
   })
 
+  it('forwards dropped directories to addFiles and announces its refusal', () => {
+    const addFiles = vi.fn((_files: readonly File[], directories?: ReadonlySet<File>) =>
+      directories !== undefined && directories.size > 0 ? '只有桌面端支持添加文件夹，浏览器里请添加单个文件' : null)
+    const result = bench({ addFiles })
+    const folder = new File([], 'project')
+    const note = new File([Uint8Array.of(1)], 'notes.md', { type: 'text/markdown' })
+    act(() => { attachmentOwner(result.slotCalls).onAddFiles([folder, note], new Set([folder])) })
+    expect(addFiles).toHaveBeenCalledWith([folder, note], new Set([folder]))
+    expect(result.view.getByRole('alert').textContent).toContain('只有桌面端支持添加文件夹')
+  })
+
   it('announces server attachment rejections as product copy, other codes as developer text', () => {
     const attachmentError = (reason: string): SessionSnapshot['promptError'] => ({
       op: 'send',
@@ -1610,7 +1649,7 @@ describe('command launcher chrome and control seats', () => {
     expect([...new Set(slotCalls.map(c => c.key))]).toEqual([
       'conversation.input.overlay', 'conversation.input.attachments',
       'conversation.input.permission', 'conversation.input.plan', 'conversation.input.left',
-      'conversation.input.right', 'conversation.input.model',
+      'conversation.input.right', 'conversation.input.model', 'conversation.input.activity',
       'conversation.composer.dock',
     ])
     expect(view.queryByLabelText('Plan mode')).toBeNull()
@@ -1673,3 +1712,42 @@ describe('command launcher chrome and control seats', () => {
     expect((live.view.getByLabelText('添加文件或调用指令') as HTMLButtonElement).disabled).toBe(false)
   })
 })
+
+it('lets a toolbar activity replace accessories without replacing the draft editor or send action', () => {
+  const { view } = bench({ draft: 'keep this draft', modelEntry: <button>model choice</button>,
+    activityEntry: owner => <>
+      <button onClick={() => { owner.onActiveChange(true) }}>expand activity</button>
+      <button onClick={() => { owner.onActiveChange(false) }}>close activity</button>
+    </>,
+  })
+  const editor = view.getByRole('textbox')
+  fireEvent.click(view.getByRole('button', { name: 'expand activity' }))
+  expect(view.queryByRole('button', { name: 'model choice' })).toBeNull()
+  expect(view.getByRole('textbox')).toBe(editor)
+  expect(editor.textContent).toBe('keep this draft')
+  expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy()
+  fireEvent.click(view.getByRole('button', { name: 'close activity' }))
+  expect(view.getByRole('button', { name: 'model choice' })).toBeTruthy()
+})
+
+it('places context usage below the composer and hides it until the activity closes', () => {
+  const { view } = bench({ draft: 'draft', contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 },
+    activityEntry: owner => <>
+      <button onClick={() => { owner.onActiveChange(true) }}>microphone</button>
+      <button onClick={() => { owner.onActiveChange(false) }}>close activity</button>
+    </>,
+  })
+  const meter = view.getByRole('button', { name: '上下文已用 25%' })
+  const microphone = view.getByRole('button', { name: 'microphone' })
+  expect(microphone.compareDocumentPosition(meter) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+  fireEvent.click(meter)
+  expect(view.getByRole('dialog', { name: '上下文已用' })).toBeTruthy()
+  fireEvent.click(microphone)
+  expect(view.queryByRole('dialog', { name: '上下文已用' })).toBeNull()
+  expect(view.queryByRole('button', { name: '上下文已用 25%' })).toBeNull()
+  expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy()
+  fireEvent.click(view.getByRole('button', { name: 'close activity' }))
+  fireEvent.click(view.getByRole('button', { name: '上下文已用 25%' }))
+  expect(view.getByRole('dialog', { name: '上下文已用' })).toBeTruthy()
+  expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy()
+})
diff --git a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
index 15d87a0ca7..1dcbd65f9c 100644
--- a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
@@ -54,7 +54,7 @@ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled
     useSession: bindSnapshotSelector(session),
     useSessions: bindSnapshotSelector(createSnapshotStore({
       ids: [], byId: {}, current: undefined, phase: 'ready',
-      projectionsBySession: {}, jobsBySession: {}, currentAddress: undefined,
+      projectionsBySession: {}, currentAddress: undefined,
     })),
     useSessionStatus: bindSnapshotSelector(
       createSnapshotStore<SessionStatusSnapshot>(new Map()),
@@ -283,6 +283,11 @@ describe('matrix row: claimed with attachments', () => {
     act(() => { shell.addAttachments([img]) })
     fireEvent.keyDown(textarea, { key: 'Enter' })
     expect(shell.snapshot.phase).toBe('submitting')
+    const draft = shell.snapshot.draft
+    expect(shell.addFiles([{
+      source: 'reference', ref: '@note.txt', label: 'note.txt', clipboardText: '@note.txt',
+    }], ['new-file' as DraftAttachmentId])).toBe(false)
+    expect(shell.snapshot.draft).toBe(draft)
     let removed = true
     act(() => { removed = shell.removeAttachment(img) })
     expect(removed).toBe(false)
diff --git a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
index 347b4d05c1..e119a8104d 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
@@ -148,7 +148,7 @@ async function scopedBench(register?: (inputTriggers: InputTriggerService) => vo
     useSession: bindSnapshotSelector(sessionStore),
     useSessions: bindSnapshotSelector(createSnapshotStore({
       ids: [], byId: {}, current: undefined, phase: 'ready',
-      projectionsBySession: {}, jobsBySession: {}, currentAddress: undefined,
+      projectionsBySession: {}, currentAddress: undefined,
     })),
     useSessionStatus: bindSnapshotSelector(
       createSnapshotStore<SessionStatusSnapshot>(new Map()),
diff --git a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
index 17aadfb056..911e331bc1 100644
--- a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
@@ -164,7 +164,7 @@ function mount(
       ...listed && options.nestedSubagent === true && { [parent]: parentRow },
       ...listed && { [SID]: childRow },
     },
-    phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+    phase: 'ready', projectionsBySession: {},
   })
   const workspaces = createSnapshotStore<WorkspaceSnapshot>(workspaceState(workspaceRows))
   const session = createSnapshotStore<SessionSnapshot>(snapshot)
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index 1dbe8b1ce5..a4df996a41 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -92,6 +92,9 @@
     {
       "path": "../../util/values"
     },
+    {
+      "path": "../../context/file-reference"
+    },
     {
       "path": "../../util/workspace-path"
     }
diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml
index 7ea790985c..c3c62898a1 100644
--- a/packages/client/ui-deliverables/README.i18n.yaml
+++ b/packages/client/ui-deliverables/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-deliverables/README.md
-README.md: 71f3545b8fb3fed3ecd678258e6c50bbfa4b580c
-README.zh.md: 3e59ed2b7d4ac7e9d64b7d1f2f3c477e3ca1c50e
+README.md: ce006783310c257957bc8cfddcfd18226972d18f
+README.zh.md: 82239ba169f4ada188e8a5ba8e1889c61b336f96
diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md
index 71f3545b8f..ce00678331 100644
--- a/packages/client/ui-deliverables/README.md
+++ b/packages/client/ui-deliverables/README.md
@@ -30,9 +30,9 @@ Mount this plugin alongside `ui-conversation` and the Host [workspace-changes](.
 <a id="explicit-deliveries"></a>
 ### Explicit deliveries
 
-The Web `standard`, `ptc`, and `cordis` presets expose `present` for final files accessible through the Session filesystem, including files created through Bash. Call it with `files: [{ path, description? }]` after creating the files. The [present tool](../../deliverables/tool-present/README.md) owns file-count limits and Session declarations. The closing turn shows one delivery as a full-width card and multiple deliveries in a two-column grid with 10px gaps. A list longer than four files starts collapsed and provides a control that reveals or hides the complete list. Each 60px-high card uses 8px vertical and 10px horizontal inset spacing, a 20px shared `FileTypeIcon` in a 40px frame, 13px filename text, 10px secondary text, and a 12px Open action. It shows the basename and description, or the file type when no description exists; a trailing parenthesized suffix in the description is omitted, and hovering the card replaces that line with the Sidebar-preview action. Clicking the card or the left side of its split Open control previews the file in the right Sidebar. The chevron opens the standard menu for the Host default application plus Show in Finder on macOS, Show in File Explorer on Windows and WSL, or Open containing folder through the default Linux file manager. Matching inline-code references preview the same source files in the right Sidebar; native opening requires an explicit card-menu action. Repeated declaration of a path selects its latest description before the closing reply.
+The Web `standard`, `ptc`, and `cordis` presets expose `present` for final files accessible through the Session filesystem, including files created through Bash. Call it with `files: [{ path, description? }]` after creating the files. The [present tool](../../deliverables/tool-present/README.md) owns file-count limits and Session declarations. A single delivery fills the row; multiple deliveries form a two-column grid, collapsed after four files. Cards show the basename, description or file type, and a shared native opening control. Clicking the card previews the file in the right Sidebar. The control opens the default application and lists associated applications, with file reveal last. Matching inline-code references also open Sidebar previews. Duplicate declarations use the last description before the closing reply.
 
-The `present` tool row retains the delivery-document glyph while showing running, delivered, failed, or interrupted status; expanding a settled row reveals its recorded result. The collapsible card grid retains every delivered file. Both menu actions share pending state and show progress, acknowledgement, or an action-specific retryable error. Desktop information is read when delivery cards appear and invalidated on connection replacement; responses from a replaced connection cannot publish metadata. Selecting a native menu action returns keyboard focus to the available Sidebar Open button. Pending actions close the menu until another explicit gesture. A missing desktop disables the Open menu; a failed desktop-information read offers Retry. It requires a desktop and a suitable default application on the serving Host; a remote browser does not open applications on its own device.
+The `present` tool row retains its document icon and recorded result across progress, success, failure, and interruption. Native actions share pending state and publish progress or retryable errors on the card. Successful open or reveal feedback stays visible for five seconds, fades over 200ms, then restores the file description; failures remain visible until another attempt. Desktop metadata is loaded when cards mount and invalidated on connection replacement. Without a Host desktop, cards retain Sidebar preview but omit native controls; failed metadata reads offer Retry. Delivery cards and change review expose `deliverables.file.actions` and `deliverables.review.file.actions`, supplied by [ui-open-in-app](../ui-open-in-app/README.md). Association GET requests and native POST actions both validate the recorded file coordinates and Session filesystem mapping before using the Host desktop.
 
 ### The changed-files card
 
diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md
index 3e59ed2b7d..82239ba169 100644
--- a/packages/client/ui-deliverables/README.zh.md
+++ b/packages/client/ui-deliverables/README.zh.md
@@ -30,9 +30,9 @@ kind: "package-reference"
 <a id="explicit-deliveries"></a>
 ### 显式交付
 
-Web 的 `standard`、`ptc` 与 `cordis` preset 提供 `present` 用于声明交付会话文件系统可访问的最终文件，包括通过 Bash 创建的文件。创建文件后，以 `files: [{ path, description? }]` 调用。[present 工具](../../deliverables/tool-present/README.zh.md)拥有文件数量限制和会话声明。收尾轮次把单个交付显示为横向占满内容区的卡片，把多个交付显示为间距 10px 的双列网格。文件超过四个时，列表默认收起，并提供显示或隐藏完整列表的控件。每张卡片高 60px，上下内边距为 8px、左右为 10px；40px 图标框内使用 20px 的共享 `FileTypeIcon`，文件名为 13px、次要文本为 10px，“打开”操作为 12px。卡片显示 basename 与说明；没有说明时显示文件类型，说明末尾的括号后缀会被省略，悬停卡片时该行切换为侧栏预览提示。点击卡片或分段“打开”控件的左侧会在右侧 Sidebar 中预览文件；右侧箭头打开标准菜单，其中提供 Host 默认应用，以及 macOS 上的“在 Finder 中显示”、Windows 和 WSL 上的“在文件资源管理器中显示”或 Linux 默认文件管理器的“打开所在文件夹”。匹配的行内代码引用在右侧 Sidebar 中预览相同源文件；原生打开需要显式选择卡片菜单中的操作。同一路径重复声明时，选择收尾回复之前最近一次的说明。
+Web 的 `standard`、`ptc` 与 `cordis` preset 提供 `present`，用于声明会话文件系统可访问的最终文件，包括通过 Bash 创建的文件。创建后以 `files: [{ path, description? }]` 调用。[present 工具](../../deliverables/tool-present/README.zh.md)拥有文件数量限制和会话声明。单个交付占满一行，多个交付使用双列网格，超过四个时默认收起。卡片显示文件名、说明或文件类型，以及共享的原生打开控件。点击卡片会在右侧 Sidebar 预览文件。控件打开默认应用，并列出关联应用，文件定位始终放在最后。匹配的行内代码引用也打开 Sidebar 预览。重复声明使用收尾回复之前最近一次的说明。
 
-`present` 工具行在正在交付、已交付、失败或中断状态下都保留交付文档图标；展开已结束的调用可查看其记录的结果。可折叠卡片网格保留全部交付文件。菜单中的两个操作共享等待状态，并显示进度、成功确认或各自可重试的错误。交付卡片出现时读取桌面信息，连接更换时清除缓存，旧连接的响应不能更新元数据。选择原生菜单操作后，键盘焦点回到仍可用的侧边栏“打开”按钮。等待操作完成时关闭菜单，用户再次点击才会打开。Host 没有桌面时禁用“打开”菜单；桌面信息读取失败时提供“重试”。服务 Host 必须具备桌面和合适的默认应用；远程浏览器不会打开其所在设备上的应用。
+`present` 工具行在执行、成功、失败和中断状态下保留文档图标及记录的结果。原生操作共享等待状态，并在卡片显示进度或可重试错误。打开或定位成功的反馈显示五秒后，在 200ms 内淡出并恢复文件说明；失败信息保留到下次尝试。卡片挂载时读取桌面信息，连接更换时清除缓存。Host 没有桌面时，卡片保留 Sidebar 预览并隐藏原生控件；元数据读取失败时提供重试。交付卡片和变更对比页通过 `deliverables.file.actions` 和 `deliverables.review.file.actions` 使用 [ui-open-in-app](../ui-open-in-app/README.zh.md) 提供的控件。关联应用 GET 查询与原生 POST 操作都会先校验记录中的文件坐标及会话文件系统映射，再调用 Host 桌面。
 
 ### 改动文件卡片
 
diff --git a/packages/client/ui-deliverables/src/client/Deliverables.module.css b/packages/client/ui-deliverables/src/client/Deliverables.module.css
index c772e6d01c..c59f619a02 100644
--- a/packages/client/ui-deliverables/src/client/Deliverables.module.css
+++ b/packages/client/ui-deliverables/src/client/Deliverables.module.css
@@ -18,18 +18,14 @@
 .description { overflow: hidden; color: var(--dsw-alias-label-tertiary); font-size: 10px; font-weight: 400; line-height: 16px; text-overflow: ellipsis; white-space: nowrap; }
 .description[data-error='true'] { color: var(--dsw-alias-state-error-primary); }
 .previewHint { display: none; }
-.file:hover .secondaryText { display: none; }
-.file:hover .previewHint { display: inline; }
-.split { display: inline-flex; flex: none; align-items: stretch; box-sizing: border-box; height: 28px; overflow: hidden; pointer-events: auto; border: 0.5px solid var(--dsw-alias-border-l3); border-radius: 10px; background: var(--dsw-alias-button-floating-fill); }
-.menuAnchor { align-self: stretch; }
-.open, .chevron { display: inline-flex; align-items: center; justify-content: center; border: 0; background: none; color: var(--dsw-alias-label-primary); cursor: pointer; font-family: var(--dsw-font-family); }
-.open { padding: 4px 8px; font-size: 12px; line-height: 18px; }
-.chevron { padding: 4px 5px; border-left: 0.5px solid var(--dsw-alias-border-l3); color: var(--dsw-alias-label-secondary); }
-.open:hover, .open:focus-visible, .chevron:hover:not(:disabled), .chevron:focus-visible { background: var(--dsw-alias-interactive-bg-hover); }
-.chevron:disabled { color: var(--dsw-alias-label-dimmed); cursor: not-allowed; }
-.menuActionIcon { display: block; width: 16px; height: 16px; }
+.file:hover .description:not([role='status']) .secondaryText { display: none; }
+.file:hover .description:not([role='status']) .previewHint { display: inline; }
 .toggle { align-self: center; display: inline-flex; align-items: center; gap: 4px; min-width: 0; padding: 1px 11px; border: 0; border-radius: 8px; background: transparent; color: var(--dsw-alias-label-tertiary); cursor: pointer; font: inherit; font-size: 12px; line-height: 18px; }
 .toggle:hover { background: var(--dsw-alias-interactive-bg-hover); }
 .toggle svg { flex: none; width: 14px; height: 14px; }
 @container (max-width: 620px) { .presented { grid-template-columns: minmax(0, 1fr); } }
-@media (pointer: coarse) { .split { min-height: 44px; } .open, .chevron { min-width: 44px; } }
+.actions { display: inline-flex; flex: none; pointer-events: auto; }
+
+.secondaryText[data-success] { animation-name: success-fade; animation-timing-function: ease-out; animation-fill-mode: forwards; }
+@keyframes success-fade { to { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) { .secondaryText[data-success] { animation-name: none; } }
diff --git a/packages/client/ui-deliverables/src/client/Deliverables.tsx b/packages/client/ui-deliverables/src/client/Deliverables.tsx
index ed7c034941..3fae39bd01 100644
--- a/packages/client/ui-deliverables/src/client/Deliverables.tsx
+++ b/packages/client/ui-deliverables/src/client/Deliverables.tsx
@@ -2,7 +2,7 @@
 import { useEffect, useState } from 'react'
 import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { Button, IconChevronDownOutlineRegular, IconChevronUpOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { GlobalStandardProps, InjectFace, PropsLocale, PropsRuntime, SessionStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
+import type { GlobalStandardProps, InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, SessionStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { PresentedOpenController } from './present-open.ts'
 import type { ChangesSummaryStore } from './changes-summary.ts'
@@ -50,24 +50,24 @@ export function selectDeliverables(owner: TurnTailOwnerProps): DeliverablesMatch
  * @param props - closing Turn, file actions, and localized copy.
  * @returns file rows, or null when the Turn declares none.
  */
-export function DeliverablesTail(props: PropsRuntime<'conversation.chat.turnTail'> & PropsLocale<typeof NS> & InjectFace<DeliverablesInjected>) {
+export function DeliverablesTail(props: PropsRuntime<'conversation.chat.turnTail'> & PropsLocale<typeof NS> & InjectFace<DeliverablesInjected> & PropsRenderSlots<'deliverables.file.actions'>) {
   const matched = selectDeliverables(props)
   return matched === null ? null : <Deliverables {...props} matched={matched} />
 }
 
 /**
  * Render the changed-files card, once the Host has served the announced
- * summary and it lists a file, and default-application buttons for declared
+ * summary and it lists a file, and shared native opening controls for declared
  * files. A summary the Host no longer serves leaves no card.
  * @param props - matched announcement and files, workspace opener, and localized copy.
  * @returns the closing turn's file rows.
  */
 export function Deliverables({
   matched, openFile, t, sessionId, useSessions, openPresented, openChangesReview, usePresentedOpen, usePresentedHost,
-  useChangesSummary, reloadPresentedHost, loadChangesSummary, useShowCodeDiff,
+  useChangesSummary, reloadPresentedHost, loadChangesSummary, useShowCodeDiff, renderSlot,
 }: Pick<TurnTailOwnerProps, 'openFile'> & {
   matched: DeliverablesMatch
-} & PropsLocale<typeof NS> & Pick<SessionStandardProps, 'sessionId'> & Pick<GlobalStandardProps, 'useSessions'> & InjectFace<DeliverablesInjected>) {
+} & PropsLocale<typeof NS> & Pick<SessionStandardProps, 'sessionId'> & Pick<GlobalStandardProps, 'useSessions'> & InjectFace<DeliverablesInjected> & PropsRenderSlots<'deliverables.file.actions'>) {
   const [expanded, setExpanded] = useState(false)
   const showCodeDiff = useShowCodeDiff(value => value)
   const cwd = useSessions(state => state.byId[sessionId]?.cwd)
@@ -105,7 +105,13 @@ export function Deliverables({
           phase={states[presentedFileUrl(sessionId, file.seq, file.index)]}
           host={host === 'error' ? null : host} t={t}
           onPreview={() => { openFile(file.path) }}
-          onAction={(action) => { void openPresented(sessionId, file.seq, file.index, action) }} />)}
+          actions={renderSlot('deliverables.file.actions', {
+            actionUrl: presentedFileUrl(sessionId, file.seq, file.index),
+            available: host !== null && host !== 'error' && host.available,
+            pending: states[presentedFileUrl(sessionId, file.seq, file.index)] === 'opening'
+              || states[presentedFileUrl(sessionId, file.seq, file.index)] === 'revealing',
+            onAction: (action, application) => openPresented(sessionId, file.seq, file.index, action, application),
+          })} />)}
       </div>
       {collapsible && <button type="button" className={css.toggle}
         aria-expanded={expanded}
diff --git a/packages/client/ui-deliverables/src/client/PresentedFileCard.tsx b/packages/client/ui-deliverables/src/client/PresentedFileCard.tsx
index 97fd431e32..f0dd26035b 100644
--- a/packages/client/ui-deliverables/src/client/PresentedFileCard.tsx
+++ b/packages/client/ui-deliverables/src/client/PresentedFileCard.tsx
@@ -1,13 +1,10 @@
-/** File identity and explicit default-app or file-manager actions for one delivery. */
-import { useRef, useState } from 'react'
+/** File identity, Sidebar preview, and contributed native actions for one delivery. */
+import type { ReactNode } from 'react'
 import { resolveWorkspacePath } from '@deepseek-ai/dsh-util-workspace-path'
-import {
-  Menu, FileTypeIcon, fileExtension, IconRightUpOutlineRegular,
-  IconChevronDownOutlineRegular, IconFolderOpenOutlineRegular,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+import { FileTypeIcon, fileExtension } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
-import type { PresentedAction, PresentedHost } from '../presented.ts'
-import type { PresentedOpenPhase } from './present-open.ts'
+import type { PresentedHost } from '../presented.ts'
+import { PRESENTED_SUCCESS_HOLD_MS, PRESENTED_SUCCESS_FADE_MS, type PresentedOpenPhase } from './present-open.ts'
 import { basename, type PresentedPath } from './turn-deliverables.ts'
 import type { NS } from './locales.ts'
 import css from './Deliverables.module.css'
@@ -22,25 +19,16 @@ function cardDescription(description: string | undefined, fallback: string): str
  * @param props - durable file metadata, Sidebar preview, Host capabilities, gesture status, and localized copy.
  * @returns the file card and its anchored action menu.
  */
-export function PresentedFileCard({ file, cwd, phase, host, onPreview, onAction, t }: {
+export function PresentedFileCard({ file, cwd, phase, host, onPreview, actions, t }: {
   file: PresentedPath
   cwd: string | undefined
   phase: PresentedOpenPhase | undefined
   host: PresentedHost | null
   onPreview: () => void
-  onAction: (action: PresentedAction) => void
+  actions: ReactNode
 } & PropsLocale<typeof NS>) {
-  const [menuOpen, setMenuOpen] = useState(false)
-  const previewRef = useRef<HTMLButtonElement>(null)
-  const pending = phase === 'opening' || phase === 'revealing'
-  const menuDisabled = pending || host === null || !host.available
-  if (menuDisabled && menuOpen) setMenuOpen(false)
+  const succeeded = phase === 'opened' || phase === 'revealed'
   const reveal = host?.fileManager ?? 'directory'
-  const act = (action: PresentedAction) => {
-    setMenuOpen(false)
-    previewRef.current?.focus()
-    onAction(action)
-  }
   const name = basename(file.path)
   const metadata = fileExtension(name).toUpperCase() || t('presented.file')
   const status = phase === undefined
@@ -55,31 +43,16 @@ export function PresentedFileCard({ file, cwd, phase, host, onPreview, onAction,
     <div className={css.fileBody}>
       <div className={css.details}>
         <span className={css.fileName}>{name}</span>
-        <span className={css.description} role={phase === undefined ? undefined : 'status'}
+        <span className={css.description} data-presented-description role={phase === undefined ? undefined : 'status'}
           data-error={phase === 'error' || phase === 'revealError' || phase === 'nativeUnavailable' ? true : undefined}>
-          <span className={css.secondaryText}>{status}</span>
+          <span className={css.secondaryText} data-success={succeeded || undefined}
+            style={succeeded ? { animationDelay: `${PRESENTED_SUCCESS_HOLD_MS}ms`, animationDuration: `${PRESENTED_SUCCESS_FADE_MS}ms` } : undefined}>
+            {status}
+          </span>
           <span className={css.previewHint}>{t('presented.preview')}</span>
         </span>
       </div>
-      <div className={css.split}>
-        <button ref={previewRef} type="button" className={css.open}
-          aria-label={t('presented.previewButton', { name: file.path })}
-          onClick={onPreview}>{t('presented.action')}</button>
-        <Menu className={css.menuAnchor} open={menuOpen && !menuDisabled} autoFocus portal align="end" onClose={() => { setMenuOpen(false) }}
-          anchor={<button type="button" className={css.chevron} disabled={menuDisabled}
-            aria-haspopup="menu" aria-expanded={menuOpen && !menuDisabled}
-            aria-label={t('presented.more', { name: file.path })}
-            onClick={() => { setMenuOpen(value => !value) }}>
-            <IconChevronDownOutlineRegular size={11} />
-          </button>}
-          items={[
-            { id: 'open', icon: <IconRightUpOutlineRegular size={16} className={css.menuActionIcon} />,
-              label: t('presented.defaultApp') },
-            { id: 'reveal', icon: <IconFolderOpenOutlineRegular />,
-              label: t(`presented.${reveal}`) },
-          ]}
-          onSelect={(id) => { act(id === 'reveal' ? 'reveal' : 'open') }} />
-      </div>
+      <div className={css.actions}>{actions}</div>
     </div>
   </div>
 }
diff --git a/packages/client/ui-deliverables/src/client/ReviewTab.tsx b/packages/client/ui-deliverables/src/client/ReviewTab.tsx
index 01ac90f1fa..362f88ec9d 100644
--- a/packages/client/ui-deliverables/src/client/ReviewTab.tsx
+++ b/packages/client/ui-deliverables/src/client/ReviewTab.tsx
@@ -7,11 +7,11 @@ import { useEffect, useMemo, useRef, useState } from 'react'
 import type { ReactNode, UIEvent } from 'react'
 import {
   Button, IconChevronDownOutlineRegular, IconCompareSplitOutlineRegular, IconInspectOutlineRegular,
-  IconNowrapFillRegular, IconRightUpOutlineRegular, IconWrapFillRegular, Menu, Tooltip,
+  IconNowrapFillRegular, IconWrapFillRegular, Menu, Tooltip,
   languageForPath, useCodeHighlighter,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { CodeHighlighter, HighlightSpan } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import { fileAddressFor } from '@deepseek-ai/dsh-util-workspace-path'
 import type { WorkspaceChangedFile, WorkspaceDiffHunk } from '@deepseek-ai/dsh-workspace-changes/types'
@@ -45,7 +45,7 @@ export interface ReviewInjected {
 
 /** The body's composed props: the tab it draws, its store, its injected face, and its copy. */
 export type ReviewTabProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsStore<ReturnType<typeof createReviewStore>>
-  & InjectFace<ReviewInjected> & PropsLocale<typeof NS>
+  & InjectFace<ReviewInjected> & PropsLocale<typeof NS> & PropsRenderSlots<'deliverables.review.file.actions'>
 
 /** One drawn line of a hunk with its line numbers on each side. */
 export interface DiffRow {
@@ -189,7 +189,7 @@ function Counts({ file, t }: { file: WorkspaceChangedFile } & PropsLocale<typeof
  */
 export function ReviewTab({
   useTabInfo, sessionId, useSessions, useStore, actions, useChangesSummary, useChangesDiff, usePresentedOpen, usePresentedHost,
-  loadChangesSummary, loadChangesDiff, reloadPresentedHost, openChanged, t,
+  loadChangesSummary, loadChangesDiff, reloadPresentedHost, openChanged, t, renderSlot,
 }: ReviewTabProps): ReactNode {
   const { tab } = useTabInfo()
   const { navigation, signal } = tab
@@ -266,11 +266,11 @@ export function ReviewTab({
             <button type="button" className={css.tool} aria-label={t('review.openFileAria', { name: file.display })} data-review-tool="open-file"
               onClick={() => { tab.actions.openResource(fileAddressFor(sessionId, cwd, file.path)) }}><IconInspectOutlineRegular /></button>
           </Tooltip>}
-          {file !== undefined && native && <Tooltip label={t(phase === 'error' ? 'diff.openNativeError' : 'diff.openNative')} side="bottom" delayMs={500}>
-            <button type="button" className={css.tool} disabled={phase === 'opening'} data-review-tool="open-native"
-              aria-label={t('diff.openNativeAria', { name: file.display })} data-error={phase === 'error' || undefined}
-              onClick={() => { void openChanged(sessionId, seq, index) }}><IconRightUpOutlineRegular /></button>
-          </Tooltip>}
+          {file !== undefined && renderSlot('deliverables.review.file.actions', {
+            actionUrl: changedFileUrl(sessionId, seq, index), available: native,
+            pending: phase === 'opening' || phase === 'revealing',
+            onAction: (action, application) => openChanged(sessionId, seq, index, action, application),
+          })}
         </span>
       </div>
       {summaryState === 'loading' && <p className={css.status} role="status">{t('diff.loading')}</p>}
diff --git a/packages/client/ui-deliverables/src/client/file-actions.ts b/packages/client/ui-deliverables/src/client/file-actions.ts
new file mode 100644
index 0000000000..1326f80b76
--- /dev/null
+++ b/packages/client/ui-deliverables/src/client/file-actions.ts
@@ -0,0 +1,27 @@
+/** Native file-action contribution shared by delivery cards and change review. */
+import type { PresentedOpenFailure } from './present-open.ts'
+import type { PresentedAction } from '../presented.ts'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** Open one file through its authorized Session event coordinates. */
+    'deliverables.file.actions': {
+      kind: 'list'
+      scope: 'session'
+      owner: {
+        /** Authenticated document-relative action route carrying Session event coordinates. */
+        readonly actionUrl: string
+        readonly available: boolean
+        readonly pending: boolean
+        /** Execute the selected native action and publish status on the owning file surface. */
+        readonly onAction: (action: PresentedAction, application?: string) => Promise<PresentedOpenFailure>
+      }
+    }
+    /** The same file actions owned by a changed-file review tab. */
+    'deliverables.review.file.actions': {
+      kind: 'list'
+      scope: 'session'
+      owner: SlotMap['deliverables.file.actions']['owner']
+    }
+  }
+}
diff --git a/packages/client/ui-deliverables/src/client/index.ts b/packages/client/ui-deliverables/src/client/index.ts
index e61596ea4b..f000547756 100644
--- a/packages/client/ui-deliverables/src/client/index.ts
+++ b/packages/client/ui-deliverables/src/client/index.ts
@@ -8,6 +8,7 @@
  * cap, and copy — so composing this plugin out of cordis.yml removes every
  * surface; the owning view renders an empty list and inert prose at zero cost.
  */
+import './file-actions.ts'
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type {} from '@deepseek-ai/dsh-client-connection/client'
@@ -63,13 +64,14 @@ export function apply(ctx: ClientContext): void {
       name: 'conversation.chat.turnTail',
       id: '@deepseek-ai/dsh-client-ui-deliverables',
       locale: NS,
+      children: { 'deliverables.file.actions': { kind: 'list', scope: 'session' } },
       inject: (): DeliverablesInjected => ({
         hooks: { presentedOpen: opener.state, presentedHost: opener.host, changesSummary: summaries.state,
           showCodeDiff: ctx.settingsScope.developerTools.enabled },
         reloadPresentedHost: () => opener.loadHost(),
         loadChangesSummary: (sessionId, seq) => summaries.load(sessionId, seq),
-        openPresented: (sessionId, seq, index, action) => opener.open(sessionId, seq, index, action),
-        openChanged: (sessionId, seq, index) => opener.openChanged(sessionId, seq, index),
+        openPresented: (sessionId, seq, index, action, application) => opener.open(sessionId, seq, index, action, application),
+        openChanged: (sessionId, seq, index, action, application) => opener.openChanged(sessionId, seq, index, action, application),
         openChangesReview: (coordinates, index) => {
           ctx.sidebarRight.openResource(changesReviewAddress(coordinates), { params: { index } })
         },
@@ -84,12 +86,13 @@ export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
     {
       name: 'sidebar.right.pane.tab', key: CHANGES_REVIEW_ID, locale: NS, store: createReviewStore(),
+      children: { 'deliverables.review.file.actions': { kind: 'list', scope: 'session' } },
       inject: (): ReviewInjected => ({
         hooks: { changesSummary: summaries.state, changesDiff: diffs.state, presentedOpen: opener.state, presentedHost: opener.host },
         loadChangesSummary: (sessionId, seq) => summaries.load(sessionId, seq),
         loadChangesDiff: (sessionId, seq, index) => diffs.load(sessionId, seq, index),
         reloadPresentedHost: () => opener.loadHost(),
-        openChanged: (sessionId, seq, index) => opener.openChanged(sessionId, seq, index),
+        openChanged: (sessionId, seq, index, action, application) => opener.openChanged(sessionId, seq, index, action, application),
       }),
     },
     ReviewTab,
diff --git a/packages/client/ui-deliverables/src/client/locales.ts b/packages/client/ui-deliverables/src/client/locales.ts
index 7eacc52c34..69e976fa06 100644
--- a/packages/client/ui-deliverables/src/client/locales.ts
+++ b/packages/client/ui-deliverables/src/client/locales.ts
@@ -15,12 +15,6 @@ export const zh = {
   'presented.unavailable': '此主机没有可用的桌面，无法使用外部程序打开文件或文件夹；文件仍可在侧边栏预览',
   'presented.retry': '重试',
   'presented.hostError': '无法读取主机桌面信息',
-  'presented.directory': '打开所在文件夹',
-  'presented.explorer': '在文件资源管理器中显示',
-  'presented.finder': '在 Finder 中显示',
-  'presented.defaultApp': '用默认应用打开',
-  'presented.more': '{name} 的更多文件操作',
-  'presented.action': '打开',
   'presented.preview': '在侧边栏预览',
   'presented.previewButton': '在侧边栏打开 {name}',
   'presented.previewCard': '在侧边栏预览 {name}',
@@ -29,7 +23,7 @@ export const zh = {
   'presented.collapse': '收起',
   'presented.collapseAria': '收起交付文件列表',
   'presented.opening': '正在打开…',
-  'presented.opened': '已在默认程序中打开',
+  'presented.opened': '已请求打开',
   'presented.error': '打开失败，点击重试',
   'presented.file': '文件',
   'row.title': '交付文件',
@@ -59,7 +53,6 @@ export const zh = {
   'review.wrapAria': '自动换行',
   'review.openFile': '在侧边栏打开整个文件',
   'review.openFileAria': '在侧边栏打开 {name}',
-  'diff.openNativeAria': '用默认应用打开 {name}',
   'diff.loading': '正在读取改动…',
   'diff.missing': '这轮改动的内容已不可用',
   'diff.error': '无法读取改动',
@@ -70,8 +63,6 @@ export const zh = {
   'diff.unchanged': '两侧内容相同',
   'diff.coarse': '逐行对比超时，按整个文件替换显示',
   'diff.truncated': '只显示前 {count} 行',
-  'diff.openNative': '用默认应用打开',
-  'diff.openNativeError': '打开失败，点击重试',
 }
 
 /** English dictionary (same key set). */
@@ -86,12 +77,6 @@ export const en: Record<DeliverablesKey, string> = {
   'presented.unavailable': 'This Host has no desktop available to open files or folders in external apps. Files can still be previewed in the sidebar.',
   'presented.retry': 'Retry',
   'presented.hostError': 'Could not read the Host desktop information',
-  'presented.directory': 'Open containing folder',
-  'presented.explorer': 'Show in File Explorer',
-  'presented.finder': 'Show in Finder',
-  'presented.defaultApp': 'Open in default app',
-  'presented.more': 'More file actions for {name}',
-  'presented.action': 'Open',
   'presented.preview': 'Preview in sidebar',
   'presented.previewButton': 'Open {name} in sidebar',
   'presented.previewCard': 'Preview {name} in sidebar',
@@ -100,7 +85,7 @@ export const en: Record<DeliverablesKey, string> = {
   'presented.collapse': 'Collapse',
   'presented.collapseAria': 'Collapse delivered files',
   'presented.opening': 'Opening…',
-  'presented.opened': 'Opened in default app',
+  'presented.opened': 'Open requested',
   'presented.error': 'Could not open. Click to retry.',
   'presented.file': 'File',
   'row.title': 'Present files',
@@ -130,7 +115,6 @@ export const en: Record<DeliverablesKey, string> = {
   'review.wrapAria': 'Line wrap',
   'review.openFile': 'Open the whole file in the sidebar',
   'review.openFileAria': 'Open {name} in sidebar',
-  'diff.openNativeAria': 'Open {name} in default app',
   'diff.loading': 'Reading changes…',
   'diff.missing': 'The contents of this turn’s changes are no longer available',
   'diff.error': 'Could not read the changes',
@@ -141,8 +125,6 @@ export const en: Record<DeliverablesKey, string> = {
   'diff.unchanged': 'Both sides hold the same lines',
   'diff.coarse': 'Line comparison timed out; shown as a whole-file replacement',
   'diff.truncated': 'Showing the first {count} lines',
-  'diff.openNative': 'Open in default app',
-  'diff.openNativeError': 'Could not open. Click to retry.',
 }
 
 /** Union of this namespace's dictionary keys. */
diff --git a/packages/client/ui-deliverables/src/client/present-open.ts b/packages/client/ui-deliverables/src/client/present-open.ts
index d724816d19..c116de3a44 100644
--- a/packages/client/ui-deliverables/src/client/present-open.ts
+++ b/packages/client/ui-deliverables/src/client/present-open.ts
@@ -4,7 +4,15 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { changedFileUrl } from '../changes.ts'
 import { presentedFileUrl, PRESENT_HOST_ROUTE, isPresentedHost, type PresentedAction, type PresentedHost } from '../presented.ts'
 
-/** State of the latest explicit open gesture for one saved file. */
+/** Success feedback remains fully visible for five seconds before fading. */
+export const PRESENTED_SUCCESS_HOLD_MS = 5000
+/** Fade interval shared by the card animation and status expiry. */
+export const PRESENTED_SUCCESS_FADE_MS = 200
+
+/** Failure feedback for the shared native opening control. */
+export type PresentedOpenFailure = 'openError' | 'revealError' | null
+
+/** State published on the owning file card. */
 export type PresentedOpenPhase = 'opening' | 'opened' | 'revealing' | 'revealed' | 'error' | 'revealError' | 'nativeUnavailable'
 
 /** One browser plugin's file-open requests, cancelled when that plugin is disposed. */
@@ -13,10 +21,11 @@ export class PresentedOpenController {
   readonly state = createSnapshotStore<Record<string, PresentedOpenPhase | undefined>>({})
   /** Native destination metadata, or a retryable read failure. */
   readonly host = createSnapshotStore<PresentedHost | 'error' | null>(null)
+  private readonly expiry = new Map<string, ReturnType<typeof setTimeout>>()
   private loading: Promise<void> | undefined
   private metadata = new AbortController()
   private readonly lifetime = new AbortController()
-  private readonly pending = new Set<Promise<void>>()
+  private readonly pending = new Set<Promise<void | PresentedOpenFailure>>()
 
   /**
    * Open a declared file once while a request for the same coordinates is pending.
@@ -25,10 +34,13 @@ export class PresentedOpenController {
    * @param seq - durable delivery event sequence.
    * @param index - original file index within that event.
    * @param action - default application open or file-manager reveal.
-   * @returns after the Host acknowledges opening or the error state is published.
+   * @param application - registered handler identifier for an explicit application choice.
+   * @returns null after a successful handoff, or the failure to announce after publishing card status.
    */
-  open(sessionId: SessionId, seq: number, index: number, action: PresentedAction = 'open'): Promise<void> {
-    return this.openUrl(presentedFileUrl(sessionId, seq, index), action)
+  open(
+    sessionId: SessionId, seq: number, index: number, action: PresentedAction = 'open', application?: string,
+  ): Promise<PresentedOpenFailure> {
+    return this.openUrl(presentedFileUrl(sessionId, seq, index), action, application)
   }
 
   /**
@@ -36,20 +48,25 @@ export class PresentedOpenController {
    * @param sessionId - viewed Session.
    * @param seq - durable workspace/changes event sequence.
    * @param index - original file index within that event.
-   * @returns after the Host acknowledges opening or the error state is published.
+   * @param action - application open or file-manager reveal.
+   * @param application - registered handler identifier for an explicit application choice.
+   * @returns null after a successful handoff, or the failure to announce after publishing card status.
    */
-  openChanged(sessionId: SessionId, seq: number, index: number): Promise<void> {
-    return this.openUrl(changedFileUrl(sessionId, seq, index), 'open')
+  openChanged(
+    sessionId: SessionId, seq: number, index: number, action: PresentedAction = 'open', application?: string,
+  ): Promise<PresentedOpenFailure> {
+    return this.openUrl(changedFileUrl(sessionId, seq, index), action, application)
   }
 
-  private async openUrl(url: string, action: PresentedAction): Promise<void> {
+  private async openUrl(url: string, action: PresentedAction, application?: string): Promise<PresentedOpenFailure> {
     const phase = this.state.getSnapshot()[url]
-    if (this.lifetime.signal.aborted || phase === 'opening' || phase === 'revealing') return
+    if (this.lifetime.signal.aborted || phase === 'opening' || phase === 'revealing') return null
+    this.clearExpiry(url)
     this.state.update((state) => { state[url] = action === 'open' ? 'opening' : 'revealing' })
-    const task = this.request(url, action)
+    const task = this.request(url, action, application)
     this.pending.add(task)
     try {
-      await task
+      return await task
     } finally {
       this.pending.delete(task)
     }
@@ -100,19 +117,36 @@ export class PresentedOpenController {
   /** Cancel outstanding requests and wait until no request can publish state. */
   async dispose(): Promise<void> {
     this.lifetime.abort()
+    for (const url of this.expiry.keys()) this.clearExpiry(url)
     await Promise.all(this.pending)
   }
 
-  private async request(url: string, action: PresentedAction): Promise<void> {
+  private clearExpiry(url: string): void {
+    clearTimeout(this.expiry.get(url))
+    this.expiry.delete(url)
+  }
+
+  private async request(url: string, action: PresentedAction, application?: string): Promise<PresentedOpenFailure> {
     const failure = action === 'open' ? 'error' : 'revealError'
     let phase: PresentedOpenPhase = action === 'open' ? 'opened' : 'revealed'
     try {
-      const response = await fetch(action === 'open' ? url : `${url}&action=reveal`, { method: 'POST', signal: this.lifetime.signal })
+      const target = action === 'reveal' ? `${url}&action=reveal`
+        : application === undefined ? url : `${url}&application=${encodeURIComponent(application)}`
+      const response = await fetch(target, { method: 'POST', signal: this.lifetime.signal })
       if (!response.ok) phase = response.status === 422 ? 'nativeUnavailable' : failure
     } catch {
       // Transport failures share the retryable card state with Host open failures.
       phase = failure
     }
-    if (!this.lifetime.signal.aborted) this.state.update((state) => { state[url] = phase })
+    if (!this.lifetime.signal.aborted) {
+      if (phase === 'opened' || phase === 'revealed') {
+        this.expiry.set(url, setTimeout(() => {
+          this.expiry.delete(url)
+          this.state.update((state) => { Reflect.deleteProperty(state, url) })
+        }, PRESENTED_SUCCESS_HOLD_MS + PRESENTED_SUCCESS_FADE_MS))
+      }
+      this.state.update((state) => { state[url] = phase })
+    }
+    return phase === 'opened' || phase === 'revealed' ? null : action === 'reveal' ? 'revealError' : 'openError'
   }
 }
diff --git a/packages/client/ui-deliverables/src/present-open.ts b/packages/client/ui-deliverables/src/present-open.ts
index 56b88f0651..6023625644 100644
--- a/packages/client/ui-deliverables/src/present-open.ts
+++ b/packages/client/ui-deliverables/src/present-open.ts
@@ -34,12 +34,12 @@ export function registerPresentOpen(ctx: Context): void {
     await Promise.allSettled(pending)
   })
   const routes = [
-    [PRESENT_OPEN_PATH, 'POST', handlePresentOpen], [CHANGES_OPEN_PATH, 'POST', handleChangesOpen], [CHANGES_DIFF_PATH, 'GET', handleChangesDiff],
+    [PRESENT_OPEN_PATH, ['GET', 'POST'], handlePresentOpen], [CHANGES_OPEN_PATH, ['GET', 'POST'], handleChangesOpen], [CHANGES_DIFF_PATH, ['GET'], handleChangesDiff],
   ] as const
-  for (const [path, method, handler] of routes) {
+  for (const [path, methods, handler] of routes) {
     ctx.connection.fetch.register({
       path,
-      methods: [method],
+      methods: [...methods],
       requestBody: 'buffered',
       fetch: (request) => {
         const task = handler(ctx, new Request(request, {
@@ -91,7 +91,13 @@ async function openVerified(ctx: Context, request: Request, path: string, action
     return new Response('Path has no verified Host path.', { status: 422 })
   }
   request.signal.throwIfAborted()
-  await ctx.sessionController.openWorkspacePath({ path, ...(action === 'reveal' ? { action } : {}) }, request.signal)
+  if (request.method === 'GET') {
+    return Response.json(await ctx.sessionController.workspacePathApplications({ path }, request.signal),
+      { headers: { 'cache-control': 'no-store' } })
+  }
+  const application = new URL(request.url).searchParams.get('application')
+  await ctx.sessionController.openWorkspacePath({ path, ...(action === 'reveal' ? { action }
+    : application === null ? {} : { application }) }, request.signal)
   return new Response(null, { status: 204, headers: { 'cache-control': 'no-store' } })
 }
 
@@ -159,6 +165,8 @@ async function handleChangesDiff(ctx: Context, request: Request): Promise<Respon
 }
 
 async function handleChangesOpen(ctx: Context, request: Request): Promise<Response> {
+  const action = new URL(request.url).searchParams.get('action') ?? 'open'
+  if (action !== 'open' && action !== 'reveal') return new Response('Invalid file action.', { status: 400 })
   const coordinates = changedFileCoordinates(request)
   if (coordinates instanceof Response) return coordinates
   const { id, seq, index } = coordinates
@@ -171,7 +179,7 @@ async function handleChangesOpen(ctx: Context, request: Request): Promise<Respon
     const file = changes.files[index]
     if (file === undefined) return new Response('Changed file not found in this summary.', { status: 404 })
     const { absolutePath: path } = await ctx.workspaceFiles.stat({ sessionId: id, workspaceRoot }, file.path, request.signal)
-    return await openVerified(ctx, request, path, 'open')
+    return await openVerified(ctx, request, path, action)
   } catch (error: unknown) {
     request.signal.throwIfAborted()
     return new Response('Changed file unavailable.', { status: failureStatus(error) })
diff --git a/packages/client/ui-deliverables/tests/changes-open.host.spec.ts b/packages/client/ui-deliverables/tests/changes-open.host.spec.ts
index b391263de5..6fda6fed4a 100644
--- a/packages/client/ui-deliverables/tests/changes-open.host.spec.ts
+++ b/packages/client/ui-deliverables/tests/changes-open.host.spec.ts
@@ -61,7 +61,8 @@ async function fixture() {
     sessionId === 'owner' && seq === 9 && index === 0 ? comparison : undefined)
   ctx.provide('workspaceChanges', { summary, diff })
   const opener = vi.fn(async (_request: { path: string; action?: 'reveal' }, _signal: AbortSignal) => ({ opened: true as const }))
-  ctx.provide('sessionController', { openWorkspacePath: opener, workspaceDesktop: () => ({ name: 'desktop', available: true, fileManager: 'finder' }) } as never)
+  const applications = vi.fn(async () => [{ id: 'player', name: 'Player', default: true, icon: null }])
+  ctx.provide('sessionController', { workspacePathApplications: applications, openWorkspacePath: opener, workspaceDesktop: () => ({ name: 'desktop', available: true, fileManager: 'finder' }) } as never)
   const connection = new HostConnectionService(ctx, [], {} as BrowserAuth)
   await ctx.plugin({
     inject: ['connection', 'sessionQuery', 'sessionController', 'workspaceFiles', 'fs', 'sandboxPolicy', 'workspaceChanges'],
@@ -71,7 +72,7 @@ async function fixture() {
   const open = (query = '?sessionId=owner&seq=9&index=0') => handler.fetch(new Request(`http://localhost${CHANGES_OPEN_PATH}${query}`, { method: 'POST' }))
   const read = (query = '?sessionId=owner&seq=9') => handler.fetch(new Request(`http://localhost${CHANGED_FILES_PATH}${query}`))
   const compare = (query = '?sessionId=owner&seq=9&index=0') => handler.fetch(new Request(`http://localhost${CHANGES_DIFF_PATH}${query}`))
-  return { root, cwd, ctx, data, readEvent, open, read, compare, comparison, diff, opener, outside, summary }
+  return { handler, applications, root, cwd, ctx, data, readEvent, open, read, compare, comparison, diff, opener, outside, summary }
 }
 
 describe('change summary route', () => {
@@ -199,3 +200,26 @@ describe('changed files native open route', () => {
     expect(isChangesEvent(null)).toBe(false)
   })
 })
+
+
+it('queries handlers only after file authorization and forwards explicit application choices', async () => {
+  const { handler, applications, opener, open, ctx } = await fixture()
+  const url = 'http://localhost/api/changes.open?sessionId=owner&seq=9&index=0'
+  const response = await handler.fetch(new Request(url))
+  expect(response.status).toBe(200)
+  expect(await response.json()).toEqual([{ id: 'player', name: 'Player', default: true, icon: null }])
+  expect(opener).not.toHaveBeenCalled()
+  expect((await open('?sessionId=owner&seq=9&index=0&application=player')).status).toBe(204)
+  expect(opener.mock.lastCall?.[0]).toMatchObject({ application: 'player' })
+  expect((await handler.fetch(new Request(url.replace('index=0', 'index=999')))).status).toBe(404)
+  vi.spyOn(ctx.fs, 'processPathFromHostPath').mockReturnValue(undefined)
+  expect((await handler.fetch(new Request(url))).status).toBe(422)
+  expect(applications).toHaveBeenCalledOnce()
+})
+
+
+it('rejects an unsupported changed-file action before invoking the desktop', async () => {
+  const { open, opener } = await fixture()
+  expect((await open('?sessionId=owner&seq=9&index=0&action=remove')).status).toBe(400)
+  expect(opener).not.toHaveBeenCalled()
+})
diff --git a/packages/client/ui-deliverables/tests/deliverables.client.spec.tsx b/packages/client/ui-deliverables/tests/deliverables.client.spec.tsx
index c6cb256373..831c32a74d 100644
--- a/packages/client/ui-deliverables/tests/deliverables.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/deliverables.client.spec.tsx
@@ -6,6 +6,7 @@
  * registrations' fiber-teardown removal (HMR safety) against the real
  * SlotRegistry.
  */
+import { renderFileActions } from './file-actions.tsx'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { Context } from '@deepseek-ai/cordis'
 import { cleanup, fireEvent, render, within } from '@testing-library/react'
@@ -39,8 +40,10 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 
 function openProps(controller = new PresentedOpenController(), summaries = new ChangesSummaryStore()) {
   controller.host.set({ name: 'desktop', available: true, fileManager: 'finder' })
-  const sessions: SessionListState = { ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {} }
+  const sessions: SessionListState = { ids: [], byId: {}, phase: 'ready', projectionsBySession: {} }
   return {
+    SessionProvider: ({ children }: { children?: import('react').ReactNode }) => <>{children}</>,
+    renderSlot: renderFileActions,
     useShowCodeDiff: <T,>(select: (value: boolean) => T): T => select(true),
     useSessions: <T,>(select: (state: SessionListState) => T): T => select(sessions),
     reloadPresentedHost: vi.fn(() => controller.loadHost()),
@@ -494,7 +497,7 @@ describe('ChangedFiles card', () => {
     controller = new PresentedOpenController(), locale = en, matched = { changes, presented: [] as never[] }, summaries = servedStore(),
   ) {
     const props = openProps(controller, summaries)
-    props.openChanged.mockResolvedValue(undefined)
+    props.openChanged.mockResolvedValue(null)
     const openFile = vi.fn<(path: string) => void>()
     const view = render(<Deliverables {...props} matched={matched} openFile={openFile} sessionId={SessionId('child-session')} t={makeTranslate(locale)} />)
     return { props, openFile, view }
@@ -845,7 +848,7 @@ describe('presented files', () => {
     const owner = tailOwner(deliverablesOf(value), 3, preview)
     const matched = selectDeliverables(owner)!
     const props = openProps()
-    props.openPresented.mockResolvedValue(undefined)
+    props.openPresented.mockResolvedValue(null)
     const view = render(<Deliverables {...props} matched={matched} openFile={owner.openFile} sessionId={SessionId('child-session')} t={makeTranslate(en)} />)
     expect(view.container.querySelectorAll('[data-presented-file]')).toHaveLength(4)
     const expand = view.getByRole('button', { name: 'Show all 8 delivered files' })
@@ -855,12 +858,10 @@ describe('presented files', () => {
     expect(view.getByRole('button', { name: 'Collapse delivered files' }).getAttribute('aria-expanded')).toBe('true')
     expect(view.queryByRole('link')).toBeNull()
     fireEvent.click(view.getByRole('button', { name: 'Preview report-0.docx in sidebar' }))
-    fireEvent.click(view.getByRole('button', { name: 'Open report-0.docx in sidebar' }))
-    expect(preview).toHaveBeenCalledTimes(2)
+    expect(preview).toHaveBeenCalledTimes(1)
     expect(preview).toHaveBeenLastCalledWith('report-0.docx')
-    fireEvent.click(view.getByRole('button', { name: 'More file actions for report-0.docx' }))
-    fireEvent.click(view.getByRole('menuitem', { name: 'Open in default app' }))
-    expect(props.openPresented).toHaveBeenCalledWith('child-session', 2, 0, 'open')
+    fireEvent.click(view.getAllByRole('button', { name: 'Native file action' })[0]!)
+    expect(props.openPresented).toHaveBeenCalledWith('child-session', 2, 0, 'open', undefined)
     fireEvent.click(view.getByRole('button', { name: 'Collapse delivered files' }))
     expect(view.container.querySelectorAll('[data-presented-file]')).toHaveLength(4)
     expect(view.container.querySelector('[data-changed-files]')).toBeNull()
@@ -934,7 +935,7 @@ it.each(['opening', 'opened', 'error'] as const)('shows the %s state and permits
     { path: 'report.txt', seq: 2, index: 0 },
   ] }} openFile={() => {}} sessionId={SessionId('session')} t={makeTranslate(en)} />)
   expect(view.getByText(en[`presented.${phase}`])).toBeTruthy()
-  expect((view.getByRole('button', { name: 'More file actions for report.txt' }) as HTMLButtonElement).disabled).toBe(phase === 'opening')
+  expect((view.getByRole('button', { name: 'Native file action' }) as HTMLButtonElement).disabled).toBe(phase === 'opening')
 })
 
 
diff --git a/packages/client/ui-deliverables/tests/file-actions.tsx b/packages/client/ui-deliverables/tests/file-actions.tsx
new file mode 100644
index 0000000000..d1904bea6a
--- /dev/null
+++ b/packages/client/ui-deliverables/tests/file-actions.tsx
@@ -0,0 +1,10 @@
+/** Capture delivery action ownership without duplicating the opening-control implementation. */
+import type { PropsRenderSlots, SlotMap } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '../src/client/index.ts'
+
+/** Slot renderer exposing the owning route and gesture for component tests. */
+export const renderFileActions: PropsRenderSlots<'deliverables.file.actions' | 'deliverables.review.file.actions'>['renderSlot'] = (_name: string, input: object) => {
+  const props = input as SlotMap['deliverables.file.actions']['owner']
+  return props.available ? <button type="button" data-action-url={props.actionUrl} disabled={props.pending}
+    onClick={() => { void props.onAction('open') }}>Native file action</button> : null
+}
diff --git a/packages/client/ui-deliverables/tests/present-open.client.spec.ts b/packages/client/ui-deliverables/tests/present-open.client.spec.ts
index 35fd278616..f6910df3f9 100644
--- a/packages/client/ui-deliverables/tests/present-open.client.spec.ts
+++ b/packages/client/ui-deliverables/tests/present-open.client.spec.ts
@@ -3,7 +3,7 @@ import { afterEach, expect, it, vi } from 'vitest'
 import { SessionId } from '@deepseek-ai/dsh-session/types'
 import { PresentedOpenController } from '../src/client/present-open.ts'
 
-afterEach(() => { vi.unstubAllGlobals() })
+afterEach(() => { vi.unstubAllGlobals(); vi.useRealTimers() })
 
 const id = SessionId('fork')
 const url = 'api/present.open?sessionId=fork&seq=2&index=1'
@@ -174,3 +174,68 @@ it.each(['open', 'reveal'] as const)('reports an unavailable Host path for %s wh
   expect(controller.state.getSnapshot()[url]).toBe('nativeUnavailable')
   await controller.dispose()
 })
+
+
+it('encodes an explicit application identifier without changing the file coordinates', async () => {
+  const fetcher = vi.fn(async () => new Response(null, { status: 204 }))
+  vi.stubGlobal('fetch', fetcher)
+  const controller = new PresentedOpenController()
+  expect(await controller.open(id, 2, 1, 'open', '/Apps/A&B.app')).toBeNull()
+  expect(fetcher).toHaveBeenCalledWith(`${url}&application=%2FApps%2FA%26B.app`, { method: 'POST', signal: expect.any(AbortSignal) as AbortSignal })
+  await controller.dispose()
+})
+
+
+it.each(['open', 'reveal'] as const)('expires successful %s feedback after five seconds and its fade', async (action) => {
+  vi.useFakeTimers()
+  vi.stubGlobal('fetch', vi.fn(async () => new Response(null, { status: 204 })))
+  const controller = new PresentedOpenController()
+  await controller.open(id, 2, 1, action)
+  await vi.advanceTimersByTimeAsync(5000)
+  expect(controller.state.getSnapshot()[url]).toBe(action === 'open' ? 'opened' : 'revealed')
+  await vi.advanceTimersByTimeAsync(200)
+  expect(controller.state.getSnapshot()[url]).toBeUndefined()
+  await controller.dispose()
+})
+
+it('cancels an earlier success expiry when the next action fails', async () => {
+  vi.useFakeTimers()
+  const fetcher = vi.fn().mockResolvedValueOnce(new Response(null, { status: 204 }))
+    .mockResolvedValueOnce(new Response(null, { status: 500 }))
+  vi.stubGlobal('fetch', fetcher)
+  const controller = new PresentedOpenController()
+  await controller.open(id, 2, 1)
+  await vi.advanceTimersByTimeAsync(4000)
+  await controller.open(id, 2, 1)
+  await vi.advanceTimersByTimeAsync(6000)
+  expect(controller.state.getSnapshot()[url]).toBe('error')
+  await controller.dispose()
+})
+
+it('cancels success expiry when its controller is disposed', async () => {
+  vi.useFakeTimers()
+  vi.stubGlobal('fetch', vi.fn(async () => new Response(null, { status: 204 })))
+  const controller = new PresentedOpenController()
+  await controller.open(id, 2, 1)
+  const state = controller.state.getSnapshot()
+  await controller.dispose()
+  await vi.advanceTimersByTimeAsync(6000)
+  expect(controller.state.getSnapshot()).toBe(state)
+})
+
+
+it('owns the expiry before notifying subscribers that can dispose the controller', async () => {
+  vi.useFakeTimers()
+  vi.stubGlobal('fetch', vi.fn(async () => new Response(null, { status: 204 })))
+  const controller = new PresentedOpenController()
+  let disposal: Promise<void> | undefined
+  const release = controller.state.subscribe(() => {
+    if (controller.state.getSnapshot()[url] === 'opened') disposal = controller.dispose()
+  })
+  await controller.open(id, 2, 1)
+  await disposal
+  const state = controller.state.getSnapshot()
+  await vi.advanceTimersByTimeAsync(6000)
+  expect(controller.state.getSnapshot()).toBe(state)
+  release()
+})
diff --git a/packages/client/ui-deliverables/tests/present-open.host.spec.ts b/packages/client/ui-deliverables/tests/present-open.host.spec.ts
index 072529cdde..b313ee0aa8 100644
--- a/packages/client/ui-deliverables/tests/present-open.host.spec.ts
+++ b/packages/client/ui-deliverables/tests/present-open.host.spec.ts
@@ -46,7 +46,8 @@ async function fixture() {
   })
   ctx.provide('sessionQuery', { readEvent } as never)
   const opener = vi.fn(async (_request: { path: string; action?: 'reveal' }, _signal: AbortSignal) => ({ opened: true as const }))
-  ctx.provide('sessionController', { resolveAgent, openWorkspacePath: opener, workspaceDesktop: () => ({ name: 'desktop', available: true, fileManager: 'finder' }) } as never)
+  const applications = vi.fn(async () => [{ id: 'player', name: 'Player', default: true, icon: null }])
+  ctx.provide('sessionController', { workspacePathApplications: applications, resolveAgent, openWorkspacePath: opener, workspaceDesktop: () => ({ name: 'desktop', available: true, fileManager: 'finder' }) } as never)
   const connection = new HostConnectionService(ctx, [], {} as BrowserAuth)
   const fiber = ctx.plugin({ inject: ['connection', 'sessionQuery', 'sessionController', 'workspaceFiles', 'fs', 'sandboxPolicy'], apply: registerPresentOpen })
   await fiber
@@ -54,7 +55,7 @@ async function fixture() {
   const open = (query = '?sessionId=owner&seq=7&index=0', signal?: AbortSignal) => handler.fetch(new Request(
     `http://localhost${PRESENT_OPEN_PATH}${query}`, { method: 'POST', signal: signal ?? null },
   ))
-  return { root, cwd, ctx, fiber, file, session, readEvent, open, opener, handler, resolveAgent }
+  return { applications, root, cwd, ctx, fiber, file, session, readEvent, open, opener, handler, resolveAgent }
 }
 
 describe('Presented workspace file native open route', () => {
@@ -62,7 +63,7 @@ describe('Presented workspace file native open route', () => {
     const { cwd, open, file, fiber, opener, handler, ctx } = await fixture()
     const source = await realpath(join(cwd, file.path))
     expect(presentedFileUrl(SessionId('owner'), 7, 0)).toBe('api/present.open?sessionId=owner&seq=7&index=0')
-    expect((await handler.fetch(new Request(`http://localhost${PRESENT_OPEN_PATH}`))).status).toBe(404)
+    expect((await handler.fetch(new Request(`http://localhost${PRESENT_OPEN_PATH}`))).status).toBe(400)
     expect((await handler.fetch(new Request('http://localhost/api/present.download?sessionId=owner&seq=7&index=0'))).status).toBe(404)
     for (const contents of ['current source', 'edited source']) {
       await writeFile(source, contents)
@@ -233,3 +234,19 @@ it('uses the deployment workspace root when the viewed Session has no cwd', asyn
   expect((await open()).status).toBe(204)
   expect(opener.mock.lastCall?.[0].path).toBe(await realpath(join(cwd, file.path)))
 })
+
+
+it('queries handlers only after file authorization and forwards explicit application choices', async () => {
+  const { handler, applications, opener, open, ctx } = await fixture()
+  const url = 'http://localhost/api/present.open?sessionId=owner&seq=7&index=0'
+  const response = await handler.fetch(new Request(url))
+  expect(response.status).toBe(200)
+  expect(await response.json()).toEqual([{ id: 'player', name: 'Player', default: true, icon: null }])
+  expect(opener).not.toHaveBeenCalled()
+  expect((await open('?sessionId=owner&seq=7&index=0&application=player')).status).toBe(204)
+  expect(opener.mock.lastCall?.[0]).toMatchObject({ application: 'player' })
+  expect((await handler.fetch(new Request(url.replace('index=0', 'index=999')))).status).toBe(404)
+  vi.spyOn(ctx.fs, 'processPathFromHostPath').mockReturnValue(undefined)
+  expect((await handler.fetch(new Request(url))).status).toBe(422)
+  expect(applications).toHaveBeenCalledOnce()
+})
diff --git a/packages/client/ui-deliverables/tests/presented-file-card.client.spec.tsx b/packages/client/ui-deliverables/tests/presented-file-card.client.spec.tsx
index 28207b5a29..62a017f33a 100644
--- a/packages/client/ui-deliverables/tests/presented-file-card.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/presented-file-card.client.spec.tsx
@@ -13,66 +13,9 @@ const props = () => ({
   host: { name: 'remote-desktop', available: true, fileManager: 'finder' as const },
   phase: undefined,
   onPreview: vi.fn(),
-  onAction: vi.fn(),
+  actions: <button type="button">Native file action</button>,
   t: makeTranslate(en),
 })
-
-it.each([
-  ['finder', 'Show in Finder'], ['explorer', 'Show in File Explorer'], ['directory', 'Open containing folder'],
-] as const)('uses the Host %s action and closes the menu after selection', (fileManager, label) => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} host={{ ...p.host, fileManager }} />)
-  fireEvent.click(view.getByRole('button', { name: 'More file actions for out/report.pdf' }))
-  fireEvent.click(view.getByRole('menuitem', { name: new RegExp(label) }))
-  expect(p.onAction).toHaveBeenCalledWith('reveal')
-  expect(view.queryByRole('menu')).toBeNull()
-  fireEvent.click(view.getByRole('button', { name: 'More file actions for out/report.pdf' }))
-  fireEvent.click(view.getByRole('menuitem', { name: /Open in default app/ }))
-  expect(p.onAction).toHaveBeenLastCalledWith('open')
-  expect(p.onAction).toHaveBeenCalledTimes(2)
-})
-
-it('dismisses the menu with Escape or an outside click without launching anything', () => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} />)
-  const trigger = view.getByRole('button', { name: 'More file actions for out/report.pdf' })
-  fireEvent.click(trigger)
-  fireEvent.keyDown(document, { key: 'Escape' })
-  expect(view.queryByRole('menu')).toBeNull()
-  fireEvent.click(trigger)
-  fireEvent.pointerDown(document.body)
-  expect(view.queryByRole('menu')).toBeNull()
-  expect(p.onAction).not.toHaveBeenCalled()
-})
-
-it.each(['opening', 'revealing'] as const)('keeps sidebar previews available while the native action is %s', (phase) => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} phase={phase} />)
-  expect((view.getByRole('button', { name: 'More file actions for out/report.pdf' }) as HTMLButtonElement).disabled).toBe(true)
-  fireEvent.click(view.getByRole('button', { name: 'Preview out/report.pdf in sidebar' }))
-  fireEvent.click(view.getByRole('button', { name: 'Open out/report.pdf in sidebar' }))
-  expect(p.onPreview).toHaveBeenCalledTimes(2)
-  expect(p.onAction).not.toHaveBeenCalled()
-})
-
-it('keeps the native menu disabled until a desktop is available', () => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} host={null} />)
-  expect((view.getByRole('button', { name: 'More file actions for out/report.pdf' }) as HTMLButtonElement).disabled).toBe(true)
-  expect((view.getByRole('button', { name: 'Open out/report.pdf in sidebar' }) as HTMLButtonElement).disabled).toBe(false)
-  view.rerender(<PresentedFileCard {...p} host={{ ...p.host, available: false, fileManager: null }} />)
-  expect((view.getByRole('button', { name: 'More file actions for out/report.pdf' }) as HTMLButtonElement).disabled).toBe(true)
-})
-
-it('opens the right sidebar from either the card or its primary button', () => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} />)
-  fireEvent.click(view.getByRole('button', { name: 'Preview out/report.pdf in sidebar' }))
-  fireEvent.click(view.getByRole('button', { name: 'Open out/report.pdf in sidebar' }))
-  expect(p.onPreview).toHaveBeenCalledTimes(2)
-  expect(p.onAction).not.toHaveBeenCalled()
-})
-
 it('localizes reveal failures and accurately reports a directory-only action', () => {
   const p = props()
   const view = render(<PresentedFileCard {...p} phase="revealError" t={makeTranslate(zh)} />)
@@ -84,36 +27,12 @@ it('localizes reveal failures and accurately reports a directory-only action', (
 })
 
 
-it('supports keyboard selection and returns focus to the trigger on Escape', () => {
-  const view = render(<PresentedFileCard {...props()} />)
-  const trigger = view.getByRole('button', { name: 'More file actions for out/report.pdf' })
-  fireEvent.click(trigger)
-  const items = view.getAllByRole('menuitem')
-  expect(document.activeElement).toBe(items[0])
-  fireEvent.keyDown(document.activeElement!, { key: 'ArrowDown' })
-  expect(document.activeElement).toBe(items[1])
-  fireEvent.keyDown(document.activeElement!, { key: 'ArrowDown' })
-  expect(document.activeElement).toBe(items[0])
-  fireEvent.keyDown(document.activeElement!, { key: 'End' })
-  expect(document.activeElement).toBe(items[1])
-  fireEvent.keyDown(document.activeElement!, { key: 'ArrowUp' })
-  expect(document.activeElement).toBe(items[0])
-  fireEvent.keyDown(document.activeElement!, { key: 'Home' })
-  expect(document.activeElement).toBe(items[0])
-  fireEvent.keyDown(document.activeElement!, { key: 'Escape' })
-  expect(document.activeElement).toBe(trigger)
-})
-
-
 it('shows the basename while retaining the full location for hover and actions', () => {
   const p = props()
   const path = '/work/reports/result.pdf'
   const view = render(<PresentedFileCard {...p} cwd="/work" file={{ ...p.file, path }} />)
   expect(view.getByTitle(path)).toBeTruthy()
   expect(view.getByText('result.pdf')).toBeTruthy()
-  fireEvent.click(view.getByRole('button', { name: `More file actions for ${path}` }))
-  fireEvent.click(view.getByRole('menuitem', { name: 'Open in default app' }))
-  expect(p.onAction).toHaveBeenCalledWith('open')
   view.rerender(<PresentedFileCard {...p} cwd="/work" />)
   expect(view.getByTitle('/work/out/report.pdf')).toBeTruthy()
   expect(view.getByText('report.pdf')).toBeTruthy()
@@ -130,31 +49,6 @@ it.each([
 })
 
 
-it('does not reopen a menu after a shared native request settles', () => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} />)
-  fireEvent.click(view.getByRole('button', { name: 'More file actions for out/report.pdf' }))
-  expect(view.getByRole('menu')).toBeTruthy()
-  view.rerender(<PresentedFileCard {...p} phase="opening" />)
-  expect(view.queryByRole('menu')).toBeNull()
-  view.rerender(<PresentedFileCard {...p} phase="opened" />)
-  expect(view.queryByRole('menu')).toBeNull()
-})
-
-it('keeps focus on the available preview button after selecting a native action', () => {
-  const p = props()
-  const view = render(<PresentedFileCard {...p} />)
-  fireEvent.click(view.getByRole('button', { name: 'More file actions for out/report.pdf' }))
-  const item = view.getByRole('menuitem', { name: 'Show in Finder' })
-  item.focus()
-  fireEvent.click(item)
-  view.rerender(<PresentedFileCard {...p} phase="revealing" />)
-  const preview = view.getByRole('button', { name: 'Open out/report.pdf in sidebar' })
-  expect(document.activeElement).toBe(preview)
-  view.rerender(<PresentedFileCard {...p} phase="revealed" />)
-  expect(document.activeElement).toBe(preview)
-})
-
 it.each([en, zh])('distinguishes directory-only progress and errors in each locale', (dictionary) => {
   const p = { ...props(), t: makeTranslate(dictionary) }
   const view = render(<PresentedFileCard {...p} phase="revealing" />)
@@ -164,3 +58,15 @@ it.each([en, zh])('distinguishes directory-only progress and errors in each loca
   view.rerender(<PresentedFileCard {...p} phase="revealError" host={{ ...p.host, fileManager: 'directory' }} />)
   expect(view.getByText(dictionary['presented.directoryError'])).toBeTruthy()
 })
+
+
+it('renders the supplied action independently from the card preview', () => {
+  const p = props()
+  const native = vi.fn()
+  const view = render(<PresentedFileCard {...p} actions={<button type="button" onClick={native}>Native file action</button>} />)
+  fireEvent.click(view.getByRole('button', { name: 'Native file action' }))
+  expect(native).toHaveBeenCalledOnce()
+  expect(p.onPreview).not.toHaveBeenCalled()
+  fireEvent.click(view.getByRole('button', { name: 'Preview out/report.pdf in sidebar' }))
+  expect(p.onPreview).toHaveBeenCalledOnce()
+})
diff --git a/packages/client/ui-deliverables/tests/review-tab.client.spec.tsx b/packages/client/ui-deliverables/tests/review-tab.client.spec.tsx
index 9cdc89ec65..2af2a12b4a 100644
--- a/packages/client/ui-deliverables/tests/review-tab.client.spec.tsx
+++ b/packages/client/ui-deliverables/tests/review-tab.client.spec.tsx
@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
 /** The review tab type: its addresses, its store, the row pairing of the split view, and the states its body draws. */
+import { renderFileActions } from './file-actions.tsx'
 import { useSyncExternalStore } from 'react'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -158,11 +159,17 @@ describe('ReviewTab', () => {
       loadChangesSummary: vi.fn<ReviewInjected['loadChangesSummary']>(() => Promise.resolve()),
       loadChangesDiff: vi.fn<ReviewInjected['loadChangesDiff']>(() => Promise.resolve()),
       reloadPresentedHost: vi.fn<ReviewInjected['reloadPresentedHost']>(() => Promise.resolve()),
-      openChanged: vi.fn<ReviewInjected['openChanged']>(() => Promise.resolve()),
+      openChanged: vi.fn<ReviewInjected['openChanged']>(() => Promise.resolve(null)),
+    }
+    const sessions: SessionListState = {
+      ids: [SESSION],
+      byId: { [SESSION]: { id: SESSION, displayTitle: 'Workspace', cwd: options.cwd ?? '/work/app',
+        running: false, retainedBy: {}, blank: false, updatedAt: 0 } },
+      phase: 'ready', projectionsBySession: {},
     }
-    const sessions = { byId: { [SESSION]: { cwd: options.cwd ?? '/work/app' } } } as unknown as SessionListState
     const navigation = { address: options.address ?? ADDRESS, params: options.params, revision: options.revision ?? 1 }
     const runtime = {
+      renderSlot: renderFileActions,
       useTabInfo: () => ({
         sidebar: { expanded: true, fullscreen: false }, panel: { id: 'pane-1' },
         tab: { id: TAB, kind: 'changes-review', contentId: options.address ?? ADDRESS, title: 'Review', visible: true, navigation, signal: aborter.signal, actions: tabActions },
@@ -177,7 +184,7 @@ describe('ReviewTab', () => {
       usePresentedHost: hookOf(controller.host),
       t: makeTranslate(options.locale ?? en),
       ...injected,
-    } as unknown as ReviewTabProps
+    } as ReviewTabProps
     const view = render(<ReviewTab {...runtime} />)
     return {
       view, injected, tabActions, store, aborter, summaries, diffs, controller,
@@ -313,19 +320,18 @@ describe('ReviewTab', () => {
     expect(view.container.querySelector('[data-review-tool="open-file"] svg')?.getAttribute('width')).toBe('12')
     fireEvent.click(view.getByRole('button', { name: 'Open ~/out/big.bin in sidebar' }))
     expect(tabActions.openResource).toHaveBeenCalledWith(fileAddressFor(SESSION, '/work/app', '/tmp/out/big.bin'))
-    fireEvent.click(view.getByRole('button', { name: 'Open ~/out/big.bin in default app' }))
-    expect(injected.openChanged).toHaveBeenCalledWith('viewed', 5, 1)
+    fireEvent.click(view.getByRole('button', { name: 'Native file action' }))
+    expect(injected.openChanged).toHaveBeenCalledWith('viewed', 5, 1, 'open', undefined)
     act(() => { controller.state.set({ 'api/changes.open?sessionId=viewed&seq=5&index=1': 'opening' }) })
-    expect((view.getByRole('button', { name: 'Open ~/out/big.bin in default app' }) as HTMLButtonElement).disabled).toBe(true)
+    expect((view.getByRole('button', { name: 'Native file action' }) as HTMLButtonElement).disabled).toBe(true)
     act(() => { controller.state.set({ 'api/changes.open?sessionId=viewed&seq=5&index=1': 'error' }) })
-    expect(view.getByRole('button', { name: 'Open ~/out/big.bin in default app' }).hasAttribute('data-error')).toBe(true)
     act(() => { controller.state.set({ 'api/changes.open?sessionId=viewed&seq=5&index=1': 'nativeUnavailable' }) })
-    expect(view.queryByRole('button', { name: 'Open ~/out/big.bin in default app' })).toBeNull()
+    expect(view.queryByRole('button', { name: 'Native file action' })).toBeNull()
     act(() => {
       controller.state.set({})
       controller.host.set({ name: 'server', available: false, fileManager: null })
     })
-    expect(view.queryByRole('button', { name: 'Open ~/out/big.bin in default app' })).toBeNull()
+    expect(view.queryByRole('button', { name: 'Native file action' })).toBeNull()
     expect(view.getByText(en['changes.oversized'])).toBeTruthy()
   })
 
diff --git a/packages/client/ui-deliverables/tests/turn-tail-spacing.client.spec.ts b/packages/client/ui-deliverables/tests/turn-tail-spacing.client.spec.ts
index 6bd7af1bc5..9d9bb1cbc4 100644
--- a/packages/client/ui-deliverables/tests/turn-tail-spacing.client.spec.ts
+++ b/packages/client/ui-deliverables/tests/turn-tail-spacing.client.spec.ts
@@ -18,7 +18,6 @@ describe('deliverables layout', () => {
     expect(read('PresentedFileCard.tsx')).toMatch(/<FileTypeIcon path=\{file\.path\} size=\{20\} \/>/)
     expect(deliveries).toMatch(/\.fileName\s*\{[^}]*font-size:\s*13px;[^}]*line-height:\s*20px/s)
     expect(deliveries).toMatch(/\.description\s*\{[^}]*font-size:\s*10px;[^}]*line-height:\s*16px/s)
-    expect(deliveries).toMatch(/\.open\s*\{[^}]*padding:\s*4px 8px;[^}]*font-size:\s*12px;[^}]*line-height:\s*18px/s)
     expect(deliveries).toMatch(/\.presented\s*\{[^}]*gap:\s*10px/s)
   })
 
diff --git a/packages/client/ui-directory-picker-native/tests/client-flow.client.spec.tsx b/packages/client/ui-directory-picker-native/tests/client-flow.client.spec.tsx
index 11f6083a2a..ed033999aa 100644
--- a/packages/client/ui-directory-picker-native/tests/client-flow.client.spec.tsx
+++ b/packages/client/ui-directory-picker-native/tests/client-flow.client.spec.tsx
@@ -14,17 +14,18 @@ const desktopIpc = await vi.hoisted(async () => {
   const path = await import('node:path')
   // Electron belongs to the Desktop app; resolve its mock from that workspace.
   const electron = createRequire(path.resolve(import.meta.dirname, '../../../../apps/desktop/package.json')).resolve('electron')
-  return { invoke: vi.fn(), electron }
+  return { invoke: vi.fn(), on: vi.fn(), electron }
 })
 vi.mock(desktopIpc.electron, () => ({
-  ipcRenderer: { invoke: desktopIpc.invoke },
+  ipcRenderer: { invoke: desktopIpc.invoke, on: desktopIpc.on },
   contextBridge: { exposeInMainWorld: (name: string, value: unknown) => { vi.stubGlobal(name, value) } },
 }))
 vi.mock('../../../../apps/desktop/src/preload-platform.ts', () => ({ markDocumentPlatform: vi.fn(), syncWindowFullscreen: vi.fn() }))
 vi.mock('../../../../apps/desktop/src/preload-theme.ts', () => ({ syncNativeTheme: vi.fn() }))
 vi.mock('../../../../apps/desktop/src/preload-windows.ts', () => ({ syncWindowsAppearance: vi.fn() }))
+vi.mock('../../../../apps/desktop/src/preload-mandatory-overlay.ts', () => ({ installMandatoryUpdateOverlay: vi.fn() }))
 
-afterEach(() => { cleanup(); vi.unstubAllGlobals() })
+afterEach(() => { cleanup(); vi.unstubAllGlobals(); vi.restoreAllMocks(); desktopIpc.invoke.mockReset(); desktopIpc.on.mockReset() })
 
 const HOLES = ['conversation.hero.workspace.directoryFlow', 'sidebar.workspaces.directoryFlow'] as const
 
@@ -164,7 +165,9 @@ describe('directory-picker-native client half', () => {
     expect(b.pickDirectory).toHaveBeenCalledOnce()
   })
 
-  it('consumes the actual Desktop preload bridge and sends its directory-pick IPC', async () => {
+  it.each(['win32', 'darwin'] as const)('consumes the actual Desktop preload directory bridge on %s', async (platform) => {
+    vi.spyOn(process, 'platform', 'get').mockReturnValue(platform)
+    vi.resetModules()
     vi.stubGlobal('location', new URL('dsh-app://app/'))
     // Desktop's preload is typechecked by its own compiler program.
     const preload = '../../../../apps/desktop/src/preload-app.ts'
diff --git a/packages/client/ui-dockkit/README.i18n.yaml b/packages/client/ui-dockkit/README.i18n.yaml
index bbf8417672..333cd57389 100644
--- a/packages/client/ui-dockkit/README.i18n.yaml
+++ b/packages/client/ui-dockkit/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-dockkit/README.md
-README.md: f41668ad2eb6c16e13deb5fcc554c8717811a468
-README.zh.md: 6a4c70a1ddb46b75b614e9e63eaddd89f3641ac3
+README.md: 613cdbcb105108eb848160f1cb6bc8ee28d39fac
+README.zh.md: 77b256f01dd46aea5144e9f8da644fd39330f187
diff --git a/packages/client/ui-dockkit/README.md b/packages/client/ui-dockkit/README.md
index f41668ad2e..613cdbcb10 100644
--- a/packages/client/ui-dockkit/README.md
+++ b/packages/client/ui-dockkit/README.md
@@ -50,13 +50,15 @@ Everything host-specific arrives through props:
 | `TabRenderer` | one tab's body (`renderTab`), drawn flush to the pane's edges and the unbordered strip's bottom edge with the insets it chooses, and optionally what its chip or panel header shows as a title (`renderTabTitle`, falling back to the record's `title`); the embedder dispatches on `tab.kind` |
 | `DockIntents` | the settled results of every gesture |
 
-`DockController` satisfies `DockIntents` as written, so the simplest embedding hands the controller straight to `DockSurface`. An embedder that routes through its own store implements the same method names instead. Three props carry control policy rather than gestures: `canSplit` (surface-wide, the pane budget; disables the split control with `splitPaneDisabled`), `canAddTab(paneId)` (per pane, omits the add control; leave it out to draw one in every pane), and `canCloseTab(tabId)` (per tab, withholds the chip's close control and the menu's close item together; leave it out to keep every tab closable). Hiding the add control moves nothing else in the strip, and a withheld close moves nothing in the chip — the close control paints over the title's end rather than beside it. A pane's lone chip whose close is withheld draws quiet — no capsule, no hover fill — since there is nothing to select against and nothing to do to it. The kit adds one policy of its own, the room rule below, which disables a pane's split control with `splitPaneNarrow`; `onRoom(fits)` reports its readings so an embedder splitting programmatically can honour the same rule.
+`DockController` satisfies `DockIntents` as written, so an embedding can pass it to `DockLayout` for retained Sidebar layouts or `DockSurface` for recursive split trees. An embedder that routes through its own store implements the same method names instead. Three props carry control policy rather than gestures: `canSplit` (surface-wide, the pane budget; disables the split control with `splitPaneDisabled`), `canAddTab(paneId)` (per pane, omits the add control; leave it out to draw one in every pane), and `canCloseTab(tabId)` (per tab, withholds the chip's close control and the menu's close item together; leave it out to keep every tab closable). Hiding the add control moves nothing else in the strip, and a withheld close moves nothing in the chip — the close control paints over the title's end rather than beside it. A pane's lone chip whose close is withheld draws quiet — no capsule, no hover fill — since there is nothing to select against and nothing to do to it. The kit adds one policy of its own, the room rule below, which disables a pane's split control with `splitPaneNarrow`; `onRoom(fits)` reports its readings so an embedder splitting programmatically can honour the same rule.
 
 `dropZones="horizontal"` offers two half-pane hints; once budget or width forbids another split, the whole body accepts a move. A hint is a dashed card inset 8px inside its region, showing the zone's glyph and `labels.dropZone[zone]`; the preview layer covers all tab-body content, while the card under the pointer takes the accent and its neighbour stays a quiet outline. `minPaneFraction` sets the preview minimum, and `planResizeSplit` accepts the same minimum for the committed operation. The Sidebar uses 0.2 and enforces two panes in its own store. The generic engine retains its tree and other split directions. `hideSplitWhenBlocked` hides a blocked split control — pane budget spent or pane too narrow — instead of rendering it disabled; its default is false.
 
 A tab's `kind` is an opaque string. Seeded tabs are factories (`DockControllerOptions`), so what a fresh pane contains is the embedder's decision, not this package's. Content identity is the pair (`kind`, `contentId`): `findContentTab(state, contentId, kind?)` finds the tab showing it anywhere and `findPaneContentTab(state, paneId, contentId, kind?)` within one pane, and `planOpenContent` focuses that tab instead of opening another unless told `revealIfOpened: false`; an explicit `index` seats a new tab at a strip slot rather than at the end.
 
-`DockSurface` is the docked area. Chrome around it — a rail, a collapsed presentation, any history controls — belongs to the embedder, which reads `state.expanded` and decides; the kit ships no undo/redo control of its own. Surface-wide controls the embedder does want on the surface go through the `chrome` prop, which the kit places at the far end of the top-right pane's tab strip (the last child of every row split, the first of every column split), so a surface needs no header row of its own. `FloatLayer` owns its own gestures and positions panels in viewport coordinates, so it may be mounted anywhere, including a portal.
+`DockLayout`, used by the Sidebar, keeps each tab in a stable DOM cell across selection, pane moves and floating. It accepts one docked pane or two horizontal panes; CSS Grid resolves their widths. `keepMounted(tab)` retains visited bodies and `active` controls Session visibility without reparenting content.
+
+`DockSurface` is the docked area for the separate recursive renderer. Chrome around it — a rail, a collapsed presentation, any history controls — belongs to the embedder, which reads `state.expanded` and decides; the kit ships no undo/redo control of its own. Surface-wide controls the embedder does want on the surface go through the `chrome` prop, which the kit places at the far end of the top-right pane's tab strip (the last child of every row split, the first of every column split), so a surface needs no header row of its own. `FloatLayer` owns its own gestures and positions panels in viewport coordinates, so it may be mounted anywhere, including a portal.
 
 <a id="interaction-rules-worth-keeping"></a>
 ## Interaction rules worth keeping
diff --git a/packages/client/ui-dockkit/README.zh.md b/packages/client/ui-dockkit/README.zh.md
index 6a4c70a1dd..77b256f01d 100644
--- a/packages/client/ui-dockkit/README.zh.md
+++ b/packages/client/ui-dockkit/README.zh.md
@@ -50,13 +50,15 @@ kind: "package-reference"
 | `TabRenderer` | 一个 tab 的正文（`renderTab`），贴着格的边缘和（不带边线的）tab 条底边绘制、自己决定留白，以及可选的 chip 或浮窗头部显示的标题（`renderTabTitle`，回退到记录的 `title`）；嵌入方按 `tab.kind` 分发 |
 | `DockIntents` | 每次手势落定的结果 |
 
-`DockController` 原样满足 `DockIntents`，所以最简单的嵌入就是把 controller 直接交给 `DockSurface`。经由自己 store 路由的嵌入方则实现同名方法。有三个 props 承载的是控制策略而非手势：`canSplit`（整面有效，即格预算；用 `splitPaneDisabled` 禁用分栏控件）、`canAddTab(paneId)`（按格，省略添加控件；不传则每格都画）与 `canCloseTab(tabId)`（按 tab，把 chip 的关闭控件和菜单的关闭项一并收起；不传则每个 tab 都可关闭）。隐藏添加控件不会移动 tab 条里的其它任何东西，收起关闭也不会移动 chip 里的任何东西——关闭控件压在标题末端之上而非并排。某格仅剩的一个 chip 在关闭被收起时画成安静样式——没有胶囊底色，没有悬停填充——因为既没有别的 tab 可供选择，也没有任何可对它做的事。套件自己再加一条策略，即下文的空间规则，它用 `splitPaneNarrow` 禁用某格的分栏控件；`onRoom(fits)` 上报其读数，让以编程方式分栏的嵌入方能遵守同一规则。
+`DockController` 原样满足 `DockIntents`，因此嵌入方可将它交给 `DockLayout` 来保活 Sidebar 布局，或交给 `DockSurface` 来渲染递归分割树。经由自己 store 路由的嵌入方则实现同名方法。有三个 props 承载的是控制策略而非手势：`canSplit`（整面有效，即格预算；用 `splitPaneDisabled` 禁用分栏控件）、`canAddTab(paneId)`（按格，省略添加控件；不传则每格都画）与 `canCloseTab(tabId)`（按 tab，把 chip 的关闭控件和菜单的关闭项一并收起；不传则每个 tab 都可关闭）。隐藏添加控件不会移动 tab 条里的其它任何东西，收起关闭也不会移动 chip 里的任何东西——关闭控件压在标题末端之上而非并排。某格仅剩的一个 chip 在关闭被收起时画成安静样式——没有胶囊底色，没有悬停填充——因为既没有别的 tab 可供选择，也没有任何可对它做的事。套件自己再加一条策略，即下文的空间规则，它用 `splitPaneNarrow` 禁用某格的分栏控件；`onRoom(fits)` 上报其读数，让以编程方式分栏的嵌入方能遵守同一规则。
 
 `dropZones="horizontal"` 提供左右两个半区提示；预算或宽度不允许再拆时，正文整格接收移动。提示是一张内缩 8px 的虚线卡片，显示该落区的图形和 `labels.dropZone[zone]`；预览层覆盖全部 tab 正文，指针所在的卡片取强调色，另一张保持安静的轮廓。`minPaneFraction` 控制预览的最小比例，`planResizeSplit` 接受相同最小值以约束提交；Sidebar使用0.2并在自己的store限制两格。通用引擎仍保留原有树与其它分割方向。 `hideSplitWhenBlocked` 在分栏被阻止时（窗格预算已满或格太窄）直接隐藏分栏控件而不是渲染禁用态，默认值为 false。
 
 tab 的 `kind` 是不透明字符串。种子 tab 是工厂（`DockControllerOptions`），因此新格里放什么由嵌入方决定，与本包无关。内容身份是二元组（`kind`、`contentId`）：`findContentTab(state, contentId, kind?)` 在任意位置找到展示它的 tab，`findPaneContentTab(state, paneId, contentId, kind?)` 在一个格内找；`planOpenContent` 会聚焦该 tab 而非再开一个，除非被告知 `revealIfOpened: false`；显式的 `index` 把新 tab 放到 tab 条的某个位置而非末尾。
 
-`DockSurface` 是停靠区。它周围的 chrome——轨道、折叠形态、任何历史控件——属于嵌入方，由嵌入方读取 `state.expanded` 后自行决定；套件不自带撤销/重做控件。嵌入方确实想放到面上的整面控件通过 `chrome` prop 传入，套件把它放在右上格 tab 条的最末端（每个横向分裂的最后一个子节点、每个纵向分裂的第一个子节点），因此停靠面不需要自己的标题行。`FloatLayer` 拥有自己的手势并以视口坐标定位浮窗，因此可以挂在任何位置，包括 portal 里。
+Sidebar 使用的 `DockLayout` 在选中项变化、跨格移动与浮动期间，把每个 tab 保留在稳定的 DOM 容器中。它接受一个停靠格或左右两个格，由 CSS Grid 计算宽度。`keepMounted(tab)` 保留已访问正文，`active` 控制 Session 可见性，不改变内容的父子关系。
+
+`DockSurface` 是独立递归渲染器的停靠区。它周围的 chrome——轨道、折叠形态、任何历史控件——属于嵌入方，由嵌入方读取 `state.expanded` 后自行决定；套件不自带撤销/重做控件。嵌入方确实想放到面上的整面控件通过 `chrome` prop 传入，套件把它放在右上格 tab 条的最末端（每个横向分裂的最后一个子节点、每个纵向分裂的第一个子节点），因此停靠面不需要自己的标题行。`FloatLayer` 拥有自己的手势并以视口坐标定位浮窗，因此可以挂在任何位置，包括 portal 里。
 
 <a id="interaction-rules-worth-keeping"></a>
 ## 值得保留的交互规则
diff --git a/packages/client/ui-dockkit/src/components/DockSurface.tsx b/packages/client/ui-dockkit/src/components/DockSurface.tsx
index 6c3e0ced4d..17ca70f0c9 100644
--- a/packages/client/ui-dockkit/src/components/DockSurface.tsx
+++ b/packages/client/ui-dockkit/src/components/DockSurface.tsx
@@ -21,6 +21,7 @@ import {
 import { fitOf, measurePaneFits, paneElements, sameFits } from './measure.ts'
 import { useGesture } from './pointer.ts'
 import { PaneTree, type SizePreview } from './PaneTree.tsx'
+import { TabLayout, type TabRetention } from './TabLayout.tsx'
 import type { PaneCallbacks, SplitBlock } from './render.ts'
 import css from './dockkit.module.css'
 
@@ -161,10 +162,11 @@ function sameSizes(a: readonly number[], b: readonly number[]): boolean {
 }
 
 /** The split tree and the gestures over it. */
-export function DockSurface({
+function Surface({
   state, canSplit, canAddTab, canCloseTab, intents, labels, renderTab, renderTabTitle, renderTabMenuItems, chrome, onRoom,
+  draw,
   dropZones = 'edges', minPaneFraction = MIN_PANE_FRACTION, hideSplitWhenBlocked = false,
-}: DockSurfaceProps): ReactNode {
+}: DockSurfaceProps & { readonly draw: (callbacks: PaneCallbacks, preview: SizePreview | undefined) => ReactNode }): ReactNode {
   const surface = useRef<HTMLDivElement | null>(null)
   const [preview, setPreview] = useState<Preview>(NO_PREVIEW)
   const [fits, setFits] = useState(NO_FITS)
@@ -289,7 +291,26 @@ export function DockSurface({
 
   return (
     <div className={css.surface} ref={surface} data-dockkit-surface data-dockkit-drop-zones={dropZones}>
-      <PaneTree state={state} nodeId={state.rootId} callbacks={callbacks} preview={preview.sizes} />
+      {draw(callbacks, preview.sizes)}
     </div>
   )
 }
+
+/** Recursive docked layout; floating content is rendered separately by FloatLayer. */
+export function DockSurface(props: DockSurfaceProps): ReactNode {
+  return <Surface {...props} draw={(callbacks, preview) =>
+    <PaneTree state={props.state} nodeId={props.state.rootId} callbacks={callbacks} preview={preview} />} />
+}
+
+/** Horizontal Sidebar layout with stable tab containers across docking and floating. */
+export type DockLayoutProps = DockSurfaceProps & TabRetention
+
+/**
+ * Render one pane or two horizontal panes, and their floats, in one stable content tree.
+ * @param props - layout, gestures and lazy body-retention policy.
+ * @returns the layout; the containing ancestors must not clip or establish a fixed-position containing block.
+ */
+export function DockLayout(props: DockLayoutProps): ReactNode {
+  return <Surface {...props} draw={(callbacks, preview) =>
+    <TabLayout {...props} callbacks={callbacks} preview={preview} />} />
+}
diff --git a/packages/client/ui-dockkit/src/components/FloatLayer.tsx b/packages/client/ui-dockkit/src/components/FloatLayer.tsx
index a1efe4ce40..5f512423bd 100644
--- a/packages/client/ui-dockkit/src/components/FloatLayer.tsx
+++ b/packages/client/ui-dockkit/src/components/FloatLayer.tsx
@@ -18,7 +18,7 @@ import type { PointerEvent as ReactPointerEvent, ReactNode } from 'react'
 import clsx from 'clsx'
 import { IconCloseOutlineRegular, IconPanelLeftOutlineRegular, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { DockIntents, DockLabels, TabRenderer } from '../contract/adapter.ts'
-import type { FloatRect, LayoutState, PaneId, TabId } from '../contract/types.ts'
+import type { FloatRect, LayoutState, PaneId, TabId, TabRecord } from '../contract/types.ts'
 import { FLOAT_MIN_SIZE } from '../engine/constraints.ts'
 import { movedRect, resizedRect } from '../engine/geometry.ts'
 import { floatRect, getPane, getTab, onlyTabId } from '../engine/tree.ts'
@@ -65,8 +65,13 @@ function raised(state: LayoutState, paneId: PaneId): boolean {
   return state.activePaneId === paneId && state.floats.at(-1) === paneId
 }
 
-/** Every floating panel, in z order. */
-export function FloatLayer({ state, intents, labels, renderTab, renderTabTitle, canCloseTab }: FloatLayerProps): ReactNode {
+/**
+ * Shared move/resize gestures; changing layout mode never owns the content DOM.
+ * @param state - committed layout and float stacking order.
+ * @param intents - gesture settlements.
+ * @returns the current preview and focus/gesture callbacks.
+ */
+export function useFloatGestures(state: LayoutState, intents: DockIntents) {
   const [preview, setPreview] = useState<{ paneId: PaneId; rect: FloatRect } | undefined>(undefined)
   const begin = useGesture(() => { setPreview(undefined) })
 
@@ -93,6 +98,54 @@ export function FloatLayer({ state, intents, labels, renderTab, renderTabTitle,
     })
   }
 
+  return { preview, raise, drag }
+}
+
+/**
+ * Header-only controls, usable above either retained or visibility-mounted bodies.
+ * @param props - owning pane/tab, localized labels and gesture callbacks.
+ * @returns the float header without a content container.
+ */
+export function FloatHeader({ paneId, tab, labels, intents, renderTabTitle, canCloseTab, drag }: {
+  readonly paneId: PaneId
+  readonly tab: TabRecord
+  readonly labels: DockLabels
+  readonly intents: DockIntents
+  readonly renderTabTitle: TabRenderer | undefined
+  readonly canCloseTab: ((id: TabId) => boolean) | undefined
+  readonly drag: ReturnType<typeof useFloatGestures>['drag']
+}): ReactNode {
+  return (
+    <header className={clsx(css.tabStrip, css.floatHeader)} data-dockkit-float-grip={paneId}
+      onPointerDown={(event) => { drag('move', paneId, event) }}>
+      <div className={clsx(css.tab, css.floatTitle)} data-dockkit-float-title>
+        <TabTitle>{renderTabTitle?.(tab) ?? tab.title}</TabTitle>
+      </div>
+      <div className={css.stripFill} />
+      <Tooltip label={labels.dockFloat} side="bottom" delayMs={500}>
+        <button type="button" className={css.iconButton} aria-label={labels.dockFloat}
+          data-dockkit-float-dock={paneId} onPointerDown={(event) => { event.stopPropagation() }}
+          onClick={() => { intents.unfloatPane(paneId) }}>
+          <IconPanelLeftOutlineRegular className={css.dockGlyph} />
+        </button>
+      </Tooltip>
+      {(canCloseTab?.(tab.id) ?? true) && (
+        <Tooltip label={labels.closeFloat} side="bottom" delayMs={500}>
+          <button type="button" className={css.iconButton} aria-label={labels.closeFloat}
+            data-dockkit-float-close={paneId} onPointerDown={(event) => { event.stopPropagation() }}
+            onClick={() => { intents.closeTab(tab.id) }}>
+            <IconCloseOutlineRegular />
+          </button>
+        </Tooltip>
+      )}
+    </header>
+  )
+}
+
+/** Every floating panel, in z order. */
+export function FloatLayer({ state, intents, labels, renderTab, renderTabTitle, canCloseTab }: FloatLayerProps): ReactNode {
+  const { preview, raise, drag } = useFloatGestures(state, intents)
+
   return (
     <>
       {state.floats.map((paneId, depth) => {
@@ -117,42 +170,7 @@ export function FloatLayer({ state, intents, labels, renderTab, renderTabTitle,
             }}
             onPointerDown={() => { raise(paneId) }}
           >
-            <header
-              className={clsx(css.tabStrip, css.floatHeader)}
-              data-dockkit-float-grip={paneId}
-              onPointerDown={(event) => { drag('move', paneId, event) }}
-            >
-              <div className={clsx(css.tab, css.floatTitle)} data-dockkit-float-title>
-                <TabTitle>{renderTabTitle?.(tab) ?? tab.title}</TabTitle>
-              </div>
-              <div className={css.stripFill} />
-              <Tooltip label={labels.dockFloat} side="bottom" delayMs={500}>
-                <button
-                  type="button"
-                  className={css.iconButton}
-                  aria-label={labels.dockFloat}
-                  data-dockkit-float-dock={paneId}
-                  onPointerDown={(event) => { event.stopPropagation() }}
-                  onClick={() => { intents.unfloatPane(paneId) }}
-                >
-                  <IconPanelLeftOutlineRegular className={css.dockGlyph} />
-                </button>
-              </Tooltip>
-              {(canCloseTab?.(tab.id) ?? true) && (
-                <Tooltip label={labels.closeFloat} side="bottom" delayMs={500}>
-                  <button
-                    type="button"
-                    className={css.iconButton}
-                    aria-label={labels.closeFloat}
-                    data-dockkit-float-close={paneId}
-                    onPointerDown={(event) => { event.stopPropagation() }}
-                    onClick={() => { intents.closeTab(tab.id) }}
-                  >
-                    <IconCloseOutlineRegular />
-                  </button>
-                </Tooltip>
-              )}
-            </header>
+            <FloatHeader {...{ paneId, tab, labels, intents, renderTabTitle, canCloseTab, drag }} />
             <div className={css.floatBody}>{renderTab(tab)}</div>
             <div
               className={css.floatResize}
diff --git a/packages/client/ui-dockkit/src/components/TabLayout.tsx b/packages/client/ui-dockkit/src/components/TabLayout.tsx
new file mode 100644
index 0000000000..1bb41b353d
--- /dev/null
+++ b/packages/client/ui-dockkit/src/components/TabLayout.tsx
@@ -0,0 +1,157 @@
+/** Stable tab siblings in one horizontal Grid, including viewport-positioned floats. */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { MutableRefObject, ReactNode } from 'react'
+import clsx from 'clsx'
+import type { DockIntents } from '../contract/adapter.ts'
+import type { LayoutState, PaneNode, TabId, TabRecord } from '../contract/types.ts'
+import { findTabPane, floatRect, getNode, getPane } from '../engine/tree.ts'
+import type { SizePreview } from './PaneTree.tsx'
+import type { PaneCallbacks } from './render.ts'
+import { FloatHeader, useFloatGestures } from './FloatLayer.tsx'
+import { PaneDropHints, TabPanel, TabStrip } from './TabPanel.tsx'
+import css from './dockkit.module.css'
+
+/** Host policy for lazily retaining a tab body without reparenting it. */
+export interface TabRetention {
+  /** Whether a visited body survives hiding; omitted means visibility-mounted. */
+  readonly keepMounted?: (tab: TabRecord) => boolean
+  /** Whether this layout's Session is on screen; defaults to true. */
+  readonly active?: boolean
+}
+
+interface LayoutProps extends TabRetention {
+  readonly state: LayoutState
+  readonly callbacks: PaneCallbacks
+  readonly preview: SizePreview | undefined
+  readonly intents: DockIntents
+}
+
+interface TabHostProps extends LayoutProps {
+  readonly tab: TabRecord
+  readonly pane: PaneNode
+  readonly column: number
+  readonly floats: ReturnType<typeof useFloatGestures>
+  readonly focusRequest: MutableRefObject<{ readonly tabId: TabId; readonly origin: Element | null } | undefined>
+}
+
+/** A tab's ancestors stay identical across selection, pane moves and floating. */
+function TabHost({ state, callbacks, intents, tab, pane, column, floats, focusRequest, keepMounted,
+  active = true }: TabHostProps): ReactNode {
+  const floating = pane.host === 'float'
+  const selected = floating || pane.activeTabId === tab.id
+  const visible = active && selected && (floating || state.expanded)
+  const retained = keepMounted?.(tab) ?? false
+  const [visited, setVisited] = useState(visible)
+  if (visible && !visited) setVisited(true)
+  const host = useRef<HTMLElement | null>(null)
+  const body = useRef<HTMLDivElement | null>(null)
+  useLayoutEffect(() => {
+    // Both refs target unconditional descendants attached before these effects.
+    const section = host.current as HTMLElement
+    section.inert = !visible
+    const focused = document.activeElement
+    if (!visible && focused instanceof HTMLElement && section.contains(focused)) focused.blur()
+    const request = focusRequest.current
+    if (!visible || request?.tabId !== tab.id) return
+    focusRequest.current = undefined
+    // Preserve deliberate focus taken by another control or the newly shown body.
+    if (focused !== null && focused !== document.body && focused !== document.documentElement && focused !== request.origin) return
+    const strip = section.querySelector('[data-dockkit-strip]')
+    const chip = [...strip?.querySelectorAll<HTMLElement>('[data-dockkit-tab]') ?? []]
+      .find(element => element.dataset.dockkitTab === tab.id)
+    chip?.focus({ preventScroll: true })
+  }, [visible, tab.id, focusRequest])
+  // Electron emits a non-bubbling focus event on the webview element.
+  useEffect(() => {
+    const element = body.current as HTMLDivElement
+    const focus = (): void => {
+      if (!visible) return
+      if (floating) floats.raise(pane.id)
+      else if (state.activePaneId !== pane.id) callbacks.onFocusPane(pane.id)
+    }
+    element.addEventListener('focus', focus, true)
+    return () => { element.removeEventListener('focus', focus, true) }
+  }, [visible, floating, floats, pane.id, state.activePaneId, callbacks])
+  const lifted = floating && floats.preview?.paneId === pane.id ? floats.preview.rect : undefined
+  const rect = floating ? lifted ?? floatRect(pane) : undefined
+  const depth = lifted === undefined ? state.floats.indexOf(pane.id) + 1 : state.floats.length + 1
+  return (
+    <div className={clsx(css.tabCell, floating && css.floatingCell)} hidden={!selected}
+      data-dockkit-host={floating ? 'float' : 'dock'} data-dockkit-column={floating ? undefined : column}
+      style={{ gridColumn: floating ? 1 : column * 2 + 1, gridRow: 1, order: floating ? depth : 0 }}>
+      <section ref={host} className={clsx(css.tabHost, floating ? css.float : css.pane)}
+        aria-hidden={!visible || undefined}
+        data-dockkit-content={tab.id}
+        data-dockkit-pane={!floating && selected ? pane.id : undefined}
+        data-dockkit-pane-active={!floating && state.activePaneId === pane.id || undefined}
+        data-dockkit-float={floating ? pane.id : undefined}
+        data-dockkit-float-active={floating && state.activePaneId === pane.id || undefined}
+        data-dockkit-column={!floating ? column : undefined}
+        style={rect === undefined ? undefined : {
+          left: rect.x, top: rect.y, width: rect.width, height: rect.height,
+        }}
+        onPointerDown={() => { if (floating) floats.raise(pane.id) }}
+        onClick={() => { if (!floating && state.activePaneId !== pane.id) callbacks.onFocusPane(pane.id) }}>
+        <div className={css.tabHostHeader}>
+          {selected && (floating
+            ? <FloatHeader paneId={pane.id} tab={tab} labels={callbacks.labels} intents={intents}
+              renderTabTitle={callbacks.renderTabTitle} canCloseTab={callbacks.canCloseTab} drag={floats.drag} />
+            : <TabStrip state={state} pane={pane} callbacks={callbacks} />)}
+        </div>
+        <div ref={body} className={clsx(css.tabHostBody, floating ? css.floatBody : css.paneBody)}>
+          {visited && (retained || (active && selected)) ? callbacks.renderTab(tab) : null}
+          {!floating && <PaneDropHints pane={pane} callbacks={callbacks} />}
+        </div>
+        {floating && <div className={css.floatResize} data-dockkit-float-resize={pane.id}
+          onPointerDown={(event) => { floats.drag('resize', pane.id, event) }} />}
+      </section>
+    </div>
+  )
+}
+
+/**
+ * One or two horizontal panes; CSS resolves content sizes from track fractions.
+ * @param props - committed layout, gesture preview and body retention policy.
+ * @returns stable tab containers, including floating tabs.
+ * @throws if the docked tree is not one pane or two horizontal panes.
+ */
+export function TabLayout(props: LayoutProps): ReactNode {
+  const { state, callbacks, preview } = props
+  const focusRequest = useRef<{ readonly tabId: TabId; readonly origin: Element | null }>()
+  const tabCallbacks: PaneCallbacks = {
+    ...callbacks,
+    onFocusTab: (tabId) => {
+      // Only changing the selected body replaces its strip; pane-only focus does not.
+      focusRequest.current = findTabPane(state, tabId).activeTabId === tabId
+        ? undefined : { tabId, origin: document.activeElement }
+      callbacks.onFocusTab(tabId)
+    },
+  }
+  const root = getNode(state, state.rootId)
+  if (root.kind === 'split' && (root.axis !== 'row' || root.children.length !== 2)) {
+    throw new Error('DockLayout requires one pane or two horizontally split panes')
+  }
+  const panes = root.kind === 'pane' ? [root] : root.children.map(id => getPane(state, id))
+  const sizes = root.kind === 'split' ? preview?.splitId === root.id ? preview.sizes : root.sizes : [1]
+  const floats = useFloatGestures(state, props.intents)
+  const columns = sizes.map(size => `minmax(0, ${size}fr)`).join(' 0px ')
+  return (
+    <div className={css.tabLayout} data-dockkit-split={root.kind === 'split' ? root.id : undefined}
+      style={{ gridTemplateColumns: columns }}>
+      {/* Logical order changes must not make React move a connected webview's ancestor. */}
+      {Object.values(state.tabs).sort((a, b) => a.id.localeCompare(b.id)).map((tab) => {
+        const pane = findTabPane(state, tab.id)
+        return <TabHost key={tab.id} {...props} callbacks={tabCallbacks} tab={tab} pane={pane}
+          column={panes.findIndex(candidate => candidate.id === pane.id)} floats={floats} focusRequest={focusRequest} />
+      })}
+      {panes.filter(pane => pane.tabs.length === 0).map(pane => (
+        <div key={pane.id} className={css.emptyTabHost} data-dockkit-empty style={{ gridColumn: panes.indexOf(pane) * 2 + 1, gridRow: 1 }}>
+          <TabPanel state={state} pane={pane} callbacks={callbacks} />
+        </div>
+      ))}
+      {root.kind === 'split' && <div className={clsx(css.divider, css.tabLayoutDivider)}
+        data-dockkit-divider={`${root.id}:0`} style={{ gridColumn: 2, gridRow: 1 }}
+        onPointerDown={(event) => { callbacks.onDividerPressed(root.id, 0, event) }} />}
+    </div>
+  )
+}
diff --git a/packages/client/ui-dockkit/src/components/TabPanel.tsx b/packages/client/ui-dockkit/src/components/TabPanel.tsx
index ae7d2e6fa7..1088e71399 100644
--- a/packages/client/ui-dockkit/src/components/TabPanel.tsx
+++ b/packages/client/ui-dockkit/src/components/TabPanel.tsx
@@ -208,8 +208,8 @@ function splitBlockedTitle(labels: PaneCallbacks['labels'], block: SplitBlock):
   }
 }
 
-/** The pane's tab strip, split control, and body. */
-export function TabPanel({ state, pane, callbacks }: TabPanelProps): ReactNode {
+/** @param props - pane state and gestures. @returns its tab strip without a content container. */
+export function TabStrip({ state, pane, callbacks }: TabPanelProps): ReactNode {
   // The open context menu and the chip that opened it; the menu positions
   // itself against that chip from its portal.
   const [menu, setMenu] = useState<{ readonly tabId: TabId; readonly anchor: HTMLElement } | undefined>(undefined)
@@ -218,15 +218,11 @@ export function TabPanel({ state, pane, callbacks }: TabPanelProps): ReactNode {
   const stripTabs = useRef<HTMLDivElement | null>(null)
   useStripScrollFades(stripTabs, pane.tabs)
   useActiveChipInView(stripTabs, chips, pane.tabs, pane.activeTabId)
-  const active = pane.activeTabId === undefined ? undefined : getTab(state, pane.activeTabId)
   const block = callbacks.splitBlock(pane.id)
   const target = callbacks.dropTarget
   const stripIndex = target !== undefined && target.kind === 'strip' && target.paneId === pane.id
     ? target.index
     : undefined
-  const zone = target !== undefined && target.kind === 'zone' && target.paneId === pane.id
-    ? target.zone
-    : undefined
 
   /** Select a tab from a click or a key, unless it is the active pane's selected tab already: that changes nothing. */
   const activate = (tabId: TabId): void => {
@@ -241,187 +237,196 @@ export function TabPanel({ state, pane, callbacks }: TabPanelProps): ReactNode {
     chip.focus()
   }
 
+  return (
+    <div className={css.tabStrip} role="tablist" data-dockkit-strip={pane.id}>
+      <div ref={stripTabs} className={css.stripTabs} role="presentation" data-dockkit-strip-tabs={pane.id}>
+        {pane.tabs.map((tabId, index) => {
+          const tab = getTab(state, tabId)
+          const selected = tabId === pane.activeTabId
+          const closable = callbacks.canCloseTab(tabId)
+          // A pane's lone unclosable chip is a label, not a choice: there is
+          // no other tab to select against and nothing to do to it.
+          const quiet = !closable && pane.tabs.length === 1
+          return (
+            <Fragment key={tabId}>
+              {(index > 0 || stripIndex === index) && (
+                <div
+                  className={clsx(css.slot, stripIndex === index && css.slotCaret)}
+                  data-dockkit-caret={stripIndex === index ? index : undefined}
+                />
+              )}
+              <div
+                role="tab"
+                aria-selected={selected}
+                tabIndex={selected ? 0 : -1}
+                className={clsx(
+                  css.tab,
+                  selected && css.tabActive,
+                  quiet && css.tabQuiet,
+                  callbacks.draggingTabId === tabId && css.tabDragging,
+                )}
+                data-dockkit-tab={tabId}
+                data-dockkit-tab-quiet={quiet || undefined}
+                ref={(element) => {
+                  if (element === null) chips.delete(tabId)
+                  else chips.set(tabId, element)
+                }}
+                // Focus lands on click, not on press: a state change between
+                // pointerdown and the first pointermove rebuilds this subtree,
+                // and Chromium cancels the pointer when the pressed element is
+                // replaced — which would abandon every drag. A drag that ends
+                // elsewhere fires no click, and its own operation carries focus.
+                onPointerDown={(event) => {
+                  // A secondary press is the menu, never a drag.
+                  if (event.button === 2) return
+                  callbacks.onTabPressed(tabId, event)
+                }}
+                onClick={(event) => {
+                  event.stopPropagation()
+                  activate(tabId)
+                }}
+                onKeyDown={(event) => {
+                  // Keys on the chip's nested close control are that control's.
+                  if (event.target !== event.currentTarget) return
+                  const next = chipToFocus(event.key, pane.tabs, tabId)
+                  if (next !== undefined) {
+                    event.preventDefault()
+                    focusChip(next)
+                    return
+                  }
+                  if (selects(event.key)) {
+                    event.preventDefault()
+                    activate(tabId)
+                  }
+                }}
+                onContextMenu={(event) => {
+                  event.preventDefault()
+                  const anchor = event.currentTarget
+                  setMenu(current => current?.tabId === tabId ? undefined : { tabId, anchor })
+                }}
+              >
+                <TabTitle>{callbacks.renderTabTitle?.(tab) ?? tab.title}</TabTitle>
+                {closable && (
+                  <button
+                    type="button"
+                    className={css.tabClose}
+                    aria-label={callbacks.labels.closeTab}
+                    data-dockkit-tab-close={tabId}
+                    // A nested control stops its own press: otherwise the press
+                    // starts a drag, captures the pointer, and this click never lands.
+                    onPointerDown={(event) => { event.stopPropagation() }}
+                    onClick={(event) => {
+                      event.stopPropagation()
+                      callbacks.onCloseTab(tabId)
+                    }}
+                  >
+                    <IconCloseFillRegular size={14} />
+                  </button>
+                )}
+                {menu?.tabId === tabId && (
+                  <TabMenu
+                    labels={callbacks.labels}
+                    anchor={menu.anchor}
+                    onClose={closable ? () => { setMenu(undefined); callbacks.onCloseTab(tabId) } : undefined}
+                    onDismiss={() => { setMenu(undefined) }}
+                    extras={callbacks.renderTabMenuItems?.(tab, () => { setMenu(undefined) })}
+                  />
+                )}
+              </div>
+            </Fragment>
+          )
+        })}
+        {stripIndex === pane.tabs.length && <div className={clsx(css.slot, css.slotCaret)} data-dockkit-caret={stripIndex} />}
+      </div>
+      {callbacks.canAddTab(pane.id) && (
+        <Tooltip label={callbacks.labels.addTab} side="bottom" delayMs={500}>
+          <button
+            type="button"
+            className={css.addTab}
+            aria-label={callbacks.labels.addTab}
+            data-dockkit-add-tab={pane.id}
+            onClick={(event) => {
+              event.stopPropagation()
+              callbacks.onAddTab(pane.id)
+            }}
+          >
+            <IconPlusOutlineRegular size={14} />
+          </button>
+        </Tooltip>
+      )}
+      <div className={css.stripFill} data-dockkit-strip-fill />
+      {!(callbacks.hideSplitWhenBlocked && block !== undefined) && (
+        <Tooltip label={callbacks.labels.splitPane} side="bottom" delayMs={500} disabled={block !== undefined}>
+          <button
+            type="button"
+            className={css.iconButton}
+            aria-label={callbacks.labels.splitPane}
+            // Disabled buttons fire no hover events, so the blocked reason
+            // stays a native title.
+            title={block === undefined ? undefined : splitBlockedTitle(callbacks.labels, block)}
+            disabled={block !== undefined}
+            data-dockkit-split-button={pane.id}
+            data-dockkit-split-blocked={block}
+            onClick={(event) => {
+              event.stopPropagation()
+              callbacks.onSplitPane(pane.id)
+            }}
+          >
+            <SplitGlyph />
+          </button>
+        </Tooltip>
+      )}
+      {/* The embedder's surface-wide controls, in the top-right pane only: the
+            strip is the surface's top edge, and this pane's end is its corner. */}
+      {pane.id === callbacks.chromePaneId && callbacks.chrome !== undefined && (
+      // The embedder's controls report their own intents; the pane's
+      // click-to-focus must not add a focus entry to each of them.
+        <div
+          className={css.stripChrome}
+          data-dockkit-strip-chrome
+          onClick={(event) => { event.stopPropagation() }}
+        >
+          {callbacks.chrome}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/** @param props - target pane and drag preview. @returns body-local drop feedback, or nothing. */
+export function PaneDropHints({ pane, callbacks }: Pick<TabPanelProps, 'pane' | 'callbacks'>): ReactNode {
+  const target = callbacks.dropTarget
+  const zone = target?.kind === 'zone' && target.paneId === pane.id ? target.zone : undefined
+  if (zone === undefined) return null
+  return <>
+    <div className={css.dockScrim} data-dockkit-dock-scrim />
+    {callbacks.horizontalDrops && zone !== 'center'
+      ? <>
+        <DockHint zone="left" active={zone === 'left'} labels={callbacks.labels} />
+        <DockHint zone="right" active={zone === 'right'} labels={callbacks.labels} />
+      </>
+      : <DockHint zone={zone} active labels={callbacks.labels} />}
+  </>
+}
+
+/** @param props - pane state and gestures. @returns one pane in the recursive, visibility-mounted layout. */
+export function TabPanel({ state, pane, callbacks }: TabPanelProps): ReactNode {
+  const active = pane.activeTabId === undefined ? undefined : getTab(state, pane.activeTabId)
   return (
     <section
       className={css.pane}
       data-dockkit-pane={pane.id}
       data-dockkit-pane-active={state.activePaneId === pane.id || undefined}
-      // A click on the pane's body or strip focuses the pane, unless it is the
-      // active one already: that click changes nothing and records nothing. The
-      // chips and the strip's controls stop their own clicks: each reports one
-      // intent, and that intent already decides which pane is active.
       onClick={() => {
-        if (state.activePaneId === pane.id) return
-        callbacks.onFocusPane(pane.id)
+        if (state.activePaneId !== pane.id) callbacks.onFocusPane(pane.id)
       }}
     >
-      <div className={css.tabStrip} role="tablist" data-dockkit-strip={pane.id}>
-        <div ref={stripTabs} className={css.stripTabs} role="presentation" data-dockkit-strip-tabs={pane.id}>
-          {pane.tabs.map((tabId, index) => {
-            const tab = getTab(state, tabId)
-            const selected = tabId === pane.activeTabId
-            const closable = callbacks.canCloseTab(tabId)
-            // A pane's lone unclosable chip is a label, not a choice: there is
-            // no other tab to select against and nothing to do to it.
-            const quiet = !closable && pane.tabs.length === 1
-            return (
-              <Fragment key={tabId}>
-                {(index > 0 || stripIndex === index) && (
-                  <div
-                    className={clsx(css.slot, stripIndex === index && css.slotCaret)}
-                    data-dockkit-caret={stripIndex === index ? index : undefined}
-                  />
-                )}
-                <div
-                  role="tab"
-                  aria-selected={selected}
-                  tabIndex={selected ? 0 : -1}
-                  className={clsx(
-                    css.tab,
-                    selected && css.tabActive,
-                    quiet && css.tabQuiet,
-                    callbacks.draggingTabId === tabId && css.tabDragging,
-                  )}
-                  data-dockkit-tab={tabId}
-                  data-dockkit-tab-quiet={quiet || undefined}
-                  ref={(element) => {
-                    if (element === null) chips.delete(tabId)
-                    else chips.set(tabId, element)
-                  }}
-                  // Focus lands on click, not on press: a state change between
-                  // pointerdown and the first pointermove rebuilds this subtree,
-                  // and Chromium cancels the pointer when the pressed element is
-                  // replaced — which would abandon every drag. A drag that ends
-                  // elsewhere fires no click, and its own operation carries focus.
-                  onPointerDown={(event) => {
-                    // A secondary press is the menu, never a drag.
-                    if (event.button === 2) return
-                    callbacks.onTabPressed(tabId, event)
-                  }}
-                  onClick={(event) => {
-                    event.stopPropagation()
-                    activate(tabId)
-                  }}
-                  onKeyDown={(event) => {
-                    // Keys on the chip's nested close control are that control's.
-                    if (event.target !== event.currentTarget) return
-                    const next = chipToFocus(event.key, pane.tabs, tabId)
-                    if (next !== undefined) {
-                      event.preventDefault()
-                      focusChip(next)
-                      return
-                    }
-                    if (selects(event.key)) {
-                      event.preventDefault()
-                      activate(tabId)
-                    }
-                  }}
-                  onContextMenu={(event) => {
-                    event.preventDefault()
-                    const anchor = event.currentTarget
-                    setMenu(current => current?.tabId === tabId ? undefined : { tabId, anchor })
-                  }}
-                >
-                  <TabTitle>{callbacks.renderTabTitle?.(tab) ?? tab.title}</TabTitle>
-                  {closable && (
-                    <button
-                      type="button"
-                      className={css.tabClose}
-                      aria-label={callbacks.labels.closeTab}
-                      data-dockkit-tab-close={tabId}
-                      // A nested control stops its own press: otherwise the press
-                      // starts a drag, captures the pointer, and this click never lands.
-                      onPointerDown={(event) => { event.stopPropagation() }}
-                      onClick={(event) => {
-                        event.stopPropagation()
-                        callbacks.onCloseTab(tabId)
-                      }}
-                    >
-                      <IconCloseFillRegular size={14} />
-                    </button>
-                  )}
-                  {menu?.tabId === tabId && (
-                    <TabMenu
-                      labels={callbacks.labels}
-                      anchor={menu.anchor}
-                      onClose={closable ? () => { setMenu(undefined); callbacks.onCloseTab(tabId) } : undefined}
-                      onDismiss={() => { setMenu(undefined) }}
-                      extras={callbacks.renderTabMenuItems?.(tab, () => { setMenu(undefined) })}
-                    />
-                  )}
-                </div>
-              </Fragment>
-            )
-          })}
-          {stripIndex === pane.tabs.length && <div className={clsx(css.slot, css.slotCaret)} data-dockkit-caret={stripIndex} />}
-        </div>
-        {callbacks.canAddTab(pane.id) && (
-          <Tooltip label={callbacks.labels.addTab} side="bottom" delayMs={500}>
-            <button
-              type="button"
-              className={css.addTab}
-              aria-label={callbacks.labels.addTab}
-              data-dockkit-add-tab={pane.id}
-              onClick={(event) => {
-                event.stopPropagation()
-                callbacks.onAddTab(pane.id)
-              }}
-            >
-              <IconPlusOutlineRegular size={14} />
-            </button>
-          </Tooltip>
-        )}
-        <div className={css.stripFill} data-dockkit-strip-fill />
-        {!(callbacks.hideSplitWhenBlocked && block !== undefined) && (
-          <Tooltip label={callbacks.labels.splitPane} side="bottom" delayMs={500} disabled={block !== undefined}>
-            <button
-              type="button"
-              className={css.iconButton}
-              aria-label={callbacks.labels.splitPane}
-              // Disabled buttons fire no hover events, so the blocked reason
-              // stays a native title.
-              title={block === undefined ? undefined : splitBlockedTitle(callbacks.labels, block)}
-              disabled={block !== undefined}
-              data-dockkit-split-button={pane.id}
-              data-dockkit-split-blocked={block}
-              onClick={(event) => {
-                event.stopPropagation()
-                callbacks.onSplitPane(pane.id)
-              }}
-            >
-              <SplitGlyph />
-            </button>
-          </Tooltip>
-        )}
-        {/* The embedder's surface-wide controls, in the top-right pane only: the
-            strip is the surface's top edge, and this pane's end is its corner. */}
-        {pane.id === callbacks.chromePaneId && callbacks.chrome !== undefined && (
-          // The embedder's controls report their own intents; the pane's
-          // click-to-focus must not add a focus entry to each of them.
-          <div
-            className={css.stripChrome}
-            data-dockkit-strip-chrome
-            onClick={(event) => { event.stopPropagation() }}
-          >
-            {callbacks.chrome}
-          </div>
-        )}
-      </div>
+      <TabStrip state={state} pane={pane} callbacks={callbacks} />
       <div className={css.paneBody}>
         {active === undefined
           ? <p className={css.empty}>{callbacks.labels.emptyPane}</p>
           : callbacks.renderTab(active)}
-        {zone !== undefined && (
-          <>
-            <div className={css.dockScrim} data-dockkit-dock-scrim />
-            {callbacks.horizontalDrops && zone !== 'center'
-              ? <>
-                <DockHint zone="left" active={zone === 'left'} labels={callbacks.labels} />
-                <DockHint zone="right" active={zone === 'right'} labels={callbacks.labels} />
-              </>
-              : <DockHint zone={zone} active labels={callbacks.labels} />}
-          </>
-        )}
+        <PaneDropHints pane={pane} callbacks={callbacks} />
       </div>
     </section>
   )
diff --git a/packages/client/ui-dockkit/src/components/dockkit.module.css b/packages/client/ui-dockkit/src/components/dockkit.module.css
index fab875c5b6..fd24348a10 100644
--- a/packages/client/ui-dockkit/src/components/dockkit.module.css
+++ b/packages/client/ui-dockkit/src/components/dockkit.module.css
@@ -129,6 +129,82 @@
   min-height: 0;
 }
 
+/* Every tab remains a sibling. Explicit tracks determine placement; order only
+   changes painting, so raising a float never moves a connected DOM ancestor. */
+.tabLayout {
+  display: grid;
+  flex: 1 1 auto;
+  grid-template-rows: minmax(0, 1fr);
+  min-width: 0;
+  min-height: 0;
+}
+
+.tabCell,
+.emptyTabHost {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  z-index: var(--dsh-dockkit-dock-layer, 10);
+}
+
+.tabCell[hidden] {
+  display: none;
+}
+
+/* A zero-sized Grid item supplies a stacking context, not a containing block
+   for its fixed child. Floats share one layer and use Grid paint order within it. */
+.floatingCell {
+  width: 0;
+  height: 0;
+  z-index: var(--dsh-dockkit-float-layer, 60);
+}
+
+.tabHost {
+  min-width: 0;
+  min-height: 0;
+  pointer-events: auto;
+}
+
+.tabHost:not(.float),
+.emptyTabHost {
+  background: var(--dsw-alias-bg-base);
+}
+
+.tabCell[data-dockkit-host='dock'][data-dockkit-column='0'] > .tabHost {
+  border-left: 0.5px solid var(--dsw-alias-border-l4);
+}
+
+.tabHostHeader {
+  flex: none;
+}
+
+.tabHostBody {
+  position: relative;
+  min-width: 0;
+}
+
+.tabLayoutDivider {
+  width: 0;
+  cursor: col-resize;
+  z-index: calc(var(--dsh-dockkit-dock-layer, 10) + 1);
+  pointer-events: auto;
+}
+
+.tabLayoutDivider::before {
+  top: 0;
+  bottom: 0;
+  left: -0.25px;
+  width: 0.5px;
+}
+
+.tabLayoutDivider::after {
+  top: 0;
+  bottom: 0;
+  left: -4px;
+  right: -4px;
+  background: linear-gradient(to bottom, transparent, var(--dsw-alias-label-caption) 50%, transparent) center / 1px 100% no-repeat;
+}
+
 /* A body that overflows scrolls inside its pane; nothing escapes the pane. */
 .pane {
   display: flex;
@@ -234,6 +310,7 @@
 :global(html[data-platform='darwin']) .stripTabs,
 :global(html[data-platform='darwin']) .stripChrome,
 :global(html[data-platform='darwin']) .paneBody,
+:global(html[data-platform='darwin']) .float,
 :global(html[data-platform='darwin']) .divider {
   -webkit-app-region: no-drag;
 }
diff --git a/packages/client/ui-dockkit/src/components/pointer.ts b/packages/client/ui-dockkit/src/components/pointer.ts
index a3b368ea9b..bd2f136bf4 100644
--- a/packages/client/ui-dockkit/src/components/pointer.ts
+++ b/packages/client/ui-dockkit/src/components/pointer.ts
@@ -40,6 +40,10 @@ export function followPointer(element: HTMLElement, pointerId: number, followers
   capturePointer(element, pointerId)
   const controller = new AbortController()
   const { signal } = controller
+  element.dataset.dockkitPointer = String(pointerId)
+  signal.addEventListener('abort', () => {
+    if (element.dataset.dockkitPointer === String(pointerId)) delete element.dataset.dockkitPointer
+  }, { once: true })
   const own = (event: PointerEvent): boolean => event.pointerId === pointerId
   window.addEventListener('pointermove', (event) => { if (own(event)) followers.move(event) }, { signal })
   window.addEventListener('pointerup', (event) => {
diff --git a/packages/client/ui-dockkit/src/index.ts b/packages/client/ui-dockkit/src/index.ts
index f72adb9271..0632f84fe5 100644
--- a/packages/client/ui-dockkit/src/index.ts
+++ b/packages/client/ui-dockkit/src/index.ts
@@ -66,3 +66,5 @@ export { DockSurface } from './components/DockSurface.tsx'
 export type { DockSurfaceProps } from './components/DockSurface.tsx'
 export { FloatLayer } from './components/FloatLayer.tsx'
 export type { FloatLayerProps } from './components/FloatLayer.tsx'
+export { DockLayout } from './components/DockSurface.tsx'
+export type { DockLayoutProps } from './components/DockSurface.tsx'
diff --git a/packages/client/ui-dockkit/tests/tab-layout.client.spec.tsx b/packages/client/ui-dockkit/tests/tab-layout.client.spec.tsx
new file mode 100644
index 0000000000..8a884ba72a
--- /dev/null
+++ b/packages/client/ui-dockkit/tests/tab-layout.client.spec.tsx
@@ -0,0 +1,212 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import type { ComponentProps } from 'react'
+import { TabLayout } from '../src/components/TabLayout.tsx'
+import { DockController } from '../src/engine/controller.ts'
+import { getNode, getPane } from '../src/engine/tree.ts'
+import type { PaneCallbacks } from '../src/components/render.ts'
+import type { TabId } from '../src/contract/types.ts'
+import { followPointer } from '../src/components/pointer.ts'
+import { seededController, TEST_LABELS } from './fixtures.client.ts'
+
+afterEach(() => { cleanup(); vi.restoreAllMocks() })
+
+function mounted(controller = seededController(), options: Partial<ComponentProps<typeof TabLayout>> = {}) {
+  const callbacks: PaneCallbacks = {
+    onFocusTab: (id) => { controller.focusTab(id); redraw() },
+    onFocusPane: (id) => { controller.focusPane(id); redraw() },
+    onSplitPane: vi.fn(), onAddTab: vi.fn(), onCloseTab: vi.fn(), onTabPressed: vi.fn(), onDividerPressed: vi.fn(),
+    splitBlock: () => undefined, canAddTab: () => true, canCloseTab: () => true,
+    dropTarget: undefined, draggingTabId: undefined, labels: TEST_LABELS,
+    renderTab: tab => <input data-body={tab.id} defaultValue={tab.title} />,
+    renderTabTitle: undefined, renderTabMenuItems: undefined,
+    chromePaneId: getPane(controller.getSnapshot().state, controller.getSnapshot().state.rootId).id,
+    chrome: undefined,
+  }
+  const props = () => ({ state: controller.getSnapshot().state, callbacks, intents: controller, preview: undefined, ...options })
+  const view = render(<TabLayout {...props()} />)
+  function redraw(next: typeof options = {}) {
+    options = { ...options, ...next }
+    view.rerender(<TabLayout {...props()} />)
+  }
+  const node = (selector: string): HTMLElement => {
+    const element = view.container.querySelector<HTMLElement>(selector)
+    if (element === null) throw new Error(`missing ${selector}`)
+    return element
+  }
+  return { controller, view, redraw, callbacks, node, body: (id: TabId) => node(`[data-body="${id}"]`) }
+}
+
+it('retains visited bodies and hands keyboard focus to the newly selected strip', () => {
+  const controller = seededController()
+  controller.setExpanded(true)
+  const first = getPane(controller.getSnapshot().state, controller.getSnapshot().state.rootId).tabs[0]!
+  const second = controller.openContent({ kind: 'file', contentId: 'file:b', title: 'B' })
+  controller.focusTab(first)
+  const h = mounted(controller, { keepMounted: () => true })
+  const original = h.body(first)
+  expect(h.view.container.querySelector(`[data-body="${second}"]`)).toBeNull()
+  const chip = h.node(`[data-dockkit-tab="${second}"]`)
+  chip.focus()
+  fireEvent.click(chip)
+  expect(document.activeElement).toBe(h.node(`[data-dockkit-content="${second}"] [data-dockkit-tab="${second}"]`))
+  expect(h.body(first)).toBe(original)
+  expect(original.closest('[data-dockkit-host]')).toHaveProperty('hidden', true)
+  fireEvent.click(h.node(`[data-dockkit-content="${second}"] [data-dockkit-tab="${second}"]`))
+  const body = h.body(second)
+  body.focus()
+  h.redraw({ active: false })
+  expect(body.closest('[data-dockkit-content]')).toHaveProperty('inert', true)
+  expect(document.activeElement).not.toBe(body)
+  fireEvent.focus(body)
+  h.redraw({ active: true })
+  expect(h.body(second)).toBe(body)
+  expect(body.closest('[data-dockkit-content]')).toHaveProperty('inert', false)
+  act(() => { controller.setExpanded(false); h.redraw() })
+  expect(h.body(second)).toBe(body)
+})
+
+it('keeps body ancestors through pane moves, floating, raising and docking', () => {
+  const controller = seededController()
+  controller.setExpanded(true)
+  const tab = controller.openContent({ kind: 'file', contentId: 'file:a', title: 'A' })
+  const h = mounted(controller, { keepMounted: () => true })
+  const body = h.body(tab)
+  const host = body.closest('[data-dockkit-host]')!
+  act(() => { controller.splitPane(); h.redraw() })
+  expect(h.view.container.querySelectorAll('[data-dockkit-pane]')).toHaveLength(2)
+  const state = controller.getSnapshot().state
+  const split = getNode(state, state.rootId)
+  if (split.kind !== 'split') throw new Error('expected a split')
+  h.redraw({ preview: { splitId: split.id, sizes: [0.3, 0.7] } })
+  expect(h.node('[data-dockkit-split]').style.gridTemplateColumns).toContain('0.3fr')
+  fireEvent.pointerDown(h.node('[data-dockkit-divider]'), { button: 0, pointerId: 1 })
+  expect(h.callbacks.onDividerPressed).toHaveBeenCalledOnce()
+  h.redraw({ preview: undefined })
+  const secondPane = getPane(state, split.children[1]!).id
+  fireEvent.click(h.node(`[data-dockkit-content="${tab}"] [data-dockkit-tab="${tab}"]`))
+  expect(controller.getSnapshot().state.activePaneId).toBe(split.children[0])
+  act(() => { controller.focusPane(secondPane); h.redraw() })
+  fireEvent.focus(body)
+  expect(controller.getSnapshot().state.activePaneId).toBe(split.children[0])
+  act(() => { controller.focusPane(secondPane); h.redraw() })
+  fireEvent.pointerDown(h.node(`[data-dockkit-content="${tab}"]`), { button: 0, pointerId: 1 })
+  fireEvent.click(body)
+  fireEvent.focus(body)
+  expect(controller.getSnapshot().state.activePaneId).toBe(getPane(state, split.children[0]!).id)
+  act(() => { controller.placeTab(tab, secondPane, 0); h.redraw() })
+  expect(h.body(tab)).toBe(body)
+  expect(body.closest('[data-dockkit-host]')).toBe(host)
+  act(() => { controller.floatTab(tab); h.redraw() })
+  const floating = controller.getSnapshot().state.floats[0]!
+  expect(body.closest('[data-dockkit-host]')).toBe(host)
+  expect(host.getAttribute('data-dockkit-host')).toBe('float')
+  act(() => { controller.setExpanded(false); h.redraw() })
+  expect(body.closest('[data-dockkit-content]')?.getAttribute('aria-hidden')).toBeNull()
+  fireEvent.pointerDown(h.node(`[data-dockkit-float="${floating}"]`), { pointerId: 1, button: 0 })
+  fireEvent.click(h.node(`[data-dockkit-float="${floating}"]`))
+  fireEvent.focus(body)
+  const resize = h.node('[data-dockkit-float-resize]')
+  fireEvent.pointerDown(resize, { pointerId: 2, button: 0, clientX: 500, clientY: 400 })
+  fireEvent.pointerMove(window, { pointerId: 2, clientX: 540, clientY: 440 })
+  fireEvent.pointerUp(window, { pointerId: 2, clientX: 540, clientY: 440 })
+  act(() => { h.redraw(); controller.unfloatPane(floating); h.redraw() })
+  expect(h.body(tab)).toBe(body)
+  expect(body.closest('[data-dockkit-host]')).toBe(host)
+})
+
+it('unmounts unretained bodies and restores focus to their replacement strip', () => {
+  const controller = seededController()
+  controller.setExpanded(true)
+  const first = getPane(controller.getSnapshot().state, controller.getSnapshot().state.rootId).tabs[0]!
+  const second = controller.openContent({ kind: 'file', contentId: 'file:b', title: 'B' })
+  controller.focusTab(first)
+  const h = mounted(controller)
+  const original = h.body(first)
+  fireEvent.click(h.node(`[data-dockkit-tab="${second}"]`))
+  expect(original.isConnected).toBe(false)
+  h.redraw({ active: false })
+  expect(h.view.container.querySelector('[data-body]')).toBeNull()
+  h.redraw({ active: true })
+  const focus = vi.spyOn(HTMLElement.prototype, 'focus')
+  fireEvent.click(h.node(`[data-dockkit-tab="${first}"]`))
+  expect(focus).toHaveBeenCalled()
+})
+
+it.for(['new-control', 'origin-control', 'document', 'no-focus'] as const)('transfers tab focus without overriding a new owner: %s', (kind, test) => {
+  const controller = seededController()
+  controller.setExpanded(true)
+  const first = getPane(controller.getSnapshot().state, controller.getSnapshot().state.rootId).tabs[0]!
+  const second = controller.openContent({ kind: 'file', contentId: 'file:b', title: 'B' })
+  controller.focusTab(first)
+  const h = mounted(controller)
+  const control = document.createElement('button')
+  document.body.append(control)
+  test.onTestFinished(() => { control.remove() })
+  if (kind === 'origin-control') control.focus()
+  vi.spyOn(h.callbacks, 'onFocusTab').mockImplementation((id) => {
+    if (kind === 'new-control') control.focus()
+    if (kind === 'document' || kind === 'no-focus') {
+      vi.spyOn(document, 'activeElement', 'get').mockReturnValue(kind === 'document' ? document.documentElement : null)
+    }
+    controller.focusTab(id)
+    h.redraw()
+  })
+  const focus = vi.spyOn(HTMLElement.prototype, 'focus')
+  fireEvent.click(h.node(`[data-dockkit-tab="${second}"]`))
+  if (kind === 'new-control') expect(document.activeElement).toBe(control)
+  else expect(focus).toHaveBeenCalledWith({ preventScroll: true })
+})
+
+it('does not require a docked strip when a selected tab becomes floating in the same update', () => {
+  const controller = seededController()
+  controller.setExpanded(true)
+  const first = getPane(controller.getSnapshot().state, controller.getSnapshot().state.rootId).tabs[0]!
+  const second = controller.openContent({ kind: 'file', contentId: 'file:b', title: 'B' })
+  controller.focusTab(first)
+  const h = mounted(controller)
+  vi.spyOn(h.callbacks, 'onFocusTab').mockImplementation((id) => {
+    controller.focusTab(id)
+    controller.floatTab(id)
+    h.redraw()
+  })
+  fireEvent.click(h.node(`[data-dockkit-tab="${second}"]`))
+  expect(h.node(`[data-dockkit-content="${second}"]`).hasAttribute('data-dockkit-float')).toBe(true)
+})
+
+it('renders an empty pane and rejects unsupported docked trees', () => {
+  const controller = new DockController()
+  controller.setExpanded(true)
+  const h = mounted(controller)
+  expect(h.node('[data-dockkit-empty]')).toBeDefined()
+  controller.openContent({ kind: 'file', contentId: 'file:a', title: 'A' })
+  controller.splitPane()
+  const state = controller.getSnapshot().state
+  const root = getNode(state, state.rootId)
+  if (root.kind !== 'split') throw new Error('expected a split')
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  const suppress = (event: ErrorEvent): void => {
+    if (event.error instanceof Error && event.error.message === 'DockLayout requires one pane or two horizontally split panes') {
+      event.preventDefault()
+    }
+  }
+  window.addEventListener('error', suppress)
+  try {
+    expect(() =>{  h.redraw({ state: { ...state, nodes: { ...state.nodes, [root.id]: { ...root, axis: 'column' } } } }) })
+      .toThrow('two horizontally split panes')
+  } finally {
+    window.removeEventListener('error', suppress)
+  }
+})
+
+it('keeps a superseding gesture marker when an older follower detaches', () => {
+  const element = document.createElement('div')
+  const followers = { move: vi.fn(), up: vi.fn(), cancel: vi.fn() }
+  const first = followPointer(element, 1, followers)
+  const second = followPointer(element, 2, followers)
+  first()
+  expect(element.dataset.dockkitPointer).toBe('2')
+  second()
+  expect(element.dataset.dockkitPointer).toBeUndefined()
+})
diff --git a/packages/client/ui-goal/README.i18n.yaml b/packages/client/ui-goal/README.i18n.yaml
index 36f5e15909..c00ca00404 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: 7e6e0502db9720f788711fa3e98cab1581cc8738
-README.zh.md: 7e3fb604469ec73238f0843fdc95e6ea175c1d03
+README.md: ac23ac87c5b1bfe3eb849679c30a2ed283f33455
+README.zh.md: bc9971a5e8917bf636de34a742530b113e4e4453
diff --git a/packages/client/ui-goal/README.md b/packages/client/ui-goal/README.md
index 7e6e0502db..ac23ac87c5 100644
--- a/packages/client/ui-goal/README.md
+++ b/packages/client/ui-goal/README.md
@@ -45,6 +45,8 @@ A rejected mutation surfaces the Remote error inline on the strip; loading, abse
 
 The durable goal arrives through `useProjection('goal')` (seeded by the history tail page and updated by `session/projection` frames). The inject face carries a registrant-private activation hook source plus the four mutation verbs. That source starts only while the framework hook observes it, reads `ctx.remote.goals.get`, subscribes to `goal/activation-changed`, and refreshes on running-state or connection resets. Live-event epochs invalidate in-flight reads, so a stale HTTP result cannot overwrite a newer activation edge; running refreshes retain the last known activation until the read resolves. The strip owns no domain store or cross-plugin cache. Each mutation reads the CAS ref from the session's current projected value at call time, and the RPC's compare-and-set is the staleness guard. The strip single-flights mutations synchronously because a pending render cannot fence same-frame clicks. The command-input projection is a separate Conversation Definition that builds a `command-input` Chat Node before the generic command result Node; it never creates `user/message` or a model turn.
 
+Activation reads hold a temporary `goalActivation` Client reference and send `goals.get` only after that Session's initial history open succeeds. A stale binding or failed open sends no RPC. Rejected reads are logged without changing the projected goal or last known activation; the temporary reference is released when the read settles.
+
 </details>
 
 -----
diff --git a/packages/client/ui-goal/README.zh.md b/packages/client/ui-goal/README.zh.md
index 7e3fb60446..bc9971a5e8 100644
--- a/packages/client/ui-goal/README.zh.md
+++ b/packages/client/ui-goal/README.zh.md
@@ -45,6 +45,8 @@ Web GUI 的 goal 界面同时显示持久 goal 状态及当前的进程本地激
 
 持久 goal 经 `useProjection('goal')` 到达（由历史尾页播种、`session/projection` 帧更新）。注入面携带注册方私有的激活钩子源与四个变更动词。该源仅在框架钩子观察它时启动；启动后会读取 `ctx.remote.goals.get`、订阅 `goal/activation-changed`，并在 running 状态或连接重置时刷新。实时事件 epoch 会让在途读取失效，因此较旧的 HTTP 响应不能覆盖较新的 activation 变化；running 刷新会保留最后一次已知 activation，直到读取完成。条带不持有领域存储或跨插件缓存。每个变更在调用时从会话当前投影值读取 CAS ref，比较并交换（RPC 的 CAS）就是陈旧性护栏。由于 React 的 pending 渲染无法拦住同一帧内的点击，条带会同步为变更建立 single-flight 防护。指令输入投影是独立的 Conversation Definition，在通用命令结果 Node 之前构建 `command-input` Chat Node；它绝不创建 `user/message` 或模型轮次。
 
+激活状态读取持有临时的 `goalActivation` 客户端引用，仅在该会话首次历史打开成功后发送 `goals.get`。binding 已失效或打开失败时不发送 RPC。读取被拒绝时记录错误，不改变投影中的目标或最后一次已知激活状态；读取结束时释放临时引用。
+
 </details>
 
 -----
diff --git a/packages/client/ui-goal/src/client/activation-source.ts b/packages/client/ui-goal/src/client/activation-source.ts
index 23c65740a0..f1e74c8668 100644
--- a/packages/client/ui-goal/src/client/activation-source.ts
+++ b/packages/client/ui-goal/src/client/activation-source.ts
@@ -13,7 +13,7 @@ export interface GoalActivationDeps {
   readonly projection: HostObservable<GoalProjection | null | undefined>
   /** Session snapshot; running flips trigger a fresh authoritative read. */
   readonly session: HostObservable<{ readonly running: boolean }>
-  /** Read the current live goal at call time. */
+  /** Read live activation after initial history; rejected reads leave the current snapshot unchanged. */
   readonly getGoal: () => Promise<RemoteResult<GoalView | undefined>>
   /** Subscribe to activation edges after the transport delivers them. */
   readonly subscribeActivation: (listener: (goal: GoalActivationChanged['goal']) => void) => () => void
@@ -69,6 +69,8 @@ export function createGoalActivationSource(deps: GoalActivationDeps): HostObserv
         return
       }
       publish({ id: goal.id, revision: goal.revision, activation: goal.activation })
+    }, (error: unknown) => {
+      console.warn('[ui-goal] goal activation read failed:', error)
     })
   }
 
diff --git a/packages/client/ui-goal/src/client/index.ts b/packages/client/ui-goal/src/client/index.ts
index 93e1c996bf..e6feba92f5 100644
--- a/packages/client/ui-goal/src/client/index.ts
+++ b/packages/client/ui-goal/src/client/index.ts
@@ -4,6 +4,8 @@
  * `useProjection('goal')`. A registrant-private activation hook source owns
  * the live Remote read and event subscription; the inject face carries that
  * hook plus the four mutation verbs through the generated Goal Remote API.
+ * Activation reads retain the Client Session through completion and wait
+ * for its initial history open to succeed before contacting the Host.
  * This plugin does not create goals; deployments may expose /goal separately.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
@@ -38,6 +40,13 @@ export type {
 } from './slots.ts'
 export type { GoalKey } from './locales.ts'
 
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+  interface SessionReferenceSourceMap {
+    /** A live goal read waiting for initial history and its RPC result. */
+    goalActivation: unknown
+  }
+}
+
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
     /** The goal strip's copy. */
@@ -91,7 +100,18 @@ export function apply(ctx: ClientContext): void {
       const goalActivation = createGoalActivationSource({
         projection: binding.session.projections.faceOf('goal') as HostObservable<GoalProjection | null | undefined>,
         session: binding.session,
-        getGoal: () => ctx.remote.goals.get(sessionId),
+        getGoal: async () => {
+          if (sessions.binding(sessionId) !== binding) {
+            throw new Error(`ui-goal: session "${sessionId}" is unavailable`)
+          }
+          return sessions.using(sessionId, { source: 'goalActivation' }, async (reference) => {
+            const state = reference.binding.session.getSnapshot()
+            if (state.openState !== 'open') {
+              throw state.openError ?? new Error(`session "${sessionId}" is not open`)
+            }
+            return ctx.remote.goals.get(sessionId)
+          })
+        },
         subscribeActivation: listener => ctx.remote.$on('goal/activation-changed', (event) => {
           if (event.sessionId === sessionId) listener(event.goal)
         }),
diff --git a/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx b/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx
index 6181f3621b..bfa9828985 100644
--- a/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx
+++ b/packages/client/ui-goal/tests/browser-plugin.client.spec.tsx
@@ -10,7 +10,7 @@
  * plugin fiber (HMR safety), and the node half stays inert.
  */
 import { Context, Service } from '@deepseek-ai/cordis'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import { cleanup, render, screen, waitFor } from '@testing-library/react'
 import { afterEach } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
@@ -18,7 +18,8 @@ import { UiConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { GoalActivation, GoalId, GoalProjection, GoalView } from '@deepseek-ai/dsh-goal/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
-import { makeTranslate, RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { makeTranslate, RemoteError, TestSessions } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionFixture } from '@deepseek-ai/dsh-client-test-runtime'
 import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import type { GoalActivationSnapshot, GoalBarActions, GoalBarInjected } from '../src/client/slots.ts'
@@ -52,25 +53,25 @@ async function bench(options: {
   projection?: GoalProjection | null | undefined
   activation?: GoalActivation
   failWith?: RemoteFailure
+  initialOpen?: SessionFixture['initialOpen']
+  snapshot?: SessionFixture['snapshot']
 } = {}) {
   const ctx = new Context()
   const calls: { method: string; args: unknown[] }[] = []
-  const sessions = {
-    binding: (id: SessionId) => id === sid('missing') ? undefined : ({
-      sessionId: id,
-      session: {
-        getSnapshot: () => ({ running: false }),
-        subscribe: () => () => {},
-        projections: { faceOf: (key: string) => ({
-          getSnapshot: () => (key === 'goal' ? options.projection : undefined),
-          subscribe: () => () => {},
-        }) },
-      },
-      ctx,
-    }),
-  }
+  const sessions = new TestSessions(async (action) => { await action() }, ctx)
+  onTestFinished(async () => {
+    await sessions.disposeScopes()
+    await ctx.fiber.dispose()
+  })
+  await sessions.add({
+    id: 's1',
+    ...options.initialOpen === undefined ? {} : { initialOpen: options.initialOpen },
+    ...options.snapshot === undefined ? {} : { snapshot: options.snapshot },
+  })
+  await sessions.setProjection('s1', 'goal', options.projection)
+  const owner = sessions.retainFor(ctx, sid('s1'))
   ctx.provide('sessions', sessions)
-  const conversationEvents = new UiConversation(ctx, sessions as never).events
+  const conversationEvents = new UiConversation(ctx, sessions).events
   function answer<T>(method: string, value: T) {
     return (...args: unknown[]) => {
       calls.push({ method, args })
@@ -145,6 +146,8 @@ async function bench(options: {
     ctx,
     fiber,
     calls,
+    sessions,
+    owner,
     emitActivation: remote.emitActivation.bind(remote),
     definitions: () => conversationEvents.entries(),
     remountGoals: () => { activeGoals = goals('remounted-goals') },
@@ -163,6 +166,65 @@ async function bench(options: {
 }
 
 describe('ui-goal browser plugin', () => {
+  it('waits for initial history before reading activation and releases the read reference', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const b = await bench({ projection: makeProjection(), activation: 'disarmed', initialOpen: () => opened.promise })
+    await b.fiber.await()
+    const source = b.entry()!.inject!(sid('s1')).hooks.goalActivation
+    const dispose = source.subscribe(() => {})
+    try {
+      expect(b.calls).toEqual([])
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().retainedBy.goalActivation).toBe(1)
+      opened.resolve(undefined)
+      await waitFor(() => { expect(source.getSnapshot().activation).toBe('disarmed') })
+      expect(b.calls).toEqual([{ method: 'goals/get', args: [sid('s1')] }])
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      opened.resolve(undefined)
+      dispose()
+    }
+  })
+
+  it.each([true, false])('keeps projected goal state after an unsuccessful history open (reported error: %s)', async (reported) => {
+    const error = new RemoteError('gateway/internal', 'history unavailable', {})
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    onTestFinished(() => { warn.mockRestore() })
+    const b = await bench({ projection: makeProjection(), snapshot: { openState: 'error', openError: reported ? error : null } })
+    await b.fiber.await()
+    const source = b.entry()!.inject!(sid('s1')).hooks.goalActivation
+    const dispose = source.subscribe(() => {})
+    try {
+      await waitFor(() => { expect(warn).toHaveBeenCalledOnce() })
+      expect(warn).toHaveBeenCalledWith('[ui-goal] goal activation read failed:', expect.objectContaining({
+        message: reported ? 'history unavailable' : 'session "s1" is not open',
+      }))
+      expect(source.getSnapshot()).toEqual({ id: GOAL_ID, revision: 3 })
+      expect(b.calls).toEqual([])
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      dispose()
+    }
+  })
+
+  it('refuses activation reads captured from a replaced Session binding', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    onTestFinished(() => { warn.mockRestore() })
+    const b = await bench({ projection: makeProjection() })
+    await b.fiber.await()
+    const source = b.entry()!.inject!(sid('s1')).hooks.goalActivation
+    b.owner.release()
+    b.sessions.retainFor(b.ctx, sid('s1'))
+    const dispose = source.subscribe(() => {})
+    try {
+      await waitFor(() => { expect(warn).toHaveBeenCalledWith('[ui-goal] goal activation read failed:', expect.objectContaining({
+        message: 'ui-goal: session "s1" is unavailable',
+      })) })
+      expect(b.calls).toEqual([])
+    } finally {
+      dispose()
+    }
+  })
+
   it('registers the GoalBar dock, command input Definition, and keyed Chat renderer', async () => {
     const b = await bench()
     await b.fiber.await()
diff --git a/packages/client/ui-jobs/README.i18n.yaml b/packages/client/ui-jobs/README.i18n.yaml
index 3be8b2febf..0f1cb98168 100644
--- a/packages/client/ui-jobs/README.i18n.yaml
+++ b/packages/client/ui-jobs/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-jobs/README.md
-README.md: b775bdd354dda43f7427de7878299e6a7d7e9d2d
-README.zh.md: ef7ac07710393b9af8bb47d8763ef2c79f176d7d
+README.md: b6c8f39d40ca4630313659a94adc305f4c379119
+README.zh.md: 871948194dfcc9a5f0a9ab1f795556944b19144f
diff --git a/packages/client/ui-jobs/README.md b/packages/client/ui-jobs/README.md
index b775bdd354..b6c8f39d40 100644
--- a/packages/client/ui-jobs/README.md
+++ b/packages/client/ui-jobs/README.md
@@ -1,5 +1,5 @@
 ---
-description: "Web background-job surface: the session-header action listing the jobs this session can see; for users and maintainers of the background-job experience."
+description: "The session-header background-job list: expandable streaming output panels, running/finished sections, and static rows for settled jobs without retained output."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-This package renders the background-job surface of the Web GUI: a session-header action that opens a popover listing the jobs this session can see. It reads host-computed registry state through the runtime's `jobsBySession` mirror and issues no RPC of its own. The trigger appears only when the session has at least one job, with a badge counting running and stopping jobs; settled rows stay visible and de-emphasized until the registry drops them. The model's own view of the same jobs belongs to `dsh-tool-jobs`; this package is a read-only projection for the human.
+`dsh-client-ui-jobs` shows the session's background jobs in one header control, with lifecycle, elapsed time, progress, and terminal detail. Live jobs and settled jobs with retained output offer expandable output panels; collapsing stops the stream. Live rows lead with a ticking duration, followed by kind and status. Settled rows fold under a section heading; those without retained output, including subagents whose answers went to the model, stay static.
 
 ## Table of Contents
 
@@ -25,11 +25,15 @@ This package renders the background-job surface of the Web GUI: a session-header
 <a id="use-this-package"></a>
 ## Use this package
 
-Mount this plugin alongside the runtime; the job action then appears in the session header whenever the session has at least one job. A click opens the popover: live rows first by start time, then settled rows by finish time, each showing the producer kind, label, status, and an elapsed duration that ticks once per second while live and freezes at completion.
+Load the plugin through the web-app manifest; it renders nothing until the session can see at least one job, so an ordinary conversation never grows a control for a capability it is not using.
 
-### Dismissal and limits
+### One row per job
 
-Escape closes the list and returns focus to the trigger, as does a pointer press outside it. The list shows what one session can see through the wire view, so a job owned by another session never appears here; a process restart empties the list while the transcript keeps the `run_in_background` cards that started those jobs.
+The `job.list` stream `ctx.jobs` mirrors is the single roster: each `JobView` row carries lifecycle, duration, the live `progress` line or the terminal `detail`, and its retained byte count — a live job, or a settled one with retained output, is what makes a row expandable. There is no second roster to join.
+
+### The expanded panel
+
+Expanding an observable row opens that job's output observation stream from `ctx.jobs` (installed by `dsh-api-job-controller`) into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream interruptions render as notices above the panel.
 
 -----
 
@@ -39,7 +43,13 @@ Escape closes the list and returns focus to the trigger, as does a pointer press
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-The package contributes one entry to `conversation.session.header.actions` (`JobListAction`), and the data arrives entirely through the `jobsBySession` list mirror that the Session Controller binding folds from `session/jobs` frames — no RPC, and no state beyond popover visibility. The badge counts `running` plus `stopping` and is omitted at zero. Rows are ordered with live rows first by `startedAt` ascending, then settled rows by `finishedAt` descending, with a same-millisecond tie broken on start order; a settled row missing `finishedAt` reads as zero rather than as a negative figure, and a duration past an hour stays in hours. Settled rows stay visible because a failed job's `detail` is the only place its failure is legible. The behavior is specified by the [Web background-job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md).
+One slot entry in the header actions band (after the preset label, before the subagent catalog) renders the trigger and popover; the popover fits itself to the viewport by measuring its anchor. All data arrives through `ctx.jobs` — the component holds no transport state. The roster follows the mount: one `useEffect` keeps the session's `job.list` stream open while the control lives. Observation follows visibility: another `useEffect` opens the stream for the expanded row's job and closes it on collapse, unmount, or popover close.
+
+| File | Role |
+|---|---|
+| [`src/client/JobListAction.tsx`](src/client/JobListAction.tsx) | The job list: sections, durations, panels |
+| [`src/client/index.ts`](src/client/index.ts) | Slot registration and the dictionaries |
+| [`src/client/locales.ts`](src/client/locales.ts) | The `job` namespace copy (zh source of truth) |
 
 </details>
 
@@ -48,19 +58,16 @@ The package contributes one entry to `conversation.session.header.actions` (`Job
 <a id="further-exploration"></a>
 ## Further Exploration
 
-Read these pages when the job surface is not enough. They move from the browser list to the registry and the model-facing tool.
-
-- [dsh-tool-jobs](../../jobs/tool-jobs/README.md) — the model-facing jobs tool over the same registry.
-- [Session Controller](../../api/session-controller/README.md) — folds the `jobsBySession` mirror this package reads.
-- [ui-subagent](../ui-subagent/README.md) — the subagent catalog, where a running one-shot background subagent also appears.
-- [Web client architecture](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) — how browser plugin rows load and register slots.
+- [`dsh-api-job-controller`](../../api/job-controller/README.md) — the `job.list` and `job.follow` streams and the `ctx.jobs` service behind the rows and the panel.
+- [`dsh-jobs`](../../jobs/jobs/README.md) — the registry contract that owns the ring and projection semantics.
+- [`dsh-client-ui-primitives`](../ui-primitives/README.md) — the `TerminalBlock` surface the panel configures.
 
 -----
 
 <a id="model-experience"></a>
 ## Model Experience
 
-None, as this package renders host-computed registry state for a human and touches no prompt, message, schema, stream, or tool result.
+None, as this package renders host-observed state and live output for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md).
 
 #### KV Cache effect
 
@@ -70,11 +77,10 @@ None; the package never assembles or sends provider requests.
 
 <a id="known-limitations-and-deferred-work"></a>
 
+These limits define current package constraints, not a task backlog.
 
-These limits define the current job list. They are current package constraints, not a general job-management comparison or a task backlog.
-
-- **Rows are read-only** — a job's streamed output and a human-initiated cancellation are separate phases. Cancellation additionally owes a model-facing decision the seam does not answer: `kill()` marks terminal delivery reported, so an interrupt written against the current contract would leave the model believing its job is still running.
-- **The list is not the registry's own set** — it shows what one session can see through the wire view, so a job owned by another session never appears here, and a process restart empties the list while the transcript keeps the `run_in_background` cards that started those jobs. An unowned job (one started without a live `Agent`) reaches every session's list, matching what `list(caller)` reports to every caller.
+- **No kill control** — cancellation stays with the model's `job_kill`.
+- **Channel labels are not rendered** — stdout and stderr chunks concatenate into one stream; per-channel tinting is a presentation follow-up.
 
 <a id="dev-note"></a>
 ### Dev Note
@@ -86,4 +92,4 @@ None.
 
 </details>
 
-**Runtime invariant:** No companion is published. This package is a read-only projection of the `jobsBySession` mirror onto one header slot entry. It emits no Cordis events, owns no cross-plugin mutable state, and its single slot registration proves disposal through the HMR-safety spec.
+**Runtime invariant:** No companion is published. This package is a read-only projection of the `ctx.jobs` rosters and views onto one header slot entry. It emits no Cordis events, owns no cross-plugin mutable state, and its single slot registration proves disposal through the HMR-safety spec.
diff --git a/packages/client/ui-jobs/README.zh.md b/packages/client/ui-jobs/README.zh.md
index ef7ac07710..871948194d 100644
--- a/packages/client/ui-jobs/README.zh.md
+++ b/packages/client/ui-jobs/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "Web 后台任务界面：列出本会话可见任务的会话头部动作；供后台任务体验的用户与维护者阅读。"
+description: "会话头部后台任务列表：可展开的流式输出面板、进行中/已结束分组，以及无保留输出的已结束任务的静态行。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-本包渲染 Web GUI 的后台任务界面：一个会话头部动作，打开后以弹层列出本会话可见的任务。它经运行时提供的 `jobsBySession` 镜像读取宿主计算的注册表状态，自身不发任何 RPC。触发器只在会话至少有一个任务时出现，角标计数运行中与停止中的任务；终态行保持可见并弱化，直到注册表把它们丢弃。模型对同一批任务的视角属于 `dsh-tool-jobs`；本包是给人类看的只读投影。
+`dsh-client-ui-jobs` 在一个头部控件中展示本会话的后台任务，包括生命周期、耗时、进度与终态详情。进行中的任务和保留了输出的已结束任务提供可展开的输出面板；收起即停流。进行中的行以持续更新的时长为主行，随后展示类型与状态。已结束的行折叠在分组标题下；没有保留输出的任务保持静态，包括回答已交给模型的 subagent。
 
 ## 目录
 
@@ -25,11 +25,15 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-与运行时一起挂载本插件；只要会话至少有一个任务，任务动作就会出现在会话头部。点击打开弹层：活跃行在前按开始时间升序，随后终态行按结束时间降序，每行显示生产者 kind、标签、状态，以及一个活跃时每秒跳动、完成后冻结的已耗时。
+通过 web-app 清单加载本插件；在会话看得到至少一个 job 之前它不渲染任何东西，因此普通对话不会为未使用的能力长出控件。
 
-### 关闭与边界
+### 一 job 一行
 
-Escape 关闭列表并把焦点交还触发器，在其外部按下指针同理。列表展示的是「一个会话通过协议视图能看到什么」，因此别的会话拥有的任务在这里永不出现；进程重启会清空列表，而 transcript（文本记录）里启动这些任务的 `run_in_background` 卡片仍在。
+`ctx.jobs` 镜像的 `job.list` 流是唯一名册：每个 `JobView` 行携带生命周期、时长、实时 `progress` 行或终态 `detail`，以及其保留字节数——进行中的 job，或留有保留输出的已结束 job，就是行可展开的依据。不存在需要 join 的第二份名册。
+
+### 展开的面板
+
+展开可观察的行会从 `ctx.jobs`（由 `dsh-api-job-controller` 安装）打开该 job 的输出观测流，注入内嵌终端面板。面板复制的是命令（不是输出），命令与输出行完整换行，输出在固定高度内滚动而非折叠，且不绘制自己的运行状态点——上方的行承载状态。保留缺口与流中断在面板上方渲染为提示。
 
 -----
 
@@ -37,9 +41,15 @@ Escape 关闭列表并把焦点交还触发器，在其外部按下指针同理
 ## 理解实现
 
 <details>
-<summary>实现细节——点击展开</summary>
+<summary>实现内幕——点击展开</summary>
 
-本包向 `conversation.session.header.actions` 贡献一个条目（`JobListAction`），数据完全来自会话控制器绑定从 `session/jobs` 帧折叠出的 `jobsBySession` 列表镜像——不发 RPC，除弹层开合外不持有任何状态。角标计数 `running` 加 `stopping`，为零时省略。行序为活跃行在前按 `startedAt` 升序、终态行按 `finishedAt` 降序，毫秒并列按启动顺序打破；缺少 `finishedAt` 的终态行读作零而不是负数，超过一小时的耗时停留在小时单位。终态行保持可见，因为失败任务的 `detail` 是其失败唯一可读之处。行为由 [Web 后台任务展示 Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 规定。
+头部操作带里的一个 slot 条目（preset 标签之后、subagent 目录之前）渲染触发器与弹出层；弹出层通过测量锚点把自己收进视口。所有数据经 `ctx.jobs` 到达——组件不持有任何传输状态。名册跟随挂载：一个 `useEffect` 在控件存活期间保持会话的 `job.list` 流打开。观测跟随可见性：另一个 `useEffect` 为展开行的 job 打开流，并在收起、卸载或弹出层关闭时关闭它。
+
+| 文件 | 角色 |
+|---|---|
+| [`src/client/JobListAction.tsx`](src/client/JobListAction.tsx) | 任务列表：分组、时长、面板 |
+| [`src/client/index.ts`](src/client/index.ts) | slot 注册与词典 |
+| [`src/client/locales.ts`](src/client/locales.ts) | `job` 命名空间文案（zh 为事实源） |
 
 </details>
 
@@ -48,42 +58,38 @@ Escape 关闭列表并把焦点交还触发器，在其外部按下指针同理
 <a id="further-exploration"></a>
 ## 进一步探索
 
-当任务界面本身无法满足需要时，请阅读以下页面。它们从浏览器列表进入注册表与面向模型的工具。
-
-- [dsh-tool-jobs](../../jobs/tool-jobs/README.zh.md)——同一注册表之上的面向模型任务工具。
-- [会话控制器](../../api/session-controller/README.zh.md)——折叠出本包读取的 `jobsBySession` 镜像。
-- [ui-subagent](../ui-subagent/README.zh.md)——subagent 目录，运行中的一次性后台 subagent 也会出现在那里。
-- [Web 客户端架构](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md)——浏览器插件行如何加载并注册 slot。
+- [`dsh-api-job-controller`](../../api/job-controller/README.zh.md) —— 行与面板背后的 `job.list`、`job.follow` 流与 `ctx.jobs` 服务。
+- [`dsh-jobs`](../../jobs/jobs/README.zh.md) —— 拥有环与投影语义的注册表契约。
+- [`dsh-client-ui-primitives`](../ui-primitives/README.zh.md) —— 面板所配置的 `TerminalBlock` 表面。
 
 -----
 
 <a id="model-experience"></a>
 ## 模型体验
 
-无，因为本包为人类渲染宿主计算出的注册表状态，不触及提示词、消息、schema、流或工具结果。
+无。本包为人类渲染宿主观测到的状态与实时输出，不触碰任何提示词、消息、schema、流或工具结果。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。
 
-#### KV Cache 影响
+#### KV 缓存影响
 
-无；本包从不组装或发送提供方请求。
+无；本包从不组装或发送 provider 请求。
 
 ## 已知限制与延期工作
 
 <a id="known-limitations-and-deferred-work"></a>
 
+这些限制界定当前包约束，不是任务清单。
 
-这些限制界定了当前任务列表。它们是当前包约束，不是通用任务管理对比或任务积压。
-
-- **行是只读的**——任务的流式输出与人类发起的取消是各自独立的阶段。取消还额外欠一个 seam 没有回答的、面向模型的决策：`kill()` 会把终态投递标为已上报，所以照当前契约写出来的中断会让模型一直以为它的任务还在跑。
-- **列表不等于注册表自己的集合**——它展示的是一个会话通过协议视图能看到什么，因此别的会话拥有的任务在这里永不出现；进程重启会清空列表，而 transcript 里启动这些任务的 `run_in_background` 卡片仍在。无主任务（没有活体 `Agent` 时启动的）反过来会进入每个会话的列表，与 `list(caller)` 对每个调用方的报告一致。
+- **没有 kill 控件**——取消仍归模型的 `job_kill`。
+- **不渲染 channel 标签**——stdout 与 stderr 块拼接为一条流；按 channel 着色是展示层的后续工作。
 
 <a id="dev-note"></a>
 ### 开发备注
 
 <details>
-<summary>维护者的工作上下文——点击展开</summary>
+<summary>维护者工作语境——点击展开</summary>
 
 无。
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。本包只是将 `jobsBySession` 镜像以只读方式投影为一个会话头部 slot 条目，不发出 Cordis 事件，也不持有跨插件可变状态；其唯一的 slot 注册通过 HMR（热模块替换）安全性规范验证了资源释放行为。
+**运行时不变式：** 不发布伴生入口。本包只把 `ctx.jobs` 的名册与视图只读投影到一个 header slot，不发出 Cordis 事件，也不持有跨插件可变状态；其唯一的 slot 注册通过 HMR（热模块替换）安全性规范验证了资源释放行为。
diff --git a/packages/client/ui-jobs/package.json b/packages/client/ui-jobs/package.json
index e98eca744b..4a5d68d808 100644
--- a/packages/client/ui-jobs/package.json
+++ b/packages/client/ui-jobs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-jobs",
-  "description": "Session-header background-job list: live registry state mirrored from session/jobs frames",
+  "description": "Session-header background-job list with on-demand streaming record panels",
   "version": "0.1.6-alpha.2",
   "type": "module",
   "main": "lib/index.js",
@@ -17,16 +17,6 @@
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
-  "dsh": {
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-conversation",
-        "@deepseek-ai/dsh-client-ui-primitives"
-      ],
-      "platform": "web"
-    }
-  },
   "scripts": {
     "bundle": "tsdown",
     "watch": "tsdown --watch"
@@ -44,21 +34,33 @@
     "@deepseek-ai/cordis": "workspace:^"
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-api-job-controller": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
-    "@types/react": "~18.3.1",
-    "@deepseek-ai/cordis": "workspace:^",
-    "react": "^18.2.0",
-    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
     "@deepseek-ai/dsh-client-ui-renderer": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-session": "workspace:^"
+    "@deepseek-ai/dsh-client-ui-session": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0"
   },
   "files": [
     "lib/index.js",
     "lib/client.js",
     "lib/types/**/*.d.ts"
-  ]
+  ],
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-job-controller",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ],
+      "platform": "web"
+    }
+  }
 }
diff --git a/packages/client/ui-jobs/src/client/JobListAction.module.css b/packages/client/ui-jobs/src/client/JobListAction.module.css
index 06a78a4492..8d0cc4440c 100644
--- a/packages/client/ui-jobs/src/client/JobListAction.module.css
+++ b/packages/client/ui-jobs/src/client/JobListAction.module.css
@@ -47,9 +47,9 @@
   display: flex;
   flex-direction: column;
   gap: 1px;
-  width: 336px;
-  max-width: min(400px, calc(100vw - 32px));
-  max-height: min(420px, calc(100vh - 140px));
+  width: 440px;
+  max-width: min(520px, calc(100vw - 32px));
+  max-height: min(480px, calc(100vh - 140px));
   margin: 0;
   padding: 3px;
   overflow: auto;
@@ -64,6 +64,27 @@
   box-shadow: var(--dsw-elevation-prominent);
 }
 
+/* Section labels over the live rows and the settled tail. */
+.sectionHeader {
+  margin: 4px 4px 1px;
+  padding: 4px 4px 3px;
+  border-top: 0.5px solid var(--dsw-alias-border-l1);
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+/* The leading section needs no divider above it. */
+.sectionHeader:first-child {
+  margin-top: 0;
+  border-top: 0;
+}
+
+.item {
+  display: flex;
+  flex-direction: column;
+}
+
 .row {
   display: flex;
   align-items: center;
@@ -72,20 +93,61 @@
   width: 100%;
   min-height: 28px;
   padding: 4px 7px;
+  border: 0;
   border-radius: 7px;
+  background: transparent;
   color: var(--dsw-alias-label-primary);
   font-size: 12px;
   line-height: 17px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.row:hover,
+.row:focus-visible {
+  background: var(--dsw-alias-fill-l1);
+}
+
+/* A row with no observable output offers no interaction. */
+.rowStatic {
+  cursor: default;
+}
+
+.rowStatic:hover {
+  background: transparent;
 }
 
 .rowSettled {
   color: var(--dsw-alias-label-tertiary);
 }
 
-.rowDot {
+/* Live rows align the dot with the first text line, not the row center. */
+.row .rowDot {
   flex: none;
 }
 
+.main {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.primary {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  min-width: 0;
+}
+
+.secondary {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
 .kind {
   flex: none;
   padding: 0 5px;
@@ -105,23 +167,61 @@
   text-overflow: ellipsis;
 }
 
-.status,
-.duration {
+/* A failed task's detail is the producer's raw text, so it has no bound;
+   without this it widens the row past the menu instead of eliding like .label. */
+.status {
   flex: none;
+  max-width: 60%;
+  overflow: hidden;
   color: var(--dsw-alias-label-tertiary);
   font-size: 10px;
   line-height: 16px;
-}
-
-/* A failed job's detail is the producer's raw error text, so it has no bound;
-   without this it widens the row past the menu instead of eliding like .label. */
-.status {
-  max-width: 40%;
-  overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
 }
 
 .duration {
+  flex: none;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11px;
+  line-height: 18px;
   font-variant-numeric: tabular-nums;
 }
+
+.chevron {
+  flex: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.chevronOpen {
+  transform: rotate(180deg);
+}
+
+.panel {
+  margin: 0 8px 8px;
+  /* Long commands and output lines wrap in full instead of ellipsizing or
+     scrolling sideways, and the output region scrolls within a fixed height
+     instead of folding its middle lines. */
+  --dsl-terminal-command-whitespace: pre-wrap;
+  --dsl-terminal-line-whitespace: pre-wrap;
+  --dsl-terminal-output-max-height: 288px;
+}
+
+/* The row carries the state dot, so the panel omits its own and reclaims the
+   dot gutter down to an ordinary content inset. The override targets the card
+   element itself because the gutter variable is declared on it — a value
+   inherited from this container would lose to that declaration. */
+.panel :global([data-terminal]) {
+  --dsl-terminal-gutter: 12px;
+}
+
+.notice {
+  margin: 0 8px 6px;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+.noticeError {
+  color: var(--dsw-alias-label-error, var(--dsw-alias-label-secondary));
+}
diff --git a/packages/client/ui-jobs/src/client/JobListAction.tsx b/packages/client/ui-jobs/src/client/JobListAction.tsx
index 7853ec4e2c..95b35d8f53 100644
--- a/packages/client/ui-jobs/src/client/JobListAction.tsx
+++ b/packages/client/ui-jobs/src/client/JobListAction.tsx
@@ -1,23 +1,66 @@
-import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react'
-import type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types'
-import { IconChevronDownOutlineRegular, StateDot, useDismissOnOutsidePointer, type StateDotState } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react'
+import type { JobsSnapshot, JobView, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import {
+  IconChevronDownOutlineRegular, StateDot, TerminalBlock, useDismissOnOutsidePointer,
+  type StateDotState, type TerminalBlockLabels,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { InjectFace, PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import { NS } from './locales.ts'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import css from './JobListAction.module.css'
 
-/** Full props for the session-header background-job action. */
+/** Registration-side business face for the job list. */
+export interface JobListInjected {
+  hooks: {
+    /** Client jobs snapshot (rosters and observations) bound by the renderer as useJobs. */
+    jobs: {
+      getSnapshot(): JobsSnapshot
+      subscribe(listener: () => void): () => void
+    }
+  }
+  /**
+   * Keep one session's roster current while the list is mounted; returns the
+   * stop function. Reference-counted by the client service.
+   */
+  watchRows: (sessionId: SessionId) => () => void
+  /**
+   * Start observing one job's live output; returns the stop function.
+   * Reference-counted by the client service, so panels can overlap safely.
+   */
+  observe: (sessionId: SessionId | undefined, id: JobView['id']) => () => void
+}
+
+/** Full props for the session-header job-list action. */
 export type JobListActionProps =
-  PropsRuntime<'conversation.session.header.actions'> & PropsLocale<typeof NS>
+  PropsRuntime<'conversation.session.header.actions'>
+  & PropsLocale<typeof NS>
+  & InjectFace<JobListInjected>
 
 /** Stable empty list so a session with no jobs keeps one array identity. */
-const NO_TASKS: readonly JobView[] = []
+const NO_JOBS: readonly JobView[] = []
+
+/** Minimum gap kept between the popover and the viewport edges (the Menu primitive's portal margin). */
+const VIEWPORT_MARGIN = 12
+
 
-/** A job the registry still holds open, and whose duration therefore ticks. */
 function isLive(job: JobView): boolean {
   return job.status === 'running' || job.status === 'stopping'
 }
 
+/**
+ * Whether the row offers an output panel: every live job (its output may
+ * still arrive) and a settled one that left retained output behind.
+ */
+function isObservable(job: JobView): boolean {
+  return isLive(job) || job.output.total > 0
+}
+
+/** The one-line qualifier beside the status: live progress while running, the terminal reason once settled. */
+function jobDetail(job: JobView): string | undefined {
+  return job.progress ?? job.detail
+}
+
 /** Closed-union exhaustiveness fence for the wire status set. */
 /* v8 ignore next 3 -- closed-union backstop; only reached if a status is forged */
 function assertNever(value: never): never {
@@ -40,7 +83,6 @@ function dotState(status: JobView['status']): StateDotState {
   }
 }
 
-/** Human status word for the row and its accessible name. */
 function statusLabel(status: JobView['status'], t: TranslateNS<typeof NS>): string {
   switch (status) {
     case 'running': return t('status.running')
@@ -54,9 +96,9 @@ function statusLabel(status: JobView['status'], t: TranslateNS<typeof NS>): stri
 }
 
 /**
- * Elapsed time in at most two adjacent units. A background job that outlives
- * an hour is already exceptional, so hours is the widest unit — beyond that the
- * figure stays in hours rather than growing a day/month vocabulary no producer
+ * Elapsed time in at most two adjacent units. A job that outlives an hour is
+ * already exceptional, so hours is the widest unit — beyond that the figure
+ * stays in hours rather than growing a day/month vocabulary no producer
  * currently reaches.
  */
 function formatDuration(elapsedMs: number, t: TranslateNS<typeof NS>): string {
@@ -69,8 +111,35 @@ function formatDuration(elapsedMs: number, t: TranslateNS<typeof NS>): string {
   return t('duration.seconds', { seconds })
 }
 
+/** Localized display copy for the embedded terminal panel. */
+function terminalLabels(t: TranslateNS<typeof NS>): TerminalBlockLabels {
+  return {
+    // The labels contract requires exit-fact formatters, but this panel never
+    // passes exit facts, so TerminalBlock never invokes them.
+    /* v8 ignore next */
+    signal: signal => t('terminal.signal', { signal }),
+    /* v8 ignore next */
+    exitCode: code => t('terminal.exitCode', { code }),
+    noExitCode: t('terminal.noExitCode'),
+    running: t('terminal.running'),
+    failed: t('terminal.failed'),
+    done: t('terminal.done'),
+    copy: t('terminal.copy'),
+    copied: t('terminal.copied'),
+    noOutput: t('terminal.noOutput'),
+    collapseAria: t('terminal.collapseAria'),
+    collapse: t('terminal.collapse'),
+    // The panel never caps lines (it scrolls), so the fold controls that
+    // would invoke these stay unrendered.
+    /* v8 ignore next */
+    expandAria: hidden => t('terminal.expandAria', { n: hidden }),
+    /* v8 ignore next */
+    expand: hidden => t('terminal.expand', { n: hidden }),
+  }
+}
+
 /**
- * Live rows first in start order, then settled rows newest-first. Two jobs
+ * Live rows first in start order, then settled rows newest-first. Two rows
  * that settled in the same millisecond fall back to start order, so the sort
  * never depends on the host's map iteration.
  */
@@ -84,45 +153,202 @@ function ordered(jobs: readonly JobView[]): JobView[] {
   })
 }
 
+/** One job row plus, when observable and expanded, its live output panel. */
+function JobItem({ job, view, expanded, now, onToggle, t }: {
+  job: JobView
+  view: ObservedJob | undefined
+  expanded: boolean
+  /** Clock sample live rows derive their running duration from. */
+  now: number
+  onToggle: () => void
+  t: TranslateNS<typeof NS>
+}) {
+  const live = isLive(job)
+  const status = statusLabel(job.status, t)
+  const detail = jobDetail(job)
+  const observable = isObservable(job)
+  const labels = useMemo(() => terminalLabels(t), [t])
+  const elapsed = live ? now - job.startedAt : (job.finishedAt ?? job.startedAt) - job.startedAt
+  const duration = formatDuration(elapsed, t)
+  const durationCell = (
+    <span
+      className={css.duration}
+      title={t(live ? 'duration.title.live' : 'duration.title.done', { duration })}
+    >
+      {duration}
+    </span>
+  )
+  const body = live
+    ? (
+      <>
+        <StateDot state={dotState(job.status)} className={css.rowDot} />
+        <span className={css.main}>
+          <span className={css.primary}>
+            <span className={css.label} title={job.label}>{job.label}</span>
+            {durationCell}
+          </span>
+          <span className={css.secondary}>
+            <span className={css.kind}>{job.kind}</span>
+            <span className={css.status} title={detail ?? status}>{detail ?? status}</span>
+          </span>
+        </span>
+        {/* A live row is always observable: its output may still arrive. */}
+        <IconChevronDownOutlineRegular size={14} className={expanded ? `${css.chevron} ${css.chevronOpen}` : css.chevron} />
+      </>
+    )
+    : (
+      <>
+        <StateDot state={dotState(job.status)} className={css.rowDot} />
+        <span className={css.kind}>{job.kind}</span>
+        <span className={css.label} title={job.label}>{job.label}</span>
+        <span className={css.status} title={detail ?? status}>{detail ?? status}</span>
+        {durationCell}
+        {observable ? <IconChevronDownOutlineRegular size={14} className={expanded ? `${css.chevron} ${css.chevronOpen}` : css.chevron} /> : null}
+      </>
+    )
+  return (
+    <li className={css.item}>
+      {observable
+        ? (
+          <button
+            type="button"
+            className={live ? css.row : `${css.row} ${css.rowSettled}`}
+            aria-expanded={expanded}
+            aria-label={t(expanded ? 'row.collapseAria' : 'row.expandAria', { label: job.label })}
+            onClick={onToggle}
+          >
+            {body}
+          </button>
+        )
+        : (
+          <span className={`${css.row} ${css.rowSettled} ${css.rowStatic}`}>
+            {body}
+          </span>
+        )}
+      {expanded && view !== undefined
+        ? (
+          <div className={css.panel}>
+            {view.gapBefore ? <div className={css.notice}>{t('output.gap')}</div> : null}
+            {view.error !== undefined
+              ? <div className={`${css.notice} ${css.noticeError}`}>{t('output.error', { error: view.error })}</div>
+              : null}
+            <TerminalBlock
+              command={job.label}
+              output={view.text}
+              running={live}
+              copyText={job.label}
+              // The row above the panel already carries the state dot.
+              runStateDot={false}
+              // The panel scrolls its output (a stylesheet height cap) instead
+              // of collapsing the middle.
+              maxLines={Number.POSITIVE_INFINITY}
+              labels={labels}
+            />
+          </div>
+        )
+        : null}
+    </li>
+  )
+}
+
 /**
- * Session-header entry point for this session's background jobs. It renders
- * nothing at all until the session has at least one job, so an ordinary
- * conversation never grows a control for a capability it is not using.
- * @param props - runtime slot currency plus the namespace translator.
+ * Session-header entry point for this session's background jobs. Mounting it
+ * keeps the session's roster stream open; it renders nothing at all until the
+ * session can see at least one job. Expanding an observable row (a live job,
+ * or a settled one with retained output) starts its observation stream, and
+ * collapsing (or closing the popover) stops it — output only flows while
+ * someone is watching.
+ * @param props - runtime slot currency, the jobs snapshot hook, the roster
+ *   and observation controls, and the namespace translator.
  * @returns the trigger and its popover list, or null when there is nothing to show.
  */
-export function JobListAction({ sessionId, useSessions, t }: JobListActionProps) {
-  const jobs = useSessions(state => state.jobsBySession[sessionId]) ?? NO_TASKS
+export function JobListAction({ sessionId, useJobs, watchRows, observe, t }: JobListActionProps) {
+  const jobs = useJobs(state => state.rows[sessionId]) ?? NO_JOBS
+  const observedViews = useJobs(state => state.observed)
   const [open, setOpen] = useState(false)
+  const [expandedKey, setExpandedKey] = useState<string | undefined>(undefined)
   const [now, setNow] = useState(() => Date.now())
   const rootRef = useRef<HTMLDivElement>(null)
   const triggerRef = useRef<HTMLButtonElement>(null)
+  const menuRef = useRef<HTMLUListElement>(null)
+  // Horizontal shift applied to the trigger-anchored popover so it stays
+  // inside the viewport (the stylesheet alone cannot see the anchor offset).
+  const [menuShift, setMenuShift] = useState(0)
 
   const rows = useMemo(() => ordered(jobs), [jobs])
-  const liveCount = useMemo(() => jobs.filter(isLive).length, [jobs])
+  const liveRows = useMemo(() => rows.filter(isLive), [rows])
+  const settledRows = useMemo(() => rows.filter(job => !isLive(job)), [rows])
 
   useDismissOnOutsidePointer(rootRef, open, setOpen)
 
+  // The roster follows the mounted session: one stream while this control
+  // lives, released with it.
+  useEffect(() => watchRows(sessionId), [sessionId, watchRows])
+
   // The clock only runs while an open list is showing something that moves.
   useEffect(() => {
-    if (!open || liveCount === 0) return
+    if (!open || liveRows.length === 0) return
     setNow(Date.now())
     const timer = setInterval(() => { setNow(Date.now()) }, 1_000)
     return () => { clearInterval(timer) }
-  }, [open, liveCount])
+  }, [open, liveRows.length])
 
-  // The last job disappearing removes this control; close first so focus does
-  // not vanish from an unmounting node.
+  // Fit the open popover to the viewport: shift left when the anchored width
+  // would cross the right edge, never past the left margin.
+  useLayoutEffect(() => {
+    if (!open) {
+      setMenuShift(0)
+      return
+    }
+    const fit = (): void => {
+      const root = rootRef.current
+      const menu = menuRef.current
+      /* v8 ignore next -- both refs are attached while the open popover renders. */
+      if (root === null || menu === null) return
+      const width = menu.offsetWidth
+      // Unlaid-out nodes (and jsdom) measure 0: keep the pure CSS anchor.
+      if (width === 0) return
+      const anchorLeft = root.getBoundingClientRect().left
+      setMenuShift(Math.max(
+        VIEWPORT_MARGIN - anchorLeft,
+        Math.min(0, window.innerWidth - VIEWPORT_MARGIN - width - anchorLeft),
+      ))
+    }
+    fit()
+    window.addEventListener('resize', fit)
+    return () => { window.removeEventListener('resize', fit) }
+  }, [open])
+
+  // Observation follows visibility: the stream opens when an observable panel
+  // expands and closes when it collapses, unmounts, or the popover closes.
+  const expandedRow = open && expandedKey !== undefined
+    ? rows.find(job => String(job.id) === expandedKey)
+    : undefined
+  const activeJob = expandedRow !== undefined && isObservable(expandedRow) ? expandedRow.id : undefined
   useEffect(() => {
-    if (jobs.length === 0 && open) setOpen(false)
-  }, [jobs.length, open])
+    if (activeJob === undefined) return
+    return observe(sessionId, activeJob)
+  }, [sessionId, activeJob, observe])
 
-  if (jobs.length === 0) return null
+  // The last job disappearing removes this control; close first so focus
+  // does not vanish from an unmounting node.
+  useEffect(() => {
+    if (rows.length === 0 && open) setOpen(false)
+  }, [rows.length, open])
 
-  const countKey = liveCount > 0
-    ? (liveCount === 1 ? 'count.live.one' : 'count.live.other')
-    : (jobs.length === 1 ? 'count.idle.one' : 'count.idle.other')
-  const countLabel = t(countKey, { count: liveCount > 0 ? liveCount : jobs.length })
+  // An expanded row that left the list (owner disposal) folds its panel.
+  useEffect(() => {
+    if (expandedKey !== undefined && !rows.some(job => String(job.id) === expandedKey)) {
+      setExpandedKey(undefined)
+    }
+  }, [rows, expandedKey])
+
+  if (rows.length === 0) return null
+
+  const countKey = liveRows.length > 0
+    ? (liveRows.length === 1 ? 'count.live.one' : 'count.live.other')
+    : (rows.length === 1 ? 'count.idle.one' : 'count.idle.other')
+  const countLabel = t(countKey, { count: liveRows.length > 0 ? liveRows.length : rows.length })
 
   const onKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
     if (event.key !== 'Escape' || !open) return
@@ -131,6 +357,20 @@ export function JobListAction({ sessionId, useSessions, t }: JobListActionProps)
     triggerRef.current?.focus()
   }
 
+  const item = (job: JobView) => (
+    <JobItem
+      key={String(job.id)}
+      job={job}
+      view={isObservable(job) ? observedViews[String(job.id)] : undefined}
+      expanded={expandedKey === String(job.id)}
+      now={now}
+      onToggle={() => {
+        setExpandedKey(current => current === String(job.id) ? undefined : String(job.id))
+      }}
+      t={t}
+    />
+  )
+
   return (
     <div ref={rootRef} className={css.root} onKeyDown={onKeyDown}>
       <button
@@ -148,33 +388,21 @@ export function JobListAction({ sessionId, useSessions, t }: JobListActionProps)
           setOpen(current => !current)
         }}
       >
-        {liveCount > 0 ? <StateDot state="ongoing" className={css.triggerDot} /> : null}
+        {liveRows.length > 0 ? <StateDot state="ongoing" className={css.triggerDot} /> : null}
         <span className={css.count}>{countLabel}</span>
         <IconChevronDownOutlineRegular size={12} className={open ? css.triggerOpen : undefined} />
       </button>
       {open
         ? (
-          <ul className={css.menu} aria-label={t('list.aria')}>
-            {rows.map((job) => {
-              const live = isLive(job)
-              const elapsed = live ? now - job.startedAt : (job.finishedAt ?? job.startedAt) - job.startedAt
-              const duration = formatDuration(elapsed, t)
-              const status = statusLabel(job.status, t)
-              return (
-                <li key={job.id} className={live ? css.row : `${css.row} ${css.rowSettled}`}>
-                  <StateDot state={dotState(job.status)} className={css.rowDot} />
-                  <span className={css.kind}>{job.kind}</span>
-                  <span className={css.label} title={job.label}>{job.label}</span>
-                  <span className={css.status} title={job.detail ?? status}>{job.detail ?? status}</span>
-                  <span
-                    className={css.duration}
-                    title={t(live ? 'duration.title.live' : 'duration.title.done', { duration })}
-                  >
-                    {duration}
-                  </span>
-                </li>
-              )
-            })}
+          <ul ref={menuRef} className={css.menu} style={{ left: menuShift }} aria-label={t('list.aria')}>
+            {liveRows.length > 0
+              ? <li className={css.sectionHeader} aria-hidden="true">{t('section.live')}</li>
+              : null}
+            {liveRows.map(item)}
+            {settledRows.length > 0
+              ? <li className={css.sectionHeader} aria-hidden="true">{t('section.settled')}</li>
+              : null}
+            {settledRows.map(item)}
           </ul>
         )
         : null}
diff --git a/packages/client/ui-jobs/src/client/index.ts b/packages/client/ui-jobs/src/client/index.ts
index 22dc2c8425..4ee3c3b5de 100644
--- a/packages/client/ui-jobs/src/client/index.ts
+++ b/packages/client/ui-jobs/src/client/index.ts
@@ -1,11 +1,13 @@
 /**
  * Background-job plugin, browser half: contributes one session-header action
- * that renders this session's `ctx.jobs` records. The data arrives entirely
- * through the `jobsBySession` list mirror, so the plugin issues no RPC and
- * holds no state of its own beyond popover visibility.
+ * that renders this session's jobs. Job rows and per-row observation streams
+ * both arrive through the `jobs` client service; this plugin holds no
+ * transport state of its own.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import { JobListAction } from './JobListAction.tsx'
+import type { JobListInjected } from './JobListAction.tsx'
+import type {} from '@deepseek-ai/dsh-api-job-controller/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-session/client'
@@ -18,25 +20,31 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   }
 }
 
-export type { JobListActionProps } from './JobListAction.tsx'
+export type { JobListActionProps, JobListInjected } from './JobListAction.tsx'
 
-/** Required services for locale registration and header-slot contribution. */
-export const inject = ['sessions', 'slots', 'locale']
+/** Required services: the jobs rosters and observations, the slot registry, and dictionaries. */
+export const inject = ['jobs', 'slots', 'locale']
 
 /**
  * Client plugin body: register the dictionaries and the header action.
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
-  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-job: dictionaries')
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-jobs: dictionaries')
   ctx.slots.inject(
     'conversation.session.header.actions',
     () => ctx.slots.register({
       name: 'conversation.session.header.actions',
       id: 'job-list',
-      // After the subagent catalog: session lineage reads before process work.
+      // Between the preset label and the subagent catalog (order 30): running
+      // work reads before the session lineage.
       order: 20,
       locale: NS,
+      inject: (): JobListInjected => ({
+        hooks: { jobs: ctx.jobs.state },
+        watchRows: sessionId => ctx.jobs.watchRows(sessionId),
+        observe: (sessionId, id) => ctx.jobs.observe(sessionId, id),
+      }),
     }, JobListAction),
   )
 }
diff --git a/packages/client/ui-jobs/src/client/locales.ts b/packages/client/ui-jobs/src/client/locales.ts
index 70bb2e9e0f..1dc263aa19 100644
--- a/packages/client/ui-jobs/src/client/locales.ts
+++ b/packages/client/ui-jobs/src/client/locales.ts
@@ -10,6 +10,10 @@ export const zh = {
   'count.idle.one': '{count} 个后台任务',
   'count.idle.other': '{count} 个后台任务',
   'list.aria': '后台任务',
+  'section.live': '进行中',
+  'section.settled': '已结束',
+  'row.expandAria': '展开 {label} 的实时输出',
+  'row.collapseAria': '收起 {label} 的实时输出',
   'status.running': '运行中',
   'status.stopping': '正在停止',
   'status.completed': '已完成',
@@ -20,6 +24,21 @@ export const zh = {
   'duration.hours': '{hours}小时{minutes}分',
   'duration.title.live': '已运行 {duration}',
   'duration.title.done': '耗时 {duration}',
+  'output.gap': '……较早的输出已丢弃……',
+  'output.error': '实时输出流中断：{error}',
+  'terminal.signal': '信号 {signal}',
+  'terminal.exitCode': '退出码 {code}',
+  'terminal.noExitCode': '未正常退出',
+  'terminal.running': '运行中',
+  'terminal.failed': '已失败',
+  'terminal.done': '已完成',
+  'terminal.copy': '复制',
+  'terminal.copied': '已复制',
+  'terminal.noOutput': '（无输出）',
+  'terminal.collapse': '收起',
+  'terminal.collapseAria': '收起输出',
+  'terminal.expand': '展开其余 {n} 行',
+  'terminal.expandAria': '展开被折叠的 {n} 行输出',
 } as const
 
 /** English dictionary, key-identical to the Chinese source of truth. */
@@ -29,6 +48,10 @@ export const en: Record<JobKey, string> = {
   'count.idle.one': '{count} background job',
   'count.idle.other': '{count} background jobs',
   'list.aria': 'Background jobs',
+  'section.live': 'Running',
+  'section.settled': 'Finished',
+  'row.expandAria': 'Show live output of {label}',
+  'row.collapseAria': 'Hide live output of {label}',
   'status.running': 'running',
   'status.stopping': 'stopping',
   'status.completed': 'completed',
@@ -39,6 +62,21 @@ export const en: Record<JobKey, string> = {
   'duration.hours': '{hours}h {minutes}m',
   'duration.title.live': 'Running for {duration}',
   'duration.title.done': 'Took {duration}',
+  'output.gap': '… earlier output dropped …',
+  'output.error': 'live output stream interrupted: {error}',
+  'terminal.signal': 'signal {signal}',
+  'terminal.exitCode': 'exit {code}',
+  'terminal.noExitCode': 'no exit code',
+  'terminal.running': 'running',
+  'terminal.failed': 'failed',
+  'terminal.done': 'done',
+  'terminal.copy': 'Copy',
+  'terminal.copied': 'Copied',
+  'terminal.noOutput': '(no output)',
+  'terminal.collapse': 'Collapse',
+  'terminal.collapseAria': 'Collapse output',
+  'terminal.expand': 'Show {n} more lines',
+  'terminal.expandAria': 'Expand {n} collapsed output lines',
 }
 
 /** Key domain of the `job` namespace (zh is the source of truth). */
diff --git a/packages/client/ui-jobs/src/css-modules.d.ts b/packages/client/ui-jobs/src/css-modules.d.ts
index bc5e482353..8811db1264 100644
--- a/packages/client/ui-jobs/src/css-modules.d.ts
+++ b/packages/client/ui-jobs/src/css-modules.d.ts
@@ -2,5 +2,3 @@ declare module '*.module.css' {
   const classes: Record<string, string>
   export default classes
 }
-
-declare module '*.css'
diff --git a/packages/client/ui-jobs/src/index.ts b/packages/client/ui-jobs/src/index.ts
index 94d45c3ba1..457e7eeb9c 100644
--- a/packages/client/ui-jobs/src/index.ts
+++ b/packages/client/ui-jobs/src/index.ts
@@ -1,9 +1,9 @@
 /**
- * Background-job list plugin, node half. Pure UI plugin: the empty apply
- * exists so the plugin appears in the host cordis.yml / Loader; the browser
- * half ships via exports["./client"], discovered through the package.json
- * dshClient declaration.
+ * Node half of the background-job list plugin. The browser half in
+ * `src/client/` owns every contribution; this entry exists so the package
+ * appears as an ordinary Loader row.
+ * @module @deepseek-ai/dsh-client-ui-jobs
  */
 
-/** Host plugin body — no host-side behavior for this source plugin. */
+/** Loader-visible no-op body; the browser half carries the feature. */
 export function apply(): void {}
diff --git a/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts
index ceee59fe1d..c78482198d 100644
--- a/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts
@@ -1,15 +1,18 @@
 /**
- * ui-job plugin halves: the browser entry's dictionary and header-slot
+ * ui-jobs plugin halves: the browser entry's dictionary and header-slot
  * registrations against the real SlotRegistry (with fiber teardown proving
  * removal — HMR safety), and the inert node entry.
  */
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { Context } from '@deepseek-ai/cordis'
+import { JobId } from '@deepseek-ai/dsh-jobs/brand'
+import { SessionId } from '@deepseek-ai/dsh-session/types'
 import { describe, expect, it } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client'
 import { apply, inject } from '../src/client/index.ts'
+import type { JobListInjected } from '../src/client/JobListAction.tsx'
 import { apply as applyNode } from '../src/index.ts'
 import { en, NS, zh } from '../src/client/locales.ts'
 
@@ -20,6 +23,11 @@ function headerEntryIds(ctx: Context): (string | undefined)[] {
     .map(entry => entry.options.id)
 }
 
+/** Observation requests handed to the stubbed jobs service. */
+const observed: [string | undefined, string][] = []
+/** Roster watches handed to the stubbed jobs service. */
+const watched: string[] = []
+
 /** Boot the browser half over a real slot tree that declares the header list. */
 async function bench(): Promise<{ ctx: Context; fiber: ReturnType<Context['plugin']> }> {
   const ctx = new Context()
@@ -30,7 +38,17 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType<Context['plugi
       'conversation.session.header.actions': { kind: 'list', scope: 'session' },
     },
   } as never, () => null)
-  ctx.provide('sessions', {})
+  ctx.provide('jobs', {
+    state: { getSnapshot: () => ({ rows: {}, observed: {} }), subscribe: () => () => {} },
+    watchRows: (sessionId: string) => {
+      watched.push(sessionId)
+      return () => {}
+    },
+    observe: (sessionId: string | undefined, id: string) => {
+      observed.push([sessionId, id])
+      return () => {}
+    },
+  } as never)
   // The locale plugin binds a settings scope, which reads the connection handle
   // and the forwarded-event port.
   ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
@@ -46,9 +64,26 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType<Context['plugi
   return { ctx, fiber }
 }
 
-describe('ui-job browser half', () => {
+describe('ui-jobs browser half', () => {
   it('declares the services it binds', () => {
-    expect(inject).toEqual(['sessions', 'slots', 'locale'])
+    expect(inject).toEqual(['jobs', 'slots', 'locale'])
+  })
+
+  it('exposes the jobs source and the roster and observation controls through the inject face', async () => {
+    const { ctx } = await bench()
+    const entry = ctx.slots
+      .entries('conversation.session.header.actions')
+      .find(candidate => candidate.options.id === 'job-list')
+    const inject = entry?.inject as (() => JobListInjected) | undefined
+    if (inject === undefined) throw new Error('job-list entry registered no inject face')
+    const face = inject()
+    expect(face.hooks.jobs).toBeDefined()
+    const release = face.watchRows(SessionId('session'))
+    expect(watched).toEqual(['session'])
+    release()
+    const stopper = face.observe(SessionId('session'), JobId('bash-1'))
+    expect(observed).toEqual([['session', 'bash-1']])
+    stopper()
   })
 
   it('registers the header action, and fiber teardown removes it (HMR safety)', async () => {
@@ -75,7 +110,7 @@ describe('ui-job browser half', () => {
   })
 })
 
-describe('ui-job node half', () => {
+describe('ui-jobs node half', () => {
   it('contributes no host behavior', () => {
     // The node half exists only so the plugin appears in the Loader tree.
     expect(applyNode).not.toThrow()
diff --git a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx
index e42e0ef556..dd50c639c6 100644
--- a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx
+++ b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx
@@ -1,241 +1,370 @@
 // @vitest-environment jsdom
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
-import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
-import type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types'
+import type { JobsSnapshot, JobView, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { JobListAction, type JobListActionProps } from '../src/client/JobListAction.tsx'
 import { zh } from '../src/client/locales.ts'
 
-// Live rows render `now - startedAt`, so every assertion needs a pinned clock.
-beforeEach(() => {
-  vi.useFakeTimers()
-  vi.setSystemTime(START)
-})
-
 afterEach(() => {
   cleanup()
-  vi.useRealTimers()
   vi.restoreAllMocks()
+  vi.useRealTimers()
 })
 
 const SESSION = 'session' as SessionId
-const START = 1_700_000_000_000
 const t: JobListActionProps['t'] = makeTranslate(zh)
 
+/** A running job with nothing retained yet. */
 function job(over: Partial<JobView> = {}): JobView {
   return {
     id: 'bash-1' as JobView['id'],
     kind: 'bash',
     label: 'pnpm run build',
     status: 'running',
-    startedAt: START,
+    startedAt: 1_700_000_000_000,
+    output: { total: 0, earliest: 0 },
     ...over,
   }
 }
 
-function props(jobs: readonly JobView[] | undefined): JobListActionProps {
-  const state = {
-    ids: [SESSION],
-    byId: {},
-    phase: 'ready',
-    projectionsBySession: {},
-    jobsBySession: jobs === undefined ? {} : { [SESSION]: jobs },
-  } satisfies SessionListState
-  function useSessions<T>(select: (snapshot: SessionListState) => T): T {
-    return select(state)
-  }
-  return { sessionId: SESSION, useSessions, t } as unknown as JobListActionProps
+/** A job that left retained output behind, so its row offers a panel even once settled. */
+function outputJob(over: Partial<JobView> = {}): JobView {
+  return job({ output: { total: 12, earliest: 0 }, ...over })
 }
 
-/**
- * Rows in render order as `[kind, label, status, duration]`. Adjacent spans
- * carry no whitespace between them, so the cells are read one element at a
- * time rather than split out of a flattened string.
- */
-function rowCells(): string[][] {
-  return within(screen.getByRole('list', { name: zh['list.aria'] }))
-    .getAllByRole('listitem')
-    .map(row => [...row.children]
-      .map(cell => cell.textContent ?? '')
-      .filter(text => text !== ''))
+function props(
+  jobs: readonly JobView[],
+  observe: JobListActionProps['observe'] = () => () => {},
+  observed: Readonly<Record<string, ObservedJob>> = {},
+  watchRows: JobListActionProps['watchRows'] = () => () => {},
+): JobListActionProps {
+  const jobsState: JobsSnapshot = { rows: jobs.length > 0 ? { [SESSION]: jobs } : {}, observed }
+  function useJobs<T>(select: (value: JobsSnapshot) => T): T {
+    return select(jobsState)
+  }
+  return { sessionId: SESSION, useJobs, watchRows, observe, t } as JobListActionProps
+}
+
+function openList(): void {
+  fireEvent.click(screen.getAllByRole('button')[0]!)
 }
 
 describe('JobListAction visibility', () => {
-  it('renders nothing while the session has no jobs', () => {
-    const { container } = render(<JobListAction {...props(undefined)} />)
+  it('renders nothing while the session sees no jobs', () => {
+    const { container } = render(<JobListAction {...props([])} />)
     expect(container.innerHTML).toBe('')
   })
 
-  it('counts only live jobs, and falls back to the total when none are live', () => {
-    const { rerender } = render(<JobListAction {...props([job(), job({ id: 'bash-2' as JobView['id'] })])} />)
+  it('watches the session roster while mounted and releases it on unmount', () => {
+    const stop = vi.fn()
+    const watchRows = vi.fn(() => stop)
+    const { unmount } = render(<JobListAction {...props([], undefined, {}, watchRows)} />)
+    expect(watchRows).toHaveBeenCalledWith(SESSION)
+    expect(stop).not.toHaveBeenCalled()
+    unmount()
+    expect(stop).toHaveBeenCalledTimes(1)
+  })
+
+  it('counts live jobs on the trigger', () => {
+    render(<JobListAction {...props([
+      job(),
+      job({ id: 'subagent-1' as JobView['id'], kind: 'subagent', label: 'explore' }),
+    ])} />)
     expect(screen.getByRole('button', { name: '2 个后台任务运行中' })).toBeDefined()
-
-    rerender(<JobListAction {...props([job({ status: 'completed', finishedAt: START + 3_000 })])} />)
-    expect(screen.getByRole('button', { name: '1 个后台任务' })).toBeDefined()
   })
 
-  it('closes and unmounts when the last job disappears while the list is open', () => {
-    const { container, rerender } = render(<JobListAction {...props([job()])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(screen.getByRole('list', { name: zh['list.aria'] })).toBeDefined()
-
-    rerender(<JobListAction {...props([])} />)
-    expect(container.innerHTML).toBe('')
+  it('falls back to the total when nothing is live', () => {
+    render(<JobListAction {...props([
+      job({ status: 'completed', finishedAt: 1_700_000_003_000 }),
+    ])} />)
+    expect(screen.getByRole('button', { name: '1 个后台任务' })).toBeDefined()
   })
 })
 
 describe('JobListAction rows', () => {
-  it('orders live jobs by start, then settled jobs newest-first', () => {
+  it('renders a settled job without retained output as a static row', () => {
     render(<JobListAction {...props([
-      job({ id: 'bash-3' as JobView['id'], label: 'old done', status: 'completed', startedAt: START, finishedAt: START + 1_000 }),
-      job({ id: 'bash-4' as JobView['id'], label: 'new done', status: 'failed', startedAt: START, finishedAt: START + 9_000 }),
-      job({ id: 'bash-2' as JobView['id'], label: 'later live', startedAt: START + 5_000 }),
-      job({ id: 'bash-1' as JobView['id'], label: 'earlier live', startedAt: START }),
+      job({ id: 'subagent-1' as JobView['id'], kind: 'subagent', label: 'explore the repo', status: 'completed', finishedAt: 1_700_000_003_000 }),
     ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells()).toEqual([
-      ['bash', 'earlier live', '运行中', '0秒'],
-      ['bash', 'later live', '运行中', '0秒'],
-      ['bash', 'new done', '已失败', '9秒'],
-      ['bash', 'old done', '已完成', '1秒'],
+    expect(screen.getByRole('button', { name: '1 个后台任务' })).toBeDefined()
+    openList()
+    expect(screen.getByText('explore the repo')).toBeDefined()
+    expect(screen.queryByRole('button', { name: zh['row.expandAria'].replace('{label}', 'explore the repo') })).toBeNull()
+  })
+
+  it('offers a panel on a live row before any output arrived', () => {
+    render(<JobListAction {...props([job({ label: 'warming up' })])} />)
+    openList()
+    expect(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'warming up') })).toBeDefined()
+  })
+
+  it('shows the live progress line in place of the status word', () => {
+    render(<JobListAction {...props([job({ status: 'stopping', progress: 'winding down' })])} />)
+    openList()
+    const list = screen.getByRole('list', { name: zh['list.aria'] })
+    expect(within(list).getAllByRole('listitem')).toHaveLength(1)
+    expect(within(list).getByText('pnpm run build')).toBeDefined()
+    expect(within(list).getByText('winding down')).toBeDefined()
+  })
+
+  it('labels each non-empty section and drops the heading of an empty one', () => {
+    const settled = [job({ id: 'bash-2' as JobView['id'], status: 'completed', finishedAt: 1_700_000_012_000 })]
+    const { rerender } = render(<JobListAction {...props([job(), ...settled])} />)
+    openList()
+    expect(screen.getByText(zh['section.live'])).toBeDefined()
+    expect(screen.getByText(zh['section.settled'])).toBeDefined()
+    // A live-only list keeps its own heading and drops the settled one.
+    rerender(<JobListAction {...props([job()])} />)
+    expect(screen.getByText(zh['section.live'])).toBeDefined()
+    expect(screen.queryByText(zh['section.settled'])).toBeNull()
+  })
+
+  it('shows a settled duration and ticks a live one', () => {
+    vi.useFakeTimers({ now: 1_700_000_020_000 })
+    render(<JobListAction {...props([
+      job({ startedAt: 1_700_000_015_000 }),
+      job({ id: 'bash-2' as JobView['id'], status: 'completed', startedAt: 1_700_000_000_000, finishedAt: 1_700_000_012_000 }),
+      job({ id: 'bash-3' as JobView['id'], status: 'completed', startedAt: 1_699_996_200_000, finishedAt: 1_700_000_000_000 }),
+      job({ id: 'bash-4' as JobView['id'], status: 'completed', startedAt: 1_699_999_900_000, finishedAt: 1_699_999_972_000 }),
+    ])} />)
+    openList()
+    expect(screen.getByText('5秒')).toBeDefined()
+    expect(screen.getByText('12秒')).toBeDefined()
+    expect(screen.getByText('1小时3分')).toBeDefined()
+    expect(screen.getByText('1分12秒')).toBeDefined()
+    act(() => { vi.advanceTimersByTime(1_000) })
+    expect(screen.getByText('6秒')).toBeDefined()
+  })
+
+  it('lists rows with kind, label, and progress, terminal detail, or status', () => {
+    render(<JobListAction {...props([
+      job(),
+      outputJob({ id: 'bash-2' as JobView['id'], status: 'failed', detail: 'exit code: 3', finishedAt: 1_700_000_002_000 }),
+    ])} />)
+    openList()
+    const list = screen.getByRole('list', { name: zh['list.aria'] })
+    const items = within(list).getAllByRole('listitem')
+    expect(items).toHaveLength(2)
+    expect(items[0]?.textContent).toContain('pnpm run build')
+    expect(items[0]?.textContent).toContain(zh['status.running'])
+    expect(items[1]?.textContent).toContain('exit code: 3')
+  })
+
+  it('orders live rows first by start and settled rows newest-first with tie-breaks', () => {
+    const settled = (id: string, label: string, startedAt: number, finishedAt?: number): JobView =>
+      job({
+        id: id as JobView['id'],
+        label,
+        status: 'completed',
+        startedAt,
+        ...finishedAt !== undefined ? { finishedAt } : {},
+      })
+    render(<JobListAction {...props([
+      settled('bash-a', 'settled-a', 10, 100),
+      settled('bash-c', 'settled-c', 80, 100),
+      settled('bash-b', 'settled-b', 90),
+      settled('bash-e', 'settled-e', 95, 50),
+      settled('bash-d', 'settled-d', 10, 200),
+      job({ id: 'bash-l1' as JobView['id'], label: 'live-1', startedAt: 5 }),
+      job({ id: 'bash-l2' as JobView['id'], label: 'live-2', startedAt: 3 }),
+    ])} />)
+    openList()
+    const labels = within(screen.getByRole('list', { name: zh['list.aria'] }))
+      .getAllByRole('listitem')
+      .map(item => item.querySelector('[title]')?.getAttribute('title'))
+    expect(labels).toEqual([
+      'live-2', 'live-1', 'settled-d', 'settled-a', 'settled-c', 'settled-b', 'settled-e',
     ])
+    expect(screen.getAllByText(zh['status.completed']).length).toBeGreaterThan(0)
   })
 
   it('breaks a settled tie on start order so map iteration never decides it', () => {
     render(<JobListAction {...props([
-      job({ id: 'bash-2' as JobView['id'], label: 'second', status: 'completed', startedAt: START + 10, finishedAt: START + 100 }),
-      job({ id: 'bash-1' as JobView['id'], label: 'first', status: 'completed', startedAt: START, finishedAt: START + 100 }),
+      job({ id: 'bash-2' as JobView['id'], label: 'second', status: 'completed', startedAt: 1_700_000_000_000 + 10, finishedAt: 1_700_000_000_000 + 100 }),
+      job({ id: 'bash-1' as JobView['id'], label: 'first', status: 'completed', startedAt: 1_700_000_000_000, finishedAt: 1_700_000_000_000 + 100 }),
     ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells().map(cells => cells[1])).toEqual(['first', 'second'])
+    openList()
+    expect(within(screen.getByRole('list')).getAllByRole('listitem').map(row => row.querySelector('[title]')?.getAttribute('title')))
+      .toEqual(['first', 'second'])
   })
 
   it('prefers the producer detail over the generic status word', () => {
     render(<JobListAction {...props([
-      job({ status: 'killed', detail: 'signal: SIGTERM', finishedAt: START + 2_000 }),
+      job({ status: 'killed', detail: 'signal: SIGTERM', finishedAt: 1_700_000_000_000 + 2_000 }),
     ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells()[0]).toContain('signal: SIGTERM')
+    openList()
+    expect(within(screen.getByRole('list')).getAllByRole('listitem')[0]?.textContent).toContain('signal: SIGTERM')
   })
 
   it('renders every status word, including the stopping transition', () => {
     render(<JobListAction {...props([
       job({ id: 'bash-1' as JobView['id'], label: 'a', status: 'running' }),
       job({ id: 'bash-2' as JobView['id'], label: 'b', status: 'stopping' }),
-      job({ id: 'bash-3' as JobView['id'], label: 'c', status: 'completed', finishedAt: START }),
-      job({ id: 'bash-4' as JobView['id'], label: 'd', status: 'killed', finishedAt: START }),
-      job({ id: 'bash-5' as JobView['id'], label: 'e', status: 'failed', finishedAt: START }),
+      job({ id: 'bash-3' as JobView['id'], label: 'c', status: 'completed', finishedAt: 1_700_000_000_000 }),
+      job({ id: 'bash-4' as JobView['id'], label: 'd', status: 'killed', finishedAt: 1_700_000_000_000 }),
+      job({ id: 'bash-5' as JobView['id'], label: 'e', status: 'failed', finishedAt: 1_700_000_000_000 }),
     ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    const words = rowCells().map(cells => cells[2])
-    expect(new Set(words)).toEqual(new Set(['运行中', '正在停止', '已完成', '已取消', '已失败']))
-    expect([...screen.getByRole('list').querySelectorAll(':scope > li [data-state]')].map(node => node.getAttribute('data-state')))
+    openList()
+    for (const word of ['运行中', '正在停止', '已完成', '已取消', '已失败']) {
+      expect(within(screen.getByRole('list')).getByText(word)).toBeDefined()
+    }
+    expect([...screen.getByRole('list').querySelectorAll('li [data-state]')].map(node => node.getAttribute('data-state')))
       .toEqual(['ongoing', 'warning', 'done', 'warning', 'error'])
   })
 })
 
-describe('JobListAction duration', () => {
-  it('advances a live row once per second and freezes a settled one', () => {
-    vi.setSystemTime(START + 1_000)
-    render(<JobListAction {...props([
-      job({ id: 'bash-1' as JobView['id'], label: 'live' }),
-      job({ id: 'bash-2' as JobView['id'], label: 'done', status: 'completed', finishedAt: START + 4_000 }),
-    ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells()[0]).toContain('1秒')
-    expect(rowCells()[1]).toContain('4秒')
-
-    act(() => { vi.advanceTimersByTime(2_000) })
-    expect(rowCells()[0]).toContain('3秒')
-    expect(rowCells()[1]).toContain('4秒')
+describe('JobListAction observation', () => {
+  it('marks killed rows, renders every output line unfolded, and copies the command', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const lines = Array.from({ length: 24 }, (_value, index) => `line ${index + 1}`).join('\n')
+    const view: ObservedJob = {
+      jobId: 'bash-1' as JobView['id'],
+      text: lines,
+      gapBefore: false,
+      streaming: false,
+    }
+    render(<JobListAction {...props(
+      [outputJob({ status: 'killed', finishedAt: 1_700_000_001_000 })],
+      undefined,
+      { 'bash-1': view },
+    )} />)
+    openList()
+    expect(screen.getByText(zh['status.killed'])).toBeDefined()
+    fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') }))
+    // The panel scrolls instead of folding: every line renders, no fold control.
+    expect(screen.getByText('line 1')).toBeDefined()
+    expect(screen.getByText('line 24')).toBeDefined()
+    expect(screen.queryByRole('button', { name: zh['terminal.expandAria'].replace('{n}', '8') })).toBeNull()
+    // The panel draws no state dot or label of its own — the row carries it.
+    expect(screen.queryByText(zh['terminal.done'])).toBeNull()
+    // The copy control carries the command, not the output.
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['terminal.copy'] })) })
+    expect(writeText).toHaveBeenCalledWith('pnpm run build')
   })
 
-  it('widens to minutes and then hours, and never shows a negative figure', () => {
-    render(<JobListAction {...props([
-      job({ id: 'bash-1' as JobView['id'], label: 'm', status: 'completed', finishedAt: START + 125_000 }),
-      job({ id: 'bash-2' as JobView['id'], label: 'h', status: 'completed', finishedAt: START + 7_380_000 }),
-      // A clock that moved backwards must not render a negative duration.
-      job({ id: 'bash-3' as JobView['id'], label: 'skew', status: 'completed', startedAt: START + 5_000, finishedAt: START }),
-    ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells().map(cells => cells[3])).toEqual(['2小时3分', '2分5秒', '0秒'])
+  it('shifts an overflowing popover back inside the viewport and follows resizes', () => {
+    vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(440)
+    vi.spyOn(HTMLDivElement.prototype, 'getBoundingClientRect').mockReturnValue({ left: 344 } as DOMRect)
+    const originalWidth = window.innerWidth
+    Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true })
+    try {
+      render(<JobListAction {...props([job()])} />)
+      openList()
+      const menu = screen.getByRole('list', { name: zh['list.aria'] })
+      // 700 - 12 - 440 - 344 = -96: the popover moves left to keep the margin.
+      expect(menu.style.left).toBe('-96px')
+
+      window.innerWidth = 900
+      fireEvent(window, new Event('resize'))
+      // 900 - 12 - 440 - 344 = 104 > 0: the anchored position fits again.
+      expect(menu.style.left).toBe('0px')
+    } finally {
+      Object.defineProperty(window, 'innerWidth', { value: originalWidth, configurable: true, writable: true })
+    }
   })
 
-  it('runs no clock while the list is closed', () => {
-    const interval = vi.spyOn(globalThis, 'setInterval')
-    render(<JobListAction {...props([job()])} />)
-    expect(interval).not.toHaveBeenCalled()
-    fireEvent.click(screen.getByRole('button'))
-    expect(interval).toHaveBeenCalledTimes(1)
+  it('never crosses the left viewport margin for an oversized popover', () => {
+    vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(800)
+    vi.spyOn(HTMLDivElement.prototype, 'getBoundingClientRect').mockReturnValue({ left: 4 } as DOMRect)
+    const originalWidth = window.innerWidth
+    Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true })
+    try {
+      render(<JobListAction {...props([job()])} />)
+      openList()
+      const menu = screen.getByRole('list', { name: zh['list.aria'] })
+      // max(12 - 4, min(0, 700 - 12 - 800 - 4)) = 8: clamped at the left margin.
+      expect(menu.style.left).toBe('8px')
+    } finally {
+      Object.defineProperty(window, 'innerWidth', { value: originalWidth, configurable: true, writable: true })
+    }
   })
 
-  it('runs no clock for an open list holding only settled jobs', () => {
-    const interval = vi.spyOn(globalThis, 'setInterval')
-    render(<JobListAction {...props([job({ status: 'completed', finishedAt: START })])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(interval).not.toHaveBeenCalled()
+  it('ignores other keys while open and closes once the roster empties', () => {
+    const settledPair = [
+      outputJob({ id: 'bash-1' as JobView['id'], status: 'completed', finishedAt: 2 }),
+      outputJob({ id: 'bash-2' as JobView['id'], status: 'completed', finishedAt: 3 }),
+    ]
+    const { rerender } = render(<JobListAction {...props(settledPair)} />)
+    expect(screen.getByRole('button', { name: '2 个后台任务' })).toBeDefined()
+    openList()
+    const list = screen.getByRole('list', { name: zh['list.aria'] })
+    fireEvent.keyDown(list, { key: 'a' })
+    expect(screen.getByRole('list', { name: zh['list.aria'] })).toBeDefined()
+    // The roster emptying unmounts the control entirely; the open flag resets first.
+    rerender(<JobListAction {...props([])} />)
+    expect(screen.queryByRole('button')).toBeNull()
   })
-})
 
-describe('JobListAction dismissal', () => {
-  it('closes on Escape and returns focus to the trigger', () => {
-    render(<JobListAction {...props([job()])} />)
-    const trigger = screen.getByRole('button')
-    fireEvent.click(trigger)
-    expect(trigger.getAttribute('aria-expanded')).toBe('true')
+  it('starts observing on expand with the session identity, renders the live text, and stops on collapse', () => {
+    const stop = vi.fn()
+    const observe = vi.fn(() => stop)
+    const view: ObservedJob = {
+      jobId: 'bash-1' as JobView['id'],
+      text: 'compiling…\n',
+      gapBefore: false,
+      streaming: true,
+    }
+    render(<JobListAction {...props([job()], observe, { 'bash-1': view })} />)
+    openList()
+    fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') }))
+    expect(observe).toHaveBeenCalledWith(SESSION, 'bash-1')
+    expect(screen.getByText('compiling…')).toBeDefined()
 
-    fireEvent.keyDown(trigger, { key: 'Escape' })
-    expect(trigger.getAttribute('aria-expanded')).toBe('false')
-    expect(document.activeElement).toBe(trigger)
+    fireEvent.click(screen.getByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'pnpm run build') }))
+    expect(stop).toHaveBeenCalledTimes(1)
   })
 
-  it('ignores other keys and a closed-list Escape', () => {
-    render(<JobListAction {...props([job()])} />)
-    const trigger = screen.getByRole('button')
-    fireEvent.keyDown(trigger, { key: 'Escape' })
-    expect(trigger.getAttribute('aria-expanded')).toBe('false')
-
-    fireEvent.click(trigger)
-    fireEvent.keyDown(trigger, { key: 'ArrowDown' })
-    expect(trigger.getAttribute('aria-expanded')).toBe('true')
+  it('renders a running panel with the prompt alone for a live row whose output has not arrived', () => {
+    const view: ObservedJob = {
+      jobId: 'bash-1' as JobView['id'],
+      text: '',
+      gapBefore: false,
+      streaming: true,
+    }
+    const { container } = render(<JobListAction {...props([job()], undefined, { 'bash-1': view })} />)
+    openList()
+    fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') }))
+    expect(container.querySelector('[data-running]')).not.toBeNull()
+    expect(screen.queryByText(zh['terminal.noOutput'])).toBeNull()
   })
-
-  it('closes on an outside pointer press but not on one inside', () => {
-    render(<JobListAction {...props([job()])} />)
-    const trigger = screen.getByRole('button')
-    fireEvent.click(trigger)
-
-    fireEvent.pointerDown(screen.getByRole('list', { name: zh['list.aria'] }))
-    expect(trigger.getAttribute('aria-expanded')).toBe('true')
 
-    fireEvent.pointerDown(document.body)
-    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+  it('surfaces retention gaps and stream failures above the panel', () => {
+    const view: ObservedJob = {
+      jobId: 'bash-1' as JobView['id'],
+      text: 'tail only',
+      gapBefore: true,
+      streaming: false,
+      error: 'connection lost',
+    }
+    render(<JobListAction {...props([job()], undefined, { 'bash-1': view })} />)
+    openList()
+    fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') }))
+    expect(screen.getByText(zh['output.gap'])).toBeDefined()
+    expect(screen.getByText('实时输出流中断：connection lost')).toBeDefined()
   })
-})
 
-describe('JobListAction wire tolerance', () => {
-  it('treats a settled job with no finishedAt as zero-duration and sorts it by start', () => {
-    // `finishedAt` is optional on the wire; the Host always sets it, so this
-    // covers a producer or carrier that ever stops doing so.
-    render(<JobListAction {...props([
-      job({ id: 'bash-1' as JobView['id'], label: 'no finish', status: 'completed' }),
-      job({ id: 'bash-2' as JobView['id'], label: 'finished', status: 'completed', startedAt: START - 1_000, finishedAt: START + 2_000 }),
-    ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells().map(cells => [cells[1], cells[3]])).toEqual([
-      ['finished', '3秒'],
-      ['no finish', '0秒'],
-    ])
+  it('stops observation when the popover closes via Escape', () => {
+    const stop = vi.fn()
+    render(<JobListAction {...props([job()], () => stop)} />)
+    openList()
+    fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') }))
+    fireEvent.keyDown(screen.getByRole('list', { name: zh['list.aria'] }), { key: 'Escape' })
+    expect(stop).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('list', { name: zh['list.aria'] })).toBeNull()
   })
 
-  it('falls back to start order when neither settled job carries a finish time', () => {
-    render(<JobListAction {...props([
-      job({ id: 'bash-2' as JobView['id'], label: 'later', status: 'failed', startedAt: START + 1_000 }),
-      job({ id: 'bash-1' as JobView['id'], label: 'earlier', status: 'failed', startedAt: START }),
-    ])} />)
-    fireEvent.click(screen.getByRole('button'))
-    expect(rowCells().map(cells => cells[1])).toEqual(['later', 'earlier'])
+  it('folds an expanded panel whose row left the roster', () => {
+    const stop = vi.fn()
+    // One stable observe identity across renders, as the inject face provides.
+    const observe = () => stop
+    const { rerender } = render(<JobListAction {...props([job()], observe)} />)
+    openList()
+    fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') }))
+    rerender(<JobListAction {...props([job({ id: 'bash-2' as JobView['id'], label: 'other' })], observe)} />)
+    expect(stop).toHaveBeenCalledTimes(1)
+    expect(screen.queryByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'other') })).toBeNull()
   })
 })
diff --git a/packages/client/ui-jobs/tsconfig.json b/packages/client/ui-jobs/tsconfig.json
index 0e66aa4958..38756e4d88 100644
--- a/packages/client/ui-jobs/tsconfig.json
+++ b/packages/client/ui-jobs/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../api/job-controller/tsconfig.client.json"
+    },
     {
       "path": "../../api/session-controller/tsconfig.client.json"
     },
diff --git a/packages/client/ui-layout/tests/app-frame.client.spec.tsx b/packages/client/ui-layout/tests/app-frame.client.spec.tsx
index b097c4b62c..7e334afb80 100644
--- a/packages/client/ui-layout/tests/app-frame.client.spec.tsx
+++ b/packages/client/ui-layout/tests/app-frame.client.spec.tsx
@@ -78,7 +78,6 @@ function mountFrame(windowWidth = frameWidth) {
     },
     phase: 'ready',
     projectionsBySession: {},
-    jobsBySession: {},
   })
   const workspaceState: WorkspaceSnapshot = {
     items: [], archivedSessionIds: [], pinnedSessionIds: [], state: 'idle', phase: 'ready', error: null,
diff --git a/packages/client/ui-layout/tests/document-title.client.spec.tsx b/packages/client/ui-layout/tests/document-title.client.spec.tsx
index 0aefd57215..0b39340f74 100644
--- a/packages/client/ui-layout/tests/document-title.client.spec.tsx
+++ b/packages/client/ui-layout/tests/document-title.client.spec.tsx
@@ -21,7 +21,6 @@ function titleSources() {
     byId: { [sessionId]: { id: sessionId, displayTitle: 'Test', running: false, retainedBy: { mainView: 1 }, blank: false, updatedAt: 1 } },
     phase: 'ready',
     projectionsBySession: {},
-    jobsBySession: {},
   })
   const panelInfo = createSnapshotStore<PanelInfo>({ activePanelId: null })
   return {
diff --git a/packages/client/ui-open-in-app/README.i18n.yaml b/packages/client/ui-open-in-app/README.i18n.yaml
index fbf2a75bc6..b0fa75db3e 100644
--- a/packages/client/ui-open-in-app/README.i18n.yaml
+++ b/packages/client/ui-open-in-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/client/ui-open-in-app/README.md
-README.md: b70b39e79a172badc2b237083d6cd268e9cce06e
-README.zh.md: 9d47e57cfe388b3823cee648f1fdf3187b534d78
+README.md: 138be128c291fc4a0611295c54768a95f33f3ae1
+README.zh.md: b81f62f9dbf8ccfbc1822b8a72df95e7169228c0
diff --git a/packages/client/ui-open-in-app/README.md b/packages/client/ui-open-in-app/README.md
index b70b39e79a..138be128c2 100644
--- a/packages/client/ui-open-in-app/README.md
+++ b/packages/client/ui-open-in-app/README.md
@@ -29,9 +29,11 @@ Mount this plugin in the Web composition beside [`dsh-host-open-in-app`](../../h
 
 ### What to expect
 
-The main button shows the remembered application's icon — the real application icon wherever the host extracts one (macOS bundle icons, Windows executable icons, Linux theme icons), a generic glyph where it serves none — and a design-system tooltip ("Open locally"); clicking launches immediately. The chevron opens a dense menu of the installed applications with the remembered one marked by a filled row. Availability is read once per page from the host; the last chosen application persists in the browser (`dsh.open-in-app.choice`), and a choice that is no longer installed falls back to the first available entry. A launch that finishes quickly leaves the button untouched — the dimmed busy treatment appears only after 250 ms in flight — and a failed launch shows the error tooltip and a red outline for two seconds. All copy lives in the bilingual `open-in-app` locale namespace; an application id the dictionaries cannot name is not offered.
+The Session header and document header use the same 24px-high split button with 9px corners. Both headers show only the icon; their tooltip names the default application or the reveal action. Both show the default action’s icon, mark its application with “(default)” in the menu, disable while their own gesture runs, and report failures through a transient toast. The directory adapter uses the existing cross-platform application catalog and remembers the last successful choice in `dsh.open-in-app.choice`; a missing choice falls back to the first available application.
 
-In the document preview, the header's "Open ▾" split button opens the previewed file in the Host's default application from its main button, and its menu offers that action and "Show file location" (the file manager's reveal). A file the preview cannot render, whether an unsupported suffix such as video or an archive or a file the reader rejected as non-text or oversized, shows an "Open in default app" button in its empty state where Retry would otherwise stand. Both controls hand the Host the absolute path the file's metadata reports, appear only after the Host answered that a desktop is available, disable only while their own gesture settles, and announce a failed gesture once through a transient toast ("Could not open. Try again." or "Could not show the file location. Try again."); nothing stays on the control afterwards.
+File menus list the discovered associated applications without a separate “Open in default app” row. “Show file location” stays in a fixed footer separated from the scrolling applications. A successful query with only one available action renders a single button without a dropdown. Initial file-association loading uses a gray skeleton icon. When no default application is identified, that row reads “Show file location (default)” and the main button reveals the file. Directory menus have no reveal row. Choosing a file application does not change the system default. An unpreviewable file uses the same menu in a 40px-high split button with an icon and action text; its label is “Open” or “Show file location” according to the default action.
+
+Mounted controls with the same association reader and file share one query and its results; opening either menu refreshes all of them. Releasing the last control cancels the query and discards its state. Cancelled queries cannot replace another file’s results. A failed query displays a menu message and leaves reveal available as the default action. File-association discovery follows [native-command](../../util/native-command/README.md); an empty result, including a platform without a discovery adapter, uses the same reveal fallback without platform branches in the control.
 
 -----
 
@@ -43,7 +45,7 @@ In the document preview, the header's "Open ▾" split button opens the previewe
 
 The plugin registers the split button on `conversation.session.header.utilities` through the standard slot/inject currency and registers the `open-in-app` dictionaries as one effect. A page-lifetime controller ([`src/client/controller.ts`](src/client/controller.ts)) owns the once-per-page availability read, the persisted choice snapshot store, and the launch POST; the component receives both stores through the inject `hooks` compartment, so every Session header shares one truth. Document-relative route forms and wire payload types come from the host package's browser-safe `@deepseek-ai/dsh-host-open-in-app/shared` subpath. In-flight launches are guarded by a ref — repeat clicks and menu picks during a launch are ignored whole (a pick would otherwise persist a choice the gesture never opened) — and the busy/error dress is timer-driven around the `launch` promise.
 
-The file controls register on the document preview's `sidebar.right.tab.document.actions` and `sidebar.right.tab.document.unpreviewable` child slots, whose owner props carry the file’s absolute execution-environment path. A second page-lifetime controller ([`src/client/open-path.ts`](src/client/open-path.ts)) reads the Session Remote's `session.canOpenWorkspacePath` once per page into a desktop snapshot store both controls share, and runs each gesture through `session.openWorkspacePath` with the path and, for reveal, `action: 'reveal'`; a refused or rejected call resolves as the failure kind the control announces. The controls share one gesture hook that owns the pending flag and the toast, so a gesture from one control never restyles the other. The node half is an empty `apply` that keeps the plugin on the host roster.
+The directory and file adapters supply application metadata and operations to [`OpenTargetButton`](src/client/OpenTargetButton.tsx), which owns menu ordering, default markers, icons, sizing, and gesture feedback. The file header and empty state share `FileOpenTarget`, while `OpenPathInjected.applications` queries `session.workspacePathApplications` through [`open-path.ts`](src/client/open-path.ts). Opening uses `session.openWorkspacePath`; the Host revalidates an explicitly selected handler before launch. The directory adapter keeps the existing catalog routes. `FileRouteAction` supplies the same control to delivery cards and change review through `deliverables.file.actions` and `deliverables.review.file.actions`; their authenticated routes retain Session file authorization. A failed or unavailable file query therefore needs no platform-specific UI implementation.
 
 </details>
 
@@ -90,4 +92,4 @@ The feature-level decisions, including the split into the host package and this
 
 </details>
 
-**Runtime invariant:** No companion is published. The plugin registers one dictionary effect and three slot entries whose disposal the HMR-safety spec proves; application availability, the choice, and the desktop answer live in the controllers' snapshot stores with no second copy to diverge.
+**Runtime invariant:** No companion is published. The plugin registers one dictionary effect and five slot entries whose disposal the HMR-safety spec proves; application availability, the choice, and the desktop answer live in the controllers' snapshot stores with no second copy to diverge.
diff --git a/packages/client/ui-open-in-app/README.zh.md b/packages/client/ui-open-in-app/README.zh.md
index 9d47e57cfe..b81f62f9db 100644
--- a/packages/client/ui-open-in-app/README.zh.md
+++ b/packages/client/ui-open-in-app/README.zh.md
@@ -29,9 +29,11 @@ kind: "package-reference"
 
 ### 预期行为
 
-主按钮显示记住的应用图标——凡主机能提取的都是应用真实图标（macOS bundle 图标、Windows 可执行文件图标、Linux 主题图标），提取不到时是通用占位图形——并带设计系统 tooltip（「在本地打开」）；点击立即启动。下拉箭头打开已安装应用的紧凑菜单，记住的条目以整行填充标记。可用性每页读取一次；上次选择的应用持久化在浏览器中（`dsh.open-in-app.choice`），不再安装的选择回退到第一个可用条目。快速完成的启动不改变按钮外观——变暗的等待态只在飞行超过 250 毫秒后出现——失败的启动显示错误 tooltip 与红色描边两秒。所有文案在双语 `open-in-app` locale 命名空间中；词典无法命名的应用 id 不会被提供。
+会话标题栏和文档标题栏共用同一个高 24px、圆角 9px 的分体按钮。两个标题栏都只显示图标，悬停提示显示默认应用名称或文件定位动作。两者都显示默认动作的图标，在菜单的默认应用后标注“（默认）”，仅在自己的操作执行期间禁用，并通过短暂提示报告失败。目录适配器使用已有的跨平台应用列表，将最后一次成功选择保存在 `dsh.open-in-app.choice` 中；原选择不可用时回退到第一个可用应用。
 
-在文档预览里，头部的「打开 ▾」分体按钮的主按钮用 Host 默认应用打开当前文件，菜单提供同一动作和「显示文件位置」（文件管理器的定位）。预览无法渲染的文件，无论是视频、压缩包这类不支持的后缀，还是被读取器判为非文本或过大的文件，都会在空态里原本放重试的位置显示「用默认应用打开」按钮。两个控件都把文件元数据报出的绝对路径交给 Host，只在 Host 回答有桌面之后出现，只在自己的手势结算期间禁用，失败时通过短暂 toast 提示一次（「打开失败，请重试」或「无法显示文件位置，请重试」），之后控件上不残留任何状态。
+文件菜单列出已发现的关联应用，不单列“用默认应用打开”。“显示文件位置”固定在菜单底部，通过分隔线与滚动的应用列表分开。查询成功且只有一个可用操作时显示单按钮，不再显示下拉箭头。文件关联首次加载时使用灰色骨架图标。未识别到默认应用时，该项显示为“显示文件位置（默认）”，主按钮也执行文件定位。目录菜单不包含定位项。选择文件应用不修改系统默认应用。无法预览文件时，空态使用同一菜单，按钮增大到 40px 高并显示图标和动作文字；根据默认动作显示“打开”或“显示文件位置”。
+
+使用同一查询函数和文件的已挂载控件共用查询与结果，打开任一菜单会刷新所有相关控件。最后一个控件释放后取消查询并清除状态。已取消的查询不会覆盖其他文件的结果。查询失败时菜单显示提示，并以文件定位作为默认动作。文件关联查询的平台支持范围见 [native-command](../../util/native-command/README.zh.md)；查询结果为空时，包括平台尚无查询适配器的情况，控件统一使用定位动作，不按操作系统分支处理。
 
 -----
 
@@ -43,7 +45,7 @@ kind: "package-reference"
 
 插件通过标准 slot/inject 机制把分体按钮注册到 `conversation.session.header.utilities`，并以一个 effect 注册 `open-in-app` 词典。一个页面生命周期的 controller（[`src/client/controller.ts`](src/client/controller.ts)）拥有每页一次的可用性读取、持久化选择的 snapshot store 与启动 POST；组件经 inject 的 `hooks` 隔间接收两个 store，因此所有会话头部共享同一份事实。文档相对的路由形式与 wire 载荷类型来自主机包的浏览器安全子路径 `@deepseek-ai/dsh-host-open-in-app/shared`。飞行中的启动由 ref 守卫——启动期间的重复点击与菜单选择被整体忽略（否则会持久化一个该手势从未打开的选择）——busy/error 视觉由围绕 `launch` promise 的定时器驱动。
 
-文件控件注册在文档预览的 `sidebar.right.tab.document.actions` 与 `sidebar.right.tab.document.unpreviewable` 子 slot 上，owner props 携带文件在执行环境中的绝对路径。第二个页面生命周期的 controller（[`src/client/open-path.ts`](src/client/open-path.ts)）每页读取一次 Session Remote 的 `session.canOpenWorkspacePath`，写进两个控件共用的桌面 snapshot store，并把每个手势交给 `session.openWorkspacePath`，带上路径，定位时再带 `action: 'reveal'`；被拒绝或抛错的调用解析为控件要提示的失败种类。两个控件共用一个手势 hook，由它持有 pending 标志和 toast，所以一个控件的手势不会改变另一个控件的样子。节点半边是一个空 `apply`，让插件出现在主机侧的插件名册上。
+目录和文件适配器把应用信息与操作交给 [`OpenTargetButton`](src/client/OpenTargetButton.tsx)，由它统一管理菜单顺序、默认标记、图标、尺寸和操作反馈。文件标题栏和空态共用 `FileOpenTarget`，`OpenPathInjected.applications` 通过 [`open-path.ts`](src/client/open-path.ts) 查询 `session.workspacePathApplications`。打开操作使用 `session.openWorkspacePath`，Host 在启动前重新验证指定的关联应用。`FileRouteAction` 通过 `deliverables.file.actions` 和 `deliverables.review.file.actions` 为交付卡片和变更对比页提供同一控件，其认证路由保留会话文件校验。目录适配器继续使用已有的应用列表路由，文件查询失败或不可用时无需增加平台专用的界面实现。
 
 </details>
 
@@ -90,4 +92,4 @@ Host 在打开或定位前通过当前文件系统验证路径。没有对应 Ho
 
 </details>
 
-**运行时不变式：** 不发布伴生入口。插件注册一个词典 effect 和三个 slot 条目，HMR 安全性 spec 证明它们都会在资源释放时撤销；应用可用性、选择与桌面回答存储在控制器的快照存储中，不存在可能与之分歧的第二份副本。
+**运行时不变式：** 不发布伴生入口。插件注册一个词典 effect 和五个 slot 条目，HMR 安全性 spec 证明它们都会在资源释放时撤销；应用可用性、选择与桌面回答存储在控制器的快照存储中，不存在可能与之分歧的第二份副本。
diff --git a/packages/client/ui-open-in-app/package.json b/packages/client/ui-open-in-app/package.json
index 3b9e784afb..fde52fc3e9 100644
--- a/packages/client/ui-open-in-app/package.json
+++ b/packages/client/ui-open-in-app/package.json
@@ -70,6 +70,8 @@
     "@deepseek-ai/dsh-host-open-in-app": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@types/react": "~18.3.1",
-    "react": "^18.2.0"
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-ui-deliverables": "workspace:^",
+    "@deepseek-ai/dsh-native-command": "workspace:^"
   }
 }
diff --git a/packages/client/ui-open-in-app/src/client/FileRouteAction.tsx b/packages/client/ui-open-in-app/src/client/FileRouteAction.tsx
new file mode 100644
index 0000000000..49c27245f1
--- /dev/null
+++ b/packages/client/ui-open-in-app/src/client/FileRouteAction.tsx
@@ -0,0 +1,37 @@
+/** Adapt authorized delivery and changed-file routes to the shared opening control. */
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-deliverables/client'
+import { parseNativeFileApplications } from '@deepseek-ai/dsh-native-command/types'
+import type { SessionWorkspacePathApplication } from '@deepseek-ai/dsh-api-session-controller/types'
+import { useFileApplications } from './file-applications.ts'
+import { OpenTargetButton } from './OpenTargetButton.tsx'
+import type { NS } from './locales.ts'
+
+async function queryRoute(url: string, signal: AbortSignal): Promise<readonly SessionWorkspacePathApplication[] | null> {
+  try {
+    const response = await fetch(url, { signal })
+    if (!response.ok) return null
+    return parseNativeFileApplications(await response.json())
+  } catch (_error) {
+    // Unavailable routes and malformed responses leave file reveal as the fallback.
+    return null
+  }
+}
+
+/**
+ * Render file actions without bypassing the owning Session's authorization route.
+ * @param props - authenticated route, desktop availability, and native gesture callback.
+ * @returns the shared compact control, or null without a desktop.
+ */
+export function FileRouteAction(
+  props: Pick<PropsRuntime<'deliverables.file.actions'>, 'actionUrl' | 'available' | 'pending' | 'onAction'> & PropsLocale<typeof NS>,
+) {
+  const association = useFileApplications(props.actionUrl, queryRoute, props.available)
+  if (!props.available) return null
+  return <OpenTargetButton key={props.actionUrl} kind="file" applications={association.apps}
+    defaultId={association.apps.find(app => app.default)?.id} failed={association.failed}
+    loading={association.loading} busy={props.pending} refresh={association.refresh} t={props.t}
+    execute={async (operation) => {
+      return props.onAction(operation.kind === 'reveal' ? 'reveal' : 'open', operation.kind === 'application' ? operation.id : undefined)
+    }} />
+}
diff --git a/packages/client/ui-open-in-app/src/client/OpenInAppAction.module.css b/packages/client/ui-open-in-app/src/client/OpenInAppAction.module.css
deleted file mode 100644
index f5186cc9a6..0000000000
--- a/packages/client/ui-open-in-app/src/client/OpenInAppAction.module.css
+++ /dev/null
@@ -1,64 +0,0 @@
-/* Compact Session-header split button beside the round icon buttons. */
-
-.split {
-  display: inline-flex;
-  align-items: stretch;
-  box-sizing: border-box;
-  height: 24px;
-  border: 0.5px solid var(--dsw-alias-border-l4);
-  border-radius: 9px;
-  overflow: hidden;
-  font-family: var(--dsw-font-family);
-}
-
-.main,
-.chevron {
-  display: inline-flex;
-  align-items: center;
-  gap: 3px;
-  border: 0;
-  background: none;
-  color: var(--dsw-alias-label-primary);
-  font-size: 11px;
-  font-weight: 400;
-  line-height: 16px;
-  cursor: pointer;
-  white-space: nowrap;
-}
-
-.main {
-  padding: 3px 5px;
-}
-
-.main:hover:not(:disabled),
-.main:focus-visible,
-.chevron:hover,
-.chevron:focus-visible {
-  background: var(--dsw-alias-interactive-bg-hover);
-}
-
-.main:disabled {
-  color: var(--dsw-alias-label-dimmed);
-  cursor: wait;
-}
-
-.main[data-state='error'] {
-  color: var(--dsw-alias-state-error-primary);
-  box-shadow: inset 0 0 0 1px var(--dsw-alias-state-error-primary);
-}
-
-.chevron {
-  padding: 3px 4px 3px 3px;
-  border-left: 0.5px solid var(--dsw-alias-border-l4);
-  color: var(--dsw-alias-label-secondary);
-}
-
-.icon {
-  flex: none;
-}
-
-img.icon {
-  display: block;
-  object-fit: contain;
-  user-select: none;
-}
diff --git a/packages/client/ui-open-in-app/src/client/OpenInAppAction.tsx b/packages/client/ui-open-in-app/src/client/OpenInAppAction.tsx
index 78f547a802..a58ed63933 100644
--- a/packages/client/ui-open-in-app/src/client/OpenInAppAction.tsx
+++ b/packages/client/ui-open-in-app/src/client/OpenInAppAction.tsx
@@ -1,10 +1,8 @@
-import { useEffect, useRef, useState } from 'react'
-import { IconChevronDownOutlineRegular, Menu, Tooltip, type MenuItem } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { NS, type OpenInAppKey } from './locales.ts'
-import css from './OpenInAppAction.module.css'
+import { OpenTargetButton } from './OpenTargetButton.tsx'
 
 /** Browser operations and state injected into the Session Header contribution. */
 export interface OpenInAppActionInjected {
@@ -65,162 +63,36 @@ const APP_LABEL_KEY: Record<string, OpenInAppKey | undefined> = {
   konsole: 'app.konsole',
 }
 
-/** App ids whose icon image already failed this page; a 404 icon is fetched once, not per menu open. */
-const failedIcons = new Set<string>()
-
 /**
- * One application's real bundle icon (host-served PNG) with an inline generic
- * app-square fallback while the host has none.
- * @param props - catalog id, host icon URL, and rendered size.
- * @returns the icon image or its fallback glyph.
- */
-function AppIcon({ id, url, size }: { id: string; url: string; size: number }): React.JSX.Element {
-  const [failed, setFailed] = useState(failedIcons.has(id))
-  if (failed) {
-    return (
-      <svg
-        width={size}
-        height={size}
-        viewBox="0 0 24 24"
-        fill="none"
-        className={css.icon}
-        aria-hidden
-      >
-        <path d="M16 3H8C5.23858 3 3 5.23858 3 8V16C3 18.7614 5.23858 21 8 21H16C18.7614 21 21 18.7614 21 16V8C21 5.23858 18.7614 3 16 3Z" fill="currentColor" fillOpacity="0.05" />
-      </svg>
-    )
-  }
-  return (
-    <img
-      src={url}
-      width={size}
-      height={size}
-      className={css.icon}
-      alt=""
-      aria-hidden
-      draggable={false}
-      onError={() => {
-        failedIcons.add(id)
-        setFailed(true)
-      }}
-    />
-  )
-}
-
-/**
- * Quick launches settle well under this delay, so their busy dress never
- * paints — the visible dim-and-wait treatment is reserved for launches that
- * are actually taking a while, instead of flashing on every click.
- */
-const BUSY_DRESS_DELAY_MS = 250
-
-/**
- * Session-header split button: the main button opens the session's workspace
- * directory in the remembered application, the chevron opens the menu of
- * every application the host probed as installed. It renders nothing until
- * the host reported at least one nameable application and the session has a
- * known workspace directory, so a host without the capability never grows
- * the control.
- * @param props - session runtime, injected controller face, and localized copy.
- * @returns the split button and its menu, or null when there is nothing to offer.
+ * Adapt the installed directory catalog to the shared opening control.
+ * @param props - workspace state, installed catalog, and launch operations.
+ * @returns the shared control, or null without an eligible application and directory.
  */
 export function OpenInAppAction(props: OpenInAppActionProps): React.JSX.Element | null {
   const { sessionId, useSessions, useOpenInAppApps, useOpenInAppChoice, t } = props
   const cwd = useSessions(state => state.byId[sessionId]?.cwd)
   const available = useOpenInAppApps(apps => apps)
   const choice = useOpenInAppChoice(id => id)
-  const [open, setOpen] = useState(false)
-  const [phase, setPhase] = useState<'idle' | 'busy' | 'error'>('idle')
-  const inFlight = useRef(false)
-  const busyTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
-  const errorTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
-
-  useEffect(() => () => {
-    clearTimeout(busyTimer.current)
-    clearTimeout(errorTimer.current)
-  }, [])
-
-  const apps = (available ?? [])
-    .map(id => ({ id, labelKey: APP_LABEL_KEY[id] }))
-    .filter((entry): entry is { id: string; labelKey: OpenInAppKey } => entry.labelKey !== undefined)
-  const currentEntry = apps.find(entry => entry.id === choice) ?? apps[0]
-  if (currentEntry === undefined || cwd === undefined || cwd === '') return null
-
-  const current = currentEntry.id
-  const currentLabel = t(currentEntry.labelKey)
-  const title = phase === 'error' ? t('open.error') : t('open.title', { app: currentLabel })
-
-  const launch = (appId: string): void => {
-    if (inFlight.current) return
-    inFlight.current = true
-    // A pending error decay must not flip the button back to idle mid-launch.
-    clearTimeout(errorTimer.current)
-    clearTimeout(busyTimer.current)
-    busyTimer.current = setTimeout(() => { setPhase('busy') }, BUSY_DRESS_DELAY_MS)
-    props.launch(appId, cwd).then(() => {
-      inFlight.current = false
-      clearTimeout(busyTimer.current)
-      setPhase('idle')
-    }, () => {
-      inFlight.current = false
-      clearTimeout(busyTimer.current)
-      setPhase('error')
-      clearTimeout(errorTimer.current)
-      errorTimer.current = setTimeout(() => { setPhase('idle') }, 2_000)
-    })
-  }
-
-  const items: MenuItem[] = apps.map(entry => ({
-    id: entry.id,
-    label: t(entry.labelKey),
-    icon: <AppIcon id={entry.id} url={props.iconUrl(entry.id)} size={14} />,
-  }))
-
+  const apps = (available ?? []).flatMap((id) => {
+    const key = APP_LABEL_KEY[id]
+    return key === undefined ? [] : [{ id, name: t(key), icon: props.iconUrl(id) }]
+  })
+  const preferred = apps.find(app => app.id === choice) ?? apps[0]
+  if (preferred === undefined || cwd === undefined || cwd === '') return null
   return (
-    <Menu
-      open={open}
-      align="end"
-      dense
-      selection="fill"
-      onClose={() => { setOpen(false) }}
-      items={items}
-      selectedId={current}
-      onSelect={(id) => {
-        setOpen(false)
-        // A pick while a launch is in flight is ignored whole: persisting the
-        // choice without launching would leave the button naming an app the
-        // gesture never opened.
-        if (inFlight.current) return
-        props.choose(id)
-        launch(id)
+    <OpenTargetButton
+      key={cwd} kind="directory" applications={apps} defaultId={preferred.id} failed={false} t={t}
+      execute={async (operation) => {
+        const id = operation.kind === 'application' ? operation.id : preferred.id
+        try {
+          await props.launch(id, cwd)
+        } catch (_error) {
+          // Native launch failure is announced by the shared control.
+          return 'openError'
+        }
+        if (operation.kind === 'application') props.choose(id)
+        return null
       }}
-      anchor={(
-        <div className={css.split}>
-          <Tooltip label={phase === 'error' ? t('open.error') : t('open.tooltip')} side="bottom">
-            <button
-              type="button"
-              className={css.main}
-              data-state={phase}
-              disabled={phase === 'busy'}
-              aria-label={title}
-              onClick={() => { launch(current) }}
-            >
-              <AppIcon id={current} url={props.iconUrl(current)} size={13} />
-            </button>
-          </Tooltip>
-          <button
-            type="button"
-            className={css.chevron}
-            aria-expanded={open}
-            aria-haspopup="menu"
-            title={t('menu.toggle')}
-            aria-label={t('menu.toggle')}
-            onClick={() => { setOpen(value => !value) }}
-          >
-            <IconChevronDownOutlineRegular size={10} />
-          </button>
-        </div>
-      )}
     />
   )
 }
diff --git a/packages/client/ui-open-in-app/src/client/OpenPathAction.tsx b/packages/client/ui-open-in-app/src/client/OpenPathAction.tsx
index bc7f842386..2b6008d9b1 100644
--- a/packages/client/ui-open-in-app/src/client/OpenPathAction.tsx
+++ b/packages/client/ui-open-in-app/src/client/OpenPathAction.tsx
@@ -1,20 +1,14 @@
-/**
- * Document-header split button: the main button opens the previewed file in
- * its default application, the chevron's menu adds the file-manager reveal.
- * Both path controls share the gesture hook declared here.
- */
-import { useEffect, useState } from 'react'
+/** File association adapter for the shared file/directory opening control. */
+import { useEffect } from 'react'
 import type { ReactNode } from 'react'
-import {
-  IconChevronDownOutlineRegular, IconFolderOpenOutlineRegular, IconRightUpOutlineRegular, Menu, Tooltip,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { SessionWorkspacePathApplication } from '@deepseek-ai/dsh-api-session-controller/types'
 import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
-import type { InjectFace, PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-documentpreview/client'
 import type { OpenInAppPathAction, OpenInAppPathFailure } from './open-path.ts'
-import { useOpenFailureToast } from './open-failure-toast.tsx'
+import { useFileApplications } from './file-applications.ts'
+import { OpenTargetButton } from './OpenTargetButton.tsx'
 import type { NS } from './locales.ts'
-import css from './OpenPathAction.module.css'
 
 /** Desktop availability and the gesture carrier injected into both path controls. */
 export interface OpenPathInjected {
@@ -22,7 +16,8 @@ export interface OpenPathInjected {
     openInAppDesktop: ObservableSnapshot<boolean | null>
   }
   loadDesktop: () => Promise<void>
-  openPath: (path: string, action: OpenInAppPathAction) => Promise<OpenInAppPathFailure | null>
+  openPath: (path: string, action: OpenInAppPathAction, application?: string) => Promise<OpenInAppPathFailure | null>
+  applications: (path: string, signal: AbortSignal) => Promise<readonly SessionWorkspacePathApplication[] | null>
 }
 
 /** Full props of the document-header contribution. */
@@ -31,102 +26,41 @@ export type OpenPathActionProps =
   & PropsLocale<typeof NS>
   & InjectFace<OpenPathInjected>
 
-/** What one path control needs from its props: the file, the injected face, and copy. */
-type PathGestureProps = Pick<OpenPathActionProps, 'absolutePath' | 'useOpenInAppDesktop' | 'loadDesktop' | 'openPath'> & {
-  t: TranslateNS<typeof NS>
+/** File inputs shared by the document header and its unpreviewable state. */
+type FileOpenTargetProps = Pick<OpenPathActionProps, 'absolutePath' | 'useOpenInAppDesktop' | 'loadDesktop' | 'openPath' | 'applications' | 't'> & {
+  empty?: boolean
 }
 
 /**
- * Desktop availability, this control's own pending state, and a gesture
- * runner announcing failures through this control's toast. Only the control
- * that ran the gesture disables while it settles; failure never persists on
- * the control.
- * @param props - the file's Host path, the injected face, and copy.
- * @returns availability, pending, the toast to render, and the runner.
+ * Resolve file associations and adapt operations without embedding platform behavior in the control.
+ * @param props - verified file path, desktop query, native operations, and display variant.
+ * @returns the shared opening control, or null without a desktop.
  */
-export function usePathGesture({ absolutePath, useOpenInAppDesktop, loadDesktop, openPath, t }: PathGestureProps): {
-  available: boolean
-  pending: boolean
-  toast: ReactNode
-  act: (action: OpenInAppPathAction) => void
-} {
-  const desktop = useOpenInAppDesktop(value => value)
-  const [pending, setPending] = useState(false)
-  const { toast, show } = useOpenFailureToast()
+export function FileOpenTarget(props: FileOpenTargetProps): ReactNode {
+  const desktop = props.useOpenInAppDesktop(value => value)
+  const association = useFileApplications(props.absolutePath, props.applications, desktop === true)
   useEffect(() => {
-    if (desktop === null) void loadDesktop()
-  }, [desktop, loadDesktop])
-  return {
-    available: desktop === true,
-    pending,
-    toast,
-    act: (action) => {
-      setPending(true)
-      void openPath(absolutePath, action).then((failure) => {
-        if (failure !== null) show(t(`path.${failure}`))
-      }).finally(() => { setPending(false) })
-    },
-  }
-}
-
-/**
- * Render the split button, or nothing until the Host reports a desktop.
- * @param props - the previewed file, the injected face, and copy.
- * @returns the split button with its menu and toast, or null.
- */
-export function OpenPathAction(props: OpenPathActionProps): ReactNode {
-  const { t } = props
-  const [menuOpen, setMenuOpen] = useState(false)
-  const { available, pending, toast, act } = usePathGesture(props)
-  if (!available) return null
-  const run = (action: OpenInAppPathAction): void => {
-    setMenuOpen(false)
-    act(action)
-  }
+    if (desktop === null) void props.loadDesktop()
+  }, [desktop, props.loadDesktop])
+  if (desktop !== true) return null
+  const { apps } = association
   return (
-    <>
-      <Menu
-        className={css.menuAnchor}
-        open={menuOpen && !pending}
-        autoFocus
-        portal
-        dense
-        align="end"
-        onClose={() => { setMenuOpen(false) }}
-        items={[
-          { id: 'open', icon: <IconRightUpOutlineRegular />, label: t('path.defaultApp') },
-          { id: 'reveal', icon: <IconFolderOpenOutlineRegular />, label: t('path.reveal') },
-        ]}
-        onSelect={(id) => { run(id === 'reveal' ? 'reveal' : 'open') }}
-        anchor={(
-          <div className={css.split} data-open-path data-state={pending ? 'busy' : 'idle'}>
-            <Tooltip label={t('path.open.tooltip')} side="bottom" delayMs={500}>
-              <button
-                type="button"
-                className={css.main}
-                disabled={pending}
-                data-open-path-open
-                onClick={() => { run('open') }}
-              >
-                {t('path.open')}
-              </button>
-            </Tooltip>
-            <button
-              type="button"
-              className={css.chevron}
-              disabled={pending}
-              aria-haspopup="menu"
-              aria-expanded={menuOpen && !pending}
-              aria-label={t('path.more')}
-              data-open-path-more
-              onClick={() => { setMenuOpen(value => !value) }}
-            >
-              <IconChevronDownOutlineRegular size={11} />
-            </button>
-          </div>
-        )}
-      />
-      {toast}
-    </>
+    <OpenTargetButton
+      key={props.absolutePath} kind="file" applications={apps} defaultId={apps.find(app => app.default)?.id}
+      loading={association.loading} failed={association.failed}
+      prominent={props.empty === true} t={props.t}
+      refresh={association.refresh}
+      execute={operation => props.openPath(props.absolutePath, operation.kind === 'reveal' ? 'reveal' : 'open',
+        operation.kind === 'application' ? operation.id : undefined)}
+    />
   )
 }
+
+/**
+ * Render the file adapter in the document header.
+ * @param props - document owner inputs and injected opening capabilities.
+ * @returns the shared split button.
+ */
+export function OpenPathAction(props: OpenPathActionProps): ReactNode {
+  return <FileOpenTarget {...props} />
+}
diff --git a/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.module.css b/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.module.css
deleted file mode 100644
index cf9036e0d6..0000000000
--- a/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.module.css
+++ /dev/null
@@ -1,26 +0,0 @@
-/* The empty state's capsule, sized like the preview's own Retry
-   (ui-sidebar-documentpreview TextPreview `.retry`) so the two recourses read
-   as one family. */
-.open {
-  display: inline-flex;
-  flex: none;
-  gap: 6px;
-  align-items: center;
-  height: 32px;
-  padding: 0 12px 0 14px;
-  color: var(--dsw-alias-label-primary);
-  font-size: var(--dsh-content-font-size-secondary, 13px);
-  font-family: inherit;
-  background: transparent;
-  border: 0.5px solid var(--dsw-alias-border-l2);
-  border-radius: 16px;
-  cursor: pointer;
-}
-
-.open:hover:not(:disabled) {
-  background: var(--dsw-alias-interactive-bg-hover);
-}
-
-.open:disabled {
-  cursor: default;
-}
diff --git a/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.tsx b/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.tsx
index bf86006ed5..05a2b66800 100644
--- a/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.tsx
+++ b/packages/client/ui-open-in-app/src/client/OpenPathEmptyAction.tsx
@@ -1,11 +1,9 @@
-/** Empty-state contribution: open a file the document preview cannot render in its default application. */
+/** File opening action in an unpreviewable document's empty state. */
 import type { ReactNode } from 'react'
-import { IconRightUpOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-documentpreview/client'
 import type { NS } from './locales.ts'
-import { usePathGesture, type OpenPathInjected } from './OpenPathAction.tsx'
-import css from './OpenPathEmptyAction.module.css'
+import { FileOpenTarget, type OpenPathInjected } from './OpenPathAction.tsx'
 
 /** Full props of the unpreviewable empty-state contribution. */
 export type OpenPathEmptyActionProps =
@@ -14,27 +12,10 @@ export type OpenPathEmptyActionProps =
   & InjectFace<OpenPathInjected>
 
 /**
- * Render the default-application open button, or nothing until the Host reports a desktop.
- * @param props - the unpreviewable file, the injected face, and copy.
- * @returns the open button and its toast, or null.
+ * Render the shared file opening menu with a larger labeled main button.
+ * @param props - unpreviewable file and injected opening capabilities.
+ * @returns the shared file opening action.
  */
 export function OpenPathEmptyAction(props: OpenPathEmptyActionProps): ReactNode {
-  const { t } = props
-  const { available, pending, toast, act } = usePathGesture(props)
-  if (!available) return null
-  return (
-    <>
-      <button
-        type="button"
-        className={css.open}
-        disabled={pending}
-        data-open-path-unpreviewable
-        onClick={() => { act('open') }}
-      >
-        {t('path.unpreviewable')}
-        <IconRightUpOutlineRegular size={14} />
-      </button>
-      {toast}
-    </>
-  )
+  return <FileOpenTarget {...props} empty />
 }
diff --git a/packages/client/ui-open-in-app/src/client/OpenPathAction.module.css b/packages/client/ui-open-in-app/src/client/OpenTargetButton.module.css
similarity index 54%
rename from packages/client/ui-open-in-app/src/client/OpenPathAction.module.css
rename to packages/client/ui-open-in-app/src/client/OpenTargetButton.module.css
index f23f590613..44a66f59f2 100644
--- a/packages/client/ui-open-in-app/src/client/OpenPathAction.module.css
+++ b/packages/client/ui-open-in-app/src/client/OpenTargetButton.module.css
@@ -1,4 +1,4 @@
-/* Sized to sit in the document header's 28px control row beside its round
+/* Sized to sit in the document header's 24px control row beside its round
    icon buttons: a hairline pill with a 12px label and a narrow chevron half. */
 
 .menuAnchor {
@@ -11,10 +11,10 @@
   display: inline-flex;
   align-items: stretch;
   box-sizing: border-box;
-  height: 28px;
+  height: 24px;
   overflow: hidden;
-  border: 0.5px solid var(--dsw-alias-border-l3);
-  border-radius: 14px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: 9px;
   font-family: var(--dsw-font-family);
 }
 
@@ -26,19 +26,20 @@
   border: 0;
   background: none;
   color: var(--dsw-alias-label-primary);
-  font-size: 12px;
+  font-size: 11px;
   line-height: 16px;
   white-space: nowrap;
   cursor: pointer;
 }
 
 .main {
-  padding: 5px 8px 5px 10px;
+  gap: 4px;
+  padding: 3px 5px;
 }
 
 .chevron {
-  padding: 5px 6px 5px 4px;
-  border-left: 0.5px solid var(--dsw-alias-border-l3);
+  padding: 3px 4px 3px 3px;
+  border-left: 0.5px solid var(--dsw-alias-border-l4);
   color: var(--dsw-alias-label-secondary);
 }
 
@@ -54,3 +55,26 @@
 .chevron:disabled {
   cursor: default;
 }
+
+.appIcon {
+  object-fit: contain;
+}
+
+/* The unavailable preview emphasizes the same actions with a labeled button. */
+.split[data-size='large'] {
+  height: 40px;
+  border-radius: 14px;
+  border-color: var(--dsw-alias-border-l2);
+}
+
+.split[data-size='large'] .main {
+  gap: 6px;
+  padding: 8px 14px;
+  font-size: 14px;
+}
+
+.split[data-size='large'] .chevron {
+  padding: 8px 10px;
+}
+
+.skeleton { display: inline-block; flex: none; border-radius: 3px; background: var(--dsw-alias-interactive-bg-hover); }
diff --git a/packages/client/ui-open-in-app/src/client/OpenTargetButton.tsx b/packages/client/ui-open-in-app/src/client/OpenTargetButton.tsx
new file mode 100644
index 0000000000..93a3a34657
--- /dev/null
+++ b/packages/client/ui-open-in-app/src/client/OpenTargetButton.tsx
@@ -0,0 +1,144 @@
+/** Shared file and directory opener: one default action, application menu, and per-gesture feedback. */
+import { useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import {
+  IconChevronDownOutlineRegular, IconFolderOpenOutlineRegular, IconRightUpOutlineRegular, Menu, Tooltip,
+} from '@deepseek-ai/dsh-client-ui-primitives'
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import type { OpenInAppPathFailure } from './open-path.ts'
+import { useOpenFailureToast } from './open-failure-toast.tsx'
+import type { NS } from './locales.ts'
+import css from './OpenTargetButton.module.css'
+
+/** Application metadata supplied by either the directory catalog or a file association query. */
+export interface OpenTargetApplication {
+  readonly id: string
+  readonly name: string
+  readonly icon: string | null
+}
+
+/** Opening intent; default selection remains owned by the target's adapter. */
+export type OpenTargetOperation = { readonly kind: 'default' } | { readonly kind: 'application'; readonly id: string } | { readonly kind: 'reveal' }
+
+/** Inputs shared by both target adapters and the file empty-state action. */
+export interface OpenTargetButtonProps {
+  readonly kind: 'file' | 'directory'
+  readonly applications: readonly OpenTargetApplication[]
+  readonly defaultId: string | undefined
+  readonly failed: boolean
+  readonly busy?: boolean
+  readonly loading?: boolean
+  readonly prominent?: boolean
+  readonly t: TranslateNS<typeof NS>
+  readonly execute: (operation: OpenTargetOperation) => Promise<OpenInAppPathFailure | null>
+  readonly refresh?: () => void
+}
+
+/**
+ * Serialize gestures and announce their failures through the initiating control's toast.
+ * @param execute - target adapter that returns the failure to announce, or null.
+ * @param t - localized control copy.
+ * @returns the pending state, feedback, and guarded action callback.
+ */
+export function useOpenTargetGesture(execute: OpenTargetButtonProps['execute'], t: TranslateNS<typeof NS>): {
+  pending: boolean
+  toast: ReactNode
+  act: (operation: OpenTargetOperation) => void
+} {
+  const [pending, setPending] = useState(false)
+  const inFlight = useRef(false)
+  const { toast, show } = useOpenFailureToast()
+  return {
+    pending,
+    toast,
+    act: (operation) => {
+      if (inFlight.current) return
+      inFlight.current = true
+      setPending(true)
+      void execute(operation).then((failure) => {
+        if (failure !== null) show(t(`path.${failure}`))
+      }).finally(() => { inFlight.current = false; setPending(false) })
+    },
+  }
+}
+
+/** One application image with a per-image fallback, shared by main and menu buttons. */
+function ApplicationIcon({ source, size = 14 }: { source: string | null; size?: number }): ReactNode {
+  const [failed, setFailed] = useState(false)
+  return source === null || failed
+    ? <IconRightUpOutlineRegular size={size} />
+    : <img src={source} width={size} height={size} className={css.appIcon} alt="" draggable={false} onError={() => { setFailed(true) }} />
+}
+
+/**
+ * Render identical split buttons for files and directories. File reveal always stays last and becomes the default when no app is selected.
+ * @param props - target applications, default selection, and operations.
+ * @returns the control and its transient failure feedback.
+ */
+export function OpenTargetButton(props: OpenTargetButtonProps): ReactNode {
+  const { applications, defaultId, kind, t } = props
+  const [menuOpen, setMenuOpen] = useState(false)
+  const { pending, toast, act } = useOpenTargetGesture(props.execute, t)
+  const preferred = applications.find(app => app.id === defaultId)
+  const disabled = pending || props.busy === true || props.loading === true
+  const hasMenu = props.loading === true || props.failed || applications.length + (kind === 'file' ? 1 : 0) > 1
+  const revealDefault = kind === 'file' && preferred === undefined && props.loading !== true
+  const primaryLabel = preferred === undefined ? t('path.reveal') : t('open.title', { app: preferred.name })
+  const run = (operation: OpenTargetOperation): void => { setMenuOpen(false); act(operation) }
+  const primary = (): void => { run({ kind: revealDefault ? 'reveal' : 'default' }) }
+  const icon = props.loading === true && preferred === undefined
+    ? <span className={css.skeleton} data-open-target-skeleton aria-hidden="true" style={{ width: props.prominent ? 18 : 13, height: props.prominent ? 18 : 13 }} />
+    : revealDefault
+      ? <IconFolderOpenOutlineRegular size={props.prominent ? 18 : 13} />
+      : <ApplicationIcon key={preferred?.icon} source={preferred?.icon ?? null} size={props.prominent ? 18 : 13} />
+  return (
+    <>
+      <Menu
+        className={css.menuAnchor}
+        open={menuOpen && !disabled && hasMenu}
+        autoFocus
+        portal
+        dense
+        align="end"
+        onClose={() => { setMenuOpen(false) }}
+        items={[
+          ...applications.map(app => ({
+            id: `app:${app.id}`,
+            icon: <ApplicationIcon key={app.icon} source={app.icon} />,
+            label: app.id === defaultId ? t('path.appDefault', { app: app.name }) : app.name,
+          })),
+          ...(props.failed ? [{ id: 'unavailable', label: t('path.appsError'), disabled: true }] : []),
+        ]}
+        footer={kind === 'file' ? [{
+          id: 'reveal', icon: <IconFolderOpenOutlineRegular />,
+          label: revealDefault ? t('path.appDefault', { app: t('path.reveal') }) : t('path.reveal'),
+        }] : []}
+        onSelect={(id) => { run(id === 'reveal' ? { kind: 'reveal' } : { kind: 'application', id: id.slice(4) }) }}
+        anchor={(
+          <div className={css.split} data-open-target={kind} data-size={props.prominent ? 'large' : 'compact'}
+            data-open-path={kind === 'file' && !props.prominent ? '' : undefined} data-state={disabled ? 'busy' : 'idle'}>
+            <Tooltip portal label={primaryLabel} side="bottom" delayMs={500}>
+              <button type="button" className={css.main} disabled={disabled} aria-label={props.prominent ? undefined : primaryLabel}
+                data-open-path-open={kind === 'file' && !props.prominent ? '' : undefined}
+                data-open-path-unpreviewable={props.prominent ? '' : undefined} onClick={primary}>
+                {icon}{(props.prominent) && (revealDefault ? t('path.reveal') : t('path.open'))}
+              </button>
+            </Tooltip>
+            {hasMenu && <button
+              type="button" className={css.chevron} disabled={disabled}
+              aria-haspopup="menu" aria-expanded={menuOpen && !disabled} aria-label={t('path.more')}
+              data-open-path-more={kind === 'file' && !props.prominent ? '' : undefined}
+              onClick={() => {
+                if (!menuOpen) props.refresh?.()
+                setMenuOpen(value => !value)
+              }}
+            >
+              <IconChevronDownOutlineRegular size={10} />
+            </button>}
+          </div>
+        )}
+      />
+      {toast}
+    </>
+  )
+}
diff --git a/packages/client/ui-open-in-app/src/client/file-applications.ts b/packages/client/ui-open-in-app/src/client/file-applications.ts
new file mode 100644
index 0000000000..5b80c14575
--- /dev/null
+++ b/packages/client/ui-open-in-app/src/client/file-applications.ts
@@ -0,0 +1,73 @@
+/** File association reads shared by mounted controls using the same reader and target. */
+import { useCallback, useSyncExternalStore } from 'react'
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { SessionWorkspacePathApplication } from '@deepseek-ai/dsh-api-session-controller/types'
+
+type Query = (target: string, signal: AbortSignal) => Promise<readonly SessionWorkspacePathApplication[] | null>
+interface Result {
+  apps: readonly SessionWorkspacePathApplication[]
+  loading: boolean
+  failed: boolean
+}
+interface Entry {
+  state: SnapshotStore<Result>
+  users: number
+  controller: AbortController | null
+  refresh: () => void
+}
+const EMPTY: Result = { apps: [], loading: true, failed: false }
+const readers = new WeakMap<Query, Map<string, Entry>>()
+
+/** Each mounted consumer retains the query; the last release cancels and discards it. */
+function subscribe(query: Query, target: string, listener: () => void): () => void {
+  let targets = readers.get(query)
+  if (targets === undefined) { targets = new Map(); readers.set(query, targets) }
+  let entry = targets.get(target)
+  const initial = entry === undefined
+  if (entry === undefined) {
+    const created: Entry = {
+      state: createSnapshotStore<Result>(EMPTY), users: 0, controller: null,
+      refresh: () => {
+        created.controller?.abort()
+        const controller = new AbortController()
+        created.controller = controller
+        void query(target, controller.signal).then((apps) => {
+          if (!controller.signal.aborted) created.state.set({ apps: apps ?? [], loading: false, failed: apps === null })
+        })
+      },
+    }
+    entry = created
+    targets.set(target, entry)
+  }
+  const retained = entry
+  retained.users += 1
+  const release = retained.state.subscribe(listener)
+  if (initial) retained.refresh()
+  return () => {
+    release()
+    retained.users -= 1
+    if (retained.users === 0) {
+      retained.controller?.abort()
+      targets.delete(target)
+    }
+  }
+}
+
+/**
+ * Share associations and refreshes across mounted controls for the same file and reader.
+ * @param target - path or authenticated route identifying the current file.
+ * @param query - stable reader scoped to the serving Host; failures resolve to null.
+ * @param enabled - whether a native desktop is available.
+ * @returns metadata, initial loading state, failure state, and a shared refresh callback.
+ */
+export function useFileApplications(
+  target: string, query: Query, enabled: boolean,
+): Result & { refresh: () => void } {
+  const retain = useCallback((listener: () => void) => enabled ? subscribe(query, target, listener) : () => {}, [enabled, query, target])
+  const snapshot = useCallback(
+    () => enabled ? readers.get(query)?.get(target)?.state.getSnapshot() ?? EMPTY : EMPTY, [enabled, query, target],
+  )
+  const state = useSyncExternalStore(retain, snapshot, snapshot)
+  const refresh = useCallback(() => { readers.get(query)?.get(target)?.refresh() }, [query, target])
+  return { ...state, refresh }
+}
diff --git a/packages/client/ui-open-in-app/src/client/index.ts b/packages/client/ui-open-in-app/src/client/index.ts
index 4073eaec1f..95f753b16f 100644
--- a/packages/client/ui-open-in-app/src/client/index.ts
+++ b/packages/client/ui-open-in-app/src/client/index.ts
@@ -1,12 +1,7 @@
 /**
- * Browser half of open-in-app: one Session-header split button opening the
- * session's workspace directory (the summary's `cwd`) in the remembered
- * installed application, and the document preview's default-application
- * controls opening one previewed file. Application availability arrives once
- * per page from the host apps route and the last choice persists in the
- * browser through the controller's persisted snapshot store; desktop
- * availability for file paths arrives once per page from the Session Remote,
- * which also runs the open and reveal gestures.
+ * Shared native opening controls for workspace directories, document previews,
+ * delivery cards, and changed-file review. Directory choices persist in the browser;
+ * file defaults and application lists come from the serving Host desktop.
  */
 
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
@@ -22,6 +17,7 @@ import { OpenInAppController } from './controller.ts'
 import { OpenInAppAction, type OpenInAppActionInjected } from './OpenInAppAction.tsx'
 import { OpenInAppPathController } from './open-path.ts'
 import { OpenPathAction, type OpenPathInjected } from './OpenPathAction.tsx'
+import { FileRouteAction } from './FileRouteAction.tsx'
 import { OpenPathEmptyAction } from './OpenPathEmptyAction.tsx'
 import { en, NS, zh, type OpenInAppKey } from './locales.ts'
 
@@ -65,10 +61,12 @@ export function apply(ctx: ClientContext): void {
       iconUrl: appId => `${OPEN_IN_APP_ICON_PREFIX_ROUTE}/${appId}`,
     }),
   }, OpenInAppAction))
+  const applications: OpenPathInjected['applications'] = (path, signal) => paths.applications(path, signal)
   const pathInjected = (): OpenPathInjected => ({
     hooks: { openInAppDesktop: paths.desktop },
     loadDesktop: () => paths.load(),
-    openPath: (path, action) => paths.openPath(path, action),
+    openPath: (path, action, application) => paths.openPath(path, action, application),
+    applications,
   })
   ctx.slots.inject('sidebar.right.tab.document.actions', () => ctx.slots.register({
     name: 'sidebar.right.tab.document.actions',
@@ -82,4 +80,10 @@ export function apply(ctx: ClientContext): void {
     locale: NS,
     inject: pathInjected,
   }, OpenPathEmptyAction))
+  ctx.slots.inject('deliverables.file.actions', () => ctx.slots.register({
+    name: 'deliverables.file.actions', id: 'open-in-app', locale: NS,
+  }, FileRouteAction))
+  ctx.slots.inject('deliverables.review.file.actions', () => ctx.slots.register({
+    name: 'deliverables.review.file.actions', id: 'open-in-app', locale: NS,
+  }, FileRouteAction))
 }
diff --git a/packages/client/ui-open-in-app/src/client/locales.ts b/packages/client/ui-open-in-app/src/client/locales.ts
index 6d32f759a0..e8aedbdbf9 100644
--- a/packages/client/ui-open-in-app/src/client/locales.ts
+++ b/packages/client/ui-open-in-app/src/client/locales.ts
@@ -39,17 +39,12 @@ const PRODUCT_NAMES = {
 
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
-  'open.title': '在 {app} 中打开工作目录',
-  'open.tooltip': '在本地打开',
-  'open.error': '打开失败',
-  'menu.toggle': '选择打开方式',
-  'menu.aria': '打开方式',
+  'open.title': '用 {app} 打开',
+  'path.appDefault': '{app}（默认）',
+  'path.appsError': '无法获取应用列表',
   'path.open': '打开',
-  'path.open.tooltip': '用默认应用打开',
   'path.more': '更多打开方式',
-  'path.defaultApp': '用默认应用打开',
   'path.reveal': '显示文件位置',
-  'path.unpreviewable': '用默认应用打开',
   'path.openError': '打开失败，请重试',
   'path.revealError': '无法显示文件位置，请重试',
   ...PRODUCT_NAMES,
@@ -61,17 +56,12 @@ export const zh = {
 
 /** English dictionary, key-identical to the Chinese source of truth. */
 export const en: Record<OpenInAppKey, string> = {
-  'open.title': 'Open workspace in {app}',
-  'open.tooltip': 'Open locally',
-  'open.error': 'Failed to open',
-  'menu.toggle': 'Choose an app to open in',
-  'menu.aria': 'Open in',
+  'open.title': 'Open in {app}',
+  'path.appDefault': '{app} (default)',
+  'path.appsError': 'Could not load applications',
   'path.open': 'Open',
-  'path.open.tooltip': 'Open in default app',
   'path.more': 'More ways to open',
-  'path.defaultApp': 'Open in default app',
   'path.reveal': 'Show file location',
-  'path.unpreviewable': 'Open in default app',
   'path.openError': 'Could not open. Try again.',
   'path.revealError': 'Could not show the file location. Try again.',
   ...PRODUCT_NAMES,
diff --git a/packages/client/ui-open-in-app/src/client/open-path.ts b/packages/client/ui-open-in-app/src/client/open-path.ts
index 161fcf104f..e403a80da9 100644
--- a/packages/client/ui-open-in-app/src/client/open-path.ts
+++ b/packages/client/ui-open-in-app/src/client/open-path.ts
@@ -1,11 +1,10 @@
 /**
- * Default-application actions on one Host file path, over the Session Remote:
- * whether this Host can hand a path to a desktop, and the open or reveal call.
+ * Host desktop availability, file associations, and open/reveal actions over the Session Remote.
  * The desktop answer is read once per page; a failed read renders no control.
  */
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
-import type { SessionOpenWorkspacePathRequest } from '@deepseek-ai/dsh-api-session-controller/types'
+import type { SessionOpenWorkspacePathRequest, SessionWorkspacePathApplication } from '@deepseek-ai/dsh-api-session-controller/types'
 
 /** What a path gesture asks of the Host desktop: the default application, or the file manager showing the file. */
 export type OpenInAppPathAction = 'open' | 'reveal'
@@ -18,6 +17,10 @@ export interface OpenInAppPathRemote {
   readonly session: {
     /** Whether the Host can hand a workspace path to a native desktop. */
     canOpenWorkspacePath(): Promise<RemoteResult<boolean>>
+    /** Current registered file handlers and their default selection. */
+    workspacePathApplications(
+      request: { path: string }, signal?: AbortSignal,
+    ): Promise<RemoteResult<readonly SessionWorkspacePathApplication[]>>
     /** Open one Host path in its default application, or reveal it in the file manager. */
     openWorkspacePath(request: SessionOpenWorkspacePathRequest, signal?: AbortSignal): Promise<RemoteResult<unknown>>
   }
@@ -47,10 +50,11 @@ export class OpenInAppPathController {
    * Open one Host path in its default application, or reveal it in the file manager.
    * @param path - absolute path on the Host, as the file's metadata reports it.
    * @param action - default application open, or file-manager reveal.
+   * @param application - registered application path for an explicit open.
    * @returns the failure kind to announce, or `null` once the Host acknowledged.
    */
-  async openPath(path: string, action: OpenInAppPathAction): Promise<OpenInAppPathFailure | null> {
-    const request: SessionOpenWorkspacePathRequest = action === 'reveal' ? { path, action } : { path }
+  async openPath(path: string, action: OpenInAppPathAction, application?: string): Promise<OpenInAppPathFailure | null> {
+    const request: SessionOpenWorkspacePathRequest = action === 'reveal' ? { path, action } : { path, ...(application === undefined ? {} : { application }) }
     let ok = false
     try {
       ok = (await this.remote.session.openWorkspacePath(request)).ok
@@ -61,6 +65,23 @@ export class OpenInAppPathController {
     return ok ? null : action === 'open' ? 'openError' : 'revealError'
   }
 
+  /**
+   * Refresh the file's OS associations; failures remain distinct from an empty handler list.
+   * @param path - file path reported by the Host.
+   * @param signal - lifetime of the requesting preview.
+   * @returns application metadata, or null when the query fails.
+   */
+  async applications(path: string, signal: AbortSignal): Promise<readonly SessionWorkspacePathApplication[] | null> {
+    let result: RemoteResult<readonly SessionWorkspacePathApplication[]>
+    try {
+      result = await this.remote.session.workspacePathApplications({ path }, signal)
+    } catch (_error) {
+      // The control reports query failure and keeps file reveal available.
+      return null
+    }
+    return result.ok ? result.value : null
+  }
+
   private async run(): Promise<void> {
     let available = false
     try {
diff --git a/packages/client/ui-open-in-app/tests/browser-plugin.client.spec.ts b/packages/client/ui-open-in-app/tests/browser-plugin.client.spec.ts
index dab2b08df0..4c86980614 100644
--- a/packages/client/ui-open-in-app/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-open-in-app/tests/browser-plugin.client.spec.ts
@@ -24,6 +24,7 @@ afterEach(() => {
 /** The Session Remote slice the path controls call; answers a desktop and acknowledges every gesture. */
 const remote = {
   session: {
+    workspacePathApplications: vi.fn(async () => ({ ok: true as const, value: [] })),
     canOpenWorkspacePath: vi.fn(async () => ({ ok: true as const, value: true })),
     openWorkspacePath: vi.fn(async () => ({ ok: true as const, value: { opened: true as const } })),
   },
@@ -39,6 +40,8 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType<Context['plugi
       'conversation.session.header.utilities': { kind: 'list', scope: 'session' },
       'sidebar.right.tab.document.actions': { kind: 'list', scope: 'session' },
       'sidebar.right.tab.document.unpreviewable': { kind: 'list', scope: 'session' },
+      'deliverables.file.actions': { kind: 'list', scope: 'session' },
+      'deliverables.review.file.actions': { kind: 'list', scope: 'session' },
     },
   } as never, () => null)
   ctx.provide('sessions', {})
@@ -66,19 +69,25 @@ describe('open-in-app browser half', () => {
     const empty = ctx.slots.entries('sidebar.right.tab.document.unpreviewable')[0]
     expect(header?.component).toBe(OpenPathAction)
     expect(empty?.component).toBe(OpenPathEmptyAction)
+    expect(ctx.slots.entries('deliverables.file.actions')).toHaveLength(1)
     expect(header?.options).toMatchObject({ id: 'open-in-app' })
     const face = (header?.inject as unknown as () => OpenPathInjected)()
     const emptyFace = (empty?.inject as unknown as () => OpenPathInjected)()
     expect(emptyFace.hooks.openInAppDesktop).toBe(face.hooks.openInAppDesktop)
+    expect(emptyFace.applications).toBe(face.applications)
     expect(face.hooks.openInAppDesktop.getSnapshot()).toBeNull()
     await Promise.all([face.loadDesktop(), emptyFace.loadDesktop()])
     expect(remote.session.canOpenWorkspacePath).toHaveBeenCalledOnce()
+    const signal = new AbortController().signal
+    await expect(face.applications('/w/clip.mp4', signal)).resolves.toEqual([])
+    expect(remote.session.workspacePathApplications).toHaveBeenCalledWith({ path: '/w/clip.mp4' }, signal)
     expect(face.hooks.openInAppDesktop.getSnapshot()).toBe(true)
     expect(await face.openPath('/w/clip.mp4', 'reveal')).toBeNull()
     expect(remote.session.openWorkspacePath).toHaveBeenLastCalledWith({ path: '/w/clip.mp4', action: 'reveal' })
     await fiber.dispose()
     expect(ctx.slots.entries('sidebar.right.tab.document.actions').map(entry => entry.options.id)).not.toContain('open-in-app')
     expect(ctx.slots.entries('sidebar.right.tab.document.unpreviewable').map(entry => entry.options.id)).not.toContain('open-in-app')
+    expect(ctx.slots.entries('deliverables.file.actions')).toHaveLength(0)
   })
 
   it('registers the header split button, and fiber teardown removes it (HMR safety)', async () => {
@@ -143,11 +152,11 @@ describe('open-in-app browser half', () => {
     const { ctx, fiber } = await bench()
     ctx.locale.setLocale('zh')
     const translate = ctx.locale.bind(NS)
-    expect(translate('menu.aria')).toBe(zh['menu.aria'])
+    expect(translate('path.more')).toBe(zh['path.more'])
     ctx.locale.setLocale('en')
-    expect(translate('menu.aria')).toBe(en['menu.aria'])
+    expect(translate('path.more')).toBe(en['path.more'])
     await fiber.dispose()
-    expect(translate('menu.aria')).not.toBe(en['menu.aria'])
+    expect(translate('path.more')).not.toBe(en['path.more'])
   })
 
   it('keeps the English dictionary key-identical to the Chinese source of truth', () => {
diff --git a/packages/client/ui-open-in-app/tests/file-applications.client.spec.tsx b/packages/client/ui-open-in-app/tests/file-applications.client.spec.tsx
new file mode 100644
index 0000000000..273f78deed
--- /dev/null
+++ b/packages/client/ui-open-in-app/tests/file-applications.client.spec.tsx
@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+/** Shared association reads retain one native request until the last control leaves. */
+import { act, cleanup, renderHook } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import type { SessionWorkspacePathApplication } from '@deepseek-ai/dsh-api-session-controller/types'
+import { useFileApplications } from '../src/client/file-applications.ts'
+
+afterEach(cleanup)
+const music = [{ id: 'music', name: 'Music', default: true, icon: null }]
+
+it('shares the initial read and publishes a menu refresh to both controls', async () => {
+  const query = vi.fn(async () => music)
+  const first = renderHook(() => useFileApplications('/file.mp3', query, true))
+  const second = renderHook(() => useFileApplications('/file.mp3', query, true))
+  await act(async () => {})
+  expect(query).toHaveBeenCalledOnce()
+  expect(first.result.current.apps).toBe(second.result.current.apps)
+  query.mockResolvedValueOnce([{ id: 'player', name: 'Player', default: true, icon: null }])
+  await act(async () => { second.result.current.refresh() })
+  expect(query).toHaveBeenCalledTimes(2)
+  expect(first.result.current.apps[0]?.id).toBe('player')
+  expect(second.result.current.apps).toBe(first.result.current.apps)
+})
+
+it('cancels only after the last consumer leaves and discards the released result', async () => {
+  const pending = Promise.withResolvers<readonly SessionWorkspacePathApplication[] | null>()
+  const query = vi.fn((_path: string, _signal: AbortSignal) => pending.promise)
+  const first = renderHook(() => useFileApplications('/file.mp3', query, true))
+  const second = renderHook(() => useFileApplications('/file.mp3', query, true))
+  const signal = query.mock.calls[0]![1]
+  first.unmount()
+  expect(signal.aborted).toBe(false)
+  second.unmount()
+  expect(signal.aborted).toBe(true)
+  await act(async () => { pending.resolve(music) })
+  const next = renderHook(() => useFileApplications('/file.mp3', query, true))
+  expect(query).toHaveBeenCalledTimes(2)
+  await act(async () => {})
+  expect(next.result.current.apps).toEqual(music)
+})
+
+it('keeps disabled controls out of the query and permits refresh only while retained', async () => {
+  const query = vi.fn(async () => music)
+  const view = renderHook(({ enabled }) => useFileApplications('/file.mp3', query, enabled), { initialProps: { enabled: false } })
+  act(() => { view.result.current.refresh() })
+  expect(query).not.toHaveBeenCalled()
+  view.rerender({ enabled: true })
+  await act(async () => {})
+  expect(view.result.current.apps).toEqual(music)
+  view.rerender({ enabled: false })
+  act(() => { view.result.current.refresh() })
+  expect(query).toHaveBeenCalledOnce()
+})
diff --git a/packages/client/ui-open-in-app/tests/file-route-action.client.spec.tsx b/packages/client/ui-open-in-app/tests/file-route-action.client.spec.tsx
new file mode 100644
index 0000000000..d67cf7127c
--- /dev/null
+++ b/packages/client/ui-open-in-app/tests/file-route-action.client.spec.tsx
@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+/** Authorized file routes use the same application menu and failure feedback as previews. */
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { FileRouteAction } from '../src/client/FileRouteAction.tsx'
+import { en } from '../src/client/locales.ts'
+
+afterEach(() => { cleanup(); vi.unstubAllGlobals() })
+const apps = [{ id: 'music', name: 'Music', default: true, icon: null }]
+const props = () => ({ actionUrl: 'api/present.open?sessionId=s&seq=2&index=0', available: true, pending: false,
+  onAction: vi.fn(async () => null), t: makeTranslate(en) })
+
+it('queries the authorized route, selects a handler, and keeps reveal last', async () => {
+  const fetcher = vi.fn(async () => Response.json(apps))
+  vi.stubGlobal('fetch', fetcher)
+  const p = props()
+  render(<FileRouteAction {...p} />)
+  await act(async () => {})
+  expect(fetcher).toHaveBeenCalledWith(p.actionUrl, { signal: expect.any(AbortSignal) as AbortSignal })
+  fireEvent.mouseEnter(screen.getByRole('button', { name: 'Open in Music' }))
+  expect(await screen.findByRole('tooltip')).toHaveProperty('textContent', 'Open in Music')
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: en['path.more'] })) })
+  expect(screen.getAllByRole('menuitem').map(item => item.textContent)).toEqual(['Music (default)', 'Show file location'])
+  await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: 'Music (default)' })) })
+  expect(p.onAction).toHaveBeenLastCalledWith('open', 'music')
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: 'Open in Music' })) })
+  expect(p.onAction).toHaveBeenLastCalledWith('open', undefined)
+})
+
+it.each(['http', 'transport', 'invalid'] as const)('keeps reveal available after a %s query failure', async (failure) => {
+  vi.stubGlobal('fetch', vi.fn(async () => {
+    if (failure === 'transport') throw new Error('offline')
+    return failure === 'http' ? new Response(null, { status: 404 }) : Response.json({ invalid: true })
+  }))
+  const p = props()
+  render(<FileRouteAction {...p} />)
+  await act(async () => {})
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: en['path.reveal'] })) })
+  expect(p.onAction).toHaveBeenCalledWith('reveal', undefined)
+})
+
+it('does not query without a desktop and honors another pending gesture', async () => {
+  const fetcher = vi.fn(async () => Response.json(apps))
+  vi.stubGlobal('fetch', fetcher)
+  const p = props()
+  const view = render(<FileRouteAction {...p} available={false} />)
+  expect(view.container.innerHTML).toBe('')
+  expect(fetcher).not.toHaveBeenCalled()
+  view.rerender(<FileRouteAction {...p} pending />)
+  await act(async () => {})
+  expect(screen.getByRole('button', { name: 'Open in Music' })).toHaveProperty('disabled', true)
+})
diff --git a/packages/client/ui-open-in-app/tests/open-in-app-action.client.spec.tsx b/packages/client/ui-open-in-app/tests/open-in-app-action.client.spec.tsx
index 62f1ba2295..23b2c943bc 100644
--- a/packages/client/ui-open-in-app/tests/open-in-app-action.client.spec.tsx
+++ b/packages/client/ui-open-in-app/tests/open-in-app-action.client.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen, waitFor, act } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen, act } from '@testing-library/react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -29,15 +29,12 @@ function bench(over: {
   cwd?: string
   launch?: (appId: string, path: string) => Promise<void>
 } = {}): Bench {
-  const state = {
+  const state: SessionListState = {
     ids: [SESSION],
-    byId: over.cwd === undefined ? {} : { [SESSION]: { cwd: over.cwd } },
-    current: SESSION,
+    byId: over.cwd === undefined ? {} : { [SESSION]: { id: SESSION, displayTitle: 'Workspace', cwd: over.cwd, running: false, retainedBy: {}, blank: false, updatedAt: 0 } },
     phase: 'ready',
     projectionsBySession: {},
-    jobsBySession: {},
-    currentAddress: undefined,
-  } as unknown as SessionListState
+  }
   const apps = createSnapshotStore<readonly string[] | null>(over.apps ?? null)
   const choice = createSnapshotStore<string>(over.choice ?? '')
   const launch = vi.fn(over.launch ?? (async () => {}))
@@ -57,7 +54,7 @@ function bench(over: {
     choose,
     iconUrl: (appId: string) => `open-in-app/icon/${appId}`,
     t,
-  } as unknown as OpenInAppActionProps
+  } as OpenInAppActionProps
   return { props, launch, choose }
 }
 
@@ -79,165 +76,73 @@ describe('OpenInAppAction visibility', () => {
 
   it('shows the remembered choice, falling back to the first available app when it is gone', () => {
     render(<OpenInAppAction {...bench({ apps: ['finder', 'cursor'], choice: 'cursor', cwd: '/w' }).props} />)
-    expect(screen.getByRole('button', { name: zh['open.title'].replace('{app}', 'Cursor') })).toBeDefined()
+    expect(screen.getByRole('button', { name: t('open.title', { app: 'Cursor' }) }).querySelector('img')?.getAttribute('src')).toBe('open-in-app/icon/cursor')
     cleanup()
 
     render(<OpenInAppAction {...bench({ apps: ['finder', 'cursor'], choice: 'vscode', cwd: '/w' }).props} />)
-    expect(screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })).toBeDefined()
+    expect(screen.getByRole('button', { name: t('open.title', { app: zh['app.finder'] }) }).querySelector('img')?.getAttribute('src')).toBe('open-in-app/icon/finder')
   })
 })
 
 describe('OpenInAppAction launching', () => {
-  it('launches without painting the busy dress when the launch settles quickly', async () => {
-    let resolve: () => void = () => {}
-    const b = bench({
-      apps: ['finder'],
-      cwd: '/w/dir',
-      launch: () => new Promise((r) => { resolve = r }),
-    })
+  it('disables both buttons and ignores duplicate gestures until the launch settles', async () => {
+    const pending = Promise.withResolvers<undefined>()
+    const b = bench({ apps: ['finder', 'cursor'], cwd: '/w/dir', launch: () => pending.promise })
+    const view = render(<OpenInAppAction {...b.props} />)
+    const main = screen.getByRole('button', { name: t('open.title', { app: zh['app.finder'] }) })
+    fireEvent.click(main)
+    expect(main).toHaveProperty('disabled', true)
+    expect(screen.getByRole('button', { name: zh['path.more'] })).toHaveProperty('disabled', true)
+    fireEvent.click(main)
+    expect(b.launch).toHaveBeenCalledOnce()
+    expect(view.container.querySelector('[data-open-target]')?.getAttribute('data-state')).toBe('busy')
+    await act(async () => { pending.resolve(undefined) })
+    expect(main).toHaveProperty('disabled', false)
+  })
+
+  it('announces launch failure without changing the remembered application', async () => {
+    const b = bench({ apps: ['finder', 'cursor'], cwd: '/w', launch: async () => { throw new Error('gone') } })
     render(<OpenInAppAction {...b.props} />)
-    const main = screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })
-    fireEvent.click(main)
-    expect(b.launch).toHaveBeenCalledWith('finder', '/w/dir')
-    // No flash: the button keeps its idle dress while the launch is fast.
-    expect((main as HTMLButtonElement).disabled).toBe(false)
-    expect(main.getAttribute('data-state')).toBe('idle')
-    // A second click while in flight is ignored rather than double-launching.
-    fireEvent.click(main)
-    expect(b.launch).toHaveBeenCalledTimes(1)
-
-    resolve()
-    await waitFor(() => {
-      fireEvent.click(main)
-      expect(b.launch).toHaveBeenCalledTimes(2)
-    })
+    fireEvent.click(screen.getByRole('button', { name: zh['path.more'] }))
+    await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: 'Cursor' })) })
+    expect(screen.getByRole('alert').textContent).toContain(zh['path.openError'])
+    expect(b.choose).not.toHaveBeenCalled()
   })
 
-  it('dresses a slow launch as busy, then shows the error state on failure', async () => {
-    vi.useFakeTimers()
-    let reject: (error: Error) => void = () => {}
-    const b = bench({
-      apps: ['finder'],
-      cwd: '/w/dir',
-      launch: () => new Promise((_, r) => { reject = r }),
-    })
-    render(<OpenInAppAction {...b.props} />)
-    const main = screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })
-    fireEvent.click(main)
-
-    // The busy dress appears only after the launch has taken a while.
-    act(() => { vi.advanceTimersByTime(300) })
-    expect((main as HTMLButtonElement).disabled).toBe(true)
-    expect(main.getAttribute('data-state')).toBe('busy')
-
-    act(() => { reject(new Error('launch failed')) })
-    await act(async () => { await vi.runOnlyPendingTimersAsync() })
-    expect(screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })).toBeDefined()
-  })
-
-  it('shows the error state and decays back to idle after a fast failure', async () => {
-    const b = bench({
-      apps: ['finder'],
-      cwd: '/w/dir',
-      launch: () => Promise.reject(new Error('launch failed')),
-    })
-    render(<OpenInAppAction {...b.props} />)
-    const main = screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })
-    fireEvent.click(main)
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: zh['open.error'] })).toBeDefined()
-    })
-    // The error state decays back to idle.
-    await waitFor(() => {
-      expect(screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })).toBeDefined()
-    }, { timeout: 4_000 })
-  })
-
-  it('shows the product tooltip on hover instead of a native title', async () => {
-    render(<OpenInAppAction {...bench({ apps: ['finder'], cwd: '/w/dir' }).props} />)
-    const main = screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })
-    expect(main.getAttribute('title')).toBeNull()
-    fireEvent.mouseEnter(main)
-    expect(await screen.findByText(zh['open.tooltip'])).toBeDefined()
-    fireEvent.mouseLeave(main)
-    await waitFor(() => {
-      expect(screen.queryByText(zh['open.tooltip'])).toBeNull()
-    })
-  })
-
-  it('opens the menu from the chevron, launches and persists a picked app', async () => {
+  it('lists only applications, marks the remembered default, and remembers a successful choice', async () => {
     const b = bench({ apps: ['finder', 'cursor', 'terminal'], cwd: '/w/dir' })
     render(<OpenInAppAction {...b.props} />)
-    fireEvent.click(screen.getByRole('button', { name: zh['menu.toggle'] }))
-    const cursorItem = await screen.findByText('Cursor')
-    fireEvent.click(cursorItem)
-    expect(b.choose).toHaveBeenCalledWith('cursor')
+    fireEvent.click(screen.getByRole('button', { name: zh['path.more'] }))
+    expect(screen.getAllByRole('menuitem').map(item => item.textContent)).toEqual(['访达（默认）', 'Cursor', '终端'])
+    expect(screen.queryByText(zh['path.reveal'])).toBeNull()
+    await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: 'Cursor' })) })
     expect(b.launch).toHaveBeenCalledWith('cursor', '/w/dir')
+    expect(b.choose).toHaveBeenCalledWith('cursor')
   })
 
-  it('ignores a menu pick while a launch is in flight', async () => {
-    let resolve: () => void = () => {}
-    const b = bench({
-      apps: ['finder', 'cursor'],
-      cwd: '/w/dir',
-      launch: () => new Promise((r) => { resolve = r }),
-    })
-    render(<OpenInAppAction {...b.props} />)
-    fireEvent.click(screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) }))
-    expect(b.launch).toHaveBeenCalledTimes(1)
-    fireEvent.click(screen.getByRole('button', { name: zh['menu.toggle'] }))
-    fireEvent.click(await screen.findByText('Cursor'))
-    // Mid-flight the pick is ignored whole: no persisted choice, no launch.
-    expect(b.choose).not.toHaveBeenCalled()
-    expect(b.launch).toHaveBeenCalledTimes(1)
-    resolve()
-    await act(async () => {})
-  })
-
-  it('clears a pending error decay when a retry starts', async () => {
-    vi.useFakeTimers()
-    const outcomes: Array<() => Promise<void>> = [
-      () => Promise.reject(new Error('launch failed')),
-      // The retry stays in flight past the original decay deadline.
-      () => new Promise(() => {}),
-    ]
-    const b = bench({
-      apps: ['finder'],
-      cwd: '/w/dir',
-      launch: () => (outcomes.shift() ?? (() => Promise.resolve()))(),
-    })
-    render(<OpenInAppAction {...b.props} />)
-    fireEvent.click(screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) }))
-    await act(async () => {})
-    fireEvent.click(screen.getByRole('button', { name: zh['open.error'] }))
-    // Past the first failure's 2s decay: the stale timer must not flip the
-    // in-flight retry's busy dress back to a clickable idle button.
-    act(() => { vi.advanceTimersByTime(2_500) })
-    const main = screen.getByRole('button', { name: zh['open.title'].replace('{app}', zh['app.finder']) })
-    expect(main.getAttribute('data-state')).toBe('busy')
-    expect((main as HTMLButtonElement).disabled).toBe(true)
-  })
-
-  it('closes an open menu on Escape without launching', async () => {
-    const b = bench({ apps: ['finder', 'terminal'], cwd: '/w/dir' })
-    render(<OpenInAppAction {...b.props} />)
-    fireEvent.click(screen.getByRole('button', { name: zh['menu.toggle'] }))
-    await screen.findByText(zh['app.terminal'])
-    fireEvent.keyDown(document, { key: 'Escape' })
-    await waitFor(() => {
-      expect(screen.queryByText(zh['app.terminal'])).toBeNull()
-    })
+  it('closes on Escape without launching and falls back after an icon fails', async () => {
+    const b = bench({ apps: ['finder', 'terminal'], cwd: '/w' })
+    const view = render(<OpenInAppAction {...b.props} />)
+    fireEvent.click(screen.getByRole('button', { name: zh['path.more'] }))
+    fireEvent.keyDown(screen.getByRole('menu'), { key: 'Escape' })
+    expect(screen.queryByRole('menu')).toBeNull()
     expect(b.launch).not.toHaveBeenCalled()
+    const image = view.container.querySelector('img')!
+    fireEvent.error(image)
+    expect(view.container.querySelector('img')).toBeNull()
+    expect(view.container.querySelector('svg')).not.toBeNull()
   })
 
-  it('falls back to the generic icon after a failed image load', async () => {
-    const b = bench({ apps: ['terminal'], cwd: '/w/dir' })
-    const { container } = render(<OpenInAppAction {...b.props} />)
-    const img = container.querySelector('img')
-    if (img !== null) fireEvent.error(img)
-    await waitFor(() => {
-      expect(container.querySelector('img')).toBeNull()
-      expect(container.querySelector('svg path[fill-opacity="0.05"]')).not.toBeNull()
-    })
+  it('names the selected application in the tooltip', async () => {
+    render(<OpenInAppAction {...bench({ apps: ['finder'], cwd: '/w' }).props} />)
+    fireEvent.mouseEnter(screen.getByRole('button', { name: t('open.title', { app: zh['app.finder'] }) }))
+    expect(await screen.findByText(t('open.title', { app: zh['app.finder'] }))).toBeTruthy()
   })
 })
+
+
+it('omits the dropdown when only one directory application is available', () => {
+  render(<OpenInAppAction {...bench({ apps: ['finder'], cwd: '/w' }).props} />)
+  expect(screen.getAllByRole('button')).toHaveLength(1)
+  expect(screen.queryByRole('button', { name: zh['path.more'] })).toBeNull()
+})
diff --git a/packages/client/ui-open-in-app/tests/open-path-action.client.spec.tsx b/packages/client/ui-open-in-app/tests/open-path-action.client.spec.tsx
index ae9803c164..0a4a13f090 100644
--- a/packages/client/ui-open-in-app/tests/open-path-action.client.spec.tsx
+++ b/packages/client/ui-open-in-app/tests/open-path-action.client.spec.tsx
@@ -5,12 +5,13 @@
  * through their own toast.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { act, cleanup, fireEvent, render, renderHook, screen } from '@testing-library/react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { OpenPathAction, type OpenPathActionProps } from '../src/client/OpenPathAction.tsx'
 import { OpenPathEmptyAction, type OpenPathEmptyActionProps } from '../src/client/OpenPathEmptyAction.tsx'
 import type { OpenInAppPathAction, OpenInAppPathFailure } from '../src/client/open-path.ts'
+import { useOpenTargetGesture } from '../src/client/OpenTargetButton.tsx'
 import { zh } from '../src/client/locales.ts'
 
 afterEach(() => {
@@ -40,9 +41,10 @@ function bench(over: { desktop?: boolean | null; openPath?: Bench['openPath'] }
     absolutePath: ABSOLUTE_PATH,
     useOpenInAppDesktop: useSelector(desktop),
     loadDesktop,
+    applications: vi.fn(async () => [{ id: '/Music.app', name: 'Music', default: true, icon: null }]),
     openPath,
     t,
-  } as unknown as Bench['props']
+  } as Bench['props']
   return { props, desktop, loadDesktop, openPath }
 }
 
@@ -63,18 +65,19 @@ describe('OpenPathAction gestures', () => {
   it('opens the file in its default application from the main button and reveals it from the menu', async () => {
     const b = bench()
     render(<OpenPathAction {...b.props} />)
-    const main = screen.getByRole('button', { name: zh['path.open'] })
+    const main = await screen.findByRole('button', { name: t('open.title', { app: 'Music' }) })
     await act(async () => { fireEvent.click(main) })
-    expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open')
+    expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open', undefined)
     fireEvent.click(screen.getByRole('button', { name: zh['path.more'] }))
     await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: zh['path.reveal'] })) })
-    expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'reveal')
+    expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'reveal', undefined)
     expect(screen.queryByRole('menu')).toBeNull()
   })
 
   it('offers the default application from the menu too, and Escape closes the menu without a gesture', async () => {
     const b = bench()
     render(<OpenPathAction {...b.props} />)
+    await act(async () => {})
     const more = screen.getByRole('button', { name: zh['path.more'] })
     fireEvent.click(more)
     expect(more.getAttribute('aria-expanded')).toBe('true')
@@ -82,15 +85,15 @@ describe('OpenPathAction gestures', () => {
     expect(screen.queryByRole('menu')).toBeNull()
     expect(b.openPath).not.toHaveBeenCalled()
     fireEvent.click(more)
-    await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: zh['path.defaultApp'] })) })
-    expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open')
+    await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: 'Music（默认）' })) })
+    expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open', '/Music.app')
   })
 
   it('disables both halves while its own gesture settles and leaves no failure on the control', async () => {
     const settled = Promise.withResolvers<OpenInAppPathFailure | null>()
     const b = bench({ openPath: vi.fn(() => settled.promise) })
     const { container } = render(<OpenPathAction {...b.props} />)
-    const main = screen.getByRole('button', { name: zh['path.open'] })
+    const main = await screen.findByRole('button', { name: t('open.title', { app: 'Music' }) })
     fireEvent.click(main)
     expect(main).toHaveProperty('disabled', true)
     expect(screen.getByRole('button', { name: zh['path.more'] })).toHaveProperty('disabled', true)
@@ -111,8 +114,9 @@ describe('OpenPathEmptyAction', () => {
     cleanup()
     const b = bench()
     render(<OpenPathEmptyAction {...b.props} />)
-    await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.unpreviewable'] })) })
-    expect(b.openPath).toHaveBeenCalledWith(ABSOLUTE_PATH, 'open')
+    await act(async () => {})
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.open'] })) })
+    expect(b.openPath).toHaveBeenCalledWith(ABSOLUTE_PATH, 'open', undefined)
     expect(screen.queryByRole('alert')).toBeNull()
   })
 
@@ -120,7 +124,8 @@ describe('OpenPathEmptyAction', () => {
     vi.useFakeTimers()
     const b = bench({ openPath: vi.fn(async () => 'openError' as const) })
     render(<OpenPathEmptyAction {...b.props} />)
-    await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.unpreviewable'] })) })
+    await act(async () => {})
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.open'] })) })
     expect(screen.getAllByRole('alert')).toHaveLength(1)
     expect(screen.getByRole('alert').textContent).toContain(zh['path.openError'])
     act(() => { vi.advanceTimersByTime(4_000) })
@@ -132,11 +137,151 @@ it('dismisses a failure on schedule even when its owner rerenders', async () =>
   vi.useFakeTimers()
   const b = bench({ openPath: vi.fn(async () => 'openError' as const) })
   const view = render(<OpenPathEmptyAction {...b.props} />)
-  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.unpreviewable'] })) })
+  await act(async () => {})
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.open'] })) })
   act(() => { vi.advanceTimersByTime(2_000) })
   view.rerender(<OpenPathEmptyAction {...b.props} />)
+  await act(async () => {})
   act(() => { vi.advanceTimersByTime(1_999) })
   expect(screen.getByRole('alert')).toBeTruthy()
   act(() => { vi.advanceTimersByTime(1) })
   expect(screen.queryByRole('alert')).toBeNull()
 })
+
+
+it('shows the default icon and current application list, and selects an application without replacing default opening', async () => {
+  const b = bench()
+  const icon = 'data:image/png;base64,aGVsbG8='
+  const applications = vi.fn(async () => [
+    { id: '/Music.app', name: 'Music', default: true, icon },
+    { id: '/Player.app', name: 'Player', default: false, icon: null },
+  ])
+  const view = render(<OpenPathAction {...b.props} applications={applications} />)
+  await act(async () => {})
+  expect(view.container.querySelector('[data-open-path-open] img')?.getAttribute('src')).toBe(icon)
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.more'] })) })
+  expect(screen.getByRole('menuitem', { name: 'Music（默认）' })).toBeTruthy()
+  await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: 'Player' })) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open', '/Player.app')
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: t('open.title', { app: 'Music' }) })) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open', undefined)
+})
+
+
+it('ignores an obsolete file query and refreshes the default application when the menu opens', async () => {
+  const b = bench()
+  const old = Promise.withResolvers<readonly { id: string; name: string; default: boolean; icon: null }[]>()
+  const applications = vi.fn<OpenPathActionProps['applications']>()
+    .mockImplementationOnce(() => old.promise)
+    .mockResolvedValue([{ id: '/Player.app', name: 'Player', default: true, icon: null }])
+  const view = render(<OpenPathAction {...b.props} applications={applications} />)
+  view.rerender(<OpenPathAction {...b.props} absolutePath="/other.mp3" applications={applications} />)
+  await act(async () => { old.resolve([{ id: '/Old.app', name: 'Old', default: true, icon: null }]) })
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.more'] })) })
+  expect(screen.queryByRole('menuitem', { name: 'Old（默认）' })).toBeNull()
+  expect(screen.getByRole('menuitem', { name: 'Player（默认）' })).toBeTruthy()
+  expect(applications.mock.calls[0]![1].aborted).toBe(true)
+  expect(applications).toHaveBeenLastCalledWith('/other.mp3', expect.any(AbortSignal))
+})
+
+it('keeps reveal last and makes it the default when the file query fails', async () => {
+  const b = bench()
+  render(<OpenPathAction {...b.props} applications={async () => null} />)
+  await act(async () => {})
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.more'] })) })
+  const items = screen.getAllByRole('menuitem')
+  expect(items.map(item => item.textContent)).toEqual([zh['path.appsError'], '显示文件位置（默认）'])
+  expect(items[0]).toHaveProperty('disabled', true)
+  await act(async () => { fireEvent.click(items[1]!) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'reveal', undefined)
+})
+
+it.each([{ apps: [] }, { apps: [{ id: '/Player.app', name: 'Player', default: false, icon: null }] }])('uses reveal as the default after the available applications when none is default', async ({ apps }) => {
+  const b = bench()
+  render(<OpenPathAction {...b.props} applications={async () => apps} />)
+  await act(async () => {})
+  if (apps.length > 0) {
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.more'] })) })
+    expect(screen.getAllByRole('menuitem').at(-1)?.textContent).toBe('显示文件位置（默认）')
+    expect(screen.queryByText('用默认应用打开')).toBeNull()
+    fireEvent.keyDown(screen.getByRole('menu'), { key: 'Escape' })
+  } else expect(screen.queryByRole('button', { name: zh['path.more'] })).toBeNull()
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.reveal'] })) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'reveal', undefined)
+})
+
+
+it('coalesces repeated gestures before the busy state renders', async () => {
+  const pending = Promise.withResolvers<OpenInAppPathFailure | null>()
+  const b = bench({ openPath: vi.fn(() => pending.promise) })
+  const { result } = renderHook(() => useOpenTargetGesture(() => b.openPath(ABSOLUTE_PATH, 'open'), t))
+  act(() => { result.current.act({ kind: 'default' }); result.current.act({ kind: 'default' }) })
+  expect(b.openPath).toHaveBeenCalledOnce()
+  await act(async () => { pending.resolve(null) })
+  expect(result.current.pending).toBe(false)
+})
+
+
+it('closes the application menu from its chevron without querying again', async () => {
+  const b = bench()
+  render(<OpenPathAction {...b.props} />)
+  await act(async () => {})
+  const more = screen.getByRole('button', { name: zh['path.more'] })
+  await act(async () => { fireEvent.click(more) })
+  expect(screen.getByRole('menu')).toBeTruthy()
+  const calls = vi.mocked(b.props.applications).mock.calls.length
+  await act(async () => { fireEvent.click(more) })
+  expect(screen.queryByRole('menu')).toBeNull()
+  expect(b.props.applications).toHaveBeenCalledTimes(calls)
+})
+
+
+it('waits for the file association query before allowing a default action', async () => {
+  const b = bench()
+  const query = Promise.withResolvers<Awaited<ReturnType<OpenPathActionProps['applications']>>>()
+  const view = render(<OpenPathAction {...b.props} applications={() => query.promise} />)
+  const main = view.container.querySelector('[data-open-path-open]')!
+  expect(main).toHaveProperty('disabled', true)
+  fireEvent.click(main)
+  expect(b.openPath).not.toHaveBeenCalled()
+  await act(async () => { query.resolve([]) })
+  expect(main).toHaveProperty('disabled', false)
+  await act(async () => { fireEvent.click(main) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'reveal', undefined)
+})
+
+
+it('uses the same application menu in the prominent empty-state control', async () => {
+  const b = bench()
+  const view = render(<OpenPathEmptyAction {...b.props} />)
+  await act(async () => {})
+  expect(view.container.querySelector('[data-open-target]')?.getAttribute('data-size')).toBe('large')
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.more'] })) })
+  expect(screen.getAllByRole('menuitem').map(item => item.textContent)).toEqual(['Music（默认）', zh['path.reveal']])
+  await act(async () => { fireEvent.click(screen.getByRole('menuitem', { name: 'Music（默认）' })) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'open', '/Music.app')
+})
+
+it('labels the prominent default action as reveal when no default application is discovered', async () => {
+  const b = bench()
+  render(<OpenPathEmptyAction {...b.props} applications={async () => []} />)
+  await act(async () => {})
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.reveal'] })) })
+  expect(b.openPath).toHaveBeenLastCalledWith(ABSOLUTE_PATH, 'reveal', undefined)
+})
+
+
+it('uses a skeleton while associations load and pins reveal outside the application list', async () => {
+  const b = bench()
+  const pending = Promise.withResolvers<readonly { id: string; name: string; default: boolean; icon: null }[]>()
+  const view = render(<OpenPathAction {...b.props} applications={() => pending.promise} />)
+  expect(view.container.querySelector('[data-open-target-skeleton]')).not.toBeNull()
+  expect(view.container.querySelector('[data-open-path-open] svg')).toBeNull()
+  await act(async () => { pending.resolve([{ id: 'music', name: 'Music', default: true, icon: null }]) })
+  expect(view.container.querySelector('[data-open-target-skeleton]')).toBeNull()
+  await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['path.more'] })) })
+  const menu = screen.getByRole('menu')
+  const reveal = screen.getByRole('menuitem', { name: zh['path.reveal'] })
+  expect(menu.firstElementChild?.contains(reveal)).toBe(false)
+  expect(menu.lastElementChild?.contains(reveal)).toBe(true)
+})
diff --git a/packages/client/ui-open-in-app/tests/open-path.client.spec.ts b/packages/client/ui-open-in-app/tests/open-path.client.spec.ts
index 2e8560f7cf..2def94a830 100644
--- a/packages/client/ui-open-in-app/tests/open-path.client.spec.ts
+++ b/packages/client/ui-open-in-app/tests/open-path.client.spec.ts
@@ -10,6 +10,7 @@ type SessionRemote = OpenInAppPathRemote['session']
 function remoteOf(over: Partial<SessionRemote> = {}): OpenInAppPathRemote {
   return {
     session: {
+      workspacePathApplications: async () => ({ ok: true, value: [] }),
       canOpenWorkspacePath: async () => ({ ok: true, value: true }),
       openWorkspacePath: async () => ({ ok: true, value: { opened: true } }),
       ...over,
@@ -69,3 +70,27 @@ describe('OpenInAppPathController gestures', () => {
     expect(await rejecting.openPath('/w/clip.mp4', 'open')).toBe('openError')
   })
 })
+
+
+it('queries current handlers and carries an explicit application without changing the default gesture', async () => {
+  const applications = [{ id: '/Applications/Music.app', name: 'Music', default: true, icon: null }]
+  const query = vi.fn(async () => ({ ok: true as const, value: applications }))
+  const open = vi.fn(async () => ({ ok: true as const, value: { opened: true } }))
+  const controller = new OpenInAppPathController(remoteOf({ workspacePathApplications: query, openWorkspacePath: open }))
+  const signal = new AbortController().signal
+  expect(await controller.applications('/file.mp3', signal)).toEqual(applications)
+  expect(query).toHaveBeenCalledWith({ path: '/file.mp3' }, signal)
+  await controller.openPath('/file.mp3', 'open', '/Applications/Music.app')
+  expect(open).toHaveBeenLastCalledWith({ path: '/file.mp3', application: '/Applications/Music.app' })
+  await controller.openPath('/file.mp3', 'open')
+  expect(open).toHaveBeenLastCalledWith({ path: '/file.mp3' })
+})
+
+
+it('distinguishes failed association queries from an empty application list', async () => {
+  const remote = remoteOf({ workspacePathApplications: async () => ({ ok: false, error: new RemoteError('gateway/internal', 'unavailable', {}) }) })
+  const controller = new OpenInAppPathController(remote)
+  expect(await controller.applications('/file.mp3', new AbortController().signal)).toBeNull()
+  const rejecting = new OpenInAppPathController(remoteOf({ workspacePathApplications: async () => { throw new Error('disconnected') } }))
+  expect(await rejecting.applications('/file.mp3', new AbortController().signal)).toBeNull()
+})
diff --git a/packages/client/ui-open-in-app/tsconfig.json b/packages/client/ui-open-in-app/tsconfig.json
index 1f0c094732..e37925c8a4 100644
--- a/packages/client/ui-open-in-app/tsconfig.json
+++ b/packages/client/ui-open-in-app/tsconfig.json
@@ -46,6 +46,12 @@
     },
     {
       "path": "../ui-slots"
+    },
+    {
+      "path": "../ui-deliverables/tsconfig.client.json"
+    },
+    {
+      "path": "../../util/native-command"
     }
   ]
 }
diff --git a/packages/client/ui-plan/README.i18n.yaml b/packages/client/ui-plan/README.i18n.yaml
index 74be8bbf76..e6ffe166f1 100644
--- a/packages/client/ui-plan/README.i18n.yaml
+++ b/packages/client/ui-plan/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-plan/README.md
-README.md: b6072cd7d75446a0a45abe4009273235e4ff4e1b
-README.zh.md: 44b5ce85ccd6250f30904f80b01ee083f804f1ce
+README.md: d87d288ace572bcaf97778f771b1ecc9b4400356
+README.zh.md: 14b98d14376bcf7b27a07a249b14627714b31282
diff --git a/packages/client/ui-plan/README.md b/packages/client/ui-plan/README.md
index b6072cd7d7..d87d288ace 100644
--- a/packages/client/ui-plan/README.md
+++ b/packages/client/ui-plan/README.md
@@ -29,7 +29,7 @@ Mount this plugin alongside `ui-conversation` and `dsh-plan-mode`; the chip then
 
 ### What the chip shows
 
-While the effective target is plan mode, the seat renders the blue "Plan ×" status button, which executes `/plan off`. Otherwise the seat stays empty: a host without plan mode, or a Draft with no session, shows nothing. While plan mode is the effective target, the composer textarea's placeholder switches to the plan-task hint — "describe your task to generate plan" — unless the owning surface supplies its own placeholder.
+While the effective target is plan mode, the seat renders the blue "Plan" status button — the plan glyph ahead of the label, swapped for a circled cross while the enabled button is hovered or keyboard-focused — which executes `/plan off`. Otherwise the seat stays empty: a host without plan mode, or a Draft with no session, shows nothing. While plan mode is the effective target, the composer textarea's placeholder switches to the plan-task hint — "describe your task to generate plan" — unless the owning surface supplies its own placeholder.
 
 ### Reading submitted plans
 
@@ -51,7 +51,7 @@ Admission failures (`matched: false`, business errors, transport faults) surface
 
 The chip occupies the conversation-declared `conversation.input.plan` single seat; the node half is an empty apply (the roster row). Reads ride the generic projection pair through the standard-kit `useProjection`: the effective target is `pending ? !active : active` — a folded host value, not client optimism, so an arriving frame corrects the chip either way. The seat's injected face carries one verb, `exitPlanMode`, which executes `/plan off` through `ctx.remote.commands.execute` and maps admission failures to an inline error line. The placeholder and hint text live in ui-conversation's `conversation` locale namespace and are shared verbatim with the claimed `/plan` command hint.
 
-Plan cards derive from native `tool/call` or PTC dispatch arguments through a Conversation Definition, with each invocation’s resolved Turn location. They contribute to the additive `conversation.chat.turnTail` list alongside file deliveries. The plan resource address identifies the invocation and its complete ordinary or direct-parent subagent Session address; its provider reads existing Session history, including older pages, without storing document text in sidebar layout. The question plugin owns the review action slot and supplies its request key, complete text, and optional invocation identity. The [decision](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.md) explains why review lifetime and document lifetime remain separate.
+Plan cards derive from native `tool/call` or PTC dispatch arguments through a Conversation Definition, with each invocation’s resolved Turn location. They contribute to the additive `conversation.chat.turnTail` list alongside file deliveries. The plan resource address identifies the invocation and its complete ordinary or direct-parent subagent Session address; its provider reads existing Session history, including older pages, without storing document text in sidebar layout. The question plugin owns the review action slot and supplies its request key, complete text, and optional invocation identity. The automatic open reads `ctx.sidebarRight.mounted` through a bound hook and runs once a seat is on screen: a review arriving while a global panel is active mounts ahead of the returning seat in the same commit, before that seat binds. The [decision](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.md) explains why review lifetime and document lifetime remain separate. Subagent plan addresses also preserve unknown mode so history reads can resolve the child descriptor.
 
 </details>
 
diff --git a/packages/client/ui-plan/README.zh.md b/packages/client/ui-plan/README.zh.md
index 44b5ce85cc..14b98d1437 100644
--- a/packages/client/ui-plan/README.zh.md
+++ b/packages/client/ui-plan/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 徽章显示什么
 
-当有效目标为 plan 模式时，该座位渲染 蓝色「计划 ×」状态按钮，执行 `/plan off`。否则座位保持为空：未组合 plan-mode 的宿主，或尚无会话的 Draft，都不显示任何内容。plan 模式为有效目标期间，composer 文本框的 placeholder 切换为 plan 任务提示——「describe your task to generate plan」——除非所属 surface 提供自己的 placeholder。
+当有效目标为 plan 模式时，该座位渲染蓝色「计划」状态按钮——标签前是计划图标，按钮可用且被悬停或键盘聚焦时换成圆形 ×——点击执行 `/plan off`。否则座位保持为空：未组合 plan-mode 的宿主，或尚无会话的 Draft，都不显示任何内容。plan 模式为有效目标期间，composer 文本框的 placeholder 切换为 plan 任务提示——「describe your task to generate plan」——除非所属 surface 提供自己的 placeholder。
 
 ### 查看已提交的计划
 
@@ -51,7 +51,7 @@ kind: "package-reference"
 
 徽章占据 conversation 声明的 `conversation.input.plan` 单实例座位；node 半部是空 apply（roster 行）。读取经 standard-kit 的 `useProjection` 走通用投影对：有效目标是 `pending ? !active : active`——折叠的宿主值而非客户端乐观态，因此到达的帧无论哪个方向都会纠正徽章。座位注入面携带一个动词 `exitPlanMode`，经 `ctx.remote.commands.execute` 执行 `/plan off`，并把准入失败映射为一行内联错误。placeholder 与提示文案位于 ui-conversation 的 `conversation` locale 命名空间，与已认领 `/plan` 命令的提示逐字共用。
 
-计划卡片通过 Conversation Definition 从原生 `tool/call` 或 PTC dispatch 参数派生，并使用每次调用已解析的回合位置。它们与文件产物一起贡献到可追加的 `conversation.chat.turnTail` 列表。计划资源地址标识调用及完整的普通会话地址或子会话直接父级地址；provider 读取已有会话历史及较早分页，不把正文存入侧边栏布局。提问插件拥有审批操作插槽，并提供请求键、完整正文和可选的调用标识。[决策记录](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.zh.md)说明审批与文档为何保持独立生命周期。
+计划卡片通过 Conversation Definition 从原生 `tool/call` 或 PTC dispatch 参数派生，并使用每次调用已解析的回合位置。它们与文件产物一起贡献到可追加的 `conversation.chat.turnTail` 列表。计划资源地址标识调用及完整的普通会话地址或子会话直接父级地址；provider 读取已有会话历史及较早分页，不把正文存入侧边栏布局。提问插件拥有审批操作插槽，并提供请求键、完整正文和可选的调用标识。自动打开通过绑定的 hook 读取 `ctx.sidebarRight.mounted`，在座位出现在屏幕上后才执行：全局面板打开期间到达的审批，会在返回时与座位在同一次提交里先挂载、早于座位完成绑定。[决策记录](../../../.agents/notes/implemented/feature/2026-09-17-persistent-plan-cards.zh.md)说明审批与文档为何保持独立生命周期。 子代理计划地址也保留未知模式，以便历史读取解析子 descriptor。
 
 </details>
 
diff --git a/packages/client/ui-plan/src/client/PlanCard.tsx b/packages/client/ui-plan/src/client/PlanCard.tsx
index 3b2e03951b..7ac1ad09f8 100644
--- a/packages/client/ui-plan/src/client/PlanCard.tsx
+++ b/packages/client/ui-plan/src/client/PlanCard.tsx
@@ -4,8 +4,9 @@ import { FileTypeIcon, IconChevronRightOutlineRegular } from '@deepseek-ai/dsh-c
 import type { ChatNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { shallowEqual } from '@deepseek-ai/dsh-client-store'
 import type {} from './plan-definition.ts'
-import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type {} from '@deepseek-ai/dsh-client-ui-user-questions/client'
 import type { createPlanReviewStore } from './review-store.ts'
 import css from './PlanPreview.module.css'
@@ -20,6 +21,10 @@ export interface PlanOpenInjected {
 export interface PlanReviewOpenInjected {
   /** Open the logged plan, or the request's temporary document when no invocation exists. */
   openReview: (review: PropsRuntime<'conversation.plan-review.actions'>['review'], requestKey: string) => void
+  readonly hooks: {
+    /** The session whose right Sidebar seat is mounted; `undefined` while none is on screen. */
+    readonly sidebarMounted: HostObservable<SessionId | undefined>
+  }
 }
 
 /**
@@ -52,17 +57,23 @@ export function PlanCards({ turn, useChat, openPlan, t }: PropsRuntime<'conversa
 
 /**
  * Open each pending plan automatically and retain a manual opener without answering it.
+ *
+ * The automatic open waits for a mounted Sidebar seat: a review that arrives
+ * while the Conversation is off screen mounts in the same commit as the seat,
+ * ahead of it, and the seat binds from its own effect. Reading the bound
+ * session through the hook opens once that binding exists.
  * @param props - Review identity, Session store, localized copy, and navigation.
  * @returns an opener for either logged or temporary plan text.
  */
-export function PlanReviewOpen({ review, requestKey, openReview, t, useStore, actions }: PropsRuntime<'conversation.plan-review.actions'> & InjectFace<PlanReviewOpenInjected> & PropsLocale<'plan'> & PropsStore<ReturnType<typeof createPlanReviewStore>>) {
+export function PlanReviewOpen({ review, requestKey, openReview, useSidebarMounted, t, useStore, actions }: PropsRuntime<'conversation.plan-review.actions'> & InjectFace<PlanReviewOpenInjected> & PropsLocale<'plan'> & PropsStore<ReturnType<typeof createPlanReviewStore>>) {
   const identity = review.callId === undefined ? `review:${requestKey}` : `call:${review.callId}`
   const opened = useStore(state => state.opened[identity] === true)
+  const mounted = useSidebarMounted(session => session !== undefined)
   useEffect(() => {
-    if (opened) return
+    if (opened || !mounted) return
     openReview(review, requestKey)
     actions.markOpened(identity)
-  }, [identity, opened, openReview, review, requestKey, actions])
+  }, [identity, opened, mounted, openReview, review, requestKey, actions])
   return <button type="button" className={css.reviewLink} title={t('preview.open')} aria-label={t('preview.open')}
     onClick={() => { openReview(review, requestKey) }}>{t('preview.full')}<IconChevronRightOutlineRegular size={14} /></button>
 }
diff --git a/packages/client/ui-plan/src/client/PlanModeControl.module.css b/packages/client/ui-plan/src/client/PlanModeControl.module.css
index 793ca4e5d6..7784f0ac08 100644
--- a/packages/client/ui-plan/src/client/PlanModeControl.module.css
+++ b/packages/client/ui-plan/src/client/PlanModeControl.module.css
@@ -1,5 +1,9 @@
 /* Active plan status: a business accent pill at the control row's own height
-   (28px, like the + control and the sibling selects). */
+   (28px, like the + control and the sibling selects). The radius is half that
+   height — the compact Button geometry — under the theme's corner curvature,
+   the same corners as the sibling access-mode trigger; a 999px pill would
+   need the circular `corner-shape: round` opt-out and read rounder than
+   every neighbouring control. */
 
 .wrap {
   display: inline-flex;
@@ -15,8 +19,7 @@
   min-width: 34px;
   padding: 0 8px;
   border: none;
-  border-radius: 999px;
-  corner-shape: round;
+  border-radius: 14px;
   background: var(--dsw-alias-state-business-tertiary);
   color: var(--dsw-alias-state-business-primary);
   font-size: 13px;
@@ -43,12 +46,28 @@
   cursor: default;
 }
 
-.close {
+/* One 14px glyph slot ahead of the label (the access-mode trigger's layout):
+   the plan glyph at rest, the circled close while the enabled chip is hovered
+   or keyboard-focused, marking the pending click as turning plan mode off. */
+.glyph {
   display: inline-flex;
-  align-items: center;
+  flex: 0 0 auto;
+  width: 14px;
+  height: 14px;
   color: currentColor;
 }
 
+.hoverGlyph,
+.chip:hover:not(:disabled) .restGlyph,
+.chip:focus-visible .restGlyph {
+  display: none;
+}
+
+.chip:hover:not(:disabled) .hoverGlyph,
+.chip:focus-visible .hoverGlyph {
+  display: block;
+}
+
 .error {
   color: var(--dsw-alias-state-error-primary);
   font-size: 12px;
diff --git a/packages/client/ui-plan/src/client/PlanModeControl.tsx b/packages/client/ui-plan/src/client/PlanModeControl.tsx
index 8cbd71d878..30bb1a2972 100644
--- a/packages/client/ui-plan/src/client/PlanModeControl.tsx
+++ b/packages/client/ui-plan/src/client/PlanModeControl.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from 'react'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { IconCloseFillRegular } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconCloseCircleFillRegular, IconPlanOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
 // Type-only: pulls the ui-conversation SlotMap merge (the input.plan seat and
 // its {locked} owner share).
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -58,10 +58,11 @@ export function PlanChip({ useProjection, locked, exitPlanMode, t }: PlanChipPro
         disabled={locked || leaving}
         onClick={off}
       >
-        {t('chip.label')}
-        <span className={css.close} aria-hidden>
-          <IconCloseFillRegular size={12} />
+        <span className={css.glyph} aria-hidden>
+          <IconPlanOutlineRegular className={css.restGlyph} size={14} />
+          <IconCloseCircleFillRegular className={css.hoverGlyph} size={14} />
         </span>
+        {t('chip.label')}
       </button>
       {error !== null && <span className={css.error} role="status" title={error}>{t('chip.exitFailed')}</span>}
     </span>
diff --git a/packages/client/ui-plan/src/client/index.ts b/packages/client/ui-plan/src/client/index.ts
index bd0a270474..d5366e8d46 100644
--- a/packages/client/ui-plan/src/client/index.ts
+++ b/packages/client/ui-plan/src/client/index.ts
@@ -88,6 +88,7 @@ export function apply(ctx: ClientContext): void {
           params: { planReview: { markdown: review.plan, title: extractMarkdownPlainText(review.plan, { mode: 'first-line' }) } },
         })
       },
+      hooks: { sidebarMounted: ctx.sidebarRight.mounted },
     }),
   }, PlanReviewOpen))
   ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
diff --git a/packages/client/ui-plan/src/client/plan.ts b/packages/client/ui-plan/src/client/plan.ts
index e3dff30e29..d44b8f2dd9 100644
--- a/packages/client/ui-plan/src/client/plan.ts
+++ b/packages/client/ui-plan/src/client/plan.ts
@@ -74,7 +74,7 @@ export function parsePlanAddress(address: string): PlanAddress | undefined {
     if (parts.length === 2) return {
       session: { kind: 'session', sessionId: parts[0] as SessionId }, callId: parts[1] as ToolCallId,
     }
-    if (parts.length === 5 && parts[0] === 'subagent' && (parts[3] === 'one-shot' || parts[3] === 'continuable')) return {
+    if (parts.length === 5 && parts[0] === 'subagent' && (parts[3] === 'one-shot' || parts[3] === 'continuable' || parts[3] === 'unknown')) return {
       session: { kind: 'subagent', parentSessionId: parts[1] as SessionId, childSessionId: parts[2] as SessionId, mode: parts[3] },
       callId: parts[4] as ToolCallId,
     }
diff --git a/packages/client/ui-plan/tests/browser-plugin.client.spec.ts b/packages/client/ui-plan/tests/browser-plugin.client.spec.ts
index 71bc23a044..ce6a761fe1 100644
--- a/packages/client/ui-plan/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-plan/tests/browser-plugin.client.spec.ts
@@ -11,6 +11,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
 import { PlanChip } from '../src/client/PlanModeControl.tsx'
 import { PlanCards, PlanReviewOpen, type PlanOpenInjected, type PlanReviewOpenInjected } from '../src/client/PlanCard.tsx'
@@ -31,13 +32,14 @@ function providePreview(ctx: Context) {
   const registerType = vi.fn<Context['sidebarRightTabs']['register']>(() => removeType)
   const openResourceIn = vi.fn<Context['sidebarRight']['openResourceIn']>()
   const openResource = vi.fn<Context['sidebarRight']['openResource']>()
+  const mounted = createSnapshotStore<SessionId | undefined>(undefined)
   const subagentAddress = vi.fn<Context['sessions']['subagentAddress']>(() => undefined)
   ctx.provide('sessions', { subagentAddress })
   ctx.provide('resources', { register: vi.fn(() => removeResources) })
   ctx.provide('sidebarRightTabs', { register: registerType })
-  ctx.provide('sidebarRight', { openResourceIn, openResource })
+  ctx.provide('sidebarRight', { openResourceIn, openResource, mounted })
   ctx.provide('remote.session', {})
-  return { events, removeResources, removeType, registerType, openResourceIn, openResource, subagentAddress }
+  return { events, removeResources, removeType, registerType, openResourceIn, openResource, mounted, subagentAddress }
 }
 
 const SID = 's-plan' as SessionId
@@ -183,6 +185,8 @@ describe('ui-plan browser apply', () => {
       const review = b.slots.entries('conversation.plan-review.actions')[0]!
       expect(review.component).toBe(PlanReviewOpen)
       const reviewInjected = (review.inject as unknown as (sessionId: SessionId) => PlanReviewOpenInjected)(SID)
+      // The automatic open reads the service's mounted-seat source, not a copy.
+      expect(reviewInjected.hooks.sidebarMounted).toBe(b.mounted)
       const pending = { id: 'review', question: 'Approve?', plan: plan.markdown, callId: plan.callId, approve: { label: 'Approve' } }
       reviewInjected.openReview(pending, 'question:1')
       expect(b.openResource).toHaveBeenLastCalledWith(address)
diff --git a/packages/client/ui-plan/tests/plan-mode-control.client.spec.tsx b/packages/client/ui-plan/tests/plan-mode-control.client.spec.tsx
index 5e1e0fa286..5348e816b2 100644
--- a/packages/client/ui-plan/tests/plan-mode-control.client.spec.tsx
+++ b/packages/client/ui-plan/tests/plan-mode-control.client.spec.tsx
@@ -11,6 +11,7 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { bindSnapshotSelector, makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import type { PlanProjection } from '@deepseek-ai/dsh-plan-mode/client'
 import { PlanChip, type PlanChipProps } from '../src/client/PlanModeControl.tsx'
+import css from '../src/client/PlanModeControl.module.css'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { zh } from '../src/client/locales.ts'
 
@@ -54,6 +55,21 @@ describe('PlanChip', () => {
     expect(chip().textContent).toBe('计划')
   })
 
+  it('leads with the plan glyph and swaps in the circled close only while hovered', () => {
+    setup({ active: true, pending: false })
+    // Glyph-then-label like the sibling access-mode trigger; the two glyphs
+    // share one slot and CSS shows exactly one of them, so no trailing cross.
+    const glyphs = chip().querySelectorAll('svg')
+    expect(glyphs).toHaveLength(2)
+    const slot = glyphs[0]!.parentElement!
+    expect(slot).toBe(chip().firstElementChild)
+    expect(slot.getAttribute('aria-hidden')).toBe('true')
+    expect(glyphs[0]!.classList.contains(css.restGlyph!)).toBe(true)
+    expect(glyphs[1]!.classList.contains(css.hoverGlyph!)).toBe(true)
+    expect(glyphs[1]!.parentElement).toBe(slot)
+    expect(chip().lastChild?.textContent).toBe('计划')
+  })
+
   it('executes /plan off once and follows the projection down', async () => {
     let resolve!: (value: string | null) => void
     const exitPlanMode = vi.fn(() => new Promise<string | null>((done) => { resolve = done }))
diff --git a/packages/client/ui-plan/tests/plan-preview.client.spec.tsx b/packages/client/ui-plan/tests/plan-preview.client.spec.tsx
index e0efcb40ef..4fb47890c6 100644
--- a/packages/client/ui-plan/tests/plan-preview.client.spec.tsx
+++ b/packages/client/ui-plan/tests/plan-preview.client.spec.tsx
@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi, type Mock } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { ConversationNodeAssembler } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { SessionLiveEventEntry } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -7,6 +7,7 @@ import type { ChatSnapshot } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { chatViewDefinition } from '../../ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
 import { en, zh } from '../src/client/locales.ts'
 import { PlanCards, PlanReviewOpen } from '../src/client/PlanCard.tsx'
@@ -29,6 +30,16 @@ function planNode(data: typeof plan) {
 function planHook(nodes: readonly unknown[]): Parameters<typeof PlanCards>[0]['useChat'] {
   return ((select: (snapshot: unknown) => unknown) => select({ nodes: { values: () => nodes } })) as Parameters<typeof PlanCards>[0]['useChat']
 }
+/** The opener's props share; each test supplies the seat hook beside it. */
+function reviewProps(review: { plan: string; callId?: typeof plan.callId }, openReview: Mock, store: ReturnType<ReturnType<typeof createPlanReviewStore>['create']>) {
+  return { review, requestKey: 'question:1', t, openReview, actions: store.actions,
+    useStore: (select: (state: ReturnType<typeof store.getSnapshot>) => unknown) => select(store.getSnapshot()),
+  } as unknown as Parameters<typeof PlanReviewOpen>[0]
+}
+/** A bound `useSidebarMounted` reading one observable seat value. */
+function seatHook(read: () => SessionId | undefined) {
+  return <S,>(select: (session: SessionId | undefined) => S): S => select(read())
+}
 
 describe('submitted plan identity', () => {
   it('reads native, running PTC, and settled PTC calls', () => {
@@ -164,9 +175,7 @@ describe('plan entry points and document', () => {
     const openReview = vi.fn()
     const store = createPlanReviewStore().create()
     const review = { plan: markdown, ...(logged ? { callId: plan.callId } : {}) }
-    const props = { review, requestKey: 'question:1', t, openReview, actions: store.actions,
-      useStore: (select: (state: ReturnType<typeof store.getSnapshot>) => unknown) => select(store.getSnapshot()),
-    } as unknown as Parameters<typeof PlanReviewOpen>[0]
+    const props = { ...reviewProps(review, openReview, store), useSidebarMounted: seatHook(() => target.session.sessionId) }
     const first = render(<PlanReviewOpen {...props} />)
     expect(openReview).toHaveBeenCalledExactlyOnceWith(review, 'question:1')
     first.rerender(<PlanReviewOpen {...props} />)
@@ -186,6 +195,31 @@ describe('plan entry points and document', () => {
     } as Parameters<typeof PlanReviewOpen>[0]} />)
     expect(openReview).toHaveBeenCalledTimes(4)
   })
+  it('waits for a mounted sidebar seat before opening automatically, then opens once', () => {
+    // The review and the seat mount in one commit, the review first: its effect
+    // runs while no seat is bound, and the seat's own effect binds afterwards.
+    const openReview = vi.fn()
+    const store = createPlanReviewStore().create()
+    const mounted = createSnapshotStore<SessionId | undefined>(undefined)
+    const review = { plan: markdown, callId: plan.callId }
+    const props = { ...reviewProps(review, openReview, store), useSidebarMounted: seatHook(() => mounted.getSnapshot()) }
+    const view = render(<PlanReviewOpen {...props} />)
+    expect(openReview).not.toHaveBeenCalled()
+    expect(store.getSnapshot().opened).toEqual({})
+    // The manual opener stays available without a seat; the service decides what to do.
+    fireEvent.click(screen.getByRole('button', { name: 'Open plan in sidebar' }))
+    expect(openReview).toHaveBeenCalledTimes(1)
+    mounted.set(target.session.sessionId)
+    view.rerender(<PlanReviewOpen {...props} />)
+    expect(openReview).toHaveBeenCalledTimes(2)
+    expect(store.getSnapshot().opened).toEqual({ [`call:${plan.callId}`]: true })
+    view.rerender(<PlanReviewOpen {...props} />)
+    mounted.set(undefined)
+    view.rerender(<PlanReviewOpen {...props} />)
+    mounted.set(target.session.sessionId)
+    view.rerender(<PlanReviewOpen {...props} />)
+    expect(openReview).toHaveBeenCalledTimes(2)
+  })
   it('renders temporary Markdown and reports expired navigation after reload', () => {
     const address = reviewPreviewAddress(target.session.sessionId, 'window:question:1')
     expect(isReviewPreviewAddress(address)).toBe(true)
diff --git a/packages/client/ui-plan/tests/plan-resource.client.spec.ts b/packages/client/ui-plan/tests/plan-resource.client.spec.ts
index a27b03c185..57be9acd36 100644
--- a/packages/client/ui-plan/tests/plan-resource.client.spec.ts
+++ b/packages/client/ui-plan/tests/plan-resource.client.spec.ts
@@ -36,7 +36,7 @@ describe('plan history resource', () => {
     expect(b.page).toHaveBeenCalledWith({ address: { kind: 'session', sessionId: 'session' }, throughSeq: 100, beforeSeq: 80 }, expect.any(AbortSignal))
     expect(b.closed).toHaveBeenCalledOnce()
   })
-  it.each(['one-shot', 'continuable'] as const)('restores a %s subagent plan with its complete parent address on every page', async (mode) => {
+  it.each(['one-shot', 'continuable', 'unknown'] as const)('restores a %s subagent plan with its complete parent address on every page', async (mode) => {
     const b = setup([{ type: 'event', event: { type: 'user/message', seq: 80, data: {} } }], true)
     const address = `dsh-resource://plan/subagent/parent/child/${mode}/call`
     const session = { kind: 'subagent', parentSessionId: 'parent', childSessionId: 'child', mode }
diff --git a/packages/client/ui-plugin-manager/README.i18n.yaml b/packages/client/ui-plugin-manager/README.i18n.yaml
index dfbe7fcedb..2489489230 100644
--- a/packages/client/ui-plugin-manager/README.i18n.yaml
+++ b/packages/client/ui-plugin-manager/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-plugin-manager/README.md
-README.md: d7bcd2299d93dab90c8440565ac87112b37c9c10
-README.zh.md: 368058dabc27968b86088c34ee387dc5dd5bd364
+README.md: 75d972a310f7f5fc505775bcc72d2f18675d0c89
+README.zh.md: 66c441950ba288f554e2e41750cfe4e0c0b0b359
diff --git a/packages/client/ui-plugin-manager/README.md b/packages/client/ui-plugin-manager/README.md
index d7bcd2299d..75d972a310 100644
--- a/packages/client/ui-plugin-manager/README.md
+++ b/packages/client/ui-plugin-manager/README.md
@@ -27,7 +27,7 @@ Use the **Plugins** entry in the Web sidebar to manage the profile's installed b
 
 Select **Plugins** in the sidebar. The page reads the inventory and the bundles through `api-remotes` when first opened; a Host without a managed profile shows the page as unavailable. **Official** comes first and lists the bundles the installation ships for switching on — off until switched on, without an uninstall, and tagged **Beta** where the feature is one — followed by the official plugins that registered a configuration page; **Installed** lists the bundles the profile holds. Cards are listed by name, so switching a bundle on or off does not move its card. A dependency without a bundle patch is not a plugin and is not listed unless the profile selects it, in which case it carries a problem tag. Global configuration remains in the Settings **Plugins** section.
 
-Installed bundles and their plugin rows display their own title and description in the current UI language on cards and detail pages. Each field falls back from exported locale `meta` to the accessible `package.json` at that plugin address; the final title is the full package or module name, with no package description when both sources omit it. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format. Installation previews still use registry or manifest information.
+Installed bundles and their plugin rows display their own title and description in the current UI language on cards and detail pages. Each field falls back from exported locale `meta` to the accessible `package.json` at that plugin address; the final title is the full package or module name, with no package description when both sources omit it. See [Plugin display metadata](../../../docs/cookbook/adding-a-package.md#plugin-display-metadata) for the author format. Bundle cards, details, and component rows display the image declared by their own `package.json.icon`; absent or undecodable images retain the default artwork. Installation previews still use registry or manifest information.
 
 ### Installing a bundle
 
@@ -77,7 +77,9 @@ The browser plugin registers the `plugins` sidebar entry and its `main` panel th
 
 ### Configuration slots
 
-The page's `main` registration declares `plugins.item`, `plugins.bundle.config`, and `plugins.row.config` as its children, so the slots exist while the page does and a registrant's `ctx.slots.inject` waits for them. `configLedgerSource` projects the three ledgers into one observable — the official items in ledger order with their labels resolved in the active locale, and the bundle and row keys — cached until a ledger or the locale moves; the page binds it as `useConfigLedger` beside the store and never names a configurable plugin itself. Which page is open is page-local state: the cards, a bundle, an official plugin, or a row of a bundle. A registration lives with the browser half that made it. `dsh-client-modules` attaches a package's browser half to the Loader row whose specifier is the bare package name, so every page a bundle registers, for itself or for any of its rows, goes away when that row is switched off; a sub-plugin whose page must outlive the other rows ships as its own package.
+The page's `main` registration declares `plugins.item`, `plugins.bundle.config`, and `plugins.row.config` as its children, so the slots exist while the page does and a registrant's `ctx.slots.inject` waits for them. `configLedgerSource` projects the three ledgers into one observable — the official items in ledger order with their labels resolved in the active locale, and the bundle and row keys — cached until a ledger or the locale moves; the page binds it as `useConfigLedger` beside the store and never names a configurable plugin itself. Which page is open is page-local state: the cards, a bundle, an official plugin, or a row of a bundle. A registration lives with the browser half that made it. `dsh-client-modules` attaches a package's browser half to the Loader row whose specifier is the bare package name, so every page a bundle registers, for itself or for any of its rows, goes away when that row is switched off; a sub-plugin whose page must outlive the other rows ships as its own package. Official packages whose names begin with `@deepseek-ai/dsh-experimental-` display the Beta marker.
+
+`plugins.bundle.config` supplies bundle detail configuration, keyed by npm package name. `plugins.bundle.activation` offers bundle-owned guidance after explicit enablement from the list, with callbacks to dismiss it or open the bundle details. It does not appear merely because an enabled bundle was listed.
 
 </details>
 
diff --git a/packages/client/ui-plugin-manager/README.zh.md b/packages/client/ui-plugin-manager/README.zh.md
index 368058dabc..66c441950b 100644
--- a/packages/client/ui-plugin-manager/README.zh.md
+++ b/packages/client/ui-plugin-manager/README.zh.md
@@ -27,7 +27,7 @@ kind: "package-reference"
 
 在侧栏选择**插件**。页面首次打开时通过 `api-remotes` 读取清单与组合包；没有受管 profile 的 Host 上页面显示为不可用。**官方**排在前面，列出安装随附、供开启的组合包——开启前保持关闭、没有卸载、属于 beta 功能的带 **Beta** 标签——其后是注册了配置页的官方插件；**已安装**列出 profile 持有的组合包。卡片按名称排序，启停组合包不会挪动它的卡片。没有组合包 patch 的依赖不是插件，除非 profile 选中了它才会带异常标签列出。全局配置仍在设置的**插件**分区中编辑。
 
-已安装的组合包及其插件行在卡片和详情页中，按当前界面语言显示各自的标题与描述。每个字段先读取导出的 locale `meta`，缺失时回退到该插件地址下可访问的 `package.json`；标题最终使用完整包名或模块名，两处都没有描述时不提供包描述。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。安装预览仍使用注册表或 manifest 信息。
+已安装的组合包及其插件行在卡片和详情页中，按当前界面语言显示各自的标题与描述。每个字段先读取导出的 locale `meta`，缺失时回退到该插件地址下可访问的 `package.json`；标题最终使用完整包名或模块名，两处都没有描述时不提供包描述。作者格式见[插件展示元信息](../../../docs/cookbook/adding-a-package.zh.md#plugin-display-metadata)。组合包卡片、详情和组件行显示各自 `package.json.icon` 声明的图片；未声明或无法解码时保留默认插画。安装预览仍使用注册表或 manifest 信息。
 
 ### 安装一个组合包
 
@@ -77,7 +77,9 @@ ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
 
 ### 配置 slot
 
-页面的 `main` 注册把 `plugins.item`、`plugins.bundle.config` 与 `plugins.row.config` 声明为子 slot，因此它们与页面同生，注册方的 `ctx.slots.inject` 会等到它们出现。`configLedgerSource` 把三份账本投影成一个可观察对象——按账本顺序排列、标签按当前语言解析的官方条目，以及组合包与行的键——在账本或语言变化前保持缓存；页面把它作为 `useConfigLedger` 绑在 store 旁边，自身从不点名任何可配置插件。打开的是哪一页是页面本地状态：卡片、某个组合包、某个官方插件，或组合包的某一行。注册与做出它的浏览器半侧同生共死。`dsh-client-modules` 只把一个包的浏览器半侧挂在说明符恰为包名的那一行 Loader 行上，所以组合包为自己或任一行注册的页面，都会在那一行被关闭时一起消失；需要在其他行关闭时仍保留页面的子插件，应作为独立的包发布。
+页面的 `main` 注册把 `plugins.item`、`plugins.bundle.config` 与 `plugins.row.config` 声明为子 slot，因此它们与页面同生，注册方的 `ctx.slots.inject` 会等到它们出现。`configLedgerSource` 把三份账本投影成一个可观察对象——按账本顺序排列、标签按当前语言解析的官方条目，以及组合包与行的键——在账本或语言变化前保持缓存；页面把它作为 `useConfigLedger` 绑在 store 旁边，自身从不点名任何可配置插件。打开的是哪一页是页面本地状态：卡片、某个组合包、某个官方插件，或组合包的某一行。注册与做出它的浏览器半侧同生共死。`dsh-client-modules` 只把一个包的浏览器半侧挂在说明符恰为包名的那一行 Loader 行上，所以组合包为自己或任一行注册的页面，都会在那一行被关闭时一起消失；需要在其他行关闭时仍保留页面的子插件，应作为独立的包发布。 名称以 `@deepseek-ai/dsh-experimental-` 开头的官方包显示 Beta 标记。
+
+`plugins.bundle.config` 以 npm 包名为 key，提供 Bundle 详情配置。`plugins.bundle.activation` 在用户从列表显式启用后提供 Bundle 自有引导，并传入关闭引导和打开详情的回调。仅列出已启用的 Bundle 不会触发引导。
 
 </details>
 
diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
index 96286b3b16..a5f1da6197 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css
@@ -202,6 +202,10 @@
   color: var(--dsw-alias-label-secondary);
 }
 
+.packageImage {
+  object-fit: contain;
+}
+
 .cardMain {
   flex: 1;
   min-width: 0;
@@ -1112,13 +1116,13 @@ label.registryOption {
   line-height: 22px;
 }
 
-/* The package name under the title: the exact spec that installs the package
-   elsewhere, where a title of its own or a shortened name hides it. */
+/* The package or row identity under the title: the exact spec that installs the
+   package elsewhere, where a title of its own or a shortened name hides it. */
 .detailName {
   margin: 0;
   font-size: 12px;
   line-height: 18px;
-  color: var(--dsw-alias-label-caption);
+  color: var(--dsw-alias-label-tertiary);
   overflow-wrap: anywhere;
 }
 
diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx
index 5235d53cd0..dfa77f913c 100644
--- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx
+++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx
@@ -17,7 +17,7 @@ import {
   IconChevronRightOutlineRegular, IconCloseOutlineMedium,
   IconPlusOutlineRegular, IconRefreshOutlineRegular, IconTrashOutlineRegular,
   IconWarningOutlineRegular, Input, Modal,
-  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTeam, PluginArtworkTerminal,
+  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTerminal,
   StateDot, Switch, Tag, TerminalBlock, Toast, useAnchoredPosition, useDismissOnOutsidePointer,
   type IconProps, type StateDotState, type TerminalBlockLabels,
 } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -37,7 +37,7 @@ import css from './PluginManagerPage.module.css'
 export type PluginManagerPageProps =
   PropsRuntime<'main'>
   & PropsLocale<'pluginManager'>
-  & PropsRenderSlots<'plugins.item' | 'plugins.bundle.config' | 'plugins.row.config'>
+  & PropsRenderSlots<'plugins.item' | 'plugins.bundle.config' | 'plugins.row.config' | 'plugins.bundle.activation'>
   & InjectFace<PluginManagerFace>
 
 /** The page's slot renderer, narrowed to the configuration slots. */
@@ -130,21 +130,23 @@ const ITEM_ARTWORK = new Map<string, (props: IconProps) => ReactNode>([
   ['web-search', PluginArtworkSearch],
 ])
 
-/** The artwork of the official bundles with artwork of their own, by package name. */
-const PACKAGE_ARTWORK = new Map<string, (props: IconProps) => ReactNode>([
-  ['@deepseek-ai/dsh-experimental-agent-team-profile', PluginArtworkTeam],
-])
-
 /** An official plugin's card and page artwork; plugins without their own get the default. */
 function itemArtwork(id: string): ReactNode {
   const Artwork = ITEM_ARTWORK.get(id) ?? PluginArtworkDefault
   return <Artwork size={CARD_ARTWORK_SIZE} />
 }
 
-/** A package's card and page artwork; packages without their own get the default. */
-function packageArtwork(name: string): ReactNode {
-  const Artwork = PACKAGE_ARTWORK.get(name) ?? PluginArtworkDefault
-  return <Artwork size={CARD_ARTWORK_SIZE} />
+/** Manifest images remain isolated from the page DOM; a failed decode keeps the position's default artwork. */
+function PackageArtwork({ src, row = false, size = row ? ROW_ARTWORK_SIZE : CARD_ARTWORK_SIZE }: {
+  readonly src: string | undefined
+  readonly row?: boolean
+  readonly size?: number
+}): ReactNode {
+  const [failedSource, setFailedSource] = useState<string>()
+  const Fallback = row ? PluginArtworkSubagent : PluginArtworkDefault
+  return src === undefined || src === failedSource
+    ? <Fallback size={size} />
+    : <img className={css.packageImage} src={src} width={size} height={size} alt="" onError={() => { setFailedSource(src) }} />
 }
 
 /** A row's switch: locked, saying why, when the Host refuses to address the row through the profile patch. */
@@ -234,7 +236,7 @@ function RowsSection({ rows, t, resolveText, toggle, configure }: {
                 {...row.phase === 'failed' ? { 'data-state': 'failed' } : row.enabled ? {} : { 'data-state': 'off' }}
               >
                 <div className={css.rowLine}>
-                  <span className={css.rowIcon} aria-hidden="true"><PluginArtworkSubagent size={ROW_ARTWORK_SIZE} /></span>
+                  <span className={css.rowIcon} aria-hidden="true"><PackageArtwork key={row.meta?.icon} src={row.meta?.icon} row /></span>
                   <div className={css.rowMain}>
                     {configure?.has(row) === true
                       ? (
@@ -367,7 +369,7 @@ function PackageCard({ pkg, t, resolveText, busy, highlighted, onOpen, onSetEnab
         title={title}
         t={t}
         onOpen={onOpen}
-        icon={packageArtwork(pkg.name)}
+        icon={<PackageArtwork key={pkg.meta?.icon} src={pkg.meta?.icon} />}
         tags={(
           <>
             {beta ? <Tag className={css.statusTag} tone="info">{t('statusBeta')}</Tag> : null}
@@ -439,7 +441,7 @@ function RowDetail({ pkg, row, t, resolveText, onBack, renderSlot }: {
   const key = rowConfigKey(pkg.name, row.rowId)
   return (
     <div className={css.detail} data-plugin-row-detail={key}>
-      <DetailTop crumbLabel={t('backToPackage', { name: title })} crumbText={title} onBack={onBack} icon={<PluginArtworkSubagent size={CARD_ARTWORK_SIZE} />} />
+      <DetailTop crumbLabel={t('backToPackage', { name: title })} crumbText={title} onBack={onBack} icon={<PackageArtwork key={row.meta?.icon} src={row.meta?.icon} row size={CARD_ARTWORK_SIZE} />} />
       <div className={css.detailMain}>
         <div className={css.titleRow}>
           <h3 className={css.detailTitle}>{rowTitle}</h3>
@@ -491,7 +493,7 @@ function PackageDetail({
         crumbLabel={t('backToList')}
         crumbText={t('crumbRoot')}
         onBack={onBack}
-        icon={packageArtwork(pkg.name)}
+        icon={<PackageArtwork key={pkg.meta?.icon} src={pkg.meta?.icon} />}
         actions={(
           <div className={css.detailActions}>
             {pkg.installed
@@ -1070,6 +1072,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
   const ledger = props.useConfigLedger(snapshot => snapshot)
   // What is open; a package that leaves the list (uninstalled) drops back to the cards.
   const [view, setView] = useState<View>({ kind: 'list' })
+  const [activation, setActivation] = useState<string | null>(null)
   useEffect(() => { ensure() }, [ensure])
   // A package an install just enabled: scroll it into view and mark it for a moment.
   const { highlight, clearHighlight } = { highlight: state.highlight, clearHighlight: props.clearHighlight }
@@ -1094,6 +1097,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
   const openItem = view.kind === 'item' ? ledger.items.find(item => item.id === view.id) : undefined
   const openRow = view.kind === 'row' && openPkg !== undefined ? openPkg.rows.find(row => row.rowId === view.rowId) : undefined
   const showsCards = openPkg === undefined && openItem === undefined
+  const activated = listed.find(pkg => pkg.name === activation && pkg.enabled && !state.busy.includes(pkg.name))
   const setRowEnabled = (row: PackageRow, enabled: boolean): void => {
     /* v8 ignore next -- a row without a live entry has its switch disabled */
     if (row.entryId !== undefined) props.setRowEnabled(row.entryId, enabled)
@@ -1110,8 +1114,8 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
       resolveText={resolveText}
       busy={state.busy.includes(pkg.name)}
       highlighted={state.highlight === pkg.name}
-      onOpen={() => { setView({ kind: 'package', name: pkg.name }) }}
-      onSetEnabled={(enabled) => { props.setEnabled(pkg.name, enabled) }}
+      onOpen={() => { setActivation(null); setView({ kind: 'package', name: pkg.name }) }}
+      onSetEnabled={(enabled) => { setActivation(enabled ? pkg.name : null); props.setEnabled(pkg.name, enabled) }}
     />
   )
   // The Official group: the bundles the installation ships, then the plugins that registered their configuration.
@@ -1240,6 +1244,12 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
             </>
           )
         : null}
+      {showsCards && activated !== undefined && !state.install.open
+        ? renderSlot('plugins.bundle.activation', {
+          packageName: activated.name,
+          onDismiss: () => { setActivation(null) },
+          onOpenDetails: () => { setActivation(null); setView({ kind: 'package', name: activated.name }) },
+        }, { entryKey: activated.name }) : null}
       <InstallDialog
         install={state.install}
         t={t}
@@ -1249,7 +1259,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode {
         onCancel={props.cancelInstall}
         onReconcile={props.reconcileInstall}
         onToggleDetails={props.toggleInstallDetails}
-        onEnableNow={props.enableInstalled}
+        onEnableNow={() => { setActivation(state.install.installed); props.enableInstalled() }}
         onApproveBuilds={props.approveBuildsAndRetry}
         onToggleRegistry={props.toggleRegistryOptions}
         onChooseRegistry={props.chooseRegistry}
diff --git a/packages/client/ui-plugin-manager/src/client/index.ts b/packages/client/ui-plugin-manager/src/client/index.ts
index f3394b69cc..e0f9e1ea26 100644
--- a/packages/client/ui-plugin-manager/src/client/index.ts
+++ b/packages/client/ui-plugin-manager/src/client/index.ts
@@ -31,7 +31,7 @@ export type { PluginManagerPageProps } from './PluginManagerPage.tsx'
 export type { ConfigLedger, OfficialItem } from './config-ledger.ts'
 export type { PluginManagerFace } from './manager-store.ts'
 export type { PluginManagerLocaleKey } from './locales.ts'
-export type { PluginConfigViewProps } from './slot-contract.ts'
+export type { PluginConfigViewProps, PluginActivationOwnerProps } from './slot-contract.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
@@ -87,6 +87,7 @@ export function apply(ctx: ClientContext): void {
     inject: () => controller.inject(configLedger, text => ctx.locale.resolveText(text)),
     children: {
       'plugins.item': { kind: 'list', scope: 'root' },
+      'plugins.bundle.activation': { kind: 'keyed', scope: 'root' },
       'plugins.bundle.config': { kind: 'keyed', scope: 'root' },
       'plugins.row.config': { kind: 'keyed', scope: 'root' },
     },
diff --git a/packages/client/ui-plugin-manager/src/client/presentation.ts b/packages/client/ui-plugin-manager/src/client/presentation.ts
index c76633ff97..b5f004b0ac 100644
--- a/packages/client/ui-plugin-manager/src/client/presentation.ts
+++ b/packages/client/ui-plugin-manager/src/client/presentation.ts
@@ -8,12 +8,6 @@ import type { FailedAction, ManagerNotice, PackageRow, PackageView, PluginManage
 /** The translate seat of the manager's dictionary. */
 export type Translate = PropsLocale<'pluginManager'>['t']
 
-/** Official packages whose release status the page identifies as beta. */
-const BETA_PACKAGES = new Set([
-  '@deepseek-ai/dsh-experimental-agent-team-profile',
-  '@deepseek-ai/dsh-experimental-auto-review',
-])
-
 /** The registries with a name of their own, by host. */
 const REGISTRY_COPY = new Map<string, PluginManagerLocaleKey>([
   ['registry.npmmirror.com', 'registryNpmmirror'],
@@ -105,7 +99,7 @@ export function packageText(
   return {
     title: pkg.meta?.title === undefined ? pkg.name : resolveText(pkg.meta.title),
     description: pkg.meta?.description === undefined ? undefined : resolveText(pkg.meta.description) || undefined,
-    beta: BETA_PACKAGES.has(pkg.name),
+    beta: pkg.name.startsWith('@deepseek-ai/dsh-experimental-'),
   }
 }
 
diff --git a/packages/client/ui-plugin-manager/src/client/slot-contract.ts b/packages/client/ui-plugin-manager/src/client/slot-contract.ts
index 89a9b52115..4f291b865f 100644
--- a/packages/client/ui-plugin-manager/src/client/slot-contract.ts
+++ b/packages/client/ui-plugin-manager/src/client/slot-contract.ts
@@ -19,8 +19,19 @@ export interface PluginConfigViewProps {
   readonly view: 'summary' | 'page'
 }
 
+/** One user-requested bundle activation and navigation to its configuration page. */
+export interface PluginActivationOwnerProps {
+  readonly packageName: string
+  /** Dismiss guidance for this activation. */
+  readonly onDismiss: () => void
+  /** Dismiss guidance and open this bundle's detail page. */
+  readonly onOpenDetails: () => void
+}
+
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
+    /** Optional guidance after the user enables a bundle from the list, keyed by npm package name. */
+    'plugins.bundle.activation': { kind: 'keyed'; scope: 'root'; owner: PluginActivationOwnerProps }
     /**
      * One official plugin the Plugins page lists in its Official group after
      * the official bundles: `label` is the card's title and `order` its place.
diff --git a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
index 2226aa0476..89bf43e9b0 100644
--- a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
+++ b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx
@@ -12,6 +12,7 @@ import type { PluginManagerPageProps } from '../src/client/index.ts'
 import type { ConfigLedger } from '../src/client/config-ledger.ts'
 import { rowKey, type InstallState, type PackageRow, type PackageView, type PluginManagerState } from '../src/client/manager-store.ts'
 import { en, zh, type PluginManagerLocaleKey } from '../src/client/locales.ts'
+import type { PluginActivationOwnerProps } from '../src/client/slot-contract.ts'
 
 afterEach(cleanup)
 
@@ -66,7 +67,7 @@ const READY: PluginManagerState = {
 }
 
 /** Configuration entries a test supplies: what each slot cell renders, by `<slot>:<cell>` and the view asked for. */
-type SlotBodies = Record<string, (view: 'summary' | 'page') => ReactNode>
+type SlotBodies = Record<string, (view: 'summary' | 'page' | 'activation', owner: unknown) => ReactNode>
 
 const NO_CONFIG: ConfigLedger = { items: [], bundles: new Set(), rows: new Set() }
 
@@ -101,20 +102,32 @@ function renderTab(state: Partial<PluginManagerState> = {}, config: Partial<Conf
     setRowEnabled: vi.fn(),
     dismissNotice: vi.fn(),
   }
-  const renderSlot: PluginManagerPageProps['renderSlot'] = (name, owner, opts) => {
-    if (!('view' in owner) || (owner.view !== 'summary' && owner.view !== 'page')) {
-      throw new Error('Configuration slot requires a summary or page view')
-    }
-    return bodies[`${name}:${opts?.only ?? opts?.entryKey ?? ''}`]?.(owner.view) ?? null
+  const unusedStandardHook = (): never => { throw new Error('Plugin manager fixture does not provide global state') }
+  const standard = {
+    usePanelInfo: unusedStandardHook,
+    useWorkspaces: unusedStandardHook,
+    useSessions: unusedStandardHook,
+    useSessionStatus: unusedStandardHook,
+    useSessionRetainInfo: unusedStandardHook,
+    useResource: unusedStandardHook,
   }
-  const props = {
+  const props: PluginManagerPageProps = {
+    ...standard,
     t,
     resolveText,
     ...actions,
     usePluginManager: bindSnapshotSelector(store),
     useConfigLedger: bindSnapshotSelector(ledger),
-    renderSlot,
-  } as PluginManagerPageProps
+    renderSlot: (name, owner, opts) => {
+      const body = bodies[`${name}:${opts?.only ?? opts?.entryKey ?? ''}`]
+      if (body === undefined) return null
+      if (name === 'plugins.bundle.activation') return body('activation', owner)
+      if (!('view' in owner) || (owner.view !== 'summary' && owner.view !== 'page')) {
+        throw new Error('Plugin configuration fixture requires a summary or page view')
+      }
+      return body(owner.view, owner)
+    },
+  }
   const { rerender } = render(<PluginManagerPage {...props} />)
   return {
     store,
@@ -245,6 +258,7 @@ describe('PluginManagerPage', () => {
   it.each([
     '@deepseek-ai/dsh-experimental-agent-team-profile',
     '@deepseek-ai/dsh-experimental-auto-review',
+    '@deepseek-ai/dsh-experimental-fixture-input',
     '@acme/dsh-local-tools',
   ])('localizes Host metadata for %s across cards, details, switches, and uninstall confirmation', (name) => {
     const meta = {
@@ -261,6 +275,7 @@ describe('PluginManagerPage', () => {
       expect(document.getElementById(card.getAttribute('aria-describedby')!)?.textContent).toBe(description(dict))
       expect(screen.getByRole('switch', { name: dict.enableToggle.replace('{name}', title(dict)) })).toBeTruthy()
       expect(screen.queryByText('Original metadata.')).toBeNull()
+      expect(screen.queryByText(dict.statusBeta) !== null).toBe(name.startsWith('@deepseek-ai/dsh-experimental-'))
     }
     assertCard(en)
     setLanguage(zh)
@@ -285,6 +300,38 @@ describe('PluginManagerPage', () => {
     }
   })
 
+  it('renders manifest icons for arbitrary bundles and rows, with decode fallback and source recovery', () => {
+    const icon = 'data:image/svg+xml;base64,PHN2Zy8+'
+    const updatedIcon = 'data:image/png;base64,cG5n'
+    const bundle = pkg({ meta: { icon }, rows: [row({ meta: { icon } }), row({ entryId: 'plain' as PluginEntryId, rowId: 'plain', moduleName: 'plain' })] })
+    const { set } = renderTab({ packages: [bundle] }, { rows: new Set(['dsh-better-sidebar#sidebar']) })
+    const image = () => document.querySelector<HTMLImageElement>('[data-plugin-package] img, [data-plugin-detail] img')!
+    expect(image().getAttribute('src')).toBe(icon)
+    expect(image().getAttribute('alt')).toBe('')
+    expect(image().width).toBe(36)
+    fireEvent.error(image())
+    expect(document.querySelector('[data-plugin-package] img')).toBeNull()
+    expect(document.querySelector('[data-plugin-package] svg')).not.toBeNull()
+    set({ packages: [{ ...bundle, meta: { icon: updatedIcon } }] })
+    expect(image().getAttribute('src')).toBe(updatedIcon)
+    set({ packages: [bundle] })
+    expect(image().getAttribute('src')).toBe(icon)
+    fireEvent.click(screen.getByRole('button', { name: 'View dsh-better-sidebar' }))
+    expect(image().getAttribute('src')).toBe(icon)
+    const rowImage = document.querySelector<HTMLImageElement>('[data-plugin-row] img')!
+    expect(rowImage.getAttribute('src')).toBe(icon)
+    expect(rowImage.width).toBe(30)
+    expect(document.querySelector('[data-plugin-row="plain"] img')).toBeNull()
+    expect(document.querySelector('[data-plugin-row="plain"] svg')).not.toBeNull()
+    fireEvent.error(rowImage)
+    expect(document.querySelector('[data-plugin-row] img')).toBeNull()
+    expect(document.querySelector('[data-plugin-row] svg')).not.toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: 'Configure dsh-better-sidebar' }))
+    const detailImage = document.querySelector<HTMLImageElement>('[data-plugin-row-detail] img')!
+    expect(detailImage.getAttribute('src')).toBe(icon)
+    expect(detailImage.width).toBe(36)
+  })
+
   it('shows metadata diagnostics without blocking management or displaying legacy descriptions', () => {
     const error = 'locale/zh.json: invalid title'
     const { actions, set, setLanguage } = renderTab({
@@ -1150,3 +1197,41 @@ describe('PluginManagerPage', () => {
     expect(actions.closeInstall).toHaveBeenCalledOnce()
   })
 })
+
+it('offers bundle-owned guidance only after explicit enablement and navigates to its detail page', () => {
+  const name = 'dsh-better-sidebar'
+  const { set, actions } = renderTab({ packages: [pkg({ enabled: false })] }, { bundles: new Set([name]) }, {
+    [`plugins.bundle.activation:${name}`]: (_view, owner) => <button onClick={(owner as PluginActivationOwnerProps).onOpenDetails}>Go to setup</button>,
+    [`plugins.bundle.config:${name}`]: () => <div>Bundle setup</div>,
+  })
+  expect(screen.queryByText('Go to setup')).toBeNull()
+  set({ packages: [pkg()] })
+  expect(screen.queryByText('Go to setup')).toBeNull()
+  set({ packages: [pkg({ enabled: false })] })
+  fireEvent.click(screen.getByRole('switch'))
+  expect(actions.setEnabled).toHaveBeenCalledWith(name, true)
+  expect(screen.queryByText('Go to setup')).toBeNull()
+  set({ packages: [pkg()], busy: [name] })
+  expect(screen.queryByText('Go to setup')).toBeNull()
+  set({ busy: [] })
+  fireEvent.click(screen.getByText('Go to setup'))
+  expect(screen.getByText('Bundle setup')).toBeTruthy()
+  expect(screen.queryByText('Go to setup')).toBeNull()
+})
+
+it('dismisses activation guidance until the user enables the bundle again', () => {
+  const name = 'dsh-better-sidebar'
+  const { set } = renderTab({ packages: [pkg({ enabled: false })] }, {}, {
+    [`plugins.bundle.activation:${name}`]: (_view, owner) => <button onClick={(owner as PluginActivationOwnerProps).onDismiss}>Later</button>,
+  })
+  fireEvent.click(screen.getByRole('switch'))
+  set({ packages: [pkg()] })
+  fireEvent.click(screen.getByText('Later'))
+  set({ packages: [pkg()] })
+  expect(screen.queryByText('Later')).toBeNull()
+  fireEvent.click(screen.getByRole('switch'))
+  set({ packages: [pkg({ enabled: false })] })
+  fireEvent.click(screen.getByRole('switch'))
+  set({ packages: [pkg()] })
+  expect(screen.getByText('Later')).toBeTruthy()
+})
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index d8df0b30d6..0c55515d7e 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
-README.md: 51ad53a79a676f013b61213764479a1247de522c
-README.zh.md: c41d19af1855c8ab1582fa92b956ef283d3466cf
+README.md: 292f1cc817d30837e36ced9adeee3d226852f4a5
+README.zh.md: c61ecb0cba1237d8fbf0e4d22333f5e21724c9fa
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 51ad53a79a..292f1cc817 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -38,18 +38,20 @@ Check this table before writing a control in a feature package. A plugin cannot
 |---|---|
 | `Button` | Clickable action; `variant` selects `primary`, `ghost`, `outline`, or `toolbar`. |
 | `Switch` | Two-state toggle, 36×20. `label` is required, so the control cannot ship unnamed. |
+| `SegmentedControl` | Tablist of two or more equal-width segments with one sliding indicator, for switching a card or panel between a few modes; the owner holds the selection and `label` names the list. `id` seeds each tab's id (`<id>-<value>`) and the panel it controls (`<id>-<value>-panel`), which the owner renders and points back at the tab with `aria-labelledby`; a segment may be `disabled` with a `title`, and `disabled` on the control locks every segment while the shown panel has work in flight. |
 | `Checkbox` | Labeled native checkbox with controlled state, keyboard interaction, and disabled styling; the caller supplies localized `label` text. |
 | `Input` | Single-line text entry for search boxes and inline forms. |
 | `Menu`, `MenuItemButton` | Dropdown of `items` data rows, separators, and group labels, with nested submenus; `children` adds component rows, each a `MenuItemButton` (`separatorBefore` starts a new group), in the same list. Every row shares the styling, the keyboard walk, and the focus return; closing stays the owner's state change for both kinds. While open, ↑/↓ (with Home and End) walk the list, Tab settles the focused row, and Escape or Shift+Tab close back to the anchor; selecting a row also returns the keyboard to the anchor unless the owner moved it itself. Only a keyboard on the anchor or inside the list is intercepted, and `autoFocus` decides solely whether opening focuses the first row. |
 | `Pill` | Selectable capsule button for view switchers and filters; takes `active` and `onClick`. |
+| `SegmentedTabs` | Controlled equal-width tabs with a sliding indicator and Left/Right, Home, and End navigation. The caller supplies labels, tab/panel ids, and panel content. |
 | `Tag` | Read-only capsule badge; `tone` selects one of eight palettes. |
-| `StateDot` | Solid green `done`, amber `warning`, red `error`, and neutral-grey `idle` marks in a 10px slot, plus a tertiary-grey 14px rotating `ongoing` loader. `aria-hidden`, so the render site owns the name. |
+| `StateDot` | Solid green `done`, amber `warning`, red `error`, and neutral-grey `idle` marks in a 10px slot, plus a tertiary-grey 14px rotating `ongoing` loader whose animations pin to document time zero so every visible loader rotates in phase. `aria-hidden`, so the render site owns the name. `appearance="step"` shows a filled check for completion and a hollow pending circle. |
 | `ConnectionIndicator` | Inline connection-recovery control across outage, retry, and recovered states. |
-| `DisclosureRow` | 24px compact disclosure that lays title and content side by side. |
+| `DisclosureRow` | 24px compact disclosure that lays title and content side by side. Memoized with shallow prop comparison; keep callbacks and React-node props stable when their content is unchanged. |
 | `Modal` | Centered dialog over a page mask. |
 | `RiskConfirmation` | Sensitive action gated behind an explicit checkbox. |
 | `OnboardingSurface` | First-run stage that holds the application root inert. |
-| `Tooltip` | Hover text on a cloned anchor, placed right, bottom, or top. |
+| `Tooltip` | Hover text anchored to a cloned child; optional `portal` rendering escapes clipping containers. |
 | `HoverCard` | Hover preview the pointer can rest on and select from; optional copy button. |
 | `Toast` | Transient top-center banner held for the owner's `holdMs`. |
 | `JsonTree`, `JsonBlock` | Read-only JSON inspection. |
@@ -57,13 +59,14 @@ Check this table before writing a control in a feature package. A plugin cannot
 | `TerminalBlock`, `ReadBlock`, `DiffBlock`, `SearchBlock`, `WebBlock` | The agent-output card matching each tool-result intent. |
 | `icons/*`, `FishLogo`, `BrandWordmark`, `ReferenceIconRegular`/`ReferenceIconMedium`, `LinkIconRegular`/`LinkIconMedium` | Glyphs and brand marks. Use `LinkIconMedium` for 14px clickable-link categories and known-site marks. |
 | `PermissionIconReadOnlyRegular`/`Medium`, `PermissionIconWorkspaceWriteRegular`/`Medium`, `PermissionIconFullAccessRegular`/`Medium` | Permission-mode glyphs for read-only, workspace-write, and full-access choices. |
-| `PluginArtworkTeam`/`Terminal`/`Loop`/`Subagent`/`Search`/`Default` | Fixed-palette 36×36 plugin artwork for the plugin-management surfaces; `Default` marks plugins without artwork of their own. Def ids are per-instance, so the same artwork repeats safely on one page. |
+| `PluginArtworkTerminal`/`Loop`/`Subagent`/`Search`/`Default` | Fixed-palette 36×36 plugin artwork for the plugin-management surfaces; `Default` marks plugins without artwork of their own. Def ids are per-instance, so the same artwork repeats safely on one page. |
 | `FileTypeIcon`, `classifyFileType`, `fileExtension` | A category-colored 28px file or folder glyph and the shared case-insensitive filename mapping behind it. Code and configuration files use detailed full-color technology glyphs; use `LinkIconMedium` for link-leading glyphs and image previews for image content. |
 | `languageForPath`, `CODE_HIGHLIGHT_EXTENSIONS`, `useCodeHighlighter` | The filename grammar selection and lazy line-token highlighter shared by code preview and diff review. |
 
-Three pairs are easy to confuse:
+Four pairs are easy to confuse:
 
 - **`Tag` against `Pill`.** Reach for `Tag` for a read-only badge at the 11px capsule size, and for `Pill` when the capsule is selectable (`active` and `onClick`, as view switchers and filters use) or when it must sit on a 24px text line — `TerminalBlock` renders its exit status as a static `Pill` for exactly that reason. Size decides as much as interactivity here; the two are not interchangeable.
+- **`Pill` against `SegmentedControl`.** A row of `Pill`s is a set of independent chips — each one toggles on its own, and several may be active. `SegmentedControl` is one choice among a few mutually exclusive modes, drawn as a tablist with one indicator, and it comes with the tab keyboard pattern (arrow keys walk the segments, only the selected one is in the tab sequence); the Models settings add card switches its two forms with it.
 - **`DisclosureRow` against a card.** The row lays its title and content side by side at a fixed 24px. A card that stacks a name over a description is a different layout, and belongs in the feature package — `ui-settings-plugins`' `PluginCard` is the precedent and records why.
 - **`FoldToggle` against the exported surface.** It is package-internal and not exported; the output cards use it for their head-tail fold.
 
@@ -119,7 +122,7 @@ While a reply streams, `MarkdownText` parses incrementally: all but the trailing
 
 ### Geometry and overflow
 
-The output cards share one geometry model: `white-space: pre` with horizontal scrolling so column-aligned content keeps its alignment, and a head-plus-tail slice behind an expand button past `maxLines` (default 16) so a long body never stretches the card. `TerminalBlock` parses ANSI into React spans with a per-line column buffer for cursor movement, honoring erase-in-line, tab stops, and character width.
+The output cards share one geometry model: `white-space: pre` with horizontal scrolling so column-aligned content keeps its alignment, and a head-plus-tail slice behind an expand button past `maxLines` (default 16) so a long body never stretches the card. `TerminalBlock` parses ANSI into React spans with a per-line column buffer for cursor movement, honoring erase-in-line, tab stops, and character width. Hosts opt out of the shared geometry per surface: rebinding `--dsl-terminal-command-whitespace` / `--dsl-terminal-line-whitespace` to `pre-wrap` wraps commands and output in full with no sideways scroll, `maxLines: Infinity` disables the fold for hosts capping height through `--dsl-terminal-output-max-height` instead, `copyText` overrides the copy payload (and keeps the control rendered before any output), and `runStateDot: false` omits the run-state dot when the surrounding row already carries the state, reclaiming its gutter via `--dsl-terminal-gutter`. The banner divider follows the rendered body, so a running card that streams live output separates its command from the text like a settled card.
 
 </details>
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index c41d19af18..c61ecb0cba 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -38,18 +38,20 @@ kind: "package-library"
 |---|---|
 | `Button` | 可点击操作；`variant` 选择 `primary`、`ghost`、`outline` 或 `toolbar`。 |
 | `Switch` | 36×20 的双态开关。`label` 必填，控件不可能在没有名称的情况下发布。 |
+| `SegmentedControl` | 两段或更多等宽分段加一个滑动指示块的 tablist，用于在几种模式间切换一张卡片或面板；选中项由调用方持有，`label` 为列表命名。`id` 派生每个 tab 的 id（`<id>-<value>`）及其控制的面板 id（`<id>-<value>-panel`），面板由调用方渲染并用 `aria-labelledby` 指回 tab；分段可 `disabled` 并带 `title`，控件级 `disabled` 在当前面板有进行中的操作时锁住全部分段。 |
 | `Checkbox` | 带标签的原生复选框，支持受控状态、键盘交互和禁用样式；调用方提供本地化的 `label` 文本。 |
 | `Input` | 单行文本输入，用于搜索框与行内表单。 |
 | `Menu`, `MenuItemButton` | 由 `items` 数据行、分隔线与分组标题构成的下拉菜单，支持嵌套子菜单；`children` 在同一列表中加入组件行，每行一个 `MenuItemButton`（`separatorBefore` 开启新分组）。所有行共享样式、键盘走位与焦点归还；两类行的关闭都是 owner 状态的改变。打开期间 `↑`／`↓`（以及 Home、End）在列表中走位，Tab 选定聚焦行，Escape 或 Shift+Tab 关闭并把焦点还给锚点；选定一行同样把键盘还给锚点——除非拥有者自己移动了焦点。只拦截位于锚点或列表内的键盘，`autoFocus` 仅决定打开时是否聚焦首行。 |
 | `Pill` | 可选中的胶囊按钮，用于视图切换与筛选器；接受 `active` 与 `onClick`。 |
+| `SegmentedTabs` | 受控的等宽分段标签，支持滑动指示条及左／右方向键、Home、End 导航。调用方提供文案、标签与面板 id，以及面板内容。 |
 | `Tag` | 只读胶囊徽章；`tone` 选择八种配色之一。 |
-| `StateDot` | 10px 槽内的绿色 `done`、琥珀色 `warning`、红色 `error`、中性灰色 `idle` 圆点，以及 tertiary 灰色 14px 旋转 `ongoing` loading。它是 `aria-hidden` 的，名称由渲染点提供。 |
+| `StateDot` | 10px 槽内的绿色 `done`、琥珀色 `warning`、红色 `error`、中性灰色 `idle` 圆点，以及 tertiary 灰色 14px 旋转 `ongoing` loading，其动画固定到文档时间零点，所以所有可见 loading 同相旋转。它是 `aria-hidden` 的，名称由渲染点提供。 `appearance="step"` 以实心勾表示完成、空心圆表示等待。 |
 | `ConnectionIndicator` | 行内连接恢复控件，覆盖断线、重试与已恢复三种状态。 |
-| `DisclosureRow` | 24px 紧凑折叠行，标题与内容左右排列。 |
+| `DisclosureRow` | 24px 紧凑折叠行，标题与内容左右排列。使用浅层 prop 比较进行 memo；内容未变时，保持回调与 React 节点 prop 的引用稳定。 |
 | `Modal` | 页面遮罩之上的居中对话框。 |
 | `RiskConfirmation` | 以显式复选框把关的敏感操作确认。 |
 | `OnboardingSurface` | 首次运行的引导舞台，期间保持应用根节点 inert。 |
-| `Tooltip` | 克隆锚点上的悬停文本，可置于右、下、上三个方向。 |
+| `Tooltip` | 锚定在克隆子元素上的悬停文本；可通过 `portal` 渲染到外层，避免被容器裁剪。 |
 | `HoverCard` | 指针可停留、可选中的悬停预览；可选带复制按钮。 |
 | `Toast` | 顶部居中的瞬时横幅，保持时长由所有者的 `holdMs` 决定。 |
 | `JsonTree`、`JsonBlock` | 只读 JSON 查看。 |
@@ -57,13 +59,14 @@ kind: "package-library"
 | `TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock`、`WebBlock` | 与各类工具结果意图对应的 agent 输出卡片。 |
 | `icons/*`、`FishLogo`、`BrandWordmark`、`ReferenceIconRegular`/`ReferenceIconMedium`、`LinkIconRegular`/`LinkIconMedium` | 字形与品牌标识。`LinkIconMedium` 用于 14px 的可点击链接分类及已知站点标记。 |
 | `PermissionIconReadOnlyRegular`/`Medium`、`PermissionIconWorkspaceWriteRegular`/`Medium`、`PermissionIconFullAccessRegular`/`Medium` | 只读、工作区写入与完全访问选项使用的权限模式图形。 |
-| `PluginArtworkTeam`/`Terminal`/`Loop`/`Subagent`/`Search`/`Default` | 插件管理界面使用的固定配色 36×36 插件插画；`Default` 用于没有自有插画的插件。def id 按实例生成，同一插画可在一页中安全重复。 |
+| `PluginArtworkTerminal`/`Loop`/`Subagent`/`Search`/`Default` | 插件管理界面使用的固定配色 36×36 插件插画；`Default` 用于没有自有插画的插件。def id 按实例生成，同一插画可在一页中安全重复。 |
 | `FileTypeIcon`、`classifyFileType`、`fileExtension` | 按类别着色的 28px 文件或文件夹图形，以及它背后共享的不区分大小写文件名映射。代码与配置文件使用细分的全彩技术图形；链接前置图形使用 `LinkIconMedium`，图片内容使用图片预览。 |
 | `languageForPath`、`CODE_HIGHLIGHT_EXTENSIONS`、`useCodeHighlighter` | 代码预览与 diff review 共用的文件名 grammar 选择和惰性逐行 token 高亮。 |
 
-有三组容易混淆：
+有四组容易混淆：
 
 - **`Tag` 与 `Pill`。** 11px 胶囊尺寸的只读徽章用 `Tag`；胶囊可选中（`active` 与 `onClick`，视图切换与筛选器就是这样用的），或者必须落在 24px 文本行上时用 `Pill`——`TerminalBlock` 把退出状态渲染成静态 `Pill` 正是后一种情况。这里尺寸和是否可交互同样是判据，两者不可互换。
+- **`Pill` 与 `SegmentedControl`。** 一排 `Pill` 是一组彼此独立的 chip——每个各自开关，可以同时激活多个。`SegmentedControl` 是在几种互斥模式中选一，画成带一个指示块的 tablist，并自带 tab 键盘模式（方向键在分段间移动，只有选中项在 Tab 序列里）；模型设置页的新增卡片就用它切换两张表单。
 - **`DisclosureRow` 与卡片。** 该行以固定 24px 把标题与内容左右排列。把名称叠在描述之上的卡片是另一种布局，属于功能包——`ui-settings-plugins` 的 `PluginCard` 是先例，并记录了原因。
 - **`FoldToggle` 与对外导出面。** 它是包内组件，未导出；输出卡片用它做头尾折叠。
 
@@ -119,7 +122,7 @@ kind: "package-library"
 
 ### 几何与溢出
 
-输出卡片共享同一套几何模型：`white-space: pre` 并横向滚动，让按列对齐的内容保持对齐；超过 `maxLines`（默认 16）时折叠为头部切片加尾部切片，由展开按钮控制，长正文不会撑高卡片。`TerminalBlock` 把 ANSI 解析为 React span，并带逐行列缓冲处理光标移动，遵循行内擦除、制表位与字符宽度。
+输出卡片共享同一套几何模型：`white-space: pre` 并横向滚动，让按列对齐的内容保持对齐；超过 `maxLines`（默认 16）时折叠为头部切片加尾部切片，由展开按钮控制，长正文不会撑高卡片。`TerminalBlock` 把 ANSI 解析为 React span，并带逐行列缓冲处理光标移动，遵循行内擦除、制表位与字符宽度。宿主可按表层选择退出共享几何：把 `--dsl-terminal-command-whitespace` / `--dsl-terminal-line-whitespace` 重绑为 `pre-wrap` 让命令与输出完整换行且不横向滚动；`maxLines: Infinity` 为改用 `--dsl-terminal-output-max-height` 限高滚动的宿主禁用折叠；`copyText` 覆盖复制载荷（并让控件在任何输出出现之前就保持渲染）；`runStateDot: false` 在外围行已携带同一状态时省去状态点，并经 `--dsl-terminal-gutter` 收回其落区。横幅分割线跟随渲染出的正文：正在流式输出的 running 卡片像已结束卡片一样把命令与文本分隔开。
 
 </details>
 
diff --git a/packages/client/ui-primitives/src/DisclosureRow.tsx b/packages/client/ui-primitives/src/DisclosureRow.tsx
index f79b7e4720..a4fa7a2124 100644
--- a/packages/client/ui-primitives/src/DisclosureRow.tsx
+++ b/packages/client/ui-primitives/src/DisclosureRow.tsx
@@ -1,6 +1,7 @@
-import { type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import { memo, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
-import { IconChevronDownOutlineRegular } from './icons/index.tsx'
+import { IconChevronDownOutlineRegular, IconChevronUpOutlineRegular } from './icons/index.tsx'
+import { TextShimmer } from './TextShimmer.tsx'
 import css from './DisclosureRow.module.css'
 
 /** Shared 24px disclosure chrome for compact flow rows. */
@@ -10,6 +11,8 @@ export interface DisclosureRowProps {
   open: boolean
   expandable: boolean
   onToggle: () => void
+  /** Animate the title while its owning operation is running. */
+  running?: boolean | undefined
   /** Makes the complete title row the disclosure target. */
   expandOnRowClick?: boolean | undefined
   /** Replaces the collapsed icon with a chevron while the row is hovered. */
@@ -27,15 +30,17 @@ export interface DisclosureRowProps {
 
 /**
  * Render one disclosure header and its controlled expanded content.
+ * Shallow prop comparison requires stable callbacks and React nodes to skip unchanged renders.
  * @param props - Visual content, controlled state, and interaction policy.
  * @returns the disclosure row.
  */
-export function DisclosureRow({
+export const DisclosureRow = memo(function DisclosureRow({
   icon,
   title,
   open,
   expandable,
   onToggle,
+  running = false,
   expandOnRowClick = false,
   previewChevron = expandable,
   keepContentWhenOpen = false,
@@ -66,7 +71,7 @@ export function DisclosureRow({
     )
     : icon
   const leading = open
-    ? <IconChevronDownOutlineRegular className={chevronClassName} />
+    ? <IconChevronUpOutlineRegular className={chevronClassName} />
     : collapsedLeading
 
   return (
@@ -95,10 +100,10 @@ export function DisclosureRow({
             {leading}
           </span>
         )}
-        <span className={clsx(css.title, titleClassName)}>{title}</span>
+        <TextShimmer className={clsx(css.title, titleClassName)} active={running}>{title}</TextShimmer>
         {(keepContentWhenOpen || !open) && collapsedContent}
       </div>
       {open && children}
     </div>
   )
-}
+})
diff --git a/packages/client/ui-primitives/src/SegmentedControl.module.css b/packages/client/ui-primitives/src/SegmentedControl.module.css
new file mode 100644
index 0000000000..a35b25edd4
--- /dev/null
+++ b/packages/client/ui-primitives/src/SegmentedControl.module.css
@@ -0,0 +1,76 @@
+/* The track is the same translucent fill the hover state uses, so it reads as
+ * a place rather than a second button; the one raised part is the indicator,
+ * a white pill that slides under the selected segment. Its stroke rides inside
+ * the soft elevation shadow (border: 0), the way every elevated surface draws
+ * its edge, so the elevation gate keeps it off the alias-border set.
+ *
+ * Segments are equal-width grid tracks sized to the widest label, which is
+ * what lets one indicator be placed arithmetically: the tablist carries the
+ * segment count and the selected index as custom properties, and the indicator
+ * derives its width and offset from them instead of measuring the DOM. */
+.control {
+  position: relative;
+  display: inline-grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+  gap: 2px;
+  padding: 3px;
+  border-radius: 9px;
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+.indicator {
+  position: absolute;
+  top: 3px;
+  left: 3px;
+  width: calc((100% - 6px - 2px * (var(--dsh-segment-count) - 1)) / var(--dsh-segment-count));
+  height: calc(100% - 6px);
+  border: 0;
+  border-radius: 7px;
+  background: var(--dsw-alias-bg-layer-1);
+  box-shadow: var(--dsw-elevation-soft);
+  transform: translateX(calc(var(--dsh-segment-index) * (100% + 2px)));
+  transition: transform 160ms ease;
+  pointer-events: none;
+}
+
+.tab {
+  box-sizing: border-box;
+  position: relative;
+  z-index: 1;
+  height: 28px;
+  padding: 0 16px;
+  border: 0;
+  border-radius: 7px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font: inherit;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: color 120ms ease;
+}
+
+.tab:hover:not(:disabled),
+.tab[aria-selected='true'] {
+  color: var(--dsw-alias-label-primary);
+}
+
+.tab:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.tab:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary);
+  outline-offset: -2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .indicator,
+  .tab {
+    transition: none;
+  }
+}
diff --git a/packages/client/ui-primitives/src/SegmentedControl.tsx b/packages/client/ui-primitives/src/SegmentedControl.tsx
new file mode 100644
index 0000000000..ffbe2a819e
--- /dev/null
+++ b/packages/client/ui-primitives/src/SegmentedControl.tsx
@@ -0,0 +1,140 @@
+// SegmentedControl: a tablist of two or more equal-width segments with one
+// sliding indicator, for switching a card or panel between a few modes. The
+// owner holds the selection; `label` is required so the tablist never ships
+// without an accessible name, and every segment label is owner-localized.
+// Each tab is `<id>-<value>` and controls the panel `<id>-<value>-panel`, the
+// element the owner renders for that mode and points back at the tab with
+// `aria-labelledby`.
+
+import { useEffect, useRef } from 'react'
+import type { CSSProperties, KeyboardEvent } from 'react'
+import clsx from 'clsx'
+import css from './SegmentedControl.module.css'
+
+/** One segment of a {@link SegmentedControl}. */
+export interface SegmentedControlOption<Value extends string> {
+  /** The value the owner receives when this segment is chosen. */
+  value: Value
+  /** Localized segment text. */
+  label: string
+  /** Whether the segment refuses selection. */
+  disabled?: boolean
+  /** Localized hover text, typically why the segment is locked. */
+  title?: string
+}
+
+/** The keys that walk the tablist, per the WAI-ARIA tabs pattern. */
+type WalkKey = 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown' | 'Home' | 'End'
+
+function isWalkKey(key: string): key is WalkKey {
+  return key === 'ArrowLeft' || key === 'ArrowRight' || key === 'ArrowUp' || key === 'ArrowDown'
+    || key === 'Home' || key === 'End'
+}
+
+/**
+ * The enabled option a walk key lands on from the selected one: arrows step
+ * to the nearest enabled neighbour and wrap, Home and End jump to the first
+ * and last enabled option.
+ */
+function walk<Value extends string>(
+  options: readonly SegmentedControlOption<Value>[],
+  from: number,
+  key: WalkKey,
+): SegmentedControlOption<Value> | undefined {
+  const enabled = options.filter(option => option.disabled !== true)
+  if (key === 'Home') return enabled[0]
+  if (key === 'End') return enabled[enabled.length - 1]
+  const step = key === 'ArrowRight' || key === 'ArrowDown' ? 1 : -1
+  const count = options.length
+  for (let offset = 1; offset < count; offset += 1) {
+    const candidate = options[((from + step * offset) % count + count) % count]
+    if (candidate !== undefined && candidate.disabled !== true) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Render a segmented control.
+ * @param props.id - the owner's base id: each tab is `<id>-<value>` and names
+ * `<id>-<value>-panel` as the panel it controls.
+ * @param props.value - the selected option's value; the control is fully controlled.
+ * @param props.options - the segments in display order; at least two.
+ * @param props.onChange - called with the value a click or a walk key asks for,
+ * never with the value already selected.
+ * @param props.label - localized accessible name of the tablist.
+ * @param props.disabled - lock every segment, typically while the shown panel
+ * has a write or a fetch in flight that switching would orphan.
+ * @param props.className - extra class for layout placement.
+ * @returns the tablist element.
+ */
+export function SegmentedControl<Value extends string>({
+  id, value, options, onChange, label, disabled = false, className,
+}: {
+  id: string
+  value: Value
+  options: readonly SegmentedControlOption<Value>[]
+  onChange: (next: Value) => void
+  label: string
+  disabled?: boolean
+  // `| undefined` so a caller can forward an optional class straight through
+  // under exactOptionalPropertyTypes (a CSS-module lookup is string|undefined).
+  className?: string | undefined
+}) {
+  const list = useRef<HTMLDivElement>(null)
+  const selected = options.findIndex(option => option.value === value)
+
+  // A walk key reports the next value and the owner re-renders with it; the
+  // keyboard then follows the selection so the roving tabindex stays usable.
+  useEffect(() => {
+    const root = list.current
+    /* v8 ignore next -- the ref is attached to the always-rendered root before any effect runs. */
+    if (root === null) return
+    if (!root.contains(document.activeElement)) return
+    root.querySelector<HTMLButtonElement>('[role="tab"][aria-selected="true"]')?.focus()
+  }, [value])
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>): void => {
+    if (!isWalkKey(event.key)) return
+    event.preventDefault()
+    const target = walk(options, selected, event.key)
+    if (target !== undefined && target.value !== value) onChange(target.value)
+  }
+
+  const indicator = {
+    '--dsh-segment-count': String(options.length),
+    '--dsh-segment-index': String(selected),
+  } as CSSProperties
+
+  return (
+    <div
+      ref={list}
+      role="tablist"
+      aria-label={label}
+      className={clsx(css.control, className)}
+      style={indicator}
+    >
+      <span aria-hidden="true" className={css.indicator} />
+      {options.map((option) => {
+        const active = option.value === value
+        return (
+          <button
+            key={option.value}
+            id={`${id}-${option.value}`}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            aria-controls={`${id}-${option.value}-panel`}
+            tabIndex={active ? 0 : -1}
+            disabled={disabled || option.disabled === true}
+            title={option.title}
+            className={css.tab}
+            onClick={() => { if (!active) onChange(option.value) }}
+            onKeyDown={onKeyDown}
+          >
+            {option.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
diff --git a/packages/client/ui-primitives/src/SegmentedTabs.module.css b/packages/client/ui-primitives/src/SegmentedTabs.module.css
new file mode 100644
index 0000000000..b16b597212
--- /dev/null
+++ b/packages/client/ui-primitives/src/SegmentedTabs.module.css
@@ -0,0 +1,55 @@
+.tabs {
+  position: relative;
+  display: grid;
+  padding: 4px;
+  border-radius: 12px;
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+.indicator {
+  position: absolute;
+  inset: 4px auto 4px 4px;
+  box-sizing: border-box;
+  border: 0.5px solid var(--dsw-alias-border-l3);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-3);
+  transition: transform 180ms ease;
+  pointer-events: none;
+}
+
+.tab {
+  position: relative;
+  justify-content: center;
+  height: 34px;
+  padding: 0 12px;
+  border-radius: 8px;
+  font-size: 14px;
+  line-height: 20px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  transition: color 180ms ease;
+}
+
+.tab:hover,
+.tab[aria-selected='true'] {
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+}
+
+.tab[aria-selected='true'] {
+  font-weight: 600;
+}
+
+.tab:focus-visible {
+  outline: none;
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 4px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .indicator,
+  .tab {
+    transition: none;
+  }
+}
diff --git a/packages/client/ui-primitives/src/SegmentedTabs.tsx b/packages/client/ui-primitives/src/SegmentedTabs.tsx
new file mode 100644
index 0000000000..2ae51be8d5
--- /dev/null
+++ b/packages/client/ui-primitives/src/SegmentedTabs.tsx
@@ -0,0 +1,81 @@
+import type { KeyboardEvent, ReactNode } from 'react'
+import clsx from 'clsx'
+import { Pill } from './Pill.tsx'
+import css from './SegmentedTabs.module.css'
+
+/** A tab links its localized label to a caller-owned panel. */
+export interface SegmentedTab<Value extends string = string> {
+  value: Value
+  label: ReactNode
+  id: string
+  panelId: string
+}
+
+/**
+ * Render equal-width, controlled tabs with a sliding selection indicator.
+ * @param props.items - non-empty ordered tabs with unique values and DOM ids.
+ * @param props.value - selected value, which must belong to items.
+ * @param props.onChange - selection requested by click, Left/Right, or Home/End.
+ * Keyboard selection also moves focus; only the selected tab is a tab stop.
+ * @param props.label - localized accessible name for the tab list.
+ * @param props.className - layout placement; panels remain caller-owned.
+ * @returns the tab list, without its panels.
+ */
+export function SegmentedTabs<Value extends string>({ items, value, onChange, label, className }: {
+  items: readonly [SegmentedTab<Value>, ...SegmentedTab<Value>[]]
+  value: Value
+  onChange: (value: Value) => void
+  label: string
+  className?: string | undefined
+}): ReactNode {
+  const selectedIndex = items.findIndex(item => item.value === value)
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    let next: number
+    switch (event.key) {
+      case 'ArrowLeft': next = (index + items.length - 1) % items.length; break
+      case 'ArrowRight': next = (index + 1) % items.length; break
+      case 'Home': next = 0; break
+      case 'End': next = items.length - 1; break
+      default: return
+    }
+    event.preventDefault()
+    event.stopPropagation()
+    const tablist = event.currentTarget.parentElement
+    const nextItem = items[next]
+    /* v8 ignore next -- the event comes from a mounted direct child and next is bounded by non-empty items. */
+    if (tablist === null || nextItem === undefined) return
+    tablist.querySelectorAll<HTMLButtonElement>('[role="tab"]').item(next).focus()
+    onChange(nextItem.value)
+  }
+
+  return (
+    <div
+      role="tablist"
+      aria-label={label}
+      className={clsx(css.tabs, className)}
+      style={{ gridTemplateColumns: `repeat(${items.length}, minmax(0, 1fr))` }}
+    >
+      <span
+        className={css.indicator}
+        aria-hidden="true"
+        style={{ width: `calc((100% - 8px) / ${items.length})`, transform: `translateX(${selectedIndex * 100}%)` }}
+      />
+      {items.map((item, index) => (
+        <Pill
+          key={item.value}
+          id={item.id}
+          role="tab"
+          className={css.tab}
+          aria-selected={value === item.value}
+          aria-controls={item.panelId}
+          tabIndex={value === item.value ? 0 : -1}
+          onClick={() => { onChange(item.value) }}
+          onKeyDown={(event) => { onKeyDown(event, index) }}
+        >
+          {item.label}
+        </Pill>
+      ))}
+    </div>
+  )
+}
diff --git a/packages/client/ui-primitives/src/StateDot.module.css b/packages/client/ui-primitives/src/StateDot.module.css
index 6a77a4e127..1a692c6892 100644
--- a/packages/client/ui-primitives/src/StateDot.module.css
+++ b/packages/client/ui-primitives/src/StateDot.module.css
@@ -32,7 +32,8 @@
 }
 
 /* Ongoing is the sole non-dot state: a quiet full ring sits behind a centered
- * breathing arc while the complete glyph rotates continuously. */
+ * breathing arc while the complete glyph rotates continuously. Both animations
+ * share one 1.5s period so pinning their start times aligns them together. */
 .spinner {
   flex: none;
   color: var(--dsw-alias-label-tertiary);
@@ -92,3 +93,8 @@
     stroke-dashoffset: -3;
   }
 }
+
+.step { display: inline-flex; flex: none; align-items: center; justify-content: center; box-sizing: border-box; border-radius: 50%; corner-shape: round; border: 1.5px solid var(--dsw-alias-label-tertiary); color: var(--dsw-alias-label-primary-foreground); }
+.step[data-state='done'] { border-color: var(--dsw-alias-state-success-primary); background: var(--dsw-alias-state-success-primary); }
+.step[data-state='error'] { border-color: var(--dsw-alias-state-error-primary); background: var(--dsw-alias-state-error-primary); }
+.step[data-state='warning'] { border-color: var(--dsw-alias-state-warn-primary); }
diff --git a/packages/client/ui-primitives/src/StateDot.tsx b/packages/client/ui-primitives/src/StateDot.tsx
index 05d869acfd..ede3c6b98c 100644
--- a/packages/client/ui-primitives/src/StateDot.tsx
+++ b/packages/client/ui-primitives/src/StateDot.tsx
@@ -1,5 +1,6 @@
 import clsx from 'clsx'
 import css from './StateDot.module.css'
+import { IconCheckOutlineRegular } from './icons/index.tsx'
 
 /**
  * State semantic: green done / amber user-attention / tertiary-grey loading /
@@ -7,22 +8,39 @@ import css from './StateDot.module.css'
  */
 export type StateDotState = 'done' | 'warning' | 'ongoing' | 'error' | 'idle'
 
+/**
+ * Pin the loader's CSS animations to document time zero. A CSS animation starts
+ * when its element is inserted, so loaders mounted at different moments rotate
+ * out of phase; one shared start time keeps every visible loader in step.
+ * @param element - the mounted loader, or null on unmount.
+ */
+function syncSpinner(element: SVGSVGElement | null): void {
+  if (element === null) return
+  // jsdom (the unit lane) implements no Web Animations despite lib.dom's
+  // non-optional typing; the optional call leaves that lane unsynced.
+  const spinner = element as { getAnimations?: SVGSVGElement['getAnimations'] }
+  for (const animation of spinner.getAnimations?.({ subtree: true }) ?? []) animation.startTime = 0
+}
+
 /**
  * Render a state dot.
  * @param props.state - which of `done`, `warning`, `ongoing`, `error`, or `idle` to show.
  * @param props.size - outer diameter in px; defaults to 14 for ongoing and 10 for solid states.
  * @param props.className - extra class for layout placement.
+ * @param props.appearance - compact dot by default; step uses a filled check or hollow pending circle.
  * @returns the dot element (aria-hidden; pair with text for accessibility).
  */
-export function StateDot({ state, size, className }: {
+export function StateDot({ state, size, className, appearance = 'dot' }: {
   state: StateDotState
   size?: number | undefined
   className?: string | undefined
+  appearance?: 'dot' | 'step'
 }) {
   const edge = size ?? (state === 'ongoing' ? 14 : 10)
   if (state === 'ongoing') {
     return (
       <svg
+        ref={syncSpinner}
         className={clsx(css.spinner, className)}
         data-state="ongoing"
         width={edge}
@@ -39,10 +57,10 @@ export function StateDot({ state, size, className }: {
   }
   return (
     <span
-      className={clsx(css.dot, className)}
+      className={clsx(appearance === 'step' ? css.step : css.dot, className)}
       data-state={state}
       style={{ width: edge, height: edge }}
       aria-hidden="true"
-    />
+    >{appearance === 'step' && state === 'done' && <IconCheckOutlineRegular size={edge - 2} />}</span>
   )
 }
diff --git a/packages/client/ui-primitives/src/TerminalBlock.module.css b/packages/client/ui-primitives/src/TerminalBlock.module.css
index 3524b1dadc..b58bbee735 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.module.css
+++ b/packages/client/ui-primitives/src/TerminalBlock.module.css
@@ -110,15 +110,18 @@
   color: var(--dsw-alias-label-tertiary);
 }
 
-/* `pre`, not `nowrap`: the prompt row renders the command verbatim, and
-   `nowrap` collapses the repeated spaces, tabs, and alignment of an indented
-   continuation. Both hold the single row and the ellipsis. */
+/* Default `pre`, not `nowrap`: the prompt row renders the command verbatim,
+   and `nowrap` would collapse the repeated spaces, tabs, and alignment of an
+   indented continuation. Hosts opt into wrapping long commands by rebinding
+   the variable to `pre-wrap`; the ellipsis then simply never engages, and
+   overflow-wrap is inert while white-space stays `pre`. */
 .command {
   min-width: 0;
   color: var(--dsw-alias-label-primary);
   overflow: hidden;
   text-overflow: ellipsis;
-  white-space: pre;
+  white-space: var(--dsl-terminal-command-whitespace, pre);
+  overflow-wrap: anywhere;
 }
 
 /* Capped to the prompt's line height (Pill's own 24px height would exceed a
@@ -176,10 +179,14 @@
   margin: 6px;
 }
 
-/* No wrapping, no word-break: alignment is the payload of terminal output. */
+/* Default `pre`: alignment is the payload of terminal output. Hosts opt
+   into wrapping long lines by rebinding the variable to `pre-wrap`, which
+   also keeps the output region from ever scrolling sideways; overflow-wrap
+   is inert while white-space stays `pre`. */
 .line {
   min-height: var(--dsl-terminal-line-height);
-  white-space: pre;
+  white-space: var(--dsl-terminal-line-whitespace, pre);
+  overflow-wrap: anywhere;
 }
 
 .expand {
diff --git a/packages/client/ui-primitives/src/TerminalBlock.tsx b/packages/client/ui-primitives/src/TerminalBlock.tsx
index dfeddcd27f..76e7f92808 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.tsx
+++ b/packages/client/ui-primitives/src/TerminalBlock.tsx
@@ -57,12 +57,24 @@ export interface TerminalBlockProps {
   /** Settled terminating signal name; any value renders the status pill, taking precedence over the exit code. */
   signal?: string | undefined
   /**
-   * The command is still running: the block shows the prompt line, and the
-   * output printed so far when there is any, with no copy control until it settles.
+   * The command is still running: with no `output` the block shows the prompt
+   * line alone; with output it renders the live text under the running state.
    */
   running?: boolean | undefined
   /** Height cap in output lines before the middle collapses (default {@link DEFAULT_TERMINAL_MAX_LINES}); Infinity disables the cap. */
   maxLines?: number | undefined
+  /**
+   * Copy-control payload override; the control copies the raw output when
+   * absent. Supplying it also keeps the control rendered before any output
+   * exists — a command is copyable before it prints.
+   */
+  copyText?: string | undefined
+  /**
+   * Draw the run-state dot and its assistive label in the card gutter
+   * (default true). Hosts whose surrounding row already carries the same
+   * state omit both and reclaim the gutter via `--dsl-terminal-gutter`.
+   */
+  runStateDot?: boolean | undefined
   /** Extra class merged onto the wrapper (callers position; this component draws). */
   className?: string | undefined
   /** Localized display copy supplied by the owning render site. */
@@ -158,6 +170,8 @@ export function TerminalBlock({
   signal,
   running = false,
   maxLines = DEFAULT_TERMINAL_MAX_LINES,
+  copyText,
+  runStateDot = true,
   className,
   labels,
 }: TerminalBlockProps) {
@@ -169,7 +183,7 @@ export function TerminalBlock({
   // newline (`line\n\x1b[0m`) leaves the string not ending in one while still
   // producing a last line with nothing visible in it. A genuinely blank final
   // line — the double newline — survives, since it has a real empty line before
-  // the terminator. The copy control still copies `text` untouched.
+  // the terminator. The copy control's payload is unaffected.
   const lines = useMemo(() => {
     const parsed = parseAnsiLines(text)
     const last = parsed[parsed.length - 1]
@@ -178,9 +192,9 @@ export function TerminalBlock({
     return terminated ? parsed.slice(0, -1) : parsed
   }, [text])
   const [expanded, setExpanded] = useState(false)
-  // The raw output, never the rendered tree: the prompt line and the status pill
-  // are chrome the user did not run.
-  const { copied, onCopy } = useCopyFeedback(text)
+  // The raw output (or the caller's override), never the rendered tree: the
+  // prompt line and the status pill are chrome the user did not run.
+  const { copied, onCopy } = useCopyFeedback(copyText ?? text)
 
   const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
 
@@ -213,14 +227,14 @@ export function TerminalBlock({
     >
       <div className={css.header}>
         <div className={css.prompt}>
-          <span className={css.runStateLabel}>{state.label}</span>
+          {runStateDot && <span className={css.runStateLabel}>{state.label}</span>}
           {commandLines.map((line, index) => (
             <div key={index} className={css.promptLine}>
               {/* One dot for the card, on the first row: the exit status the
                   view carries is the whole call's, and bash reports no
                   per-command status, so a dot per row would assert a
                   per-line outcome nothing here knows. */}
-              {index === 0 && <StateDot state={state.state} className={css.runState} />}
+              {index === 0 && runStateDot && <StateDot state={state.state} className={css.runState} />}
               {/* The cwd labels the CALL, so only its first row carries it. The
                   view knows one working directory — where the call started —
                   and a later line may well run somewhere else (a `cd` in the
@@ -235,7 +249,7 @@ export function TerminalBlock({
           ))}
         </div>
         {status !== undefined && <Pill className={css.status}>{status}</Pill>}
-        {!running && !empty && (
+        {(copyText !== undefined || (!running && !empty)) && (
           <button type="button" className={css.copyButton} onClick={onCopy}>
             {copied ? copy.copied : copy.copy}
           </button>
diff --git a/packages/client/ui-primitives/src/TextShimmer.module.css b/packages/client/ui-primitives/src/TextShimmer.module.css
new file mode 100644
index 0000000000..bdc2de9a44
--- /dev/null
+++ b/packages/client/ui-primitives/src/TextShimmer.module.css
@@ -0,0 +1,27 @@
+.root[data-text-shimmer] {
+  background-image: linear-gradient(
+    90deg,
+    currentColor calc(50% - var(--dsh-text-shimmer-spread)),
+    color-mix(in oklab, currentColor 50%, transparent),
+    currentColor calc(50% + var(--dsh-text-shimmer-spread))
+  );
+  background-position: 100% center;
+  background-repeat: no-repeat;
+  background-size: 250% 100%;
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: dsh-text-shimmer 1.5s cubic-bezier(0.33, 0, 0.67, 1) infinite;
+}
+
+@keyframes dsh-text-shimmer {
+  66.6667%, 100% { background-position: 0% center; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .root[data-text-shimmer] {
+    background-image: none;
+    -webkit-text-fill-color: currentColor;
+    animation: none;
+  }
+}
diff --git a/packages/client/ui-primitives/src/TextShimmer.tsx b/packages/client/ui-primitives/src/TextShimmer.tsx
new file mode 100644
index 0000000000..8249626435
--- /dev/null
+++ b/packages/client/ui-primitives/src/TextShimmer.tsx
@@ -0,0 +1,23 @@
+/** Text-only activity animation with a stable span across lifecycle changes. */
+import { memo, useMemo, type CSSProperties } from 'react'
+import clsx from 'clsx'
+import css from './TextShimmer.module.css'
+
+/** Text and activity supplied by the owning row. */
+export interface TextShimmerProps {
+  children: string
+  active: boolean
+  className?: string | undefined
+}
+
+/**
+ * Render text with an optional moving highlight; inactive text keeps the same node.
+ * @param props - localized text, running state, and owner styling.
+ * @returns the retained text span.
+ */
+export const TextShimmer = memo(function TextShimmer({ children, active, className }: TextShimmerProps) {
+  const style = useMemo(() => ({
+    '--dsh-text-shimmer-spread': `${children.length * 8}px`,
+  } as CSSProperties), [children.length])
+  return <span className={clsx(css.root, className)} style={style} data-text-shimmer={active || undefined}>{children}</span>
+})
diff --git a/packages/client/ui-primitives/src/Tooltip.module.css b/packages/client/ui-primitives/src/Tooltip.module.css
index 926fb68557..ed546ce13c 100644
--- a/packages/client/ui-primitives/src/Tooltip.module.css
+++ b/packages/client/ui-primitives/src/Tooltip.module.css
@@ -19,6 +19,8 @@
   animation: tooltip-in 150ms var(--ds-ease-in-out);
 }
 
+.bubble[data-portal] { z-index: 1100; }
+
 .bubble[data-side='right'] {
   transform: translateY(-50%);
 }
diff --git a/packages/client/ui-primitives/src/Tooltip.tsx b/packages/client/ui-primitives/src/Tooltip.tsx
index 688a411fb9..0316840a25 100644
--- a/packages/client/ui-primitives/src/Tooltip.tsx
+++ b/packages/client/ui-primitives/src/Tooltip.tsx
@@ -1,8 +1,8 @@
-// Cloning the anchor preserves its layout context. Fixed positioning lets the
-// bubble escape ancestor overflow clipping without a portal.
+/** Anchor-preserving tooltips with optional body portals for clipping containers. */
 
 import { cloneElement, createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { FocusEventHandler, MouseEventHandler, MutableRefObject, ReactElement, Ref } from 'react'
+import { createPortal } from 'react-dom'
 import css from './Tooltip.module.css'
 
 /** Bubble placement relative to the anchor. */
@@ -46,17 +46,18 @@ if (typeof window !== 'undefined') {
  * @param props.align - horizontal anchor-edge alignment for 'bottom'/'top' bubbles: 'end' pins
  * the bubble's right edge to the anchor's (for anchors beside other hover surfaces the centered
  * bubble would overlap); default 'center'. Ignored for side 'right'.
+ * @param props.portal - render the bubble under document.body to escape containing blocks and clipping ancestors.
  * @param props.delayMs - hover delay in milliseconds; keyboard focus remains immediate.
  * @param props.disabled - suppress the bubble while true; the anchor renders identically so
  * toggling never remounts it (which would cut its CSS transitions).
  * @param props.maxWidth - bubble width cap in pixels, for labels long enough that the default
  * half-viewport cap would render a slab wider than the surface the anchor sits on.
  * @param props.children - a single anchor element; its own ref (callback or object) is forwarded alongside the tooltip's.
- * @returns the cloned anchor plus a fixed-position bubble while hovered/focused; clicking the
+ * @returns the cloned anchor plus a fixed-position bubble, optionally portaled to the body; clicking the
  * anchor dismisses the bubble until the next trigger, and focus arriving after a pointer
  * interaction (a closing menu refocusing its trigger) never raises it.
  */
-export function Tooltip({ label, side = 'right', align = 'center', delayMs = 0, disabled = false, maxWidth, children }: { label: TooltipLabel; side?: TooltipSide; align?: 'center' | 'end'; delayMs?: number; disabled?: boolean; maxWidth?: number; children: ReactElement<AnchorProps> }) {
+export function Tooltip({ label, side = 'right', align = 'center', delayMs = 0, disabled = false, portal = false, maxWidth, children }: { label: TooltipLabel; side?: TooltipSide; align?: 'center' | 'end'; delayMs?: number; disabled?: boolean; portal?: boolean; maxWidth?: number; children: ReactElement<AnchorProps> }) {
   const anchor = useRef<HTMLElement | null>(null)
   // React 18 keeps the element's ref outside props; forward it so wrapping an
   // anchor in Tooltip never silently severs the owner's ref.
@@ -184,6 +185,20 @@ export function Tooltip({ label, side = 'right', align = 'center', delayMs = 0,
     if (!triggers.current.hover && !triggers.current.focus) withdraw()
   }
 
+  const content = visible && !suppressed && (
+    <span
+      ref={bubble}
+      className={css.bubble}
+      data-side={placement}
+      data-portal={portal || undefined}
+      data-align={align}
+      style={{ left: pos.x, top: y, ...maxWidth === undefined ? {} : { maxWidth } }}
+      role="tooltip"
+    >
+      {resolvedLabel}
+    </span>
+  )
+
   return (
     <TooltipSuppression.Provider value={setSuppressed}>
       {cloneElement(children, {
@@ -197,18 +212,7 @@ export function Tooltip({ label, side = 'right', align = 'center', delayMs = 0,
         onFocus: (e) => { children.props.onFocus?.(e); if (pointerModality) return; triggers.current.focus = true; cancelShow(); show() },
         onBlur: (e) => { children.props.onBlur?.(e); triggers.current.focus = false; hide() },
       })}
-      {visible && !suppressed && (
-        <span
-          ref={bubble}
-          className={css.bubble}
-          data-side={placement}
-          data-align={align}
-          style={{ left: pos.x, top: y, ...maxWidth === undefined ? {} : { maxWidth } }}
-          role="tooltip"
-        >
-          {resolvedLabel}
-        </span>
-      )}
+      {portal ? (content !== false && createPortal(content, document.body)) : content}
     </TooltipSuppression.Provider>
   )
 }
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
index 4f926c7e00..1c048370c1 100644
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -278,6 +278,24 @@ export const IconCloseFillMedium = (props: IconProps) => (
   <IconCloseFillArtwork {...props} strokeWidth={ICON_MEDIUM_STROKE} />
 )
 
+// A 7-unit disc with the cross knocked out of it (even-odd), so the cross
+// takes the color of whatever sits behind the glyph.
+const IconCloseCircleFillArtwork = ({ size = 16, className, strokeWidth }: WeightedIconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" strokeWidth={strokeWidth}>
+    <path fillRule="evenodd" clipRule="evenodd" d="M15 8A7 7 0 1 1 1 8A7 7 0 1 1 15 8ZM6.409 10.652L5.348 9.591L6.939 8L5.348 6.409L6.409 5.348L8 6.939L9.591 5.348L10.652 6.409L9.061 8L10.652 9.591L9.591 10.652L8 9.061Z" fill="currentColor" />
+  </svg>
+)
+
+/** Regular IconCloseCircleFill artwork (cross knocked out of a filled disc); its fill-only geometry is weight-independent. */
+export const IconCloseCircleFillRegular = (props: IconProps) => (
+  <IconCloseCircleFillArtwork {...props} strokeWidth={ICON_REGULAR_STROKE} />
+)
+
+/** Medium IconCloseCircleFill artwork; it matches Regular because the geometry is fill-only. */
+export const IconCloseCircleFillMedium = (props: IconProps) => (
+  <IconCloseCircleFillArtwork {...props} strokeWidth={ICON_MEDIUM_STROKE} />
+)
+
 const IconCopyOutlineArtwork = ({ size = 16, className, strokeWidth }: WeightedIconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" strokeWidth={strokeWidth}>
     <rect x="1.52075" y="4.07373" width="10.3932" height="10.3932" rx="2" stroke="currentColor" />
@@ -1575,3 +1593,19 @@ export const IconSlidersTwoOutlineRegular = (props: IconProps) => (
 export const IconSlidersTwoOutlineMedium = (props: IconProps) => (
   <IconSlidersTwoOutlineArtwork {...props} strokeWidth={ICON_MEDIUM_STROKE} />
 )
+
+const IconMicrophoneOutlineArtwork = ({ size = 16, className, strokeWidth }: WeightedIconProps) => (
+  <svg width={size} height={size} viewBox="0 0 16 16" className={className} fill="none" stroke="currentColor" strokeWidth={strokeWidth} aria-hidden="true">
+    <rect x="6" y="1" width="4" height="8" rx="2" /><path d="M3 7v1a5 5 0 0 0 10 0V7M8 13v2m-3 0h6" />
+  </svg>
+)
+
+/** Regular one-pixel microphone artwork. */
+export const IconMicrophoneOutlineRegular = (props: IconProps) => (
+  <IconMicrophoneOutlineArtwork {...props} strokeWidth={ICON_REGULAR_STROKE} />
+)
+
+/** Medium microphone artwork with a 1.3px stroke. */
+export const IconMicrophoneOutlineMedium = (props: IconProps) => (
+  <IconMicrophoneOutlineArtwork {...props} strokeWidth={ICON_MEDIUM_STROKE} />
+)
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index 2ad31f82b4..e40867e127 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -6,12 +6,18 @@ export { StateDot } from './StateDot.tsx'
 export type { StateDotState } from './StateDot.tsx'
 export { DisclosureRow } from './DisclosureRow.tsx'
 export type { DisclosureRowProps } from './DisclosureRow.tsx'
+export { TextShimmer } from './TextShimmer.tsx'
+export type { TextShimmerProps } from './TextShimmer.tsx'
 export { Button } from './Button.tsx'
 export type { ButtonVariant } from './Button.tsx'
 export { Pill } from './Pill.tsx'
+export { SegmentedTabs } from './SegmentedTabs.tsx'
+export type { SegmentedTab } from './SegmentedTabs.tsx'
 export { Tag } from './Tag.tsx'
 export type { TagTone } from './Tag.tsx'
 export { Switch } from './Switch.tsx'
+export { SegmentedControl } from './SegmentedControl.tsx'
+export type { SegmentedControlOption } from './SegmentedControl.tsx'
 export { Checkbox } from './Checkbox.tsx'
 export { Input } from './Input.tsx'
 export { Menu, MenuItemButton } from './Menu.tsx'
@@ -83,5 +89,5 @@ export { extractMarkdownPlainText } from './markdown/plain-text.ts'
 export type { MarkdownPlainTextMode, MarkdownPlainTextOptions } from './markdown/plain-text.ts'
 export * from './icons/index.tsx'
 export {
-  PluginArtworkTeam, PluginArtworkTerminal, PluginArtworkLoop, PluginArtworkSubagent, PluginArtworkSearch, PluginArtworkDefault,
+  PluginArtworkTerminal, PluginArtworkLoop, PluginArtworkSubagent, PluginArtworkSearch, PluginArtworkDefault,
 } from './plugin-artwork.tsx'
diff --git a/packages/client/ui-primitives/src/plugin-artwork.tsx b/packages/client/ui-primitives/src/plugin-artwork.tsx
index ec54304d3c..c5a774ca81 100644
--- a/packages/client/ui-primitives/src/plugin-artwork.tsx
+++ b/packages/client/ui-primitives/src/plugin-artwork.tsx
@@ -12,25 +12,6 @@ import type { IconProps } from './icons/props.ts'
  */
 const useArtworkId = (): string => `dsh_plugin_art_${useId().replaceAll(':', '')}`
 
-/** Agent-team plugin artwork (four interlocking quadrants). */
-export const PluginArtworkTeam = ({ size = 36, className }: IconProps) => {
-  const uid = useArtworkId()
-  return (
-    <svg width={size} height={size} className={className} viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
-      <path d="M13.3027 17.1077H9.03125V12.8372H13.3027V17.1077ZM17.5742 12.8372C17.574 15.1958 15.6623 17.1075 13.3037 17.1077V8.56567H17.5742V12.8372Z" fill={`url(#${uid}a)`} />
-      <path d="M18.5229 12.8372V8.56567H22.7944V12.8372H27.0659V17.1077H22.7944C20.4357 17.1077 18.5232 15.1959 18.5229 12.8372Z" fill="#F2AF63" />
-      <path d="M17.5742 26.6072H13.3037V18.0642C15.6625 18.0644 17.5742 19.9769 17.5742 22.3357V26.6072ZM13.3027 22.3357H9.03125V18.0642H13.3027V22.3357Z" fill="#7CB7FF" />
-      <path d="M22.7944 26.6072H18.5229V22.3357C18.5229 19.9768 20.4355 18.0642 22.7944 18.0642H27.0659V22.3357H22.7944V26.6072Z" fill="#45D9E7" />
-      <defs>
-        <linearGradient id={`${uid}a`} x1="16.1247" y1="6.6613" x2="9.03125" y2="19.2206" gradientUnits="userSpaceOnUse">
-          <stop stopColor="#7CB7FF" />
-          <stop offset="1" stopColor="#145AF3" />
-        </linearGradient>
-      </defs>
-    </svg>
-  )
-}
-
 /** Terminal plugin artwork (prompt chevron and cursor bar). */
 export const PluginArtworkTerminal = ({ size = 36, className }: IconProps) => (
   <svg width={size} height={size} className={className} viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
diff --git a/packages/client/ui-primitives/tests/SegmentedTabs.client.spec.tsx b/packages/client/ui-primitives/tests/SegmentedTabs.client.spec.tsx
new file mode 100644
index 0000000000..009b86d56b
--- /dev/null
+++ b/packages/client/ui-primitives/tests/SegmentedTabs.client.spec.tsx
@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+import { useState } from 'react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { SegmentedTabs } from '../src/SegmentedTabs.tsx'
+
+afterEach(cleanup)
+
+const items = [
+  { value: 'details', label: 'Details', id: 'details-tab', panelId: 'details-panel' },
+  { value: 'examples', label: 'Examples', id: 'examples-tab', panelId: 'examples-panel' },
+  { value: 'limits', label: 'Limits', id: 'limits-tab', panelId: 'limits-panel' },
+] as const
+
+describe('SegmentedTabs', () => {
+  it('requests a selection while the caller owns its value and panels', () => {
+    const onChange = vi.fn()
+    const { rerender } = render(<SegmentedTabs items={items} value="details" onChange={onChange} label="Help" />)
+    const examples = screen.getByRole('tab', { name: 'Examples' })
+    fireEvent.click(examples)
+    expect(onChange).toHaveBeenCalledWith('examples')
+    expect(screen.getByRole('tab', { selected: true }).textContent).toBe('Details')
+    expect(screen.queryByRole('tabpanel')).toBeNull()
+
+    rerender(<SegmentedTabs items={items} value="examples" onChange={onChange} label="Help" />)
+    expect(examples.getAttribute('aria-selected')).toBe('true')
+    expect(examples.id).toBe('examples-tab')
+    expect(examples.getAttribute('aria-controls')).toBe('examples-panel')
+    expect(examples.tabIndex).toBe(0)
+    expect(screen.getByRole('tab', { name: 'Details' }).tabIndex).toBe(-1)
+    expect(screen.getByRole('tablist', { name: 'Help' })).toBeTruthy()
+  })
+
+  it('moves focus and selection with arrows, Home, and End, and leaves Tab alone', () => {
+    const onKeyDown = vi.fn()
+    function Harness() {
+      const [value, setValue] = useState<string>('details')
+      return <div onKeyDown={onKeyDown}><SegmentedTabs items={items} value={value} onChange={setValue} label="Help" /></div>
+    }
+    render(<Harness />)
+    const details = screen.getByRole('tab', { name: 'Details' })
+    const examples = screen.getByRole('tab', { name: 'Examples' })
+    const limits = screen.getByRole('tab', { name: 'Limits' })
+    details.focus()
+    for (const [from, key, to] of [
+      [details, 'ArrowLeft', limits],
+      [limits, 'ArrowRight', details],
+      [details, 'ArrowRight', examples],
+      [examples, 'End', limits],
+      [limits, 'Home', details],
+    ] as const) {
+      fireEvent.keyDown(from, { key })
+      expect(document.activeElement).toBe(to)
+      expect(to.getAttribute('aria-selected')).toBe('true')
+      expect(to.tabIndex).toBe(0)
+    }
+    expect(onKeyDown).not.toHaveBeenCalled()
+    fireEvent.keyDown(details, { key: 'Tab' })
+    expect(onKeyDown).toHaveBeenCalledOnce()
+    expect(screen.getByRole('tab', { selected: true })).toBe(details)
+  })
+})
diff --git a/packages/client/ui-primitives/tests/icons.client.spec.tsx b/packages/client/ui-primitives/tests/icons.client.spec.tsx
index 89b17cb4bf..62f67def95 100644
--- a/packages/client/ui-primitives/tests/icons.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.client.spec.tsx
@@ -17,18 +17,34 @@ const icons = Object.fromEntries(
 const iconNames = Object.keys(icons)
 
 describe('product icon set', () => {
-  it('exports regular and medium variants for all 90 public glyphs', () => {
-    expect(iconNames.length).toBe(180)
+  it('exports regular and medium variants for all 92 public glyphs', () => {
+    expect(iconNames.length).toBe(184)
     expect(iconNames.some(name => /\d+$/.test(name))).toBe(false)
     const regular = iconNames.filter(name => name.endsWith('Regular')).map(name => name.slice(0, -'Regular'.length))
     const medium = iconNames.filter(name => name.endsWith('Medium')).map(name => name.slice(0, -'Medium'.length))
     expect(medium.sort()).toEqual(regular.sort())
     expect(iconNames).toEqual(expect.arrayContaining([
+      'IconMicrophoneOutlineRegular',
       'IconPlanOutlineRegular', 'IconCompactOutlineRegular', 'IconShieldOutlineRegular', 'IconDeliverDocRegular',
-      'IconWarningTriangleOutlineRegular', 'IconCompareSplitOutlineRegular',
+      'IconWarningTriangleOutlineRegular', 'IconCompareSplitOutlineRegular', 'IconCloseCircleFillRegular',
     ]))
   })
 
+  it('draws the circled close as one currentColor knockout path in both weights', () => {
+    // A filled disc with the cross cut out of it (even-odd), so the cross shows
+    // the surface behind the glyph on any background instead of a second color.
+    for (const Icon of [primitives.IconCloseCircleFillRegular, primitives.IconCloseCircleFillMedium]) {
+      const { container, unmount } = render(<Icon />)
+      const paths = container.querySelectorAll('path')
+      expect(paths).toHaveLength(1)
+      expect(paths[0]!.getAttribute('fill')).toBe('currentColor')
+      expect(paths[0]!.getAttribute('fill-rule')).toBe('evenodd')
+      expect(paths[0]!.getAttribute('stroke')).toBeNull()
+      expect(container.querySelector('svg')!.getAttribute('width')).toBe('16')
+      unmount()
+    }
+  })
+
   it('exports the shield contour and regular stroke for composite glyphs', () => {
     const { container } = render(<primitives.IconShieldOutlineRegular />)
     expect(container.querySelector('path')?.getAttribute('d')).toBe(primitives.SHIELD_OUTLINE_PATH)
diff --git a/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx b/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx
index 0df9c9a573..5db7f79cb8 100644
--- a/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/plugin-artwork.client.spec.tsx
@@ -2,13 +2,12 @@
 import { cleanup, render } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
 import {
-  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTeam, PluginArtworkTerminal,
+  PluginArtworkDefault, PluginArtworkLoop, PluginArtworkSearch, PluginArtworkSubagent, PluginArtworkTerminal,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
 
 const artworks = {
-  PluginArtworkTeam,
   PluginArtworkTerminal,
   PluginArtworkLoop,
   PluginArtworkSubagent,
diff --git a/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx b/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx
new file mode 100644
index 0000000000..b9883fbf6a
--- /dev/null
+++ b/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx
@@ -0,0 +1,180 @@
+// @vitest-environment jsdom
+/** The segmented control is a tablist whose selection the owner holds. */
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { SegmentedControl } from '@deepseek-ai/dsh-client-ui-primitives'
+
+afterEach(cleanup)
+
+type Mode = 'catalog' | 'custom' | 'import'
+
+const OPTIONS: ReadonlyArray<{ value: Mode; label: string; disabled?: boolean; title?: string }> = [
+  { value: 'catalog', label: 'Catalog' },
+  { value: 'custom', label: 'Custom' },
+  { value: 'import', label: 'Import' },
+]
+
+function mount(value: Mode, extra: {
+  options?: typeof OPTIONS
+  className?: string
+  disabled?: boolean
+} = {}) {
+  const onChange = vi.fn<(next: Mode) => void>()
+  const view = render(
+    <SegmentedControl
+      id="add"
+      label="Add mode"
+      value={value}
+      options={extra.options ?? OPTIONS}
+      onChange={onChange}
+      {...extra.className === undefined ? {} : { className: extra.className }}
+      {...extra.disabled === undefined ? {} : { disabled: extra.disabled }}
+    />,
+  )
+  return { view, onChange }
+}
+
+function tab(name: string): HTMLButtonElement {
+  return screen.getByRole<HTMLButtonElement>('tab', { name })
+}
+
+describe('SegmentedControl', () => {
+  it('exposes a named tablist with one tab per option and the owner-held selection', () => {
+    mount('custom')
+    const list = screen.getByRole('tablist', { name: 'Add mode' })
+    expect(list.querySelectorAll('[role="tab"]')).toHaveLength(3)
+    expect(tab('Catalog').getAttribute('aria-selected')).toBe('false')
+    expect(tab('Custom').getAttribute('aria-selected')).toBe('true')
+    expect(tab('Import').getAttribute('aria-selected')).toBe('false')
+  })
+
+  it('reports the clicked option and stays silent on the one already selected', () => {
+    const { onChange } = mount('catalog')
+    fireEvent.click(tab('Custom'))
+    expect(onChange).toHaveBeenCalledWith('custom')
+    onChange.mockClear()
+    fireEvent.click(tab('Catalog'))
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('refuses a disabled option and carries its lock reason as the hover title', () => {
+    const { onChange } = mount('catalog', {
+      options: [OPTIONS[0]!, { value: 'custom', label: 'Custom', disabled: true, title: 'No protocol is mounted' }],
+    })
+    const locked = tab('Custom')
+    expect(locked.disabled).toBe(true)
+    expect(locked.getAttribute('title')).toBe('No protocol is mounted')
+    fireEvent.click(locked)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('keeps only the selected tab in the tab sequence', () => {
+    mount('custom')
+    expect(tab('Catalog').tabIndex).toBe(-1)
+    expect(tab('Custom').tabIndex).toBe(0)
+    expect(tab('Import').tabIndex).toBe(-1)
+  })
+
+  it('moves the selection with the arrow keys, wrapping at either end', () => {
+    const { onChange } = mount('import')
+    fireEvent.keyDown(tab('Import'), { key: 'ArrowRight' })
+    expect(onChange).toHaveBeenLastCalledWith('catalog')
+    fireEvent.keyDown(tab('Import'), { key: 'ArrowLeft' })
+    expect(onChange).toHaveBeenLastCalledWith('custom')
+  })
+
+  it('jumps to the first and last enabled options with Home and End, skipping disabled ones', () => {
+    const { onChange } = mount('custom', {
+      options: [
+        { value: 'catalog', label: 'Catalog', disabled: true },
+        OPTIONS[1]!,
+        { value: 'import', label: 'Import', disabled: true },
+      ],
+    })
+    fireEvent.keyDown(tab('Custom'), { key: 'Home' })
+    fireEvent.keyDown(tab('Custom'), { key: 'End' })
+    fireEvent.keyDown(tab('Custom'), { key: 'ArrowRight' })
+    // Every enabled neighbour is the selected one itself, so nothing changes.
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('lands Home and End on the first and last enabled options, not the first and last options', () => {
+    const { onChange } = mount('import', {
+      options: [{ value: 'catalog', label: 'Catalog', disabled: true }, OPTIONS[1]!, OPTIONS[2]!],
+    })
+    fireEvent.keyDown(tab('Import'), { key: 'Home' })
+    expect(onChange).toHaveBeenLastCalledWith('custom')
+    onChange.mockClear()
+    fireEvent.keyDown(tab('Import'), { key: 'End' })
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('skips disabled options while walking with the arrow keys', () => {
+    const { onChange } = mount('catalog', {
+      options: [OPTIONS[0]!, { value: 'custom', label: 'Custom', disabled: true }, OPTIONS[2]!],
+    })
+    fireEvent.keyDown(tab('Catalog'), { key: 'ArrowRight' })
+    expect(onChange).toHaveBeenLastCalledWith('import')
+    fireEvent.keyDown(tab('Catalog'), { key: 'End' })
+    expect(onChange).toHaveBeenLastCalledWith('import')
+  })
+
+  it('moves keyboard focus onto the newly selected tab once the owner adopts it', () => {
+    const { view, onChange } = mount('catalog')
+    tab('Catalog').focus()
+    fireEvent.keyDown(tab('Catalog'), { key: 'ArrowRight' })
+    view.rerender(
+      <SegmentedControl id="add" label="Add mode" value="custom" options={OPTIONS} onChange={onChange} />,
+    )
+    expect(document.activeElement).toBe(tab('Custom'))
+  })
+
+  it('leaves unrelated keys alone', () => {
+    const { onChange } = mount('catalog')
+    fireEvent.keyDown(tab('Catalog'), { key: 'Enter' })
+    fireEvent.keyDown(tab('Catalog'), { key: 'a' })
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('places the sliding indicator by selected index and option count', () => {
+    mount('import')
+    const list = screen.getByRole('tablist')
+    expect(list.style.getPropertyValue('--dsh-segment-count')).toBe('3')
+    expect(list.style.getPropertyValue('--dsh-segment-index')).toBe('2')
+  })
+
+  it('keeps a caller class alongside its own so a render site can place it', () => {
+    mount('catalog', { className: 'placed' })
+    const list = screen.getByRole('tablist')
+    expect(list.classList.contains('placed')).toBe(true)
+    expect(list.classList.length).toBeGreaterThan(1)
+  })
+
+  it('names each tab and the panel it controls from the owner id, so panels can point back', () => {
+    mount('catalog')
+    const catalog = tab('Catalog')
+    expect(catalog.id).toBe('add-catalog')
+    expect(catalog.getAttribute('aria-controls')).toBe('add-catalog-panel')
+    expect(tab('Import').getAttribute('aria-controls')).toBe('add-import-panel')
+  })
+
+  it('locks every segment while the owner reports the control disabled', () => {
+    // A disabled button is unfocusable, so the walk keys cannot originate on
+    // one; the click path is what a pointer can still reach.
+    const { onChange } = mount('catalog', { disabled: true })
+    for (const name of ['Catalog', 'Custom', 'Import']) expect(tab(name).disabled).toBe(true)
+    fireEvent.click(tab('Custom'))
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('never submits a surrounding form', () => {
+    const onSubmit = vi.fn((event: { preventDefault: () => void }) => { event.preventDefault() })
+    render(
+      <form onSubmit={onSubmit}>
+        <SegmentedControl id="add" label="Add mode" value="catalog" options={OPTIONS} onChange={() => {}} />
+      </form>,
+    )
+    fireEvent.click(tab('Custom'))
+    expect(onSubmit).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/client/ui-primitives/tests/state-dot.client.spec.tsx b/packages/client/ui-primitives/tests/state-dot.client.spec.tsx
index dac34c3ccd..5b6bad53f0 100644
--- a/packages/client/ui-primitives/tests/state-dot.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/state-dot.client.spec.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 import { cleanup, render } from '@testing-library/react'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { StateDotState } from '@deepseek-ai/dsh-client-ui-primitives'
 
@@ -56,3 +56,29 @@ describe('StateDot', () => {
     expect(bad('paused')).toBe('paused')
   })
 })
+
+it('renders completed steps with a check and pending steps without one', () => {
+  const { container, rerender } = render(<StateDot state="done" appearance="step" size={16} />)
+  expect(container.querySelector('[data-state="done"] svg')).toBeTruthy()
+  rerender(<StateDot state="idle" appearance="step" size={16} />)
+  expect(container.querySelector('[data-state="idle"] svg')).toBeNull()
+  expect(container.firstElementChild?.className).toContain('step')
+})
+
+describe('StateDot ongoing phase', () => {
+  it('pins every loader animation to document time zero on mount', () => {
+    const animations = [{ startTime: 42 }, { startTime: 7 }]
+    const getAnimations = vi.fn(() => animations)
+    const proto = SVGElement.prototype as { getAnimations?: () => { startTime: number }[] }
+    proto.getAnimations = getAnimations
+    try {
+      const { unmount } = render(<StateDot state="ongoing" />)
+      expect(getAnimations).toHaveBeenCalledWith({ subtree: true })
+      expect(animations.map(animation => animation.startTime)).toEqual([0, 0])
+      unmount()
+      expect(getAnimations).toHaveBeenCalledTimes(1)
+    } finally {
+      delete proto.getAnimations
+    }
+  })
+})
diff --git a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
index 48f34678e9..432a20fde2 100644
--- a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
@@ -89,23 +89,50 @@ describe('TerminalBlock prompt label', () => {
 })
 
 describe('TerminalBlock states', () => {
-  it('running with nothing printed yet shows the command line only: no placeholder, no copy, no body', () => {
+  it('running with no output shows the command line only: no output box, no placeholder, no copy', () => {
     const view = render(<TerminalBlock command="sleep 5" running />)
     expect(view.getByText('sleep 5')).toBeTruthy()
+    expect(outputLines(view.container)).toEqual([])
     expect(view.queryByText('无输出')).toBeNull()
     expect(view.queryByRole('button')).toBeNull()
     expect(view.container.firstElementChild?.getAttribute('data-running')).toBe('')
-    expect(view.container.firstElementChild?.hasAttribute('data-body')).toBe(false)
+    // Banner-only: no body, so no banner divider either.
+    expect(view.container.firstElementChild?.getAttribute('data-body')).toBeNull()
   })
 
-  it('running shows the output printed so far under the banner, still without a copy control', () => {
-    const view = render(<TerminalBlock command="pnpm add x" running output={'Progress: resolved 1\n'} />)
-    expect(outputLines(view.container)).toEqual(['Progress: resolved 1'])
-    expect(view.queryByRole('button')).toBeNull()
+  it('copyText overrides the copy payload and keeps the control before any output', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const view = render(<TerminalBlock command="npm run build --verbose" running copyText="npm run build --verbose" />)
+    // No output yet, but the command is already copyable.
+    const button = view.getByRole('button', { name: '复制' })
+    await act(async () => { fireEvent.click(button) })
+    expect(writeText).toHaveBeenCalledWith('npm run build --verbose')
+  })
+
+  it('omits the run-state dot and its assistive label when the host carries the state', () => {
+    const view = render(<TerminalBlock command="sleep 5" running output="partial" runStateDot={false} />)
+    expect(view.container.querySelector('[class*="runState"]')).toBeNull()
+    expect(view.queryByText('运行中')).toBeNull()
+  })
+
+  it('running with supplied output streams the live text without a default copy control', () => {
+    const view = render(<TerminalBlock command="sleep 5" running output="partial" />)
+    expect(view.getByText('partial')).toBeTruthy()
+    expect(view.queryByText('无输出')).toBeNull()
+    expect(view.queryByRole('button', { name: '复制' })).toBeNull()
     expect(view.container.firstElementChild?.getAttribute('data-running')).toBe('')
+    // Live output renders a body, so the banner divider returns.
     expect(view.container.firstElementChild?.getAttribute('data-body')).toBe('')
   })
 
+  it('running with an empty live stream draws neither output nor placeholder', () => {
+    const view = render(<TerminalBlock command="tail -f log" running output="" />)
+    expect(outputLines(view.container)).toEqual([])
+    expect(view.queryByText('无输出')).toBeNull()
+    expect(view.queryByRole('button')).toBeNull()
+  })
+
   it('running still shows a settled-looking status pill when one is supplied', () => {
     render(<TerminalBlock command="sleep 5" running signal="SIGINT" />)
     expect(screen.getByText('信号 SIGINT')).toBeTruthy()
diff --git a/packages/client/ui-primitives/tests/text-shimmer-styles.client.spec.ts b/packages/client/ui-primitives/tests/text-shimmer-styles.client.spec.ts
new file mode 100644
index 0000000000..b416a1705f
--- /dev/null
+++ b/packages/client/ui-primitives/tests/text-shimmer-styles.client.spec.ts
@@ -0,0 +1,16 @@
+/** CSS activity and reduced-motion rules that jsdom does not execute. */
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+const css = readFileSync(new URL('../src/TextShimmer.module.css', import.meta.url), 'utf8')
+
+describe('TextShimmer styles', () => {
+  it('animates active text and disables motion and transparent fill for reduced motion', () => {
+    expect(css).toMatch(/\.root\[data-text-shimmer\]\s*\{[^}]*animation: dsh-text-shimmer/s)
+    expect(css).toMatch(/@keyframes dsh-text-shimmer\s*\{[^}]*background-position: 0% center/s)
+    const reduced = /@media \(prefers-reduced-motion: reduce\)\s*\{\s*\.root\[data-text-shimmer\]\s*\{([^}]+)\}/.exec(css)?.[1]
+    expect(reduced).toContain('background-image: none;')
+    expect(reduced).toContain('-webkit-text-fill-color: currentColor;')
+    expect(reduced).toContain('animation: none;')
+  })
+})
diff --git a/packages/client/ui-primitives/tests/text-shimmer.client.spec.tsx b/packages/client/ui-primitives/tests/text-shimmer.client.spec.tsx
new file mode 100644
index 0000000000..5f6efdf805
--- /dev/null
+++ b/packages/client/ui-primitives/tests/text-shimmer.client.spec.tsx
@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { TextShimmer } from '../src/TextShimmer.tsx'
+
+afterEach(cleanup)
+
+describe('TextShimmer', () => {
+  it('retains its text span across activity, text, and owner-class changes', () => {
+    const view = render(<TextShimmer active className="title">Run</TextShimmer>)
+    const span = view.getByText('Run')
+    expect(span.tagName).toBe('SPAN')
+    expect(span.dataset.textShimmer).toBe('true')
+    expect(span.classList.contains('title')).toBe(true)
+    expect(span.style.getPropertyValue('--dsh-text-shimmer-spread')).toBe('24px')
+
+    view.rerender(<TextShimmer active={false}>End</TextShimmer>)
+    expect(view.getByText('End')).toBe(span)
+    expect(span.hasAttribute('data-text-shimmer')).toBe(false)
+    expect(span.classList.contains('title')).toBe(false)
+    expect(span.style.getPropertyValue('--dsh-text-shimmer-spread')).toBe('24px')
+
+    view.rerender(<TextShimmer active>Running</TextShimmer>)
+    expect(view.getByText('Running')).toBe(span)
+    expect(span.dataset.textShimmer).toBe('true')
+    expect(span.style.getPropertyValue('--dsh-text-shimmer-spread')).toBe('56px')
+  })
+
+})
diff --git a/packages/client/ui-primitives/tests/tooltip.client.spec.tsx b/packages/client/ui-primitives/tests/tooltip.client.spec.tsx
index 3f1c4f059c..5d6633c387 100644
--- a/packages/client/ui-primitives/tests/tooltip.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/tooltip.client.spec.tsx
@@ -466,3 +466,18 @@ describe('Tooltip', () => {
     expect(screen.getByRole('tooltip').textContent).toBe('Open sidebar')
   })
 })
+
+
+it('keeps the anchor in its clipping container and portals only the tooltip', () => {
+  const view = render(<div style={{ overflow: 'hidden', contain: 'layout' }}>
+    <Tooltip portal label="Open in Music" side="bottom"><button type="button">File action</button></Tooltip>
+  </div>)
+  const anchor = screen.getByRole('button', { name: 'File action' })
+  fireEvent.mouseEnter(anchor)
+  const tooltip = screen.getByRole('tooltip')
+  expect(tooltip.parentElement).toBe(document.body)
+  expect(view.container.contains(anchor)).toBe(true)
+  expect(view.container.contains(tooltip)).toBe(false)
+  view.unmount()
+  expect(screen.queryByRole('tooltip')).toBeNull()
+})
diff --git a/packages/client/ui-reference/README.i18n.yaml b/packages/client/ui-reference/README.i18n.yaml
index dbd1bdcb5c..a70fa7f3f4 100644
--- a/packages/client/ui-reference/README.i18n.yaml
+++ b/packages/client/ui-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 packages/client/ui-reference/README.md
-README.md: 6b5046f1c6300f5ec02d3737617019874762d47a
-README.zh.md: 99ba6fda18a73f5686f5e02403e48d5e556f9c3c
+README.md: 57b5ae2440cf3dd4512cf44361b334dc7f3a58c9
+README.zh.md: fa5af63c939f2bb71f371262dbbf137180c63f8e
diff --git a/packages/client/ui-reference/README.md b/packages/client/ui-reference/README.md
index 6b5046f1c6..57b5ae2440 100644
--- a/packages/client/ui-reference/README.md
+++ b/packages/client/ui-reference/README.md
@@ -53,6 +53,8 @@ The source keeps candidate encoding internal to the registration effect: the `/c
 
 For an unquoted token, the browser starts the `fileReferences/list` and `sessionReferenceResolver/candidates` Remote calls together, then deterministically orders files, direct subagents of the current Session, and other Sessions. Rows use the resolver's display title, which prefers a subagent's creation label while ordinary Sessions retain their projected title, and render under locale-owned group headings without a redundant raw `reference` source title. A session row is dated from the Host session list's `updatedAt` through the same relative-time bucket that list uses, so one session reads the same age on both surfaces; a session the list does not carry falls back to the candidate's creation time. A drilled query publishes a breadcrumb from the workspace root to the current directory; each crumb carries the drill payload a folder row would, so returning to a step and descending into one are one outcome.
 
+Candidate requests require an existing retained Client Session and share one temporary `referenceCandidates` reference. Both discovery calls wait for that Session's initial history open to succeed; an unretained Session or failed open prevents both RPCs. The candidate request's cancellation signal covers the history wait and both calls, and the temporary reference is released when the lookup settles.
+
 ### Serialization
 
 File picks preserve the natural text defined by the shared `@path` grammar as the hidden serialized and clipboard form. Session picks use the canonical `@[label](dsh-session:…)` mention; serialization never reconstructs identity from the visible title.
diff --git a/packages/client/ui-reference/README.zh.md b/packages/client/ui-reference/README.zh.md
index 99ba6fda18..fa5af63c93 100644
--- a/packages/client/ui-reference/README.zh.md
+++ b/packages/client/ui-reference/README.zh.md
@@ -53,6 +53,8 @@ Web 用户需要从同一个 `@` 补全菜单提及文件、文件夹或会话
 
 对于未加引号的 token，浏览器会同时启动 `fileReferences/list` 与 `sessionReferenceResolver/candidates` Remote 调用，再按文件、当前 Session 的直接 subagent、其他 Session 的确定性顺序排列。各行使用 resolver 的显示标题；subagent 优先使用创建标签，普通 Session 保持投影标题，并渲染在 locale 管理的分组标题下，不显示重复的原始 `reference` source 标题。会话行用宿主会话列表的 `updatedAt` 经该列表相同的相对时间分档标注时间，因此同一个会话在两处读到的时长一致；列表中没有的会话回落到候选自带的创建时间。下钻后的查询会发布一条从工作区根目录到当前目录的面包屑；每一节携带的下钻载荷与文件夹行相同，因此「回到某一步」与「进入某一层」是同一个结果。
 
+候选请求要求客户端已持有该会话，并共用一个临时的 `referenceCandidates` 引用。两个发现调用都等待该会话首次历史打开成功；未持有会话或打开失败时，均不发送 RPC。候选请求的取消信号同时覆盖历史等待和两个调用，查询结束时释放临时引用。
+
 ### 序列化
 
 文件选择把共享 `@path` 语法所定义的自然文本保留为隐藏的序列化与剪贴板形式。会话选择使用规范的 `@[label](dsh-session:…)` mention；序列化永远不会根据可见标题重建身份。
diff --git a/packages/client/ui-reference/src/client/index.ts b/packages/client/ui-reference/src/client/index.ts
index bf2104a1b3..6204478f75 100644
--- a/packages/client/ui-reference/src/client/index.ts
+++ b/packages/client/ui-reference/src/client/index.ts
@@ -2,6 +2,8 @@
  * Unified Web `@` reference source. File and session discovery run through
  * the cancellable generated Remote namespaces in parallel with deterministic
  * ordering and labels.
+ * Candidate requests retain an existing Client Session through completion
+ * and wait for its initial history open to succeed before contacting the Host.
  *
  * Rows carry only what distinguishes them: a file names its parent directory
  * (nothing at the workspace root), a directory listing names none because its
@@ -28,6 +30,13 @@ import type { SessionReferenceMentionCandidate } from '@deepseek-ai/dsh-session-
 import { abbreviateHomePath, fileAddressFor } from '@deepseek-ai/dsh-util-workspace-path'
 import { en, NS, zh, type ReferenceKey } from './locales.ts'
 
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+  interface SessionReferenceSourceMap {
+    /** File and Session candidates waiting for initial history and their RPC results. */
+    referenceCandidates: unknown
+  }
+}
+
 /** Required services: the trigger registry, the Remote namespaces, and the copy. */
 export const inject = [
   'inputTriggers', 'locale', 'sessions', 'remote', 'remote.fileReferences',
@@ -47,13 +56,27 @@ export function apply(ctx: ClientContext): void {
     name: 'reference',
     showGroupTitle: false,
     async candidates(session: ClientSessionContext, { query, quoted, drilled, signal }) {
-      const fileLookup = ctx.remote.fileReferences.list(session.sessionId, query, signal)
-        .then(result => result.ok ? result.value : [])
-      const sessionLookup = quoted === true
-        ? Promise.resolve([] as SessionReferenceMentionCandidate[])
-        : ctx.remote.sessionReferenceResolver.candidates(session.sessionId, query, signal)
-          .then(result => result.ok ? result.value : [])
-      const [fileItems, sessionItems] = await Promise.all([fileLookup, sessionLookup])
+      if (sessions.binding(session.sessionId) === undefined) {
+        throw new Error(`reference candidates require a retained session "${session.sessionId}"`)
+      }
+      const [fileItems, sessionItems] = await sessions.using(
+        session.sessionId,
+        { source: 'referenceCandidates', signal },
+        async (reference) => {
+          signal.throwIfAborted()
+          const state = reference.binding.session.getSnapshot()
+          if (state.openState !== 'open') {
+            throw state.openError ?? new Error(`session "${session.sessionId}" is not open`)
+          }
+          const fileLookup = ctx.remote.fileReferences.list(session.sessionId, query, signal)
+            .then(result => result.ok ? result.value : [])
+          const sessionLookup = quoted === true
+            ? Promise.resolve([] as SessionReferenceMentionCandidate[])
+            : ctx.remote.sessionReferenceResolver.candidates(session.sessionId, query, signal)
+              .then(result => result.ok ? result.value : [])
+          return Promise.all([fileLookup, sessionLookup])
+        },
+      )
       if (signal.aborted) return []
       // The header already names the directory being listed; rows repeat it only
       // when there is no header to carry it.
diff --git a/packages/client/ui-reference/tests/browser-plugin.client.spec.ts b/packages/client/ui-reference/tests/browser-plugin.client.spec.ts
index ff8ae73411..b0cb5ebeef 100644
--- a/packages/client/ui-reference/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-reference/tests/browser-plugin.client.spec.ts
@@ -4,10 +4,11 @@
  * round-trip, and registration lifecycle.
  */
 import { Context, Service } from '@deepseek-ai/cordis'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from 'vitest'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { RemoteError, TestSessions } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionFixture } from '@deepseek-ai/dsh-client-test-runtime'
 import type {
   CandidateRequest, ClientSessionContext, InputTriggerCandidate, InputTriggerSource,
 } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
@@ -80,7 +81,8 @@ async function bench(
     parentId?: SessionId
     projectionValues?: { title?: string | null }
   }> = {},
-): Promise<{ ctx: Context; fiber: ReturnType<Context['plugin']>; source: InputTriggerSource }> {
+  opening: Pick<SessionFixture, 'initialOpen' | 'snapshot'> = {},
+) {
   const ctx = new Context()
   ctx.provide('sidebarRight', { openResource: vi.fn() })
   let source: InputTriggerSource | undefined
@@ -101,11 +103,22 @@ async function bench(
   ctx.provide('remote.fileReferences', { list: files })
   ctx.provide('remote.sessionReferenceResolver', { candidates: sessions })
   ctx.provide('locale', new LocaleRuntime(ctx))
-  ctx.provide('sessions', { list: { getSnapshot: () => ({ byId: listed }) } })
+  const sessionStore = new TestSessions(async (action) => { await action() }, ctx)
+  onTestFinished(async () => {
+    await sessionStore.disposeScopes()
+    await ctx.fiber.dispose()
+  })
+  ctx.provide('sessions', sessionStore)
+  const summary = listed[session.sessionId]
+  await sessionStore.add({ id: session.sessionId, ...opening, ...summary === undefined ? {} : { summary } })
+  for (const [id, summary] of Object.entries(listed)) {
+    if (id !== session.sessionId) await sessionStore.add({ id, summary })
+  }
+  const owner = sessionStore.retainFor(ctx, session.sessionId)
   const fiber = ctx.plugin({ inject: [...inject], apply })
   await fiber.await()
   if (source === undefined) throw new Error('reference source was not registered')
-  return { ctx, fiber, source }
+  return { ctx, fiber, source, sessions: sessionStore, owner }
 }
 
 describe('apply', () => {
@@ -150,6 +163,68 @@ describe('apply', () => {
 })
 
 describe('candidates', () => {
+  it('waits for initial history before both lookups and releases its reference after they settle', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const response = Promise.withResolvers<RemoteEnvelope<FileReferenceCandidate[]>>()
+    const files = vi.fn(() => response.promise)
+    const lookup = vi.fn(() => Promise.resolve({ ok: true as const, value: [] }))
+    const b = await bench(files, lookup, {}, { initialOpen: () => opened.promise })
+    try {
+      const pending = b.source.candidates(session, request(''))
+      expect(b.sessions.retainInfo(session.sessionId).getSnapshot().retainedBy.referenceCandidates).toBe(1)
+      expect(files).not.toHaveBeenCalled()
+      expect(lookup).not.toHaveBeenCalled()
+      opened.resolve(undefined)
+      await vi.waitFor(() => { expect(files).toHaveBeenCalledOnce() })
+      expect(lookup).toHaveBeenCalledOnce()
+      expect(b.sessions.retainInfo(session.sessionId).getSnapshot().referenceCount).toBe(2)
+      response.resolve({ ok: true, value: [] })
+      await expect(pending).resolves.toEqual([])
+      expect(b.sessions.retainInfo(session.sessionId).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      opened.resolve(undefined)
+      response.resolve({ ok: true, value: [] })
+    }
+  })
+
+  it.each([true, false])('refuses an unsuccessful history open (reported error: %s)', async (reported) => {
+    const error = new RemoteError('gateway/internal', 'history unavailable', {})
+    const files = vi.fn(() => Promise.resolve({ ok: true as const, value: [] }))
+    const lookup = vi.fn(() => Promise.resolve({ ok: true as const, value: [] }))
+    const b = await bench(files, lookup, {}, { snapshot: { openState: 'error', openError: reported ? error : null } })
+    await expect(b.source.candidates(session, request(''))).rejects.toThrow(reported ? 'history unavailable' : 'is not open')
+    expect(files).not.toHaveBeenCalled()
+    expect(lookup).not.toHaveBeenCalled()
+    expect(b.sessions.retainInfo(session.sessionId).getSnapshot().referenceCount).toBe(1)
+  })
+
+  it('does not reopen a released Session for candidates', async () => {
+    const b = await bench()
+    b.owner.release()
+    await expect(b.source.candidates(session, request(''))).rejects.toThrow('require a retained session')
+    expect(b.sessions.binding(session.sessionId)).toBeUndefined()
+  })
+
+  it('cancels a query waiting for history without starting either lookup', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const controller = new AbortController()
+    const files = vi.fn(() => Promise.resolve({ ok: true as const, value: [] }))
+    const lookup = vi.fn(() => Promise.resolve({ ok: true as const, value: [] }))
+    const b = await bench(files, lookup, {}, { initialOpen: () => opened.promise })
+    try {
+      const pending = b.source.candidates(session, request('', { signal: controller.signal }))
+      const reason = new Error('query cancelled')
+      const rejected = expect(pending).rejects.toBe(reason)
+      controller.abort(reason)
+      await rejected
+      expect(files).not.toHaveBeenCalled()
+      expect(lookup).not.toHaveBeenCalled()
+      expect(b.sessions.retainInfo(session.sessionId).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      opened.resolve(undefined)
+    }
+  })
+
   it('starts both Remote lookups together and renders files before sessions with stable labels', async () => {
     let releaseFiles!: () => void
     let releaseSessions!: () => void
@@ -194,7 +269,7 @@ describe('candidates', () => {
     }))
     const { source } = await bench(files, sessions, { source: { updatedAt: UPDATED_AT } })
     const pending = source.candidates(session, request('re'))
-    expect(files).toHaveBeenCalledTimes(1)
+    await vi.waitFor(() => { expect(files).toHaveBeenCalledTimes(1) })
     expect(sessions).toHaveBeenCalledTimes(1)
     releaseSessions()
     releaseFiles()
@@ -269,9 +344,13 @@ describe('candidates', () => {
 
   it('drops a completed result when the query signal was superseded', async () => {
     const controller = new AbortController()
-    const { source } = await bench()
+    const gate = Promise.withResolvers<RemoteEnvelope<FileReferenceCandidate[]>>()
+    const files = vi.fn(() => gate.promise)
+    const { source } = await bench(files)
     const pending = source.candidates(session, request('', { signal: controller.signal }))
+    await vi.waitFor(() => { expect(files).toHaveBeenCalledOnce() })
     controller.abort()
+    gate.resolve({ ok: true, value: [] })
     await expect(pending).resolves.toEqual([])
   })
 
diff --git a/packages/client/ui-session/tests/ui-session.client.spec.ts b/packages/client/ui-session/tests/ui-session.client.spec.ts
index 4fe28d1abf..a91f0e2b9c 100644
--- a/packages/client/ui-session/tests/ui-session.client.spec.ts
+++ b/packages/client/ui-session/tests/ui-session.client.spec.ts
@@ -54,7 +54,6 @@ function createSessionsBench(ctx: Context): SessionsBench {
     byId: {},
     phase: 'ready',
     projectionsBySession: {},
-    jobsBySession: {},
   })
   const bindings = new Map<SessionId, SessionBinding>()
   const scopes = new Map<SessionId, Context>()
diff --git a/packages/client/ui-settings-general/README.i18n.yaml b/packages/client/ui-settings-general/README.i18n.yaml
index a485e99405..c5b1574510 100644
--- a/packages/client/ui-settings-general/README.i18n.yaml
+++ b/packages/client/ui-settings-general/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-settings-general/README.md
-README.md: cf8bb5a75aa90842108646b57ceec67ada8ae711
-README.zh.md: 7df3eee13df7bd041cc5f09288d1b7fe28acded6
+README.md: e06ecf5f36234f634cbff708f592fbe83c9f175e
+README.zh.md: 6eb54b49a7a7f1a55a6f9389c57f736533715185
diff --git a/packages/client/ui-settings-general/README.md b/packages/client/ui-settings-general/README.md
index cf8bb5a75a..e06ecf5f36 100644
--- a/packages/client/ui-settings-general/README.md
+++ b/packages/client/ui-settings-general/README.md
@@ -27,13 +27,17 @@ Use this package to give the dsh web client a Settings panel, connection-recover
 
 Users reach the shell through the sidebar's bottom Settings control; feature plugins contribute their pages and onboarding steps through the slot ledgers this shell projects. In both the expanded sidebar and collapsed rail, the control exposes the localized Settings label as its accessible name. A pale-yellow **Disconnected** action beside Settings indicates browser offline suspension; its permanent retry glyph marks the retry action, which the Chinese outage copy also names (连接异常，刷新重试). Every recovery attempt shows the shared ongoing loader beside **Reconnecting** with one to three dots advancing every 500ms, and an attempt stays visible for at least 800ms so brief retries do not flicker. Selecting either yellow state starts an immediate retry; press feedback stays within the warning palette. Recovery changes the region to pale-green **Connected** for two seconds from the moment the green pill becomes visible. The pill fades in on appearance, fades out over 150ms on removal, and sizes to its current label. Initial startup and uninterrupted healthy operation remain silent. The shell renders the modal panel, the navigation built from `settings.section` entries, and exactly one mounted onboarding step at a time.
 
+When the section navigation exceeds the panel's available height, the list scrolls independently of the settings content and keeps the Settings title fixed.
+
 In Desktop, the account-row update control shows availability, progress, verification, readiness, and persistent retry feedback. The preload carries semantic phase, version, progress, and classified failures; the component resolves every visible and accessible string from the active `settings` locale, including after an in-application language change. Selecting an available update starts downloading; installation requires a separate shell-owned confirmation. A collapsed sidebar shows the same status as a dot on its top expand button. Connection feedback takes priority except during shell-reported installation, when the expected backend disconnect must not hide update status. Failure restores connection feedback. Both controls share one carrier subscription; browser code cannot choose packages or authorize installation. [Desktop updates](../../../apps/desktop/README.md) owns the release workflow.
 
 ### The General section
 
+The current release version appears at the bottom of General Settings in Web and Desktop, using the build’s `DSH_CLIENT_VERSION` metadata and the active language. Partial builds without version metadata omit the row.
+
 The Developer tools switch controls the shared preference described by [ui-settings](../ui-settings/README.md#use-this-package). It is available in both Web and desktop, follows accepted changes immediately, and disables duplicate input while a write settles. A failed write displays localized retry guidance.
 
-The General section holds the built-in Developer tools row and rows registered into `settings.general.item` by feature packages. Each registrant owns its row copy and behavior. The Appearance row, for example, lives in ui-theme.
+The General section holds the built-in Developer tools and Current version rows alongside rows registered into `settings.general.item` by feature packages. Each registrant owns its row copy and behavior. The Appearance row, for example, lives in ui-theme.
 
 ### Opening the configuration file
 
@@ -51,7 +55,7 @@ The onboarding ledger projects in ascending order and mounts exactly one step at
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-The shell owns the chrome and the projections; it contributes the Developer tools row, while feature registrants own their additional content and copy.
+The shell owns the chrome and the projections; it contributes the Developer tools and Current version rows, while feature registrants own their additional content and copy.
 
 ### Ledger projections
 
@@ -102,7 +106,8 @@ None; this package neither assembles nor sends a provider request.
 
 These limits define what the shell itself provides versus what features must supply; they are current package constraints.
 
-- **Additional General rows require their feature plugins** — the shell supplies Developer tools; feature plugins supply the remaining preferences.
+- **Additional General rows require their feature plugins** — the shell supplies Developer tools and Current version; feature plugins supply the remaining preferences.
+- **The Windows caption badge keeps a side-opening bubble** — `DesktopUpdateBadge` occupies `sidebar.toggle.badge` in the caption and requests `side="right"`, so the Desktop-owned menu text can cover its bubble while the sidebar is collapsed on Windows; the sidebar toggle and New Session bubbles open below the caption instead (#4688).
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/client/ui-settings-general/README.zh.md b/packages/client/ui-settings-general/README.zh.md
index 7df3eee13d..6eb54b49a7 100644
--- a/packages/client/ui-settings-general/README.zh.md
+++ b/packages/client/ui-settings-general/README.zh.md
@@ -27,13 +27,17 @@ kind: "package-reference"
 
 用户通过侧边栏底部的 Settings 控件进入外壳；功能插件通过本外壳所投影的 slot 账本贡献自己的页面与引导步骤。在展开侧边栏和收起轨道中，该控件都会把本地化的 Settings 文案作为其可访问名称。Settings 右侧浅黄色的**连接异常**操作表示浏览器离线暂停；其常驻重试图形与中文文案「连接异常，刷新重试」都指明重试动作。每次恢复尝试都显示共享 ongoing loading 加**重新连接中**，其后一至三个点每 500ms 前进一次，且每次尝试至少可见 800ms，短暂重试不会闪动。选中任一黄色状态都会立即发起重试；按压反馈留在黄色色阶内。恢复后该区域变为浅绿色的**连接成功**，从绿色药丸可见起驻留 2 秒再消失。药丸出现时淡入、移除时以 150ms 淡出，宽度随当前文案自适应。首次启动与未曾中断的健康连接保持静默。外壳渲染模态面板、由 `settings.section` 条目构建的导航，以及每次只挂载一个的引导步骤。
 
+当分区导航超出面板可用高度时，列表独立于设置内容滚动，并保持「设置」标题固定。
+
 在 Desktop 中，账户行更新控件显示可用版本、进度、验证、就绪和持久重试反馈。预加载仅传递语义化阶段、版本、进度和失败类别；组件从当前 `settings` locale 解析全部可见与无障碍文案，并在应用内语言变化后同步更新。选择可用更新即开始下载；安装需要独立的壳拥有的确认。侧栏收起时，其顶部展开按钮以圆点显示相同状态。连接反馈通常优先展示，但壳报告正在安装时，预期的后端断开不能遮盖更新状态；失败后恢复连接反馈。两个控件共用一次载体订阅；浏览器代码不能选择安装包或授权安装。[Desktop 更新](../../../apps/desktop/README.zh.md)负责发布流程。
 
 ### 「通用」分区
 
+Web 与桌面端的通用设置底部显示当前发布版本，使用构建注入的 `DSH_CLIENT_VERSION` 元数据和当前语言。缺少版本元数据的局部构建不显示该行。
+
 开发者工具开关控制 [ui-settings](../ui-settings/README.zh.md#use-this-package) 定义的共享偏好。Web 和桌面端均提供此开关，立即跟随已接受的变更，并在写入完成前禁用重复输入。写入失败时显示本地化的重试提示。
 
-「通用」分区承载内置的开发者工具行和功能包注册进 `settings.general.item` 的行。每个注册方拥有自己的行文案与行为。例如「外观」行位于 ui-theme。
+「通用」分区承载内置的开发者工具行与当前版本行，以及功能包注册进 `settings.general.item` 的行。每个注册方拥有自己的行文案与行为。例如「外观」行位于 ui-theme。
 
 ### 打开配置文件
 
@@ -51,7 +55,7 @@ kind: "package-reference"
 <details>
 <summary>实现细节——点击展开</summary>
 
-外壳拥有界面框架与投影，并提供开发者工具行；功能注册方拥有其余内容与文案。
+外壳拥有界面框架与投影，并提供开发者工具行与当前版本行；功能注册方拥有其余内容与文案。
 
 ### 账本投影
 
@@ -102,7 +106,8 @@ kind: "package-reference"
 
 这些限制说明外壳自身提供什么、功能包必须提供什么；它们是当前包约束。
 
-- **额外的通用设置行需要相应功能插件**：外壳提供开发者工具；功能插件提供其他偏好。
+- **额外的通用设置行需要相应功能插件**：外壳提供开发者工具与当前版本；功能插件提供其他偏好。
+- **Windows 顶栏徽标的气泡仍向右展开**：`DesktopUpdateBadge` 占用顶栏的 `sidebar.toggle.badge` 且请求 `side="right"`，侧栏收起时其气泡会被 Desktop 菜单文字遮挡；侧栏开关与新建会话的气泡则改在顶栏下方展开（#4688）。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/client/ui-settings-general/package.json b/packages/client/ui-settings-general/package.json
index b0d0e950b6..7e2ce5978b 100644
--- a/packages/client/ui-settings-general/package.json
+++ b/packages/client/ui-settings-general/package.json
@@ -22,6 +22,9 @@
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
diff --git a/packages/client/ui-settings-general/src/client/CurrentVersionRow.module.css b/packages/client/ui-settings-general/src/client/CurrentVersionRow.module.css
new file mode 100644
index 0000000000..66f159a3dd
--- /dev/null
+++ b/packages/client/ui-settings-general/src/client/CurrentVersionRow.module.css
@@ -0,0 +1,7 @@
+.row {
+  padding: 16px 0;
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  line-height: 22px;
+  overflow-wrap: anywhere;
+}
diff --git a/packages/client/ui-settings-general/src/client/CurrentVersionRow.tsx b/packages/client/ui-settings-general/src/client/CurrentVersionRow.tsx
new file mode 100644
index 0000000000..e3c8cb702f
--- /dev/null
+++ b/packages/client/ui-settings-general/src/client/CurrentVersionRow.tsx
@@ -0,0 +1,14 @@
+/** Installed release version in General Settings for Web and Desktop. */
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import css from './CurrentVersionRow.module.css'
+
+/**
+ * Render the version embedded by the client build; partial builds without metadata omit the row.
+ * @param props - runtime share and localized copy.
+ * @returns the current release label, or nothing when build metadata is absent.
+ */
+export function CurrentVersionRow({ t }: PropsRuntime<'settings.general.item'> & PropsLocale<'settings'>) {
+  const version = process.env.DSH_CLIENT_VERSION
+  if (version === undefined) return null
+  return <div className={css.row}>{t('general.currentVersion', { version })}</div>
+}
diff --git a/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx b/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx
index 4ee64a0f34..b4b10350a3 100644
--- a/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx
+++ b/packages/client/ui-settings-general/src/client/DesktopUpdateIndicator.tsx
@@ -2,7 +2,7 @@
 import { IconDownloadOutlineRegular, IconLoadingOutlineRegular, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import css from './DesktopUpdateIndicator.module.css'
-import type { DesktopUpdateFailureKind, DesktopUpdatePresentation, DesktopUpdateView } from './desktop-update-bridge.ts'
+import type { DesktopUpdateFailureKind, DesktopUpdatePresentation, DesktopUpdateView } from '../types.ts'
 import type { SettingsRootInjected } from './shell-contract.ts'
 
 type SettingsTranslate = PropsLocale<'settings'>['t']
diff --git a/packages/client/ui-settings-general/src/client/SettingsRoot.module.css b/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
index 783eea44a9..8e7569b3ca 100644
--- a/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
+++ b/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
@@ -79,7 +79,7 @@
    One height for every section, taken from the viewport rather than the
    content: sections differ by hundreds of pixels (a settings list against the
    composition editor), and a content-sized panel would resize under the
-   pointer on every nav click. Whatever does not fit scrolls in `.options`.
+   pointer on every nav click. The navigation and options scroll independently.
    24px of air above and below, widened to the frame's published top clearance
    (the macOS window strip, where clicks drag the window) on both sides so the
    panel sits centered and clear of the strip. */
@@ -129,6 +129,7 @@
   display: flex;
   flex-direction: column;
   gap: 4px;
+  overflow-y: auto;
 }
 
 /* Nav cell (figma .Setting-nav-cell 501:29962): 164x40, r12, pad
diff --git a/packages/client/ui-settings-general/src/client/desktop-update-source.ts b/packages/client/ui-settings-general/src/client/desktop-update-source.ts
index 7b34bf0efb..9b30244c1c 100644
--- a/packages/client/ui-settings-general/src/client/desktop-update-source.ts
+++ b/packages/client/ui-settings-general/src/client/desktop-update-source.ts
@@ -1,6 +1,6 @@
 /** Client-owned observation of the optional Desktop preload. */
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type { DesktopUpdateBridge, DesktopUpdateView } from './desktop-update-bridge.ts'
+import type { DesktopUpdateBridge, DesktopUpdateView } from '../types.ts'
 
 /** Owns one preload subscription across both sidebar locations. */
 export class DesktopUpdateSource {
diff --git a/packages/client/ui-settings-general/src/client/index.ts b/packages/client/ui-settings-general/src/client/index.ts
index 442ebc0c14..77c321001d 100644
--- a/packages/client/ui-settings-general/src/client/index.ts
+++ b/packages/client/ui-settings-general/src/client/index.ts
@@ -25,10 +25,11 @@ import type {
 } from './shell-contract.ts'
 import { SettingsRoot } from './SettingsRoot.tsx'
 import { DesktopUpdateBadge } from './DesktopUpdateIndicator.tsx'
-import type { DesktopUpdateBridge } from './desktop-update-bridge.ts'
+import type { DesktopUpdateBridge } from '../types.ts'
 import { DesktopUpdateSource } from './desktop-update-source.ts'
 import { CloseLabel, HeaderContent, TriggerContent } from './chrome.tsx'
 import { GeneralSection } from './GeneralSection.tsx'
+import { CurrentVersionRow } from './CurrentVersionRow.tsx'
 import { DeveloperToolsRow, type DeveloperToolsRowInjected } from './DeveloperToolsRow.tsx'
 import { SettingsDocumentAction } from './SettingsDocumentAction.tsx'
 import type { SettingsDocumentActionInjected } from './SettingsDocumentAction.tsx'
@@ -76,6 +77,10 @@ export function apply(ctx: ClientContext): void {
       setEnabled: enabled => ctx.settingsScope.developerTools.setEnabled(enabled),
     }),
   }, DeveloperToolsRow))
+  // Last row: every feature-registered preference row orders below 100.
+  ctx.slots.inject('settings.general.item', () => ctx.slots.register({
+    name: 'settings.general.item', id: 'current-version', order: 100, locale: NS,
+  }, CurrentVersionRow))
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-settings-general: dictionaries')
   const connection = ctx.get('connection') as ConnectionHandle
   const carrier = (globalThis as typeof globalThis & { dshDesktop?: { protocolVersion: number; updates?: DesktopUpdateBridge } }).dshDesktop
diff --git a/packages/client/ui-settings-general/src/client/locales.ts b/packages/client/ui-settings-general/src/client/locales.ts
index e906f1714c..9608a28152 100644
--- a/packages/client/ui-settings-general/src/client/locales.ts
+++ b/packages/client/ui-settings-general/src/client/locales.ts
@@ -26,6 +26,7 @@ export const zh = {
   'openDocument': '打开配置文件',
   'openDocument.error': '无法打开配置文件',
   'general.nav': '通用设置',
+  'general.currentVersion': '当前版本：{version}',
   'developerTools.title': '开发者工具',
   'developerTools.error': '保存失败，请重试',
   'developerTools.description': '显示用于调试和排查问题的工具与信息',
@@ -65,6 +66,7 @@ export const en = {
   'openDocument': 'Open configuration file',
   'openDocument.error': 'Could not open configuration file',
   'general.nav': 'General',
+  'general.currentVersion': 'Current version: {version}',
   'developerTools.title': 'Developer tools',
   'developerTools.error': 'Could not save. Please try again.',
   'developerTools.description': 'Show tools and information for debugging and troubleshooting',
diff --git a/packages/client/ui-settings-general/src/client/shell-contract.ts b/packages/client/ui-settings-general/src/client/shell-contract.ts
index bc8497361b..9f2690ac96 100644
--- a/packages/client/ui-settings-general/src/client/shell-contract.ts
+++ b/packages/client/ui-settings-general/src/client/shell-contract.ts
@@ -15,7 +15,7 @@ import type {
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
 // Type-only: pulls the settings slot declarations the shell renders into.
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
-import type { DesktopUpdateView } from './desktop-update-bridge.ts'
+import type { DesktopUpdateView } from '../types.ts'
 
 /** One nav row projected from a settings.section registration's options. */
 export interface SettingsSectionRow {
diff --git a/packages/client/ui-settings-general/src/client/desktop-update-bridge.ts b/packages/client/ui-settings-general/src/types.ts
similarity index 91%
rename from packages/client/ui-settings-general/src/client/desktop-update-bridge.ts
rename to packages/client/ui-settings-general/src/types.ts
index 82eda22079..f9dae34f87 100644
--- a/packages/client/ui-settings-general/src/client/desktop-update-bridge.ts
+++ b/packages/client/ui-settings-general/src/types.ts
@@ -1,4 +1,4 @@
-/** Optional Electron preload declarations consumed by the settings row. */
+/** Type-only Electron update declarations shared by the settings UI and Desktop compatibility checks. */
 
 /** Classified failure copy selected by the Web locale without exposing raw updater diagnostics. */
 export type DesktopUpdateFailureKind =
diff --git a/packages/client/ui-settings-general/tests/apply.client.spec.ts b/packages/client/ui-settings-general/tests/apply.client.spec.ts
index 1d11e8ea30..ab2e3c5415 100644
--- a/packages/client/ui-settings-general/tests/apply.client.spec.ts
+++ b/packages/client/ui-settings-general/tests/apply.client.spec.ts
@@ -102,7 +102,7 @@ describe('ui-settings-general apply', () => {
     expect(generalLabel(c)).toBe('通用设置')
     expect(c.ctx.slots.spec('settings.general.item')).toEqual({ kind: 'list', scope: 'root' })
     // The shared developer-tool control belongs to General; onboarding remains feature-owned.
-    expect(c.ctx.slots.entries('settings.general.item').filter(row => row.locale === NS).map(row => row.options.id)).toEqual(['developer-tools'])
+    expect(c.ctx.slots.entries('settings.general.item').filter(row => row.locale === NS).map(row => row.options.id)).toEqual(['developer-tools', 'current-version'])
     expect(c.ctx.slots.entries('settings.onboarding').filter(row => row.locale === NS)).toEqual([])
     const developerRow = c.ctx.slots.entries('settings.general.item').find(row => row.options.id === 'developer-tools')!
     const developer = (developerRow.inject as unknown as () => DeveloperToolsRowInjected)()
@@ -213,7 +213,7 @@ describe('ui-settings-general apply', () => {
       expect(ownEntries(c, name)[0]).not.toBe(before[index])
     })
     expect(c.ctx.slots.spec('settings.general.item')).toEqual({ kind: 'list', scope: 'root' })
-    expect(c.ctx.slots.entries('settings.general.item').filter(row => row.locale === NS).map(row => row.options.id)).toEqual(['developer-tools'])
+    expect(c.ctx.slots.entries('settings.general.item').filter(row => row.locale === NS).map(row => row.options.id)).toEqual(['developer-tools', 'current-version'])
     // The recovered registrations still ride the locale path.
     const english = localeView('en', 1)
     const chinese = localeView('zh', 2)
@@ -237,6 +237,7 @@ describe('ui-settings-general apply', () => {
     await c.unload(SELF)
     await c.flush()
     for (const [name] of SEATS) expect(ownEntries(c, name)).toHaveLength(0)
+    expect(c.ctx.slots.entries('settings.general.item').filter(row => row.locale === NS)).toEqual([])
     expect(c.ctx.slots.spec('settings.general.item')).toBeUndefined()
   })
 })
diff --git a/packages/client/ui-settings-general/tests/components.client.spec.tsx b/packages/client/ui-settings-general/tests/components.client.spec.tsx
index 89c78fe1af..e81254d0bc 100644
--- a/packages/client/ui-settings-general/tests/components.client.spec.tsx
+++ b/packages/client/ui-settings-general/tests/components.client.spec.tsx
@@ -22,11 +22,12 @@ function derivedDocumentStore(remote: object) {
   const ctx = { remote } as never
   return new SettingsDocumentStore(ctx, new SettingsDescribeMirror(ctx))
 }
-import { en } from '../src/client/locales.ts'
+import { en, zh } from '../src/client/locales.ts'
+import { CurrentVersionRow } from '../src/client/CurrentVersionRow.tsx'
 import { DesktopUpdateBadge } from '../src/client/DesktopUpdateIndicator.tsx'
-import type { DesktopUpdateView } from '../src/client/desktop-update-bridge.ts'
+import type { DesktopUpdateView } from '../src/types.ts'
 
-afterEach(cleanup)
+afterEach(() => { cleanup(); vi.unstubAllEnvs() })
 
 // The seat's key domain is settings ∪ common; the stub answers from the
 // package dictionary and falls back to the key like the real chain.
@@ -222,3 +223,26 @@ it('reports a failed developer-tool write and allows retry', async () => {
   await waitFor(() => { expect(toggle.getAttribute('aria-checked')).toBe('true') })
   expect(screen.queryByRole('alert')).toBeNull()
 })
+
+describe('current version', () => {
+  it.each([
+    ['Current version: 1.2.3-rc.4', en],
+    ['当前版本：1.2.3-rc.4', zh],
+  ])('renders the localized release label %s', (expected, dictionary) => {
+    vi.stubEnv('DSH_CLIENT_VERSION', '1.2.3-rc.4')
+    const translate: TriggerContentProps['t'] = (key, params) => {
+      let text = (dictionary as Record<string, string>)[key] ?? key
+      for (const [name, value] of Object.entries(params ?? {})) text = text.replace(`{${name}}`, String(value))
+      return text
+    }
+    render(<CurrentVersionRow {...kit} t={translate} />)
+    expect(screen.getByText(expected)).toBeTruthy()
+    expect(screen.queryByRole('button')).toBeNull()
+  })
+
+  it('omits the row when a partial build has no version metadata', () => {
+    vi.stubEnv('DSH_CLIENT_VERSION', undefined)
+    const view = render(<CurrentVersionRow {...kit} t={t} />)
+    expect(view.container.textContent).toBe('')
+  })
+})
diff --git a/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx b/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx
index 316204370d..b16119a527 100644
--- a/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx
+++ b/packages/client/ui-settings-general/tests/desktop-update.client.spec.tsx
@@ -4,7 +4,7 @@ import { useSyncExternalStore } from 'react'
 import { afterEach, expect, it, vi } from 'vitest'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import { DesktopUpdateIndicator } from '../src/client/DesktopUpdateIndicator.tsx'
-import type { DesktopUpdateBridge, DesktopUpdatePresentation } from '../src/client/desktop-update-bridge.ts'
+import type { DesktopUpdateBridge, DesktopUpdatePresentation } from '../src/types.ts'
 import { DesktopUpdateSource } from '../src/client/desktop-update-source.ts'
 import { en, zh } from '../src/client/locales.ts'
 
diff --git a/packages/client/ui-settings-general/tests/host.client.spec.ts b/packages/client/ui-settings-general/tests/index.host.spec.ts
similarity index 100%
rename from packages/client/ui-settings-general/tests/host.client.spec.ts
rename to packages/client/ui-settings-general/tests/index.host.spec.ts
diff --git a/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx b/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx
index 74a5b22cfb..aa270b6fea 100644
--- a/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx
+++ b/packages/client/ui-settings-general/tests/settings-root.client.spec.tsx
@@ -9,7 +9,7 @@ import { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SettingsRootComponentProps } from '../src/client/shell-contract.ts'
 import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
 import { en, zh } from '../src/client/locales.ts'
-import type { DesktopUpdateView } from '../src/client/desktop-update-bridge.ts'
+import type { DesktopUpdateView } from '../src/types.ts'
 
 // Every fixture carries the resource hook the resources plugin merges into GlobalStandardProps.
 const useResource = (() => ({ status: 'none' as const, value: undefined, failure: undefined, reload: () => {} })) as GlobalStandardProps['useResource']
@@ -88,7 +88,7 @@ function mount({
         updatedAt: 0,
       },
     },
-    phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+    phase: 'ready', projectionsBySession: {},
   }
   const unusedHook = (() => { throw new Error('unused by SettingsRoot') }) as never
   const props: SettingsRootComponentProps = {
diff --git a/packages/client/ui-settings-general/tests/shell.client.spec.ts b/packages/client/ui-settings-general/tests/shell.client.spec.ts
index f0ed057d43..2f4c9a6714 100644
--- a/packages/client/ui-settings-general/tests/shell.client.spec.ts
+++ b/packages/client/ui-settings-general/tests/shell.client.spec.ts
@@ -11,7 +11,7 @@ import { createClientTest, type TestClient, webApp } from '@deepseek-ai/dsh-clie
 import { inject } from '../src/client/index.ts'
 import type { SettingsRootInjected } from '../src/client/shell-contract.ts'
 import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
-import type { DesktopUpdatePresentation } from '../src/client/desktop-update-bridge.ts'
+import type { DesktopUpdatePresentation } from '../src/types.ts'
 
 const SELF = '@deepseek-ai/dsh-client-ui-settings-general'
 const SIDEBAR = '@deepseek-ai/dsh-client-ui-sidebar'
diff --git a/packages/client/ui-settings-general/tsconfig.client.json b/packages/client/ui-settings-general/tsconfig.client.json
new file mode 100644
index 0000000000..aa580faf19
--- /dev/null
+++ b/packages/client/ui-settings-general/tsconfig.client.json
@@ -0,0 +1,28 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "include": [
+    "src/client",
+    "src/types.ts",
+    "src/css-modules.d.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../ui-slots" },
+    { "path": "../ui-primitives" },
+    { "path": "../ui-renderer" },
+    { "path": "../ui-session" },
+    { "path": "../store" },
+    { "path": "../ui-settings" },
+    { "path": "../locale" },
+    { "path": "../connection/tsconfig.client.json" },
+    { "path": "../../settings/settings" },
+    { "path": "../../api/remotes/tsconfig.client.json" },
+    { "path": "../ui-sidebar" }
+  ]
+}
diff --git a/packages/client/ui-settings-general/tsconfig.host.json b/packages/client/ui-settings-general/tsconfig.host.json
new file mode 100644
index 0000000000..466d8deab2
--- /dev/null
+++ b/packages/client/ui-settings-general/tsconfig.host.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/index.ts",
+    "src/types.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../settings/settings" }
+  ]
+}
diff --git a/packages/client/ui-settings-general/tsconfig.json b/packages/client/ui-settings-general/tsconfig.json
index a0984445cd..2a0b0e33f7 100644
--- a/packages/client/ui-settings-general/tsconfig.json
+++ b/packages/client/ui-settings-general/tsconfig.json
@@ -1,51 +1,7 @@
 {
-  "extends": "../../../tsconfig.base.client.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
+  "files": [],
   "references": [
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../../vendor/schemastery"
-    },
-    {
-      "path": "../ui-slots"
-    },
-    {
-      "path": "../ui-primitives"
-    },
-    {
-      "path": "../ui-renderer"
-    },
-    {
-      "path": "../ui-session"
-    },
-    {
-      "path": "../store"
-    },
-    {
-      "path": "../ui-settings"
-    },
-    {
-      "path": "../locale"
-    },
-    {
-      "path": "../connection/tsconfig.client.json"
-    },
-    {
-      "path": "../../settings/settings"
-    },
-    {
-      "path": "../../api/remotes/tsconfig.client.json"
-    },
-    {
-      "path": "../ui-sidebar"
-    }
+    { "path": "./tsconfig.host.json" },
+    { "path": "./tsconfig.client.json" }
   ]
 }
diff --git a/packages/client/ui-settings-models/README.i18n.yaml b/packages/client/ui-settings-models/README.i18n.yaml
index c3c33c6f90..45e2289a24 100644
--- a/packages/client/ui-settings-models/README.i18n.yaml
+++ b/packages/client/ui-settings-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-settings-models/README.md
-README.md: c1567814b5de39f9b8819fcc8848e36c0a6ff842
-README.zh.md: baa0f02e8274a7146f9eade36d3ad464ac944b27
+README.md: fa9be2ef8d7b08e064c3ee5e7517e59013b7f5e1
+README.zh.md: 2974524fba91642aebd31cd155a6495989cb3eaf
diff --git a/packages/client/ui-settings-models/README.md b/packages/client/ui-settings-models/README.md
index c1567814b5..fa9be2ef8d 100644
--- a/packages/client/ui-settings-models/README.md
+++ b/packages/client/ui-settings-models/README.md
@@ -37,13 +37,13 @@ The primary field on an editor card is a single **API key** input — the page n
 
 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. Profile `headers` remain deployment configuration in `settings.yaml` or Cordis config and have no Models-page editor. 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 the editable fields: it is a per-model capability, so a provider-scoped control could only be set to a value some models reject. Each model row edits `id`, optional display `name`, optional `contextWindow`/`maxTokens`, and input types; unrelated model fields survive edits.
 
-The DeepSeek card edits the shared `llm-deepseek` endpoint, credentials, and model catalog without a protocol selector. When Cordis YAML selects Messages, the public endpoint placeholder is `https://api.deepseek.com/anthropic`. Saving the card preserves protocol configuration.
+The DeepSeek card edits the `llm-deepseek` endpoint, credentials, and model catalog. It uses Messages, with the default endpoint placeholder `https://api.deepseek.com/anthropic`.
 
 Expand **Customized settings → Model options** to edit each model. Both provider families share the same row layout, labels, and icons: context window and max output tokens occupy two columns, and **Input types** occupies a separate row with **Text** and **Image** checkboxes. A row without an input declaration displays the installed model’s input types, then the provider default, then Text. Known pi-ai providers load their installed catalog without endpoint I/O; opening a row does not write an override. Explicit input selections take precedence, including text-only overrides of vision models. Checkbox edits save the selected types, with at least one type required. DeepSeek writes `inputModalities`; pi-ai writes `input`. Unchecking Image for DeepSeek also removes `imagePixelBudget` and `imageMaxBytes`, because the adapter rejects those limits without image input. Clearing the input field in `settings.yaml` restores adapter inheritance; **Restore default models** resets the entire catalog override. Declare only input types the upstream model can actually process.
 
 ### Adding and deleting providers
 
-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. **Add a custom provider** declares a route pi-ai does not ship; the create card asks for a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model, because nothing can default those. The endpoint placeholder follows the selected protocol: OpenAI Chat Completions and Responses show `https://gateway.example/v1`, while Anthropic Messages shows `https://gateway.example` because its SDK appends `/v1/messages`. Changing the protocol preserves any address already entered. The endpoint must be a parseable HTTP or HTTPS URL; localhost, IPv4 and IPv6 literals, and custom ports remain valid. A syntax error blocks both discovery and creation at the field, while a request failure remains a separate provider error. **Fetch available models** asks the `llm/discoverModels` Remote about the endpoint the form shows, so adding a provider is one pass instead of save-then-return; the reply opens a searchable picker rather than being written, and nothing is written until **Add selected**. Each selected candidate copies its id, display name, context window, output-token cap, and disclosed input types into the editable row when disclosed, while an existing row retains its user-tuned values. Search matches model ids and optional display names without clearing hidden selections. **Select all** adds the visible results, while **Deselect all** clears the entire selection so hidden results cannot be adopted accidentally. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its confirmation dialog names the provider.
+**Add model provider** is the one entry to the add card, offered while any editor-backed settings namespace is mounted and enabled while either mode below can proceed. The card opens on a segmented mode switch with a one-line purpose beneath it: **Third-party model provider** carries the dormant-directory provider select over the provider editor — a bare-mounted `llm-pi-ai` offers its whole installed catalog before any route exists — and **Custom model API** carries the create form for a route pi-ai does not ship: a relay, a self-hosted server, or any other OpenAI- or Anthropic-compatible endpoint. A mode is offered only while its namespace is mounted; with one mode the card shows that form alone under the mode's name, and a mode whose namespace has nothing left to adopt or no protocol to declare is disabled with the reason as its hover text. A panel mounts the first time its mode is shown and stays mounted, hidden, while the card is open and its mode stays offered, so switching modes discards neither draft; the switch locks while either panel has a write or an endpoint interrogation in flight, since a switch underneath one would orphan its answer. Each tab controls its panel through ids, and closing either panel forgets the catalog draft's target. The custom form asks for a unique **Provider ID**, an endpoint, a protocol, and at least one uniquely-identified model, because nothing can default those. The protocol picker names each protocol by its product name — OpenAI Chat Completions, OpenAI Responses, Anthropic Messages — while the stored value stays the schema identifier; a protocol the adapter adds before this page names it shows that identifier. The endpoint placeholder follows the selected protocol: OpenAI Chat Completions and Responses show `https://gateway.example/v1`, while Anthropic Messages shows `https://gateway.example` because its SDK appends `/v1/messages`. Changing the protocol preserves any address already entered. The endpoint must be a parseable HTTP or HTTPS URL; localhost, IPv4 and IPv6 literals, and custom ports remain valid. A syntax error blocks both discovery and creation at the field, while a request failure remains a separate provider error. **Fetch available models** asks the `llm/discoverModels` Remote about the endpoint the form shows, so adding a provider is one pass instead of save-then-return; the reply opens a searchable picker rather than being written, and nothing is written until **Add selected**. Each selected candidate copies its id, display name, context window, output-token cap, and disclosed input types into the editable row when disclosed, while an existing row retains its user-tuned values. Search matches model ids and optional display names without clearing hidden selections. **Select all** adds the visible results, while **Deselect all** clears the entire selection so hidden results cannot be adopted accidentally. A row is deletable only when the user layer alone carries it (removal restores the composition base), and its confirmation dialog names the provider.
 
 ### First-run dialogs
 
@@ -110,7 +110,8 @@ These limits define the editor's field coverage and the page's reach; they are c
 
 - **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. Retry policy, timeouts, DeepSeek model descriptions, and other advanced fields remain in `settings.yaml`; existing model fields the editor does not show are preserved.
 - **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.
+- **Only pi-ai routes can be hand-declared** — the custom-API form 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.
+- **The catalog select lists route identifiers** — `moonshotai`, `zai`, and the other pi-ai catalog ids appear as they are, with no product names, aliases, or search. A searchable picker with the custom form as one pinned entry would let the mode switch go; it needs the directory to carry display names first.
 - **Interrogation covers OpenAI-compatible and Anthropic Messages endpoints** — OpenAI protocols accept a standard `data` array or an enriched `models` map, while Anthropic uses its native model-listing route; every other protocol reports that it cannot be asked and its models are entered by hand.
 - **Undeclared live routes render nowhere** — a route registered without a configurable-provider declaration has no settings address; it stays visible in pickers but not on this page's rows.
 
diff --git a/packages/client/ui-settings-models/README.zh.md b/packages/client/ui-settings-models/README.zh.md
index baa0f02e82..2974524fba 100644
--- a/packages/client/ui-settings-models/README.zh.md
+++ b/packages/client/ui-settings-models/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "dsh Web 客户端的模型设置与产品引导插件：提供方行、API 密钥管理、模型列表与 DeepSeek 首次运行弹窗。"
+description: "dsh Web 客户端的模型设置与产品引导插件：提供商行、API 密钥管理、模型列表与 DeepSeek 首次运行弹窗。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-client-ui-settings-models` 是 dsh Web 客户端的 Models 设置页面：用户可以配置 API 密钥（以只写方式存入 profile 的凭据引用之下）、编辑每个提供方的模型列表，并手工声明自定义 pi-ai 路由；页面以提供方行展示，一次只展开一张编辑卡片。该页面把提供方目录、设置文档与凭据描述合并为一个共享快照，因此行的状态在三个方面始终一致。它还会带首次运行的用户走两个有序弹窗——版本化内测声明，以及按条件显示的官方 DeepSeek 凭据步骤。
+`dsh-client-ui-settings-models` 是 dsh Web 客户端的 Models 设置页面：用户可以配置 API 密钥（以只写方式存入 profile 的凭据引用之下）、编辑每个提供商的模型列表，并手工声明自定义 pi-ai 路由；页面以提供商行展示，一次只展开一张编辑卡片。该页面把提供商目录、设置文档与凭据描述合并为一个共享快照，因此行的状态在三个方面始终一致。它还会带首次运行的用户走两个有序弹窗——版本化内测声明，以及按条件显示的官方 DeepSeek 凭据步骤。
 
 ## 目录
 
@@ -25,33 +25,33 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-从设置导航打开 Models 页面，即可看到每个已配置的提供方都有一行。其配置键未在任何位置配置的整分节提供方会渲染为其展开的设置卡片而非一行，但仅限首次运行姿态，且仅持续到用户关闭该卡片为止。每一类卡片各自持有自己的展开状态，因此关掉其中一张绝不会丢弃另一张里的草稿。
+从设置导航打开 Models 页面，即可看到每个已配置的提供商都有一行。其配置键未在任何位置配置的整分节提供商会渲染为其展开的设置卡片而非一行，但仅限首次运行姿态，且仅持续到用户关闭该卡片为止。每一类卡片各自持有自己的展开状态，因此关掉其中一张绝不会丢弃另一张里的草稿。
 
-存在已存储目录错误的提供方仍显示诊断以及编辑、删除入口。添加操作只面向已注册的 settings 命名空间，因此不可用的命名空间不会留下无法打开编辑器的按钮。保存被拒绝时，编辑器保持打开并展示 Host 诊断。
+存在已存储目录错误的提供商仍显示诊断以及编辑、删除入口。添加操作只面向已注册的 settings 命名空间，因此不可用的命名空间不会留下无法打开编辑器的按钮。保存被拒绝时，编辑器保持打开并展示 Host 诊断。
 
 ### API 密钥
 
-编辑卡片上的主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名。键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile，从而保留提供方原生认证（例如 Bedrock 凭据链或 Vertex ADC）。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。
+编辑卡片上的主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名。键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下，profile 没有引用时便派生 `<ROUTE>_API_KEY`，pi-ai profile 会把这次派生记录为 `apiKeyEnv`，因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供商留空密钥会保存一个不带引用的 profile，从而保留提供商原生认证（例如 Bedrock 凭据链或 Vertex ADC）。只有确认引用的凭据已配置时，行才会以绿色实心点标示 API 密钥状态；只有确认具名引用缺失时，才会以红色实心点标示。「应用」成功后会发出本地无障碍状态消息，且绝不回显任何机密内容。
 
-### 编辑提供方
+### 编辑提供商
 
-收起的「自定义设置」折叠区承载精选的额外字段：两个家族都有 `baseURL`（deepseek 的占位符显示公共端点）、各适配器自己的模型目录，以及适配器未提供的 pi-ai 路由的**显示名称**与 **API 协议**。Profile `headers` 仍是 `settings.yaml` 或 Cordis 配置中的部署配置，Models 页面不提供编辑器。Provider ID 保持固定：它是 settings 的键、其他每个 namespace 与每一条已记录会话引用的名字，也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意不在可编辑字段之列：它是按模型的能力，提供方级的控件只可能被设成某些模型会拒绝的值。每个模型行可编辑 `id`、可选显示 `name`、可选 `contextWindow`/`maxTokens` 和输入类型；无关的模型字段在编辑后仍会保留。
+收起的「自定义设置」折叠区承载精选的额外字段：两个家族都有 `baseURL`（deepseek 的占位符显示公共端点）、各适配器自己的模型目录，以及适配器未提供的 pi-ai 路由的**显示名称**与 **API 协议**。Profile `headers` 仍是 `settings.yaml` 或 Cordis 配置中的部署配置，Models 页面不提供编辑器。Provider ID 保持固定：它是 settings 的键、其他每个 namespace 与每一条已记录会话引用的名字，也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意不在可编辑字段之列：它是按模型的能力，提供商级的控件只可能被设成某些模型会拒绝的值。每个模型行可编辑 `id`、可选显示 `name`、可选 `contextWindow`/`maxTokens` 和输入类型；无关的模型字段在编辑后仍会保留。
 
-`llm-deepseek` 的 DeepSeek 卡片编辑共用的端点、凭据和模型目录，不提供协议选择器。Cordis YAML 选择 Messages 时，官方端点占位符为 `https://api.deepseek.com/anthropic`；保存卡片不会改写协议配置。
+`llm-deepseek` 的 DeepSeek 卡片编辑端点、凭据和模型目录。它使用 Messages，默认端点占位符为 `https://api.deepseek.com/anthropic`。
 
-展开**自定义设置 → 模型选项**编辑模型。两个提供方家族共用相同的模型行布局、标签和图标：上下文窗口与最大输出 token 数分为两列，**输入类型**独占下一行，提供**文本**和**图片**复选框。未声明输入类型的模型行优先显示已安装模型的输入类型，其次是提供方默认值，最后回退为文本。已知 pi-ai 提供方会加载已安装目录，不向端点发送请求；打开模型行不会写入覆盖值。显式输入选择具有优先权，包括为视觉模型设置的仅文本覆盖。修改复选框会保存所选类型，且至少保留一种。DeepSeek 写入 `inputModalities`，pi-ai 写入 `input`。DeepSeek 取消勾选图片时，还会移除 `imagePixelBudget` 和 `imageMaxBytes`，因为适配器在没有图片输入时拒绝这些限制。在 `settings.yaml` 中清除输入字段可恢复适配器继承；**恢复默认模型**会重置整个模型目录覆盖。仅声明上游模型实际能够处理的输入类型。
+展开**自定义设置 → 模型选项**编辑模型。两个提供商家族共用相同的模型行布局、标签和图标：上下文窗口与最大输出 token 数分为两列，**输入类型**独占下一行，提供**文本**和**图片**复选框。未声明输入类型的模型行优先显示已安装模型的输入类型，其次是提供商默认值，最后回退为文本。已知 pi-ai 提供商会加载已安装目录，不向端点发送请求；打开模型行不会写入覆盖值。显式输入选择具有优先权，包括为视觉模型设置的仅文本覆盖。修改复选框会保存所选类型，且至少保留一种。DeepSeek 写入 `inputModalities`，pi-ai 写入 `input`。DeepSeek 取消勾选图片时，还会移除 `imagePixelBudget` 和 `imageMaxBytes`，因为适配器在没有图片输入时拒绝这些限制。在 `settings.yaml` 中清除输入字段可恢复适配器继承；**恢复默认模型**会重置整个模型目录覆盖。仅声明上游模型实际能够处理的输入类型。
 
-### 新增与删除提供方
+### 新增与删除提供商
 
-「新增」流程是一张承载休眠目录提供方选择框的卡片——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog。**添加自定义提供方**声明一条 pi-ai 不提供的路由；创建卡片会索要唯一的 **Provider ID**、端点、协议与至少一个可唯一识别的模型，因为没有东西能为它们兜底。端点占位示例随所选协议变化：OpenAI Chat Completions 与 Responses 显示 `https://gateway.example/v1`，Anthropic Messages 显示 `https://gateway.example`，因为其 SDK 会追加 `/v1/messages`。切换协议会保留已输入的地址。端点必须是可解析的 HTTP 或 HTTPS URL；localhost、IPv4 与 IPv6 字面地址以及自定义端口仍然有效。语法错误会在字段处阻止询问与创建，请求失败则继续作为独立的提供方错误显示。**获取可用模型**通过 `llm/discoverModels` Remote 查询表单显示的端点，因此新增提供方一次即可完成，而非先保存再返回；回复打开的是可搜索选择器而非直接写入，只有点击**添加所选**才会写入。每个选中候选会在提供方公布相应信息时，把 id、显示名、上下文窗口、最大输出 token 数和已公布的输入类型复制进可编辑行；已经存在的行保留用户调整过的值。搜索会匹配模型 id 与可选显示名称，且不会清除隐藏项的勾选状态。**全选**会加入可见结果，而**取消全选**会清空全部勾选，以免意外采用隐藏结果。只有用户层单独携带某行时，该行才可删除（删除会恢复组合基线），其确认对话框会指名该提供方。
+**添加模型提供商**是新增卡片的唯一入口：只要任一带编辑器的设置 namespace 已挂载就会出现，下述两种方式任一可继续时才可点击。卡片打开后顶部是分段式的方式切换，下方一行小字说明所选方式的用途：**第三方模型提供商**承载休眠目录提供商选择框与提供商编辑器——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog；**自定义模型 API**承载为 pi-ai 不提供的路由（中转站、自部署服务或其他兼容 OpenAI / Anthropic 协议的接口）准备的创建表单。某种方式只在其 namespace 已挂载时提供；只剩一种方式时卡片以该方式为标题直接显示表单；namespace 已无可采用的提供商或没有可声明的协议时，对应方式会被禁用并把原因作为悬停提示。面板在其方式首次显示时挂载，之后在卡片打开且该方式仍被提供期间保持挂载但隐藏，因此切换方式不会丢掉任何一边的草稿；任一面板有写入或端点探测进行中时滑块锁定，因为此时切换会让结果落到看不见的面板上。每个 tab 通过 id 控制其面板，关闭任一面板都会忘记目录草稿的目标。自定义表单会索要唯一的 **Provider ID**、端点、协议与至少一个可唯一识别的模型，因为没有东西能为它们兜底。协议选择框以产品名称显示各协议——OpenAI Chat Completions、OpenAI Responses、Anthropic Messages——存储的值仍是 schema 标识符；适配器新增而本页尚未命名的协议直接显示其标识符。端点占位示例随所选协议变化：OpenAI Chat Completions 与 Responses 显示 `https://gateway.example/v1`，Anthropic Messages 显示 `https://gateway.example`，因为其 SDK 会追加 `/v1/messages`。切换协议会保留已输入的地址。端点必须是可解析的 HTTP 或 HTTPS URL；localhost、IPv4 与 IPv6 字面地址以及自定义端口仍然有效。语法错误会在字段处阻止询问与创建，请求失败则继续作为独立的提供商错误显示。**获取可用模型**通过 `llm/discoverModels` Remote 查询表单显示的端点，因此新增提供商一次即可完成，而非先保存再返回；回复打开的是可搜索选择器而非直接写入，只有点击**添加所选**才会写入。每个选中候选会在提供商公布相应信息时，把 id、显示名、上下文窗口、最大输出 token 数和已公布的输入类型复制进可编辑行；已经存在的行保留用户调整过的值。搜索会匹配模型 id 与可选显示名称，且不会清除隐藏项的勾选状态。**全选**会加入可见结果，而**取消全选**会清空全部勾选，以免意外采用隐藏结果。只有用户层单独携带某行时，该行才可删除（删除会恢复组合基线），其确认对话框会指名该提供商。
 
 ### 首次运行弹窗
 
-版本化声明步骤完成后，DeepSeek 步骤从同一份合并快照投影首次运行就绪状态。用户已经能够到达的**任何**提供方都会直接结束该步骤、不做渲染；只有没有任何提供方的用户才会被询问官方 DeepSeek 密钥。「稍后配置」只完成这次协调器遍历；适配器缺失、路由不活动、合并失败、只读部署或能力不可用时，该步骤不渲染即完成——Models 仍是诊断界面。
+版本化声明步骤完成后，DeepSeek 步骤从同一份合并快照投影首次运行就绪状态。用户已经能够到达的**任何**提供商都会直接结束该步骤、不做渲染；只有没有任何提供商的用户才会被询问官方 DeepSeek 密钥。「稍后配置」只完成这次协调器遍历；适配器缺失、路由不活动、合并失败、只读部署或能力不可用时，该步骤不渲染即完成——Models 仍是诊断界面。
 
 ### 扩展 slot
 
-本分区为仓库外分发的插件声明两个席位，类型定义在 [`src/client/slot-contract.ts`](src/client/slot-contract.ts) 并从 `./client` 导出。`settings.models.provider-card`（keyed）渲染在每张展示目录行的卡片内部——已保存行的卡片、其首次运行 setup 形态、以及「添加提供方」草稿卡——以 `entryKey = settingsNs` 分发，owner props 携带该行的 `ConfigurableProviderView`、其 configured 状态与已确认的 api-key 凭据状态，因此以某适配器家族的 namespace 注册一次即可收到该家族的全部卡片，含手工声明的路由；手工声明的草稿卡尚无目录行，保存之前不分发。`settings.models.footer`（list）渲染在行列表与新增控件之后。注册方通过 `ctx.slots.inject` 激活，并以 type-only import 引入本包 `/client` 入口；没有注册方时两个席位均不渲染任何内容。
+本分区为仓库外分发的插件声明两个席位，类型定义在 [`src/client/slot-contract.ts`](src/client/slot-contract.ts) 并从 `./client` 导出。`settings.models.provider-card`（keyed）渲染在每张展示目录行的卡片内部——已保存行的卡片、其首次运行 setup 形态、以及「添加提供商」草稿卡——以 `entryKey = settingsNs` 分发，owner props 携带该行的 `ConfigurableProviderView`、其 configured 状态与已确认的 api-key 凭据状态，因此以某适配器家族的 namespace 注册一次即可收到该家族的全部卡片，含手工声明的路由；手工声明的草稿卡尚无目录行，保存之前不分发。`settings.models.footer`（list）渲染在行列表与新增控件之后。注册方通过 `ctx.slots.inject` 激活，并以 type-only import 引入本包 `/client` 入口；没有注册方时两个席位均不渲染任何内容。
 
 -----
 
@@ -61,7 +61,7 @@ kind: "package-reference"
 <details>
 <summary>实现细节——点击展开</summary>
 
-页面只持有脱敏后的描述符，从不持有完整设置分区：因此每次编辑都以 `settings.mutate` 路径操作落到已存分区上——每个改动字段一次 set、每个清除字段一次 unset、删除提供方行则一次 unset。
+页面只持有脱敏后的描述符，从不持有完整设置分区：因此每次编辑都以 `settings.mutate` 路径操作落到已存分区上——每个改动字段一次 set、每个清除字段一次 unset、删除提供商行则一次 unset。
 
 ### 校验
 
@@ -73,7 +73,7 @@ kind: "package-reference"
 
 ### 引导协调器
 
-声明步骤在 `src/client/locales.ts` 中持有精确文案，并在 `src/onboarding-copy.ts` 中持有确认版本；回环时它通过既有 settings API 比较并写入 `ui-onboarding.welcomeNoticeVersion`，且只有显式点击「继续」才会记录当前版本。非回环浏览器无法使用这个仅限宿主的 namespace，因此确认只保留在进程内，刷新后声明会再次出现。DeepSeek 步骤面向 `llm-deepseek` 中的 `deepseek-official`，在共享引导模态框内以仅凭据模式渲染既有 `ProviderEditor`；`credentials.set` 仍是唯一的机密写入，且不改变任何提供方设置。
+声明步骤在 `src/client/locales.ts` 中持有精确文案，并在 `src/onboarding-copy.ts` 中持有确认版本；回环时它通过既有 settings API 比较并写入 `ui-onboarding.welcomeNoticeVersion`，且只有显式点击「继续」才会记录当前版本。非回环浏览器无法使用这个仅限宿主的 namespace，因此确认只保留在进程内，刷新后声明会再次出现。DeepSeek 步骤面向 `llm-deepseek` 中的 `deepseek-official`，在共享引导模态框内以仅凭据模式渲染既有 `ProviderEditor`；`credentials.set` 仍是唯一的机密写入，且不改变任何提供商设置。
 
 </details>
 
@@ -87,7 +87,7 @@ kind: "package-reference"
 - [ui-settings](../ui-settings/README.zh.md)——本页所依赖 scope 与 schema 服务所在的领域底座。
 - [settings](../../settings/README.zh.md)——持久化用户设置 seam 及其文件提供方。
 - [credentials](../../credentials/README.zh.md)——本页写入密钥所经的凭据引用 seam。
-- [llm](../../llm/README.zh.md)——本页所配置提供方所在的适配器注册表。
+- [llm](../../llm/README.zh.md)——本页所配置提供商所在的适配器注册表。
 - [Web 配置平面](../../../.agents/notes/archived/architecture/2026-07-30-web-config-plane.md)——手写编辑器的设计依据。
 
 -----
@@ -99,7 +99,7 @@ kind: "package-reference"
 
 #### KV Cache 影响
 
-无；该包既不组装也不发送提供方请求。
+无；该包既不组装也不发送提供商请求。
 
 ## 已知限制与延期工作
 
@@ -110,7 +110,8 @@ kind: "package-reference"
 
 - **卡片上只有 API 密钥与精选折叠字段可编辑**：手写编辑器以 schema 通用字段覆盖换取了 mockup 布局。重试策略、超时、DeepSeek 模型说明及其他进阶字段仍留在 `settings.yaml` 中；编辑器未展示的现有模型字段会予以保留。
 - **凭据清理范围刻意保持狭窄**：删除一行时，仅当其引用与页面派生的 `<ROUTE>_API_KEY` 目标完全一致，才会清除已配置且可写的凭据。自定义引用、环境凭据与无法识别的目标会保留，因为该行无法证明自己拥有它们。
-- **只有 pi-ai 路由可以手工声明**：自定义提供方卡片写入 `llm-pi-ai`——唯一一个其 profile 描述整个提供方的 namespace。`llm-deepseek` 路由是组合面的事实，不是本页能创建的东西。
+- **只有 pi-ai 路由可以手工声明**：自定义模型 API 表单写入 `llm-pi-ai`——唯一一个其 profile 描述整个提供商的 namespace。`llm-deepseek` 路由是组合面的事实，不是本页能创建的东西。
+- **目录选择框列出的是路由标识符**：`moonshotai`、`zai` 等 pi-ai catalog id 原样显示，没有产品名、别名或搜索。一个把自定义表单作为置顶项的可搜索选择器可以取代方式切换；前提是目录先携带显示名称。
 - **询问覆盖 OpenAI 兼容与 Anthropic Messages 端点**：OpenAI 协议接受标准 `data` 数组或富信息 `models` 对象，Anthropic 则使用原生模型列表路由；其余协议会报告自己无法被询问，其模型需手工填写。
 - **未声明的存活路由无处渲染**：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。
 
diff --git a/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx b/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
index 4f382e92a1..f568ba0103 100644
--- a/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
@@ -3,12 +3,15 @@
  * gateway, a self-hosted server, or a provider newer than the installed
  * catalog.
  *
- * This is a create, not an edit, which is why it is its own card rather than
+ * This is a create, not an edit, which is why it is its own form rather than
  * the provider editor with extra fields: the route id is being *chosen* here,
- * and the settings address does not exist until it is. One `settings.mutate`
- * sets the whole profile at `providers.<route>`; the key travels separately
- * through `credentials/set` under the reference the profile records, exactly as
- * an existing provider's key does.
+ * and the settings address does not exist until it is. It renders as the
+ * custom-API panel of the section's add card; the card's mode switch names it
+ * when both modes are offered, and with the custom mode alone the card shows
+ * this form directly. One `settings.mutate` sets the whole profile at
+ * `providers.<route>`; the key travels separately through `credentials/set`
+ * under the reference the profile records, exactly as an existing provider's
+ * key does.
  *
  * The three fields a hand-declared route cannot default — endpoint, protocol,
  * and at least one model — are required here rather than at load, so the
@@ -21,7 +24,7 @@
  * levels instead.
  */
 
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { apiKeyFailure } from './apiKey.ts'
@@ -30,6 +33,7 @@ import { validateDeepSeekModels } from './DeepSeekModelsEditor.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
 import type { ModelDraft } from './ModelListEditor.tsx'
 import { deriveKeyRef } from './store.ts'
+import { protocolLabel } from './protocol-label.ts'
 import type { ModelsOperations } from './operations.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
@@ -76,6 +80,11 @@ export interface CustomProviderCardProps {
   readOnly: boolean
   /** Close the card; `changed` reports whether a provider was created. */
   onClose: (changed: boolean) => void
+  /**
+   * Called once per change with whether the create or the list's endpoint
+   * interrogation is in flight, so the owner can hold its surface still.
+   */
+  onBusyChange?: (busy: boolean) => void
 }
 
 /**
@@ -84,7 +93,7 @@ export interface CustomProviderCardProps {
  * @returns the creation card.
  */
 export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
-  const { taken, protocols, operations, t } = props
+  const { taken, protocols, operations, t, onBusyChange } = props
   // The write is checked against the revision on which this draft was opened.
   const [openedAt] = useState(() => props.revision)
   const [route, setRoute] = useState('')
@@ -94,6 +103,8 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   const [keyDraft, setKeyDraft] = useState('')
   const [models, setModels] = useState<readonly ModelDraft[]>([])
   const [busy, setBusy] = useState(false)
+  const [listBusy, setListBusy] = useState(false)
+  useEffect(() => { onBusyChange?.(busy || listBusy) }, [busy, listBusy, onBusyChange])
   const [failure, setFailure] = useState<string | undefined>(undefined)
   /**
    * The profile write landed. Only the key write can still be outstanding, so
@@ -198,9 +209,6 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
 
   return (
     <div className={styles['editor']}>
-      <div className={styles['editorHeader']}>
-        <span className={styles['editorTitle']}>{t('customTitle')}</span>
-      </div>
       <div className={styles['field']}>
         <span className={styles['fieldLabel']}>{t('customRoute')}</span>
         <input
@@ -255,7 +263,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
           disabled={profileDisabled}
           onChange={(event) => { setProtocol(event.target.value) }}
         >
-          {protocols.map(choice => <option key={choice} value={choice}>{choice}</option>)}
+          {protocols.map(choice => <option key={choice} value={choice}>{protocolLabel(t, choice)}</option>)}
         </select>
       </div>
       <div className={styles['field']}>
@@ -292,6 +300,7 @@ export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
         operations={operations}
         t={t}
         disabled={profileDisabled}
+        onBusyChange={setListBusy}
       />
       {failure !== undefined ? <p className={styles['error']}>{failure}</p> : null}
       {/* Only the gates with something to say render; the route-id gate has its
diff --git a/packages/client/ui-settings-models/src/client/ModelListEditor.tsx b/packages/client/ui-settings-models/src/client/ModelListEditor.tsx
index 7cd0a7cdcb..e8ce776875 100644
--- a/packages/client/ui-settings-models/src/client/ModelListEditor.tsx
+++ b/packages/client/ui-settings-models/src/client/ModelListEditor.tsx
@@ -90,6 +90,13 @@ export interface ModelListEditorProps {
   t: (key: keyof typeof en) => string
   /** Disable every control (read-only deployment or a pending write). */
   disabled: boolean
+  /**
+   * Called once per change with whether an endpoint interrogation is in
+   * flight. The owning card folds it into its own busy state so the surface
+   * around the card — a mode switch, say — can refuse to move while the
+   * answer, and the picker it opens, is still bound for this list.
+   */
+  onBusyChange: (busy: boolean) => void
 }
 
 /** The two token counts edited as K/M-suffixed text behind a row's disclosure. */
@@ -139,9 +146,10 @@ function adopt(candidate: LlmDiscoveredModel): ModelDraft {
  * @returns the model-list editor.
  */
 export function ModelListEditor(props: ModelListEditorProps): ReactNode {
-  const { models, onChange, probe, operations, t, disabled } = props
+  const { models, onChange, probe, operations, t, disabled, onBusyChange } = props
   const { catalogProvider } = props
   const [busy, setBusy] = useState(false)
+  useEffect(() => { onBusyChange(busy) }, [busy, onBusyChange])
   const [failure, setFailure] = useState<string | undefined>(undefined)
   const [inheritedCatalog, setInheritedCatalog] = useState<{
     provider: string
diff --git a/packages/client/ui-settings-models/src/client/ModelsSection.module.css b/packages/client/ui-settings-models/src/client/ModelsSection.module.css
index 15b8933fa3..d39e807876 100644
--- a/packages/client/ui-settings-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-settings-models/src/client/ModelsSection.module.css
@@ -305,20 +305,16 @@
   gap: 12px;
 }
 
-/* The two ways to gain a provider, as equal siblings spanning the same width
-   as the rows above. Wraps rather than shrinking below a legible label. */
+/* The one entry to the add card, spanning the same width as the rows above. */
 .addActions {
   display: flex;
-  flex-wrap: wrap;
-  gap: 10px;
 }
 
 .addButton {
-  /* Overrides the shared button base above: these two are not pills sitting in
-     a footer but the last slot of the provider list, so they split the row
-     evenly and repeat the row cards' corner. Dashed, like every other "nothing
-     here yet" affordance on this page, to read as a place rather than a
-     command. */
+  /* Overrides the shared button base above: this is not a pill sitting in a
+     footer but the last slot of the provider list, so it fills the row and
+     repeats the row cards' corner. Dashed, like every other "nothing here yet"
+     affordance on this page, to read as a place rather than a command. */
   flex: 1 1 0;
   min-width: 180px;
   gap: 6px;
@@ -327,6 +323,28 @@
   border-radius: 16px;
 }
 
+/* The add card's mode switch with the one-line purpose of the chosen mode
+   beneath it; the switch hugs its labels rather than spanning the card. */
+.addModes {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+}
+
+/* One panel per mode. Both stay mounted while the card is open; the hidden
+   attribute must win over the panel's own display, or the inactive draft
+   would show beneath the active one. */
+.addPanel {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.addPanel[hidden] {
+  display: none;
+}
+
 .addCard,
 .setupCard {
   border-radius: 12px;
diff --git a/packages/client/ui-settings-models/src/client/ModelsSection.tsx b/packages/client/ui-settings-models/src/client/ModelsSection.tsx
index a9ce163a50..7ae8118762 100644
--- a/packages/client/ui-settings-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-settings-models/src/client/ModelsSection.tsx
@@ -5,17 +5,26 @@
  * solid configured or missing dots. A whole-section provider without a
  * configured key renders as its open setup card instead of a row, but only in
  * the first-run posture — no provider on the page can serve requests yet — and
- * only until the user closes that card; the add flow is a card carrying the
- * dormant-provider select. Each card kind owns its own open state, so closing
- * one never discards a draft in another. Every mutation writes through the
- * wire, while a provider removal first requires confirmation; the page
- * re-renders from pushed invalidations or the post-apply reload.
+ * only until the user closes that card. The add flow is one card behind one
+ * button: a mode switch chooses between adopting a dormant directory provider
+ * (the catalog select over the provider editor) and declaring a custom model
+ * API (the create form). A panel mounts the first time its mode is shown and
+ * stays mounted, hidden, while the card is open and its mode stays offered,
+ * so switching modes discards neither draft and an unvisited mode costs
+ * nothing; the switch holds still while either panel has a write or an
+ * endpoint interrogation in flight, since a switch underneath one would
+ * orphan the answer. Each card kind owns its own open state, so closing one
+ * never discards a draft in another. Every
+ * mutation writes through the wire, while a provider removal first requires
+ * confirmation; the page re-renders from pushed invalidations or the
+ * post-apply reload.
  */
 
-import { useState } from 'react'
+import { useId, useState } from 'react'
 import type { ReactNode } from 'react'
-import { Button, IconPlusOutlineRegular, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+import { Button, IconPlusOutlineRegular, Modal, SegmentedControl } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { InjectFace, PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
 // Type-only: pulls this package's SlotMap merge (the two Models child slots).
 import type {} from './slot-contract.ts'
 import { CustomProviderCard } from './CustomProviderCard.tsx'
@@ -43,6 +52,12 @@ export interface ModelsSectionInjected {
   t: (key: keyof typeof en) => string
 }
 
+/**
+ * The two ways the add card gains a provider: adopt a directory row the
+ * adapter already knows, or declare a route it does not.
+ */
+type AddMode = 'catalog' | 'custom'
+
 /** The child slots this section declares and dispatches (see ./slot-contract.ts). */
 type ModelsChildSlots = 'settings.models.provider-card' | 'settings.models.footer'
 
@@ -78,6 +93,18 @@ interface EditorTarget extends ProviderIdentity {
   declared?: boolean
 }
 
+/** A dormant directory row the add card can adopt, with its registered namespace. */
+interface AddableRow {
+  row: ProviderRow
+  namespace: SettingsNamespaceView
+}
+
+/** The catalog draft the add card shows: its editor target and the namespace that takes the write. */
+interface CatalogDraft {
+  target: EditorTarget
+  namespace: SettingsNamespaceView
+}
+
 /** Values that vary around the shared provider-editor rendering. */
 interface ProviderEditorRenderProps extends Pick<
   ProviderEditorProps,
@@ -205,12 +232,19 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS
   const { controller, operations, schema, t } = injected
   const state = injected.useSnapshot(snapshot => snapshot)
   const [editing, setEditing] = useState<EditorTarget | undefined>(undefined)
-  const [adding, setAdding] = useState(false)
+  const [addOpen, setAddOpen] = useState(false)
+  const [addMode, setAddMode] = useState<AddMode>('catalog')
+  /** The modes shown since the add card opened; each keeps its panel mounted. */
+  const [visited, setVisited] = useState<ReadonlySet<AddMode>>(() => new Set())
+  /** Whether each add panel has a write or an interrogation in flight. */
+  const [catalogBusy, setCatalogBusy] = useState(false)
+  const [customBusy, setCustomBusy] = useState(false)
+  /** Base of the add card's tab and panel ids. */
+  const addId = useId()
   const [deleteTarget, setDeleteTarget] = useState<EditorTarget | undefined>(undefined)
   const [deleting, setDeleting] = useState(false)
   const [deleteFailure, setDeleteFailure] = useState<string | undefined>(undefined)
   const [savedTarget, setSavedTarget] = useState<ProviderIdentity | undefined>(undefined)
-  const [declaring, setDeclaring] = useState(false)
   const [dismissedSetup, setDismissedSetup] = useState<ReadonlySet<string>>(() => new Set())
 
   const announceSaved = (target: ProviderIdentity): void => {
@@ -220,19 +254,31 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS
     void controller.load().then(() => { setSavedTarget(target) })
   }
 
-  const closeEditor = (changed: boolean, target: ProviderIdentity): void => {
+  /**
+   * Close the add card whole. The catalog target is forgotten with it, since
+   * `editing` doubles as the row editor's target once the card is closed and a
+   * refresh could otherwise open the row of a provider the draft never saved.
+   * The busy flags reset here because a panel that closes itself on success
+   * unmounts before it can report idle.
+   */
+  const closeAdd = (): void => {
     setEditing(undefined)
-    setAdding(false)
-    setDeclaring(false)
+    setAddOpen(false)
+    setCatalogBusy(false)
+    setCustomBusy(false)
+  }
+
+  const closeEditor = (changed: boolean, target: ProviderIdentity): void => {
+    closeAdd()
     if (changed) announceSaved(target)
   }
 
   /**
-   * Close a setup card, which owns none of the state above: the row-editor,
-   * add, and declare cards each own one of those, so clearing them here would
-   * discard a draft the user opened beside this card. Dismissal is this card's
-   * own — the provider falls back to an ordinary row for the rest of the
-   * session, and reopens through Edit.
+   * Close a setup card, which owns none of the state above: the row-editor
+   * and add cards each own one of those, so clearing them here would discard
+   * a draft the user opened beside this card. Dismissal is this card's own —
+   * the provider falls back to an ordinary row for the rest of the session,
+   * and reopens through Edit.
    */
   const closeSetup = (changed: boolean, target: ProviderIdentity): void => {
     setDismissedSetup(previous => new Set([...previous, target.provider]))
@@ -291,19 +337,47 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS
   const anyUsable = state.rows.some(providerUsable)
   const configured = state.rows.filter(row => row.configured)
   const configurable = state.rows.filter(row => state.namespaces.has(row.entry.settingsNs))
-  const addable = configurable.filter(row => !row.configured)
-  const addTarget = adding ? editing : undefined
-  const addNamespace = addTarget === undefined ? undefined : state.namespaces.get(addTarget.settingsNs)
+  const addable: AddableRow[] = state.rows.flatMap((row) => {
+    const namespace = state.namespaces.get(row.entry.settingsNs)
+    return namespace === undefined || row.configured ? [] : [{ row, namespace }]
+  })
+  // Hand-declared routes live in the pi-ai namespace, which is also the only
+  // one whose schema names the protocols one may speak; without it mounted
+  // there is nothing to declare and the mode is not offered.
+  const piAi = state.namespaces.get('llm-pi-ai')
+  const protocols = protocolChoices(piAi, schema)
+  // Each mode is offered while its namespace is mounted and enabled while it
+  // has something to offer; the card shows the chosen mode where both are
+  // offered, else the only one there is. A mode's panel is mounted while it is
+  // the shown mode or has been shown since the card opened — derived, so a
+  // refresh that changes which modes are offered can never leave the card
+  // without a panel.
+  const catalogOffered = configurable.length > 0
+  const catalogEnabled = addable.length > 0
+  const customOffered = piAi !== undefined
+  const customEnabled = protocols.length > 0
+  const bothOffered = catalogOffered && customOffered
+  const mode: AddMode = bothOffered ? addMode : customOffered ? 'custom' : 'catalog'
+  const mounted = (candidate: AddMode): boolean => mode === candidate || visited.has(candidate)
+  const switchLocked = catalogBusy || customBusy
+  // The catalog draft: the row the user chose, kept through a refresh that
+  // adopts or withdraws it elsewhere so a typed key is never discarded, for as
+  // long as its namespace can still take the write; else the first row still
+  // addable, since the mode can be entered by a refresh as well as by the
+  // switch and the button only picks a target when it opens the card.
+  const draft = ((): CatalogDraft | undefined => {
+    if (!addOpen || !catalogOffered) return undefined
+    const kept = editing === undefined ? undefined : state.namespaces.get(editing.settingsNs)
+    if (editing !== undefined && kept !== undefined) return { target: editing, namespace: kept }
+    const first = addable[0]
+    return first === undefined ? undefined : { target: targetOf(first.row), namespace: first.namespace }
+  })()
   // The draft's directory row, for the card extension seat. A refresh can drop
   // the row mid-draft (the route was adopted or withdrawn elsewhere); the
   // draft card stays while the seat simply has no row to dispatch.
-  const addRow = addTarget === undefined
+  const addRow = draft === undefined
     ? undefined
-    : state.rows.find(row => row.entry.provider === addTarget.provider)
-  // Hand-declared routes live in the pi-ai namespace, which is also the only
-  // one whose schema names the protocols one may speak; without it mounted
-  // there is nothing to declare and the entry point stays disabled.
-  const protocols = protocolChoices(state.namespaces.get('llm-pi-ai'), schema)
+    : state.rows.find(row => row.entry.provider === draft.target.provider)
 
   return (
     <div className={styles['section']}>
@@ -349,7 +423,7 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS
               </li>
             )
           }
-          const open = !adding && editing?.provider === row.entry.provider
+          const open = !addOpen && editing?.provider === row.entry.provider
           const credentialConfigured = row.credential?.configured === true
           const credentialMissing = !credentialConfigured
             && row.apiKeyEnv !== undefined
@@ -392,11 +466,10 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS
                     aria-label={providerCopy(t('editProvider'), target)}
                     onClick={() => {
                       setSavedTarget(undefined)
-                      // One card at a time: leaving `declaring` set would show
-                      // the create card beside this editor, and closing either
-                      // one discards the other's draft.
-                      setDeclaring(false)
-                      setAdding(false)
+                      // One card at a time: the add card closes with whatever
+                      // it held, since closing either card would otherwise
+                      // discard the other's draft.
+                      setAddOpen(false)
                       setEditing(open ? undefined : target)
                     }}
                   >
@@ -443,110 +516,150 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS
         })}
       </ul>
       <div className={styles['addBlock']}>
-        {addTarget !== undefined && addNamespace !== undefined
+        {addOpen
           ? (
             <div className={styles['addCard']}>
-              <div className={styles['field']}>
-                <span className={styles['fieldLabel']}>{t('provider')}</span>
-                <select
-                  className={`${styles['input']} ${styles['selectInput']}`}
-                  value={addTarget.provider}
-                  aria-label={t('provider')}
-                  onChange={(event) => {
-                    const row = addable.find(candidate => candidate.entry.provider === event.target.value)
-                    /* v8 ignore next -- the select only lists addable rows */
-                    if (row === undefined) return
-                    setEditing(targetOf(row))
-                  }}
-                >
-                  {addable.map(row => (
-                    <option key={row.entry.provider} value={row.entry.provider}>{row.entry.displayName}</option>
-                  ))}
-                </select>
+              <div className={styles['addModes']}>
+                {bothOffered
+                  ? (
+                    <SegmentedControl
+                      id={addId}
+                      label={t('addMode')}
+                      value={mode}
+                      disabled={switchLocked}
+                      options={[
+                        {
+                          value: 'catalog',
+                          label: t('addCatalog'),
+                          disabled: !catalogEnabled,
+                          ...catalogEnabled ? {} : { title: t('addCatalogExhausted') },
+                        },
+                        {
+                          value: 'custom',
+                          label: t('addCustom'),
+                          disabled: !customEnabled,
+                          ...customEnabled ? {} : { title: t('addCustomUnavailable') },
+                        },
+                      ]}
+                      onChange={(next) => {
+                        setAddMode(next)
+                        setVisited(previous => new Set([...previous, next]))
+                      }}
+                    />
+                  )
+                  : (
+                    // One mode alone has no switch to name it, so the card
+                    // carries the mode as its title instead.
+                    <div className={styles['editorHeader']}>
+                      <span className={styles['editorTitle']}>{t(mode === 'catalog' ? 'addCatalog' : 'addCustom')}</span>
+                    </div>
+                  )}
+                <p className={styles['advancedHint']}>
+                  {t(mode === 'catalog' ? 'addCatalogHint' : 'addCustomHint')}
+                </p>
               </div>
-              <ProviderEditor
-                key={addTarget.provider}
-                provider={addTarget.provider}
-                displayName={addTarget.displayName}
-                hideTitle
-                namespace={addNamespace}
-                schema={schema}
-                settingsPath={addTarget.settingsPath}
-                operations={operations}
-                t={t}
-                readOnly={!state.writable}
-                onClose={(changed) => { closeEditor(changed, addTarget) }}
-              />
-              {addRow === undefined
-                ? null
-                : renderSlot(
-                  'settings.models.provider-card',
-                  { provider: addRow.entry, configured: addRow.configured, keyConfigured: keyConfiguredOf(addRow) },
-                  { entryKey: addRow.entry.settingsNs },
-                )}
+              {mounted('catalog') && draft !== undefined
+                ? (
+                  <div
+                    id={`${addId}-catalog-panel`}
+                    {...bothOffered ? { role: 'tabpanel', 'aria-labelledby': `${addId}-catalog` } : {}}
+                    hidden={mode !== 'catalog'}
+                    className={styles['addPanel']}
+                  >
+                    <div className={styles['field']}>
+                      <span className={styles['fieldLabel']}>{t('provider')}</span>
+                      <select
+                        className={`${styles['input']} ${styles['selectInput']}`}
+                        value={draft.target.provider}
+                        aria-label={t('provider')}
+                        disabled={catalogBusy}
+                        onChange={(event) => {
+                          const picked = addable.find(candidate => candidate.row.entry.provider === event.target.value)
+                          /* v8 ignore next -- the select only lists addable rows */
+                          if (picked === undefined) return
+                          setEditing(targetOf(picked.row))
+                        }}
+                      >
+                        {addable.map(({ row }) => (
+                          <option key={row.entry.provider} value={row.entry.provider}>{row.entry.displayName}</option>
+                        ))}
+                      </select>
+                    </div>
+                    <ProviderEditor
+                      key={draft.target.provider}
+                      provider={draft.target.provider}
+                      displayName={draft.target.displayName}
+                      hideTitle
+                      namespace={draft.namespace}
+                      schema={schema}
+                      settingsPath={draft.target.settingsPath}
+                      operations={operations}
+                      t={t}
+                      readOnly={!state.writable}
+                      onClose={(changed) => { closeEditor(changed, draft.target) }}
+                      onBusyChange={setCatalogBusy}
+                    />
+                    {addRow === undefined
+                      ? null
+                      : renderSlot(
+                        'settings.models.provider-card',
+                        { provider: addRow.entry, configured: addRow.configured, keyConfigured: keyConfiguredOf(addRow) },
+                        { entryKey: addRow.entry.settingsNs },
+                      )}
+                  </div>
+                )
+                : null}
+              {mounted('custom') && piAi !== undefined
+                ? (
+                  <div
+                    id={`${addId}-custom-panel`}
+                    {...bothOffered ? { role: 'tabpanel', 'aria-labelledby': `${addId}-custom` } : {}}
+                    hidden={mode !== 'custom'}
+                    className={styles['addPanel']}
+                  >
+                    <CustomProviderCard
+                      taken={state.rows.map(row => row.entry.provider)}
+                      protocols={protocols}
+                      revision={piAi.revision}
+                      operations={operations}
+                      t={t}
+                      readOnly={!state.writable}
+                      onClose={(changed) => {
+                        closeAdd()
+                        if (changed) void controller.load()
+                      }}
+                      onBusyChange={setCustomBusy}
+                    />
+                  </div>
+                )
+                : null}
             </div>
           )
-          : declaring
+          : catalogOffered || customOffered
             ? (
-              <div className={styles['addCard']}>
-                <CustomProviderCard
-                  taken={state.rows.map(row => row.entry.provider)}
-                  protocols={protocols}
-                  /* v8 ignore next -- the card only opens from a button disabled without this namespace */
-                  revision={state.namespaces.get('llm-pi-ai')?.revision ?? 0}
-                  operations={operations}
-                  t={t}
-                  readOnly={!state.writable}
-                  onClose={(changed) => {
-                    setDeclaring(false)
-                    if (changed) void controller.load()
+              // One entry for both ways to gain a provider; the card behind it
+              // splits them. Full width, so it lines up with the rows above.
+              <div className={styles['addActions']}>
+                <button
+                  type="button"
+                  className={styles['addButton']}
+                  disabled={!state.writable || (!catalogEnabled && !customEnabled)}
+                  onClick={() => {
+                    const first = addable[0]
+                    const initial: AddMode = catalogEnabled ? 'catalog' : 'custom'
+                    setSavedTarget(undefined)
+                    setEditing(first === undefined ? undefined : targetOf(first.row))
+                    setAddMode(initial)
+                    setVisited(new Set([initial]))
+                    setAddOpen(true)
                   }}
-                />
+                >
+                  <IconPlusOutlineRegular size={14} />
+                  {t('add')}
+                </button>
               </div>
             )
-            : (
-              // One row for the two ways to gain a provider: adopt one the
-              // adapter already knows, or declare one it does not. Side by side
-              // and equal-width so they read as siblings and line up with the
-              // rows above, rather than two pills of different lengths.
-              <div className={styles['addActions']}>
-                {configurable.length > 0 && (
-                  <button
-                    type="button"
-                    className={styles['addButton']}
-                    disabled={addable.length === 0 || !state.writable}
-                    onClick={() => {
-                      const first = addable[0]
-                      /* v8 ignore next -- the button is disabled while nothing is addable */
-                      if (first === undefined) return
-                      setSavedTarget(undefined)
-                      setDeclaring(false)
-                      setAdding(true)
-                      setEditing(targetOf(first))
-                    }}
-                  >
-                    <IconPlusOutlineRegular size={14} />
-                    {t('add')}
-                  </button>
-                )}
-                {state.namespaces.has('llm-pi-ai') && (
-                  <button
-                    type="button"
-                    className={styles['addButton']}
-                    disabled={protocols.length === 0 || !state.writable}
-                    onClick={() => {
-                      setSavedTarget(undefined)
-                      setAdding(false)
-                      setEditing(undefined)
-                      setDeclaring(true)
-                    }}
-                  >
-                    <IconPlusOutlineRegular size={14} />
-                    {t('customAdd')}
-                  </button>
-                )}
-              </div>
-            )}
+            : null}
       </div>
       {renderSlot('settings.models.footer', {})}
       <Modal
diff --git a/packages/client/ui-settings-models/src/client/ProviderEditor.tsx b/packages/client/ui-settings-models/src/client/ProviderEditor.tsx
index bc89f43fc8..fe8b861503 100644
--- a/packages/client/ui-settings-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-settings-models/src/client/ProviderEditor.tsx
@@ -34,6 +34,7 @@ import { apiKeyFailure } from './apiKey.ts'
 import { EditorFooter } from './EditorFooter.tsx'
 import { ModelListEditor } from './ModelListEditor.tsx'
 import { deriveKeyRef, protocolChoices } from './store.ts'
+import { protocolLabel } from './protocol-label.ts'
 import type { ModelsOperations } from './operations.ts'
 import type { SettingsSchemaOperations } from './schema-operations.ts'
 import type { en } from './locales.ts'
@@ -86,6 +87,12 @@ export interface ProviderEditorProps {
   submitBusyLabelKey?: keyof typeof en
   /** Close the editor; `changed` reports whether an Apply committed. */
   onClose: (changed: boolean) => void
+  /**
+   * Called once per change with whether the apply or the model list's
+   * endpoint interrogation is in flight, so the owner can hold its surface
+   * still.
+   */
+  onBusyChange?: (busy: boolean) => void
 }
 
 /** A user-section subtree as a plain draft object (absent → empty). */
@@ -160,6 +167,9 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
   const [keyDraft, setKeyDraft] = useState('')
   const [keyState, setKeyState] = useState<CredentialInfo | undefined>(undefined)
   const [busy, setBusy] = useState(false)
+  const [listBusy, setListBusy] = useState(false)
+  const { onBusyChange } = props
+  useEffect(() => { onBusyChange?.(busy || listBusy) }, [busy, listBusy, onBusyChange])
   const [failure, setFailure] = useState<string | undefined>(undefined)
   // A settings success advances both retry baselines immediately. Keeping the
   // derived fields in the draft prevents a pushed namespace refresh from
@@ -414,7 +424,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                 type="text"
                 value={stringAt(draft, 'baseURL') ?? ''}
                 placeholder={family === 'deepseek'
-                  ? t(stringAt(fallback, 'protocol') === 'messages' ? 'deepSeekMessagesBaseUrl' : 'deepSeekChatBaseUrl')
+                  ? t('deepSeekBaseUrl')
                   : stringAt(fallback, 'baseURL') ?? t('baseUrlDefault')}
                 aria-describedby={family === 'deepseek' ? `${props.provider}-endpoint-hint` : undefined}
                 aria-label={t('baseUrl')}
@@ -445,7 +455,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                         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>)}
+                    {protocols.map(choice => <option key={choice} value={choice}>{protocolLabel(t, choice)}</option>)}
                   </select>
                 </div>
               )
@@ -471,6 +481,7 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
                   probe={probe}
                   probeBlocked={keyFailure}
                   operations={operations}
+                  onBusyChange={setListBusy}
                 />
               )}
           </div>
diff --git a/packages/client/ui-settings-models/src/client/locales.ts b/packages/client/ui-settings-models/src/client/locales.ts
index 2b0f92d8df..c60caf4976 100644
--- a/packages/client/ui-settings-models/src/client/locales.ts
+++ b/packages/client/ui-settings-models/src/client/locales.ts
@@ -14,7 +14,14 @@ export const en = {
   deleteDescriptionWithCredential: 'Deleting {provider} removes its configuration and stored API key.',
   deleteConfirm: 'Delete {provider}',
   deleting: 'Deleting {provider}…',
-  add: 'Add provider',
+  add: 'Add model provider',
+  addMode: 'How to add',
+  addCatalog: 'Third-party model provider',
+  addCustom: 'Custom model API',
+  addCatalogHint: 'Pick OpenAI, Anthropic, Kimi, or another provider from the built-in catalog and enter its API key.',
+  addCustomHint: 'Connect a relay, a self-hosted server, or any other OpenAI- or Anthropic-compatible endpoint by its base URL, protocol, and models.',
+  addCatalogExhausted: 'Every catalog provider is already configured.',
+  addCustomUnavailable: 'No API protocol is available to declare.',
   provider: 'Provider',
   close: 'Close',
   cancel: 'Cancel',
@@ -35,9 +42,8 @@ export const en = {
   customized: 'Customized settings',
   baseUrl: 'Base URL',
   baseUrlDefault: 'Provider default',
-  deepSeekChatBaseUrl: 'https://api.deepseek.com',
-  deepSeekMessagesBaseUrl: 'https://api.deepseek.com/anthropic',
-  deepSeekEndpointHint: 'Use an endpoint compatible with the configured connection.',
+  deepSeekBaseUrl: 'https://api.deepseek.com/anthropic',
+  deepSeekEndpointHint: 'Use an API endpoint compatible with Anthropic Messages.',
   models: 'Models',
   modelsInherited: 'Using the adapter defaults',
   modelsCustomized: 'Customized model catalog',
@@ -79,8 +85,6 @@ export const en = {
   fetchSelectAll: 'Select all',
   fetchDeselectAll: 'Deselect all',
   fetchAdopt: 'Add selected',
-  customAdd: 'Add a custom provider',
-  customTitle: 'Custom provider',
   customTag: 'Custom',
   customRoute: 'Provider ID',
   customRouteHint: 'Lowercase identifier, starting with a letter, that uniquely names this provider in requests and as its credential name.',
@@ -89,6 +93,9 @@ export const en = {
   customDisplayName: 'Display name',
   customApi: 'API protocol',
   customApiUnset: 'Not selected',
+  protocolOpenAiCompletions: 'OpenAI Chat Completions',
+  protocolOpenAiResponses: 'OpenAI Responses',
+  protocolAnthropicMessages: 'Anthropic Messages',
   customNeedsBaseUrl: 'A custom provider needs a base URL.',
   customBaseUrlInvalid: 'Enter a valid HTTP or HTTPS URL.',
   customNeedsModels: 'A custom provider needs at least one model.',
@@ -116,7 +123,7 @@ export type ModelsKey = keyof typeof en
 export const zh: { [Key in keyof typeof en]: string } = {
   nav: '模型',
   title: '模型',
-  intro: '填入各提供方的 API 密钥即可使用其模型。',
+  intro: '填入各提供商的 API 密钥即可使用其模型。',
   edit: '编辑',
   editProvider: '编辑 {provider}',
   remove: '删除',
@@ -126,8 +133,15 @@ export const zh: { [Key in keyof typeof en]: string } = {
   deleteDescriptionWithCredential: '删除 {provider} 会移除其配置和存储的 API 密钥。',
   deleteConfirm: '删除 {provider}',
   deleting: '正在删除 {provider}…',
-  add: '添加提供方',
-  provider: '提供方',
+  add: '添加模型提供商',
+  addMode: '添加方式',
+  addCatalog: '第三方模型提供商',
+  addCustom: '自定义模型 API',
+  addCatalogHint: '从内置目录中选择 OpenAI、Anthropic、Kimi 等提供商，填入其 API 密钥即可使用。',
+  addCustomHint: '连接中转站、自部署服务或其他兼容 OpenAI / Anthropic 协议的接口，需填写 API 地址、协议和模型。',
+  addCatalogExhausted: '目录中的提供商都已添加。',
+  addCustomUnavailable: '没有可用的 API 协议。',
+  provider: '提供商',
   close: '关闭',
   cancel: '取消',
   apply: '保存',
@@ -136,7 +150,7 @@ export const zh: { [Key in keyof typeof en]: string } = {
   credentialConfigured: 'API 密钥已配置',
   credentialMissing: 'API 密钥缺失',
   readOnly: '当前部署的设置文档为只读。',
-  loadFailed: '加载提供方目录失败',
+  loadFailed: '加载提供商目录失败',
   conflict: '这张卡片打开期间，这些设置已被其他地方改动。请关闭后重新打开，在当前值上编辑。',
   retry: '重试',
   keyInput: 'API 密钥',
@@ -146,10 +160,9 @@ export const zh: { [Key in keyof typeof en]: string } = {
   keyEnvLocked: '由启动环境提供（只读）',
   customized: '自定义设置',
   baseUrl: 'API 地址',
-  baseUrlDefault: '提供方默认',
-  deepSeekChatBaseUrl: 'https://api.deepseek.com',
-  deepSeekMessagesBaseUrl: 'https://api.deepseek.com/anthropic',
-  deepSeekEndpointHint: '请填写与当前连接配置兼容的 API 地址。',
+  baseUrlDefault: '提供商默认',
+  deepSeekBaseUrl: 'https://api.deepseek.com/anthropic',
+  deepSeekEndpointHint: '请填写兼容 Anthropic Messages 协议的 API 地址。',
   models: '模型目录',
   modelsInherited: '正在使用适配器默认模型',
   modelsCustomized: '已自定义模型目录',
@@ -159,9 +172,9 @@ export const zh: { [Key in keyof typeof en]: string } = {
   modelName: '显示名称',
   modelNamePlaceholder: '留空时使用模型 ID',
   contextWindow: '上下文窗口',
-  contextWindowPlaceholder: '使用提供方默认值',
+  contextWindowPlaceholder: '使用提供商默认值',
   maxTokens: '最大输出 token 数',
-  maxTokensPlaceholder: '使用提供方默认值',
+  maxTokensPlaceholder: '使用提供商默认值',
   modelAdvanced: '模型选项',
   modelInputTypes: '输入类型',
   modelInputText: '文本',
@@ -170,7 +183,7 @@ export const zh: { [Key in keyof typeof en]: string } = {
   removeModel: '删除模型',
   modelsEmpty: '模型选择器中将不显示任何模型；目录外 ID 仍可直接发送。',
   keyBlank: '请输入 API 密钥；留空则保持已存储的密钥。',
-  keyBlankNew: '请输入 API 密钥；若该提供方以其他方式鉴权，可以留空。',
+  keyBlankNew: '请输入 API 密钥；若该提供商以其他方式鉴权，可以留空。',
   keyIllegalCharacters: '该 API 密钥格式错误，请检查。',
   modelIdRequired: '模型 ID 不能为空。',
   modelIdDuplicate: '模型 ID 不能重复。',
@@ -181,33 +194,34 @@ export const zh: { [Key in keyof typeof en]: string } = {
   modelCapacityInvalid: '容量需为数字，可加 K 或 M 后缀。',
   modelDuplicate: '每个模型 ID 只能出现一次。',
   fetchModels: '获取可用模型',
-  fetching: '正在询问提供方\u2026',
+  fetching: '正在询问提供商\u2026',
   fetchNeedsBaseUrl: '请先填写 API 地址，再获取。',
-  fetchEmpty: '该提供方没有列出任何模型，请手动添加。',
+  fetchEmpty: '该提供商没有列出任何模型，请手动添加。',
   fetchTitle: '选择要添加的模型',
-  fetchDescription: '以下是模型提供方的可用模型，勾选要添加的模型。',
+  fetchDescription: '以下是模型提供商的可用模型，勾选要添加的模型。',
   fetchSearch: '搜索模型',
   fetchNoMatches: '没有匹配的模型。',
   fetchSelectAll: '全选',
   fetchDeselectAll: '取消全选',
   fetchAdopt: '添加所选',
-  customAdd: '添加自定义提供方',
-  customTitle: '自定义提供方',
   customTag: '自定义',
   customRoute: 'Provider ID',
-  customRouteHint: '以小写字母开头的标识，在请求中唯一标识该提供方，并用于派生凭据名。',
+  customRouteHint: '以小写字母开头的标识，在请求中唯一标识该提供商，并用于派生凭据名。',
   customRouteInvalid: '需以小写字母开头，之后可用小写字母、数字和短横线。',
-  customRouteTaken: '已有提供方使用了这个 ID。',
+  customRouteTaken: '已有提供商使用了这个 ID。',
   customDisplayName: '显示名称',
   customApi: 'API 协议',
   customApiUnset: '未选择',
-  customNeedsBaseUrl: '自定义提供方需要填写 API 地址。',
+  protocolOpenAiCompletions: 'OpenAI Chat Completions',
+  protocolOpenAiResponses: 'OpenAI Responses',
+  protocolAnthropicMessages: 'Anthropic Messages',
+  customNeedsBaseUrl: '自定义模型 API 需要填写 API 地址。',
   customBaseUrlInvalid: '请输入有效的 HTTP 或 HTTPS 地址。',
-  customNeedsModels: '自定义提供方至少需要一个模型。',
+  customNeedsModels: '自定义模型 API 至少需要一个模型。',
   customBaseUrlPlaceholder: 'https://gateway.example/v1',
   customAnthropicBaseUrlPlaceholder: 'https://gateway.example',
   settingsPathUnresolvable: '无法解析设置路径',
-  create: '创建提供方',
+  create: '创建提供商',
   creating: '创建中\u2026',
   welcomeTitle: '内测声明',
   welcomeBody: 'DeepSeek Harness 目前的 0.1 版本仍处在面向 Harness 开发者进行测试的阶段，还有许多地方需要持续改进和打磨，希望听取广大开发者的反馈建议。预计 DeepSeek Harness 的核心插件以及基础 API 都会在接下来的一段时间内快速迭代、持续演化。\n\n我们期待与全球开发者一起，在开源、开放、可复用、可组合的基础设施之上，共同探索智能上限。欢迎全球 Harness 开发者加入 DSH 插件生态。',
diff --git a/packages/client/ui-settings-models/src/client/protocol-label.ts b/packages/client/ui-settings-models/src/client/protocol-label.ts
new file mode 100644
index 0000000000..f65323f32c
--- /dev/null
+++ b/packages/client/ui-settings-models/src/client/protocol-label.ts
@@ -0,0 +1,27 @@
+/**
+ * Product names for the wire protocols a pi-ai route may speak. The pickers
+ * show these instead of the schema identifiers (`openai-completions`), which
+ * are what `settings.yaml` carries and what the option values stay.
+ */
+
+import type { ModelsKey } from './locales.ts'
+
+/** The protocols this page names, keyed by their schema identifier. */
+const PROTOCOL_LABEL_KEYS: Readonly<Record<string, ModelsKey>> = {
+  'openai-completions': 'protocolOpenAiCompletions',
+  'openai-responses': 'protocolOpenAiResponses',
+  'anthropic-messages': 'protocolAnthropicMessages',
+}
+
+/**
+ * The picker text for one protocol identifier.
+ * @param t - section copy.
+ * @param protocol - the schema identifier of the protocol.
+ * @returns the product name this page knows the protocol by; a protocol the
+ * adapter adds before this page names it shows its identifier, the spelling
+ * `settings.yaml` needs anyway.
+ */
+export function protocolLabel(t: (key: ModelsKey) => string, protocol: string): string {
+  const key = PROTOCOL_LABEL_KEYS[protocol]
+  return key === undefined ? protocol : t(key)
+}
diff --git a/packages/client/ui-settings-models/tests/components.client.spec.tsx b/packages/client/ui-settings-models/tests/components.client.spec.tsx
index e9cec03e60..f11b47f15f 100644
--- a/packages/client/ui-settings-models/tests/components.client.spec.tsx
+++ b/packages/client/ui-settings-models/tests/components.client.spec.tsx
@@ -46,6 +46,7 @@ function capacityInputs(label: string): HTMLInputElement[] {
 const PiAiConfig = Schema.object({
   providers: Schema.dict(Schema.object({
     apiKeyEnv: Schema.string().role('credential-ref'),
+    api: Schema.union(['openai-completions', 'openai-responses', 'anthropic-messages']),
     baseURL: Schema.string(),
     reasoning: Schema.union(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']),
     headers: Schema.dict(Schema.string()),
@@ -307,12 +308,11 @@ async function mountDeepSeekCard(overrides: Parameters<typeof scriptedFace>[0] =
 }
 
 describe('ModelsSection', () => {
-  it('hides both add actions when their settings namespaces are absent', async () => {
+  it('hides the add action when no settings namespace can open an editor', async () => {
     const scripted = scriptedFace()
     scripted.face.settings.describe.mockResolvedValue(remoteOk({ writable: true, hasDocument: false, namespaces: [] }))
     await mountFace(scripted)
     expect(screen.queryByRole('button', { name: en.add })).toBeNull()
-    expect(screen.queryByRole('button', { name: en.customAdd })).toBeNull()
   })
 
   it('offers only providers whose settings namespace can open an editor', async () => {
@@ -322,8 +322,11 @@ describe('ModelsSection', () => {
       namespaces: wireNamespaces().filter(view => view.ns !== 'llm-pi-ai'),
     }))
     await mountFace(scripted)
-    expect(screen.queryByRole('button', { name: en.customAdd })).toBeNull()
     fireEvent.click(screen.getByRole('button', { name: en.add }))
+    // Without the pi-ai namespace nothing can be hand-declared, so the card
+    // is the catalog form alone: no mode switch, no custom panel.
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull()
     expect(screen.queryByRole('option', { name: 'anthropic' })).toBeNull()
     expect(screen.getByRole('option', { name: 'plain' })).toBeTruthy()
   })
@@ -339,7 +342,6 @@ describe('ModelsSection', () => {
     fireEvent.click(screen.getByRole('button', { name: openaiCopy(en.editProvider) }))
     expect(await screen.findByLabelText(en.keyInput)).toBeTruthy()
     expect(screen.getByRole('button', { name: en.add })).toBeTruthy()
-    expect(screen.getByRole('button', { name: en.customAdd })).toBeTruthy()
   })
 
   it('renders nothing before the slot injects its dependencies', () => {
@@ -618,7 +620,7 @@ describe('ModelsSection', () => {
     const baseURL = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
     // The deepseek placeholder is pinned to the public endpoint, not the
     // effective value (which may reflect a launch-environment override).
-    expect(baseURL.placeholder).toBe('https://api.deepseek.com')
+    expect(baseURL.placeholder).toBe('https://api.deepseek.com/anthropic')
     fireEvent.change(baseURL, { target: { value: 'https://next2' } })
     fireEvent.click(screen.getByText(en.apply))
     await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
@@ -666,11 +668,11 @@ describe('ModelsSection', () => {
     ])
   })
 
-  it('edits the shared DeepSeek card while preserving the YAML protocol selection', async () => {
+  it('edits the DeepSeek endpoint and credential without a protocol selection', async () => {
     const namespace: SettingsNamespaceView = {
       ...wireNamespaces()[0]!,
       ns: 'llm-deepseek',
-      value: { protocol: 'messages', apiKeyEnv: 'DEEPSEEK_API_KEY', models: DEFAULT_DEEPSEEK_MODELS },
+      value: { apiKeyEnv: 'DEEPSEEK_API_KEY', models: DEFAULT_DEEPSEEK_MODELS },
       user: {},
     }
     const { face, mutate, set } = scriptedFace({
@@ -1102,7 +1104,7 @@ describe('ModelsSection', () => {
     />)
     fireEvent.click(screen.getByText(en.customized))
     const baseURL = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
-    expect(baseURL.placeholder).toBe('https://api.deepseek.com')
+    expect(baseURL.placeholder).toBe('https://api.deepseek.com/anthropic')
     fireEvent.change(baseURL, { target: { value: 'https://x' } })
     expect(baseURL.value).toBe('https://x')
     fireEvent.change(baseURL, { target: { value: '' } })
@@ -1437,6 +1439,253 @@ describe('ModelsSection', () => {
     expect(mutate).not.toHaveBeenCalled()
   })
 
+  it('opens the add card on the catalog mode with both modes offered', async () => {
+    await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    const modes = screen.getByRole('tablist', { name: en.addMode })
+    expect(within(modes).getByRole('tab', { name: en.addCatalog }).getAttribute('aria-selected')).toBe('true')
+    expect(within(modes).getByRole('tab', { name: en.addCustom }).getAttribute('aria-selected')).toBe('false')
+    expect(screen.getByText(en.addCatalogHint)).toBeTruthy()
+    expect(screen.queryByText(en.addCustomHint)).toBeNull()
+    expect(screen.getByRole('combobox', { name: en.provider })).toBeTruthy()
+    // The custom panel is mounted but hidden, so its fields are not reachable.
+    expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull()
+  })
+
+  it('switches between the modes without losing either draft', async () => {
+    await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-catalog' } })
+
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    expect(screen.getByText(en.addCustomHint)).toBeTruthy()
+    expect(screen.queryByText(en.addCatalogHint)).toBeNull()
+    expect(screen.queryByRole('combobox', { name: en.provider })).toBeNull()
+    fireEvent.change(screen.getByRole('textbox', { name: en.customRoute }), { target: { value: 'acme' } })
+
+    // Both panels stay mounted from here on, so the shown one is queried by name.
+    fireEvent.click(screen.getByRole('tab', { name: en.addCatalog }))
+    const catalog = screen.getByRole('tabpanel', { name: en.addCatalog })
+    expect(within(catalog).getByLabelText<HTMLInputElement>(en.keyInput).value).toBe('sk-catalog')
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    expect(screen.getByRole<HTMLInputElement>('textbox', { name: en.customRoute }).value).toBe('acme')
+  })
+
+  it('opens on the custom mode when every catalog provider is already configured', async () => {
+    const scripted = scriptedFace()
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    ]))
+    await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    const catalog = screen.getByRole<HTMLButtonElement>('tab', { name: en.addCatalog })
+    expect(catalog.disabled).toBe(true)
+    expect(screen.getByRole('tab', { name: en.addCustom }).getAttribute('aria-selected')).toBe('true')
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
+  })
+
+  it('shows the custom form alone when no directory row can be adopted', async () => {
+    const scripted = scriptedFace()
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([]))
+    await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.queryByRole('combobox', { name: en.provider })).toBeNull()
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
+  })
+
+  it('disables the add action when neither mode can proceed', async () => {
+    const scripted = scriptedFace()
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    ]))
+    // A pi-ai schema naming no protocol leaves nothing to declare either.
+    const protocolless = JSON.parse(JSON.stringify(
+      Schema.object({ providers: Schema.dict(Schema.object({})) }).toJSON(),
+    )) as JsonValue
+    scripted.face.settings.describe.mockResolvedValue(remoteOk({
+      writable: true, hasDocument: false,
+      namespaces: wireNamespaces().map(view => view.ns === 'llm-pi-ai' ? { ...view, schema: protocolless } : view),
+    }))
+    await mountFace(scripted)
+    expect(screen.getByRole<HTMLButtonElement>('button', { name: en.add }).disabled).toBe(true)
+  })
+
+  it('shows the custom panel when a refresh drops every configurable row mid-card', async () => {
+    const { face, controller } = await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.getByRole('combobox', { name: en.provider })).toBeTruthy()
+    // The directory empties while the card is open: the only mode left is the
+    // custom one, whose panel was never visited.
+    face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([]))
+    await act(async () => { await controller.load() })
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
+  })
+
+  it('picks a catalog target when the catalog becomes addable after the card opened', async () => {
+    const scripted = scriptedFace()
+    const exhausted = [
+      { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    ]
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk(exhausted))
+    const { controller } = await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.getByRole<HTMLButtonElement>('tab', { name: en.addCatalog }).disabled).toBe(true)
+    // A dormant route appears (another client deleted its profile, say).
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([
+      ...exhausted,
+      { provider: 'anthropic', displayName: 'anthropic', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'anthropic'] },
+    ]))
+    await act(async () => { await controller.load() })
+    const catalog = screen.getByRole<HTMLButtonElement>('tab', { name: en.addCatalog })
+    expect(catalog.disabled).toBe(false)
+    fireEvent.click(catalog)
+    expect(screen.getByRole<HTMLSelectElement>('combobox', { name: en.provider }).value).toBe('anthropic')
+    expect(within(screen.getByRole('tabpanel', { name: en.addCatalog })).getByLabelText(en.keyInput)).toBeTruthy()
+  })
+
+  it('drops the custom panel when the pi-ai namespace disappears mid-card', async () => {
+    const { face, controller, mirror } = await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
+    face.settings.describe.mockResolvedValue(remoteOk({
+      writable: true, hasDocument: false,
+      namespaces: wireNamespaces().filter(view => view.ns !== 'llm-pi-ai'),
+    }))
+    // A namespace change reaches the page through the mirror's own refresh.
+    await act(async () => {
+      await mirror.load()
+      await controller.load()
+    })
+    // Nothing can be declared any more, so the form is gone rather than left
+    // to create a route the Host would refuse; the catalog form stands alone.
+    expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull()
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.getByRole('combobox', { name: en.provider })).toBeTruthy()
+  })
+
+  it('forgets the catalog target when the custom form closes, so a later refresh opens no row editor', async () => {
+    const { face, controller, mirror } = await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.getByRole<HTMLSelectElement>('combobox', { name: en.provider }).value).toBe('anthropic')
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    fireEvent.click(within(screen.getByRole('tabpanel', { name: en.addCustom })).getByText(en.cancel))
+    expect(screen.queryByRole('tablist')).toBeNull()
+    // The draft's provider gets configured elsewhere: its row must arrive closed.
+    const withAnthropic = (layer: unknown): JsonValue => ({
+      providers: { ...(layer as { providers: object }).providers, anthropic: { apiKeyEnv: 'ANTHROPIC_API_KEY' } },
+    })
+    face.settings.describe.mockResolvedValue(remoteOk({
+      writable: true, hasDocument: false,
+      namespaces: wireNamespaces().map(view => view.ns === 'llm-pi-ai'
+        ? { ...view, value: withAnthropic(view.value), user: withAnthropic(view.user) }
+        : view),
+    }))
+    await act(async () => {
+      await mirror.load()
+      await controller.load()
+    })
+    expect(screen.getByRole('button', { name: providerCopy(en.editProvider, { provider: 'anthropic', displayName: 'anthropic' }) })).toBeTruthy()
+    expect(screen.queryAllByLabelText(en.keyInput)).toHaveLength(0)
+  })
+
+  it('locks the mode switch while the catalog form has a write in flight', async () => {
+    let settle: (() => void) | undefined
+    const pending = new Promise<void>((resolve) => { settle = resolve })
+    const providerNamespace = wireNamespaces().find(view => view.ns === 'llm-pi-ai')!
+    const mutate = vi.fn(() => pending.then(() => remoteOk(providerNamespace)))
+    await mountSection({ mutate })
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-slow' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await waitFor(() => { expect(screen.getByRole<HTMLButtonElement>('tab', { name: en.addCustom }).disabled).toBe(true) })
+    expect(screen.getByRole<HTMLButtonElement>('tab', { name: en.addCatalog }).disabled).toBe(true)
+    await act(async () => { settle!(); await pending })
+    // The apply closes the card once it lands; nothing was switched underneath it.
+    await waitFor(() => { expect(screen.queryByRole('tablist')).toBeNull() })
+    expect(mutate).toHaveBeenCalledOnce()
+  })
+
+  it('locks the mode switch while the custom form is asking the endpoint for models', async () => {
+    const scripted = scriptedFace()
+    let settle: (() => void) | undefined
+    const pending = new Promise<void>((resolve) => { settle = resolve })
+    scripted.face.llm.discoverModels.mockImplementation(() => pending.then(() => remoteOk([])))
+    await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    const custom = within(screen.getByRole('tabpanel', { name: en.addCustom }))
+    fireEvent.change(custom.getByRole('textbox', { name: en.baseUrl }), { target: { value: 'https://acme.test/v1' } })
+    fireEvent.click(custom.getByRole('button', { name: en.fetchModels }))
+    await waitFor(() => { expect(screen.getByRole<HTMLButtonElement>('tab', { name: en.addCatalog }).disabled).toBe(true) })
+    await act(async () => { settle!(); await pending })
+    await waitFor(() => { expect(screen.getByRole<HTMLButtonElement>('tab', { name: en.addCatalog }).disabled).toBe(false) })
+  })
+
+  it('pairs each tab with its panel through ids', async () => {
+    await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    const catalogTab = screen.getByRole('tab', { name: en.addCatalog })
+    const catalogPanel = screen.getByRole('tabpanel', { name: en.addCatalog })
+    expect(catalogTab.getAttribute('aria-controls')).toBe(catalogPanel.id)
+    expect(catalogPanel.getAttribute('aria-labelledby')).toBe(catalogTab.id)
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    const customTab = screen.getByRole('tab', { name: en.addCustom })
+    const customPanel = screen.getByRole('tabpanel', { name: en.addCustom })
+    expect(customTab.getAttribute('aria-controls')).toBe(customPanel.id)
+    expect(customPanel.getAttribute('aria-labelledby')).toBe(customTab.id)
+  })
+
+  it('titles a single-mode card with its mode instead of leaving an orphan tabpanel', async () => {
+    const scripted = scriptedFace()
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([]))
+    await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.queryByRole('tabpanel')).toBeNull()
+    expect(screen.getByText(en.addCustom)).toBeTruthy()
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
+  })
+
+  it('explains a locked mode through its hover title', async () => {
+    const scripted = scriptedFace()
+    scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([
+      { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    ]))
+    await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.getByRole('tab', { name: en.addCatalog }).getAttribute('title')).toBe(en.addCatalogExhausted)
+    expect(screen.getByRole('tab', { name: en.addCustom }).getAttribute('title')).toBeNull()
+  })
+
+  it('explains a mode with no protocol to declare through its hover title', async () => {
+    const scripted = scriptedFace()
+    const protocolless = JSON.parse(JSON.stringify(
+      Schema.object({ providers: Schema.dict(Schema.object({})) }).toJSON(),
+    )) as JsonValue
+    scripted.face.settings.describe.mockResolvedValue(remoteOk({
+      writable: true, hasDocument: false,
+      namespaces: wireNamespaces().map(view => view.ns === 'llm-pi-ai' ? { ...view, schema: protocolless } : view),
+    }))
+    await mountFace(scripted)
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    expect(screen.getByRole('tab', { name: en.addCustom }).getAttribute('title')).toBe(en.addCustomUnavailable)
+    expect(screen.getByRole('tab', { name: en.addCatalog }).getAttribute('title')).toBeNull()
+  })
+
+  it('collapses the add card from the custom mode on cancel', async () => {
+    await mountSection()
+    fireEvent.click(screen.getByRole('button', { name: en.add }))
+    fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+    fireEvent.click(within(screen.getByRole('tabpanel', { name: en.addCustom })).getByText(en.cancel))
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.getByRole('button', { name: en.add })).toBeTruthy()
+  })
+
   it('cancels the add card back to the add button', async () => {
     await mountSection()
     fireEvent.click(screen.getByText(en.add))
diff --git a/packages/client/ui-settings-models/tests/model-list-catalog.client.spec.tsx b/packages/client/ui-settings-models/tests/model-list-catalog.client.spec.tsx
index 60e7d79165..a0034f2f7c 100644
--- a/packages/client/ui-settings-models/tests/model-list-catalog.client.spec.tsx
+++ b/packages/client/ui-settings-models/tests/model-list-catalog.client.spec.tsx
@@ -27,7 +27,7 @@ it('ignores a late catalog response after the provider changes', async () => {
   const onChange = vi.fn()
   const props = {
     models: [{ id: 'm' }], onChange, operations: actions,
-    disabled: false, t: (key: keyof typeof en) => en[key],
+    disabled: false, t: (key: keyof typeof en) => en[key], onBusyChange: () => {},
   }
   const { rerender } = render(<ModelListEditor {...props} catalogProvider="old" probe={{ settingsNs: 'llm-pi-ai', provider: 'old' }} />)
   fireEvent.click(screen.getByRole('button', { name: `${en.modelAdvanced} 1` }))
@@ -44,7 +44,7 @@ it('uses provider input defaults for a model absent from the installed catalog',
   const onChange = vi.fn()
   render(<ModelListEditor
     models={[{ id: 'custom' }]} onChange={onChange} defaultInput={['image']} catalogProvider="openai"
-    probe={{ settingsNs: 'llm-pi-ai', provider: 'openai' }} disabled={false} t={key => en[key]}
+    probe={{ settingsNs: 'llm-pi-ai', provider: 'openai' }} disabled={false} t={key => en[key]} onBusyChange={() => {}}
     operations={operations(() => Promise.resolve({ kind: 'found', models: [] }))}
   />)
   fireEvent.click(screen.getByRole('button', { name: `${en.modelAdvanced} 1` }))
@@ -60,7 +60,7 @@ it('inherits catalog inputs once an incomplete draft has a model id', async () =
   const props = {
     onChange, catalogProvider: 'openai',
     probe: { settingsNs: 'llm-pi-ai', provider: 'openai' },
-    disabled: false, t: (key: keyof typeof en) => en[key],
+    disabled: false, t: (key: keyof typeof en) => en[key], onBusyChange: () => {},
     operations: operations(() => Promise.resolve({
       kind: 'found', models: [{ id: 'vision', inputModalities: ['text', 'image'] }],
     })),
@@ -89,7 +89,7 @@ it('restores inherited image input after a failed catalog read is retried manual
   const onChange = vi.fn()
   render(<ModelListEditor
     models={[{ id: 'vision' }]} onChange={onChange} catalogProvider="openai"
-    probe={{ settingsNs: 'llm-pi-ai', provider: 'openai' }} disabled={false} t={key => en[key]}
+    probe={{ settingsNs: 'llm-pi-ai', provider: 'openai' }} disabled={false} t={key => en[key]} onBusyChange={() => {}}
     operations={operations(discover)}
   />)
   await screen.findByText('Catalog unavailable')
diff --git a/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx b/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx
index 57c61d702b..e482be4fbd 100644
--- a/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx
+++ b/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx
@@ -225,6 +225,12 @@ function openEditor(provider: string): void {
   fireEvent.click(summary)
 }
 
+/** Open the add card from the section and switch it to the custom-API mode. */
+function openCustomMode(): void {
+  fireEvent.click(screen.getByRole('button', { name: en.add }))
+  fireEvent.click(screen.getByRole('tab', { name: en.addCustom }))
+}
+
 /** Open one model row's advanced fold, where the capacities live. */
 function expandModel(index: number): void {
   fireEvent.click(screen.getByLabelText(`${en.modelAdvanced} ${index}`))
@@ -1417,27 +1423,40 @@ describe('hand-declared providers', () => {
     expect(buttonNamed(en.create).disabled).toBe(true)
   })
 
-  it('closes the create card when an existing row is opened for editing', async () => {
+  it('closes the add card when an existing row is opened for editing', async () => {
     await mountSection({ providers: { openai: { baseURL: 'https://proxy.example/v1' } } })
 
-    fireEvent.click(screen.getByRole('button', { name: en.customAdd }))
-    expect(screen.getByText(en.customTitle)).toBeTruthy()
+    openCustomMode()
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
 
     // Two cards at once would each be closable by the other: whichever one is
     // dismissed clears the shared state and discards the other's draft.
     openEditor('openai')
-    expect(screen.queryByText(en.customTitle)).toBeNull()
+    expect(screen.queryByRole('tablist')).toBeNull()
+    expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull()
   })
 
-  it('reaches the card from the section and returns to the button on cancel', async () => {
+  it('reaches the custom form from the section and returns to the button on cancel', async () => {
     await mountSection()
 
-    fireEvent.click(screen.getByRole('button', { name: en.customAdd }))
-    expect(screen.getByText(en.customTitle)).toBeTruthy()
+    openCustomMode()
+    expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy()
 
     fireEvent.click(screen.getByText(en.cancel))
-    await waitFor(() => { expect(screen.queryByText(en.customTitle)).toBeNull() })
-    expect(screen.getByRole('button', { name: en.customAdd })).toBeTruthy()
+    await waitFor(() => { expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull() })
+    expect(screen.getByRole('button', { name: en.add })).toBeTruthy()
+  })
+
+  it('names each protocol by its product name and falls back to the identifier of an unknown one', () => {
+    mountCard({ protocols: [...PROTOCOLS, 'google-generative-ai'] })
+    const protocol = screen.getByLabelText<HTMLSelectElement>(en.customApi)
+    const labels = [...protocol.options].map(option => [option.value, option.textContent])
+    expect(labels).toEqual([
+      ['openai-completions', en.protocolOpenAiCompletions],
+      ['openai-responses', en.protocolOpenAiResponses],
+      ['anthropic-messages', en.protocolAnthropicMessages],
+      ['google-generative-ai', 'google-generative-ai'],
+    ])
   })
 
   it('refuses an unusable key on the field and blocks creation', () => {
@@ -1608,15 +1627,15 @@ describe('API key field', () => {
     const { controller, mutate } = await mountSection()
     const load = vi.spyOn(controller, 'load')
 
-    fireEvent.click(screen.getByRole('button', { name: en.customAdd }))
-    fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } })
-    fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } })
+    openCustomMode()
+    fireEvent.change(screen.getByRole('textbox', { name: en.customRoute }), { target: { value: 'acme' } })
+    fireEvent.change(screen.getByRole('textbox', { name: en.baseUrl }), { target: { value: 'https://acme.test/v1' } })
     fireEvent.click(screen.getByRole('button', { name: en.addModel }))
     fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } })
     fireEvent.click(screen.getByText(en.create))
 
     await waitFor(() => { expect(mutate).toHaveBeenCalledOnce() })
     await waitFor(() => { expect(load).toHaveBeenCalledOnce() })
-    expect(screen.queryByText(en.customTitle)).toBeNull()
+    expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull()
   })
 })
diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css
index bbf984fb20..5358b03f67 100644
--- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css
+++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css
@@ -178,13 +178,20 @@
   font-weight: 600;
 }
 
+/* The Loader entry id keeps one size in the card subtitle and the row it expands into;
+   the collapsed subtitle stays on the quieter label tier, while the expanded row carries
+   the card's primary value. */
+.cardIdentity,
+.entryValue {
+  font-family: var(--ds-font-family-code);
+  font-size: 12px;
+  line-height: 18px;
+}
+
 .cardIdentity {
   display: block;
   width: 100%;
   color: var(--dsw-alias-label-tertiary);
-  font-family: var(--ds-font-family-code);
-  font-size: 11px;
-  line-height: 16px;
 }
 
 .cardTrailing {
@@ -383,9 +390,6 @@
   display: block;
   overflow-wrap: anywhere;
   color: var(--dsw-alias-label-primary);
-  font-family: var(--ds-font-family-code);
-  font-size: 12px;
-  line-height: 18px;
 }
 
 .details {
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index 1b479691fd..8123e08a21 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md
-README.md: d70cb35878d77c1d3e928aa222a2c7e96874ea2c
-README.zh.md: 87687ac3ccc7f19d7b34f5724eba260a02e92044
+README.md: d688442cb003f980b037354f76997c18a2ca0be2
+README.zh.md: 92e2026d04f188854fd6205fe4d35e8c9c8e57b2
diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md
index d70cb35878..d688442cb0 100644
--- a/packages/client/ui-settings/README.md
+++ b/packages/client/ui-settings/README.md
@@ -29,7 +29,7 @@ Feature plugins use this package to store and edit their preferences without re-
 
 ### Binding a namespace
 
-`ctx.settingsScope.developerTools` owns the shared Web and desktop preference `ui-developer-tools.enabled`, defaulting to `false`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered settings writes. Desktop and loopback Web persist to the Host document; remote Web keeps this choice in one browser-local observable until reload without issuing Host writes. This controls presentation and HTML preview permissions, not Host authorization or Session recording.
+`ctx.settingsScope.developerTools` owns the shared Web and desktop preference `ui-developer-tools.enabled`, defaulting to `true`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered settings writes. Desktop and loopback Web persist to the Host document; remote Web keeps this choice in one browser-local observable until reload without issuing Host writes. This controls presentation and HTML preview permissions, not Host authorization or Session recording. Host-backed clients keep developer features disabled until the first accepted schema-resolved value arrives; missing or failed initial responses do not enable them. Later refreshes retain the last accepted choice.
 
 A feature calls `ctx.settingsScope.bind(spec)` with a per-namespace spec and gets a scope derived from the shared document mirror. The scope snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` clears that override. Writes go through the scope: `set` and `unset` submit one operation, while `mutate` submits several ordered operations atomically. These methods return `true` for Host acceptance and `false` for refusal or skipped writes; transport failures reject. Each write is fenced by the namespace revision as `expectedRevision`, so a concurrent write from another surface is refused instead of silently overwritten. A staged editor can supply the revision where its draft began as a fixed fence; otherwise the scope uses the latest queued or mirrored revision.
 
@@ -53,7 +53,7 @@ The package realizes one ownership rule: the browser keeps one shared mirror of
 
 ### The describe mirror
 
-The Host half registers the `ui-developer-tools` schema and its default-off value with settings. The Client plugin injects `remote` with its `settings` namespace, resolves Host persistence once from the fixed `remote.$host` facts, and owns the one `settings.describe` reader in the browser: a shared mirror refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included, closing the window where a commit lands between the eager read and the SSE subscription). Cross-namespace surfaces read it through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in).
+The Host half registers the `ui-developer-tools` schema and its default-on value with settings. The Client plugin injects `remote` with its `settings` namespace, resolves Host persistence once from the fixed `remote.$host` facts, and owns the one `settings.describe` reader in the browser: a shared mirror refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included, closing the window where a commit lands between the eager read and the SSE subscription). Cross-namespace surfaces read it through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in).
 
 ### Scope derivation
 
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index 87687ac3cc..92e2026d04 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 绑定命名空间
 
-`ctx.settingsScope.developerTools` 管理 Web 和桌面端共享的偏好 `ui-developer-tools.enabled`，默认为 `false`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 使用相同的有序设置写入。桌面端和回环 Web 将设置持久化到 Host 文档；远程 Web 将此选择保存在单个浏览器本地可观察值中，刷新后重置，不发送 Host 写入。此设置控制界面展示和 HTML 预览权限，不控制 Host 授权或 Session 记录。
+`ctx.settingsScope.developerTools` 管理 Web 和桌面端共享的偏好 `ui-developer-tools.enabled`，默认为 `true`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 使用相同的有序设置写入。桌面端和回环 Web 将设置持久化到 Host 文档；远程 Web 将此选择保存在单个浏览器本地可观察值中，刷新后重置，不发送 Host 写入。此设置控制界面展示和 HTML 预览权限，不控制 Host 授权或 Session 记录。 使用 Host 偏好的客户端在首个经过 schema 解析并接受的值到达前保持开发者功能关闭；首次响应缺失或失败不会启用它们。后续刷新保留已接受的选择。
 
 功能调用 `ctx.settingsScope.bind(spec)` 并传入按命名空间的 spec，得到一个由共享文档镜像派生的 scope。scope 快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host/内存模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会清除该覆盖。写入经 scope 进行：`set` 与 `unset` 提交一个操作，`mutate` 则原子提交多个有序操作。这些方法在 Host 接受时返回 `true`，拒绝或跳过写入时返回 `false`；传输失败会 reject。每次写入都以命名空间 revision 作为 `expectedRevision` 围栏，因此来自另一界面的并发写入会被拒绝，而不是被静默覆盖。暂存编辑器可以把开始草拟时读取的 revision 作为固定围栏传入；否则 scope 使用最新排队或镜像 revision。
 
@@ -53,7 +53,7 @@ kind: "package-reference"
 
 ### Describe 镜像
 
-Host 部分向 settings 注册 `ui-developer-tools` schema 及其默认关闭值。Client 插件注入 `remote` 及其 `settings` 命名空间，从固定的 `remote.$host` 事实一次性解析 Host 持久化模式，并持有浏览器中唯一的 `settings.describe` 读取方：一面共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内，关闭「提交落在急切读取与 SSE 订阅之间」的窗口）。跨命名空间表面通过 `ctx.settingsScope.describe()` 读它，这是一个读取/折叠面（`getSnapshot`/`subscribe`/`ensure`，另有把写应答折入的 `acceptView`）。
+Host 部分向 settings 注册 `ui-developer-tools` schema 及其默认开启值。Client 插件注入 `remote` 及其 `settings` 命名空间，从固定的 `remote.$host` 事实一次性解析 Host 持久化模式，并持有浏览器中唯一的 `settings.describe` 读取方：一面共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内，关闭「提交落在急切读取与 SSE 订阅之间」的窗口）。跨命名空间表面通过 `ctx.settingsScope.describe()` 读它，这是一个读取/折叠面（`getSnapshot`/`subscribe`/`ensure`，另有把写应答折入的 `acceptView`）。
 
 ### Scope 派生
 
diff --git a/packages/client/ui-settings/src/client/developer-tools.ts b/packages/client/ui-settings/src/client/developer-tools.ts
index 22e1e8de3d..907b32065a 100644
--- a/packages/client/ui-settings/src/client/developer-tools.ts
+++ b/packages/client/ui-settings/src/client/developer-tools.ts
@@ -3,11 +3,11 @@ import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-c
 import type { DeveloperToolsSettings } from '../developer-tools-settings.ts'
 import type { SettingsScope } from './settings-contract.ts'
 
-/** Shared preference; no accepted value means developer tools are disabled. */
+/** Shared preference; Host-backed features stay disabled until an accepted value arrives. */
 export class DeveloperToolsPreference {
   /** Accepted enablement, observable through renderer-bound hooks. */
   readonly enabled: ObservableSnapshot<boolean>
-  private readonly local = createSnapshotStore(false)
+  private readonly local = createSnapshotStore(true)
 
   /**
    * @param scope - settings-owned namespace controller.
diff --git a/packages/client/ui-settings/src/developer-tools-settings.ts b/packages/client/ui-settings/src/developer-tools-settings.ts
index e7a64e0e26..9b80e5d31e 100644
--- a/packages/client/ui-settings/src/developer-tools-settings.ts
+++ b/packages/client/ui-settings/src/developer-tools-settings.ts
@@ -10,7 +10,7 @@ export interface DeveloperToolsSettings {
   enabled: boolean
 }
 
-/** New installations and missing values use the basic interface. */
+/** New installations and missing values enable the full interface. */
 export const DeveloperToolsSettingsSchema: z<DeveloperToolsSettings> = z.object({
-  enabled: z.boolean().default(false),
+  enabled: z.boolean().default(true),
 })
diff --git a/packages/client/ui-settings/tests/developer-tools.client.spec.ts b/packages/client/ui-settings/tests/developer-tools.client.spec.ts
index 3a68290c19..08d9e0aa47 100644
--- a/packages/client/ui-settings/tests/developer-tools.client.spec.ts
+++ b/packages/client/ui-settings/tests/developer-tools.client.spec.ts
@@ -39,6 +39,39 @@ describe('developer tools settings', () => {
     expect(ctx.settingsScope.developerTools.enabled.getSnapshot()).toBe(false)
   })
 
+  it.each([false, true])('withholds features during a delayed Host read before accepting %s', async (enabled) => {
+    const ctx = new Context()
+    const accepted = { ok: true, value: {
+      writable: true, hasDocument: true, namespaces: [{
+        ns: DEVELOPER_TOOLS_NAMESPACE,
+        schema: DeveloperToolsSettingsSchema.toJSON(),
+        value: { enabled }, revision: 1, applies: 'live', secrets: [],
+      }],
+    } }
+    const pending = Promise.withResolvers<typeof accepted>()
+    onTestFinished(async () => { pending.resolve(accepted); await ctx.fiber.dispose() })
+    new TestRemote(ctx, { settings: { describe: () => pending.promise } })
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    const preference = ctx.settingsScope.developerTools
+    const changed = vi.fn()
+    const dispose = preference.enabled.subscribe(changed)
+    onTestFinished(dispose)
+    expect(preference.enabled.getSnapshot()).toBe(false)
+    pending.resolve(accepted)
+    await ctx.settingsScope.describe().ensure()
+    expect(preference.enabled.getSnapshot()).toBe(enabled)
+    expect(changed).toHaveBeenCalledTimes(enabled ? 1 : 0)
+  })
+
+  it('keeps features disabled when the initial Host read fails', async () => {
+    const ctx = new Context()
+    onTestFinished(() => ctx.fiber.dispose())
+    new TestRemote(ctx, { settings: { describe: () => Promise.reject(new Error('disconnected')) } })
+    await ctx.plugin({ inject, apply: clientApply }).await()
+    await ctx.settingsScope.describe().ensure()
+    expect(ctx.settingsScope.developerTools.enabled.getSnapshot()).toBe(false)
+  })
+
   it('shares one remote-browser preference across consumers and disposes it with the plugin', async () => {
     const ctx = new Context()
     onTestFinished(() => ctx.fiber.dispose())
@@ -49,13 +82,14 @@ describe('developer tools settings', () => {
     await fiber.await()
     const preference = ctx.settingsScope.developerTools
     expect(fiber.ctx.settingsScope.developerTools.enabled).toBe(preference.enabled)
+    expect(preference.enabled.getSnapshot()).toBe(true)
     await preference.setEnabled(true)
     expect(fiber.ctx.settingsScope.developerTools.enabled.getSnapshot()).toBe(true)
     expect(describeCall).not.toHaveBeenCalled()
     await fiber.dispose()
     expect(ctx.get('settingsScope')).toBeUndefined()
   })
-  it('defaults off, persists valid choices and removes its schema on disposal', async () => {
+  it('defaults on, keeps an explicit false, persists valid choices and removes its schema on disposal', async () => {
     const ctx = new Context()
     const provider = ctx.plugin(MemorySettings)
     onTestFinished(() => provider.dispose())
@@ -63,6 +97,8 @@ describe('developer tools settings', () => {
     const fiber = ctx.plugin({ apply })
     onTestFinished(() => fiber.dispose())
     await fiber.await()
+    expect(ctx.settings.get(DEVELOPER_TOOLS_NAMESPACE)).toEqual({ enabled: true })
+    await ctx.settings.update(DEVELOPER_TOOLS_NAMESPACE, { enabled: false })
     expect(ctx.settings.get(DEVELOPER_TOOLS_NAMESPACE)).toEqual({ enabled: false })
     await ctx.settings.update(DEVELOPER_TOOLS_NAMESPACE, { enabled: true })
     expect(ctx.settings.get(DEVELOPER_TOOLS_NAMESPACE)).toEqual({ enabled: true })
@@ -71,19 +107,19 @@ describe('developer tools settings', () => {
     expect(ctx.settings.describe().map(row => row.ns)).not.toContain(DEVELOPER_TOOLS_NAMESPACE)
   })
 
-  it('stays off until accepted settings arrive and follows external changes', async () => {
+  it('stays off until accepted settings arrive, then follows a stored false and external changes', async () => {
     const host = stubSettingsScope<DeveloperToolsSettings>()
     const preference = new DeveloperToolsPreference(host.scope)
+    expect(preference.enabled.getSnapshot()).toBe(false)
     const notify = vi.fn()
     const dispose = preference.enabled.subscribe(notify)
+    host.publish({ status: 'ready', value: { enabled: false } })
     expect(preference.enabled.getSnapshot()).toBe(false)
-    host.publish({ status: 'ready', value: { enabled: true } })
+    expect(notify).not.toHaveBeenCalled()
+    await preference.setEnabled(true)
+    expect(host.set).toHaveBeenCalledWith('enabled', true)
+    host.publish({ value: { enabled: true } })
     expect(preference.enabled.getSnapshot()).toBe(true)
-    expect(notify).toHaveBeenCalledOnce()
-    await preference.setEnabled(false)
-    expect(host.set).toHaveBeenCalledWith('enabled', false)
-    host.publish({ value: { enabled: false } })
-    expect(preference.enabled.getSnapshot()).toBe(false)
     dispose()
   })
 })
@@ -94,13 +130,14 @@ it('keeps remote browser choices local and publishes only changed values', async
   const preference = new DeveloperToolsPreference(host.scope)
   const notify = vi.fn()
   const dispose = preference.enabled.subscribe(notify)
-  expect(preference.enabled.getSnapshot()).toBe(false)
-  await preference.setEnabled(true)
   expect(preference.enabled.getSnapshot()).toBe(true)
-  await preference.setEnabled(true)
-  expect(notify).toHaveBeenCalledOnce()
   await preference.setEnabled(false)
   expect(preference.enabled.getSnapshot()).toBe(false)
+  await preference.setEnabled(false)
+  expect(notify).toHaveBeenCalledOnce()
+  await preference.setEnabled(true)
+  expect(preference.enabled.getSnapshot()).toBe(true)
+  expect(notify).toHaveBeenCalledTimes(2)
   expect(host.set).not.toHaveBeenCalled()
   dispose()
 })
@@ -117,3 +154,10 @@ it('ignores host revisions that do not change enablement', () => {
   expect(notify).toHaveBeenCalledOnce()
   dispose()
 })
+
+it('keeps an unavailable Host namespace disabled', () => {
+  const host = stubSettingsScope<DeveloperToolsSettings>()
+  const preference = new DeveloperToolsPreference(host.scope)
+  host.publish({ status: 'unavailable' })
+  expect(preference.enabled.getSnapshot()).toBe(false)
+})
diff --git a/packages/client/ui-sidebar-browser/README.i18n.yaml b/packages/client/ui-sidebar-browser/README.i18n.yaml
index 533b9d85e2..9cd455c8d6 100644
--- a/packages/client/ui-sidebar-browser/README.i18n.yaml
+++ b/packages/client/ui-sidebar-browser/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-browser/README.md
-README.md: 61de40ef98c72501c20c56cffb1075322bcb4886
-README.zh.md: 8bdc88a85f2473e62c640e509db53577c1f2e6d4
+README.md: 52ebeddd088a8427b1bf058442b6fab6a768de37
+README.zh.md: 93df01dbe13bfa4a5aa318a1fd3a9e9786cd3c67
diff --git a/packages/client/ui-sidebar-browser/README.md b/packages/client/ui-sidebar-browser/README.md
index 61de40ef98..52ebeddd08 100644
--- a/packages/client/ui-sidebar-browser/README.md
+++ b/packages/client/ui-sidebar-browser/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Browse HTTP(S) pages, including loopback services, inside independent right-Sidebar tabs. The current carrier is an iframe with application-managed history in both Web and Desktop. The package never injects Electron or Node access into visited content.
+Browse HTTP(S) pages, including loopback services, inside independent right-Sidebar tabs. Web uses an iframe with application-managed history; Desktop uses Electron `<webview>` with native navigation history and retained pages. The package never injects Electron or Node access into visited content.
 
 ## Table of Contents
 
@@ -25,7 +25,7 @@ Browse HTTP(S) pages, including loopback services, inside independent right-Side
 <a id="use-this-package"></a>
 ## Use this package
 
-The shipped Web and Desktop compositions already mount this package. Open **Browser** from the right-Sidebar guide, enter an HTTP(S) URL, or select an HTTP(S) link in Assistant Markdown. A host name without a scheme becomes HTTPS. Public and loopback targets use the same default sandbox. Each guide action or message-link activation creates another Browser tab.
+Browser is disabled by default in Web profiles and enabled on Desktop. Enable the shipped entry through the Web profile patch to use it. Open **Browser** from the right-Sidebar guide and enter an HTTP(S) URL. Chat HTTP(S) links open here when the [link preference](../ui-chat/README.md) selects the built-in browser. A host name without a scheme becomes HTTPS. Public and loopback targets use the same default sandbox. Each guide action or delegated message-link activation creates another Browser tab.
 
 ### When to choose it
 
@@ -33,16 +33,16 @@ Choose Browser for a Web page that should remain beside the current Session. Cho
 
 ### Minimal configuration
 
-The package has no configuration. A custom Web composition mounts its Host companion; the Client loader then discovers the browser entry declared by the package manifest:
+The package has no plugin configuration. A Web profile enables the shipped entry through its profile patch:
 
 ```yaml
 - id: ui-sidebar-browser
-  name: '@deepseek-ai/dsh-client-ui-sidebar-browser'
+  disabled: false
 ```
 
 Client plugins can open a tab through `ctx.sidebarRight.openTab('browser', { params: { url } })`. The optional URL passes the same validation as address-bar input before navigation.
 
-The toolbar provides Back, Forward, Reload, Go, Open in system browser, and a rightmost per-tab sandbox toggle. Disabling the sandbox is temporary and displays a warning. The external action accepts a known HTTP(S) target. The tab title is the Web host.
+The toolbar provides Back, Forward, Reload, Go, and Open in system browser. Web also offers a per-tab sandbox toggle; disabling it is temporary and displays a warning. Desktop shows the observed page title. After a restart, Browser shows the saved title and URL; Restore or Reload opens that address only when requested.
 
 -----
 
@@ -58,15 +58,15 @@ The address parser accepts HTTP and HTTPS, including loopback targets. It reject
 
 ### Iframe carrier
 
-Web and Desktop use `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"` by default. The frame has no direct download or top-navigation flag. Popups leave the sandbox; in Web, an escaped popup retains its opener and can navigate the top-level application. The visited origin can use its own cookies and Web storage but a cross-origin target cannot read DSH DOM, storage, or API responses. The iframe sends no referrer and adds no package-owned Permissions Policy, so browser defaults and user grants apply. The toolbar can remove the sandbox for the current tab occurrence; the choice is not persisted. An unsandboxed page can navigate the top-level application under browser activation rules and use downloads, modal dialogs, and input locks. The package does not proxy or probe remote pages.
+Web uses `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"` by default. The frame has no direct download or top-navigation flag. Popups leave the sandbox; in Web, an escaped popup retains its opener and can navigate the top-level application. The visited origin can use its own cookies and Web storage but a cross-origin target cannot read DSH DOM, storage, or API responses. The iframe sends no referrer and adds no package-owned Permissions Policy, so browser defaults and user grants apply. The toolbar can remove the sandbox for the current tab occurrence; the choice is not persisted. An unsandboxed page can navigate the top-level application under browser activation rules and use downloads, modal dialogs, and input locks. The package does not proxy or probe remote pages.
 
 Web records toolbar submissions and typed tab opens. A navigation state machine treats the first iframe load for each controlled revision as known and a later load as proof that the page changed to an unreadable URL. In that unknown state the address is marked, Back, Forward, and external-open are disabled, and Reload returns to the last controlled URL. A remounted body reloads the latest application-known URL and uses its optional initial URL only before the first controlled target. History API and fragment changes that emit no iframe load remain invisible. An iframe `error` event displays a transient load-failure notice until the next controlled load without changing URL history.
 
 ### Controller
 
-Each tab receives one `BrowserController` class. Its public commands are `loadUrl`, `goBack`, `goForward`, and `reload`; address validation and history mutation stay behind that object. Its `BrowserNavigation` class owns the serializable URL state machine. The `BrowserFrame` interface owns transient sandbox and document state plus carrier operations, and `IframeImpl` implements that interface for the current iframe carrier. Slot injection exposes keyed frame state through `useBrowserFrame` and supplies plain callbacks, so the React body receives neither the controller nor an observable source; it keeps only the editable draft and iframe DOM.
+Each tab's `BrowserController` owns address validation, commands and explicit restoration. `BrowserFrame` supplies carrier-neutral navigation state; `IframeImpl` uses `BrowserNavigation`, while `ElectronWebViewImpl` observes Chromium history. `BrowserPresentation` owns physical DOM attachment. Slot injection supplies `useBrowserState` and plain callbacks, keeping provider objects and observables out of the React body.
 
-The controller interface does not depend on iframe APIs. A future `ElectronWebViewImpl` can implement `BrowserFrame` while owning `<webview>` attachment and target identity. That deferred carrier is documented in the same Sidebar Browser decision, but is not registered or tested today.
+Desktop's main process approves guest leases and enforces attachment, navigation and permission policy. Preload exposes only scoped Browser operations. Shared declarations use the standard `/types` export with `import type`; the Host and Client compile through separate tsconfig files. Desktop Browser tabs declare `keepMounted`, so Sidebar preserves their DOM across tab changes, Session switches, collapse and floating.
 
 </details>
 
@@ -77,7 +77,8 @@ The controller interface does not depend on iframe APIs. A future `ElectronWebVi
 
 - [Right Sidebar](../../../docs/subsystems/sidebar-right.md) — tab composition, navigation, and lifecycle.
 - [Document Preview](../ui-sidebar-documentpreview/README.md) — local source, Markdown, images, HTML, and PDF rendering.
-- [Sidebar Browser decision](../../../.agents/notes/implemented/feature/2026-09-16-sidebar-browser.md) — current iframe behavior, controller ownership, and deferred Electron carrier.
+- [Sidebar Browser decision](../../../.agents/notes/implemented/feature/2026-09-16-sidebar-browser.md) — iframe behavior and controller ownership.
+- [Desktop Browser decision](../../../.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.md) — webview leases, CWD storage grouping and manual restoration.
 
 -----
 
@@ -100,9 +101,9 @@ The isolation policy deliberately gives up some browser compatibility:
 - In Web, a popup that escapes the sandbox retains its opener and can use that chain to navigate the top-level application. Desktop handles popup creation separately.
 - A later iframe load reveals that navigation occurred but not the new cross-origin URL. History API and fragment changes may remain invisible; Web Back and Forward are unavailable after the state becomes unknown.
 - Browsers conceal many iframe failures for security: DNS, TLS, mixed-content, CSP, and `X-Frame-Options` failures may emit `load` or no actionable event instead of `error`. The load-failure notice is best-effort.
-- Browser history survives body remounts and ordinary page reloads, but closing the tab or unloading `ui-sidebar-right` aborts its occurrence and removes the stored history bucket.
+- Saved title and URL survive reloads and plugin unload while the tab remains in Sidebar's layout. Closing the tab removes its checkpoint. Restart restoration does not recover page memory, unsaved forms or Chromium's history stack.
 - Local files are rejected and remain owned by Document Preview.
-- The proposed Electron `<webview>` carrier, per-tab cookie partitions, native history, and target-specific CDP connection are not implemented.
+- Desktop shares process-local storage partitions by canonical workspace CWD; Sessions without a resolved Workspace are isolated separately. Cookies and Web storage do not survive application restart. Guest permissions, downloads and native popups are denied; approved HTTP(S) popup requests open Sidebar tabs. Host-address filtering is not a general private-network or DNS-rebinding firewall.
 
 <a id="dev-note"></a>
 ### Dev Note
@@ -114,4 +115,4 @@ None.
 
 </details>
 
-**Runtime invariant:** No companion is published. `BrowserNavigation` is the sole URL-state writer; the store receives its immutable snapshots, and focused controller and component tests exercise publication and cleanup directly.
+**Runtime invariant:** No companion is published. Each navigation provider owns its live state and publishes checkpoints directly; the UI consumes the same provider state through its controller.
diff --git a/packages/client/ui-sidebar-browser/README.zh.md b/packages/client/ui-sidebar-browser/README.zh.md
index 8bdc88a85f..93df01dbe1 100644
--- a/packages/client/ui-sidebar-browser/README.zh.md
+++ b/packages/client/ui-sidebar-browser/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-在独立的右侧 Sidebar tab 中浏览 HTTP(S) 页面，包括 loopback 服务。当前 Web 与 Desktop 都使用 iframe 和应用维护的 history。本包不会向被访问内容注入 Electron 或 Node 能力。
+在独立的右侧 Sidebar tab 中浏览 HTTP(S) 页面，包括 loopback 服务。Web 使用 iframe 和应用维护的 history；Desktop 使用 Electron `<webview>`、原生导航 history 和保活页面。本包不会向被访问内容注入 Electron 或 Node 能力。
 
 ## 目录
 
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-随附的 Web 与 Desktop composition 已挂载本包。可以从右侧 Sidebar guide 打开 **浏览器**、输入 HTTP(S) URL，或点击 Assistant Markdown 中的 HTTP(S) 链接。不带 scheme 的主机名会补全为 HTTPS。公共目标与 loopback 目标使用相同的默认 sandbox。每次 guide 操作或消息链接操作都会创建一个新的 Browser tab。
+Browser 在 Web profile 中默认禁用，在 Desktop 中默认启用。Web 用户可通过 profile patch 启用随附条目。可以从右侧 Sidebar guide 打开 **浏览器**并输入 HTTP(S) URL。Chat 的[链接偏好](../ui-chat/README.zh.md)选择内置浏览器时，HTTP(S) 链接会在此打开。不带 scheme 的主机名会补全为 HTTPS。公共目标与 loopback 目标使用相同的默认 sandbox。每次 guide 操作或委托到此的消息链接操作都会创建一个新的 Browser tab。
 
 ### 何时选择
 
@@ -33,16 +33,16 @@ kind: "package-reference"
 
 ### 最小配置
 
-本包没有配置字段。自定义 Web composition 挂载 Host companion；随后 Client loader 会发现 package manifest 声明的浏览器入口：
+本包没有插件配置字段。Web profile 通过其 profile patch 启用随附条目：
 
 ```yaml
 - id: ui-sidebar-browser
-  name: '@deepseek-ai/dsh-client-ui-sidebar-browser'
+  disabled: false
 ```
 
 Client 插件可以调用 `ctx.sidebarRight.openTab('browser', { params: { url } })` 打开 tab。可选 URL 会在导航前接受与地址栏输入相同的校验。
 
-工具栏提供后退、前进、刷新、前往、在系统浏览器中打开，以及最右侧的逐 tab sandbox 开关。关闭 sandbox 是临时选择，并会显示警告。外部打开接受已知的 HTTP(S) 目标。tab 标题显示 Web 主机名。
+工具栏提供后退、前进、刷新、前往和在系统浏览器中打开。Web 还提供逐 tab sandbox 开关；关闭它是临时选择，并会显示警告。Desktop 显示观察到的页面标题。重启后，Browser 展示保存的标题和 URL；只有点击恢复或刷新才打开该地址。
 
 -----
 
@@ -58,15 +58,15 @@ Client 插件可以调用 `ctx.sidebarRight.openTab('browser', { params: { url }
 
 ### Iframe 载体
 
-Web 与 Desktop 默认使用 `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"`。frame 没有直接的下载或顶层导航 flag。popup 会脱离 sandbox；在 Web 中，逃逸的 popup 会保留 opener，并可以导航顶层应用。被访问的 origin 可以使用自身 Cookie 与 Web storage，但跨域目标无法读取 DSH DOM、storage 或 API 响应。iframe 不发送 referrer，也不添加包自有的 Permissions Policy，因此浏览器默认策略与用户授权生效。toolbar 可以为当前 tab occurrence 移除 sandbox；该选择不持久化。未受 sandbox 约束的页面可以按浏览器 activation 规则导航顶层应用，并使用下载、模态对话框和输入锁定。本包不代理或探测远程页面。
+Web 默认使用 `sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox"`。frame 没有直接的下载或顶层导航 flag。popup 会脱离 sandbox；在 Web 中，逃逸的 popup 会保留 opener，并可以导航顶层应用。被访问的 origin 可以使用自身 Cookie 与 Web storage，但跨域目标无法读取 DSH DOM、storage 或 API 响应。iframe 不发送 referrer，也不添加包自有的 Permissions Policy，因此浏览器默认策略与用户授权生效。toolbar 可以为当前 tab occurrence 移除 sandbox；该选择不持久化。未受 sandbox 约束的页面可以按浏览器 activation 规则导航顶层应用，并使用下载、模态对话框和输入锁定。本包不代理或探测远程页面。
 
 Web 记录 toolbar 提交和 typed tab 打开。导航状态机把每个受控 revision 的第一次 iframe load 视为已知，把后续 load 视为页面已经变化到不可读取 URL 的证据。进入 unknown 状态后，地址会显示标记，后退、前进和外部打开会禁用，刷新则返回最后一个受控 URL。body 重挂载时会重新加载应用最后已知的 URL，并且仅在尚无受控目标时使用可选初始 URL。不产生 iframe load 的 History API 与 fragment 变化仍不可见。iframe `error` event 会显示临时加载失败 notice，直到下一个受控加载，但不会改变 URL history。
 
 ### Controller
 
-每个 tab 获得一个 `BrowserController` class。它的公开命令只有 `loadUrl`、`goBack`、`goForward` 与 `reload`；地址校验与 history 变更均由该对象封装。它的 `BrowserNavigation` class 拥有可序列化的 URL 状态机。`BrowserFrame` 接口负责临时 sandbox 与 document 状态以及载体操作，`IframeImpl` 为当前 iframe 载体实现该接口。Slot injection 通过 `useBrowserFrame` 提供按 key 索引的 frame 状态，并提供普通 callback，因此 React body 不接收 controller 或 observable source；它只保留可编辑草稿与 iframe DOM。
+每个 tab 的 `BrowserController` 负责地址校验、命令和显式恢复。`BrowserFrame` 提供与载体无关的导航状态；`IframeImpl` 使用 `BrowserNavigation`，`ElectronWebViewImpl` 观察 Chromium history。`BrowserPresentation` 负责 DOM 的物理挂载。Slot injection 提供 `useBrowserState` 和普通 callback，React body 不接收 provider 对象或 observable。
 
-Controller 接口不依赖 iframe API。未来的 `ElectronWebViewImpl` 可以实现 `BrowserFrame`，并持有 `<webview>` attachment 与 target identity。该延期载体记录在同一份 Sidebar Browser 决策中，当前不注册也不测试。
+Desktop 主进程批准 guest 租约，并执行挂载、导航和权限策略。preload 只暴露限定范围的 Browser 操作。共享声明通过标准 `/types` 出口配合 `import type` 引入；Host 与 Client 使用独立 tsconfig 编译。Desktop Browser tab 声明 `keepMounted`，Sidebar 因而在切 tab、切 Session、收起与浮动期间保留其 DOM。
 
 </details>
 
@@ -77,7 +77,8 @@ Controller 接口不依赖 iframe API。未来的 `ElectronWebViewImpl` 可以
 
 - [右侧 Sidebar](../../../docs/subsystems/sidebar-right.zh.md)——tab composition、导航与生命周期。
 - [Document Preview](../ui-sidebar-documentpreview/README.zh.md)——本地源码、Markdown、图片、HTML 与 PDF 渲染。
-- [Sidebar Browser 决策](../../../.agents/notes/implemented/feature/2026-09-16-sidebar-browser.zh.md)——当前 iframe 行为、controller 所有权与延期 Electron 载体。
+- [Sidebar Browser 决策](../../../.agents/notes/implemented/feature/2026-09-16-sidebar-browser.zh.md)——iframe 行为与 controller 所有权。
+- [Desktop Browser 决策](../../../.agents/notes/implemented/feature/2026-09-20-desktop-browser-webview.zh.md)——webview 租约、CWD 存储分组与手动恢复。
 
 -----
 
@@ -100,9 +101,9 @@ Controller 接口不依赖 iframe API。未来的 `ElectronWebViewImpl` 可以
 - 在 Web 中，逃逸出 sandbox 的 popup 会保留 opener，并可以通过该链导航顶层应用。Desktop 会单独处理 popup 创建。
 - 后续 iframe load 能表明发生了导航，但无法给出新的跨域 URL。History API 与 fragment 变化可能仍不可见；状态变成 unknown 后，Web 的后退与前进不可用。
 - 出于安全原因，浏览器会隐藏很多 iframe 失败：DNS、TLS、mixed-content、CSP 与 `X-Frame-Options` 失败可能触发 `load`，也可能不提供可操作 event，而不是触发 `error`。加载失败 notice 只能作为 best-effort 提示。
-- Browser history 会跨 body 重挂载与普通页面刷新保留，但关闭 tab 或卸载 `ui-sidebar-right` 会中止其 occurrence 并删除已存储的 history bucket。
+- 只要 tab 仍在 Sidebar 布局中，保存的标题和 URL 就会跨刷新与插件卸载保留。关闭 tab 会删除其检查点。重启恢复不恢复页面内存、未保存的表单或 Chromium history 栈。
 - 本地文件会被拒绝，并继续由 Document Preview 负责。
-- 拟议的 Electron `<webview>` 载体、per-tab Cookie partition、原生 history 和 target-specific CDP 连接尚未实现。
+- Desktop 按规范化的工作区 CWD 共享进程内存储分区；没有解析到 Workspace 的 Session 单独隔离。Cookie 与 Web storage 不跨应用重启保留。guest 权限、下载与原生 popup 均被拒绝；通过检查的 HTTP(S) popup 请求会打开 Sidebar tab。Host 地址过滤不是通用私网或 DNS-rebinding 防火墙。
 
 <a id="dev-note"></a>
 ### 开发备注
@@ -114,4 +115,4 @@ Controller 接口不依赖 iframe API。未来的 `ElectronWebViewImpl` 可以
 
 </details>
 
-**运行时不变量：** 不发布 companion。`BrowserNavigation` 是唯一的 URL 状态写入方；store 接收它的 immutable snapshot，controller 与组件的聚焦测试直接覆盖发布与清理。
+**运行时不变量：** 不发布 companion。每个导航 provider 拥有自身的实时状态并直接发布检查点；UI 通过 controller 消费同一份 provider 状态。
diff --git a/packages/client/ui-sidebar-browser/package.json b/packages/client/ui-sidebar-browser/package.json
index 3e833cf496..94f05df6ed 100644
--- a/packages/client/ui-sidebar-browser/package.json
+++ b/packages/client/ui-sidebar-browser/package.json
@@ -22,12 +22,16 @@
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "dsh": {
     "client": {
       "inject": [
+        "@deepseek-ai/dsh-api-workspace-controller",
         "@deepseek-ai/dsh-client-ui-sidebar-right",
         "@deepseek-ai/dsh-client-ui-session"
       ],
@@ -44,6 +48,8 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-api-workspace-controller": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-client-locale": "workspace:^",
     "@deepseek-ai/dsh-client-store": "workspace:^",
     "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts b/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts
index afa413010f..45d17bb259 100644
--- a/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts
+++ b/packages/client/ui-sidebar-browser/src/client/browser/BrowserController.ts
@@ -1,166 +1,267 @@
-/** Per-tab Browser controller. */
-import type { BoundActions } from '@deepseek-ai/dsh-client-store'
+/** Carrier-independent tab commands and renderer-facing state. */
+import { createSnapshotStore, type BoundActions, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
 import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
-import { IframeImpl } from './BrowserFrame.ts'
-import type { BrowserFrame, BrowserFrameState } from './BrowserFrame.ts'
-import { BrowserNavigation } from './BrowserNavigation.ts'
-import type { BrowserTabState } from './BrowserNavigation.ts'
+import type { BrowserFrameState } from './BrowserFrame.ts'
+import type { BrowserPage, BrowserPageFactory } from './BrowserPage.ts'
+import { currentBrowserTarget, type BrowserTabState } from './BrowserPersistence.ts'
 import type { BrowserStore } from './store.ts'
-import { parseBrowserAddress } from './url.ts'
+import { parseBrowserAddress, type BrowserAddressFailure, type BrowserTarget } from './url.ts'
 
-/** Construction dependencies for one tab-scoped Browser controller. */
+/** Live tab state; navigation comes from its provider and draft validation stays local. */
+export interface BrowserControllerState {
+  readonly frame: BrowserFrameState
+  /** Saved address offered for explicit restoration before any page has been requested. */
+  readonly restoreTarget: BrowserTarget | undefined
+  readonly addressFailure: BrowserAddressFailure | undefined
+  readonly addressRevision: number
+}
+
+/** Construction inputs for one tab occurrence. */
 export interface BrowserControllerOptions {
   readonly tabId: TabId
   readonly signal: AbortSignal
   readonly applicationOrigin: string
-  readonly initial?: BrowserTabState
+  readonly initial: BrowserTabState | undefined
   readonly actions: BoundActions<BrowserStore>
+  readonly createPage: BrowserPageFactory
+  readonly openTab: (url: string) => void
 }
 
-/** Owns one Browser tab's URL state, loading lifecycle, and four navigation commands. */
-export class BrowserController {
-  /** Renderer-facing iframe and sandbox state. */
-  readonly frame: BrowserFrame
-  private readonly navigation: BrowserNavigation
+/** Owns input validation and page lifetime without inspecting the carrier type. */
+export class BrowserController implements HostObservable<BrowserControllerState> {
+  private readonly page: BrowserPage
+  private readonly store: SnapshotStore<BrowserControllerState>
+  private readonly unsubscribe: () => void
+  private actions: BoundActions<BrowserStore>
+  private checkpoint: BrowserTabState | undefined
+  private started = false
   private disposed = false
+  private disposal: Promise<void> | undefined
+  private readonly abort = (): void => { void this.dispose() }
+
+  /** @param options - identity, persistence, page factory and source-tab navigation. */
+  constructor(private readonly options: BrowserControllerOptions) {
+    this.actions = options.actions
+    this.checkpoint = options.initial
+    this.page = options.createPage({
+      initial: options.initial,
+      persist: (state) => {
+        if (this.disposed) return
+        this.checkpoint = state
+        this.actions.replace(options.tabId, state)
+      },
+      openRequested: (value) => {
+        if (this.disposed) return
+        const result = parseBrowserAddress(value, options.applicationOrigin)
+        if (!result.ok) { this.addressFailed(result.reason); return }
+        options.openTab(result.target.url)
+      },
+    })
+    this.store = createSnapshotStore({ frame: this.page.frame.getSnapshot(),
+      restoreTarget: currentBrowserTarget(this.checkpoint), addressFailure: undefined, addressRevision: 0 })
+    this.unsubscribe = this.page.frame.subscribe(() => {
+      if (this.disposed) return
+      const current = this.store.getSnapshot()
+      const frame = this.page.frame.getSnapshot()
+      const changed = frame.target?.url !== current.frame.target?.url
+      this.store.set({ frame, restoreTarget: frame.target === undefined ? currentBrowserTarget(this.checkpoint) : undefined,
+        addressFailure: changed ? undefined : current.addressFailure,
+        addressRevision: current.addressRevision + Number(changed) })
+    })
+    options.signal.addEventListener('abort', this.abort, { once: true })
+  }
+
+  /** @returns immutable state for the common toolbar. */
+  getSnapshot = (): BrowserControllerState => this.store.getSnapshot()
+  /** @param listener - state invalidation. @returns unsubscribe callback. */
+  subscribe = (listener: () => void): (() => void) => this.store.subscribe(listener)
 
   /**
-   * @param options - tab identity, persistence writer, URL origin, and lifetime.
+   * Attach the page without transferring ownership of its tab occurrence.
+   * @param viewportId - mounted content container.
+   * @returns physical attachment cleanup only.
    */
-  constructor(private readonly options: BrowserControllerOptions) {
-    this.navigation = new BrowserNavigation(options.initial)
-    this.frame = new IframeImpl(
-      () => { this.reload() },
-      (revision) => { this.frameLoaded(revision) },
-    )
-    options.signal.addEventListener('abort', () => { this.dispose() }, { once: true })
+  mount(viewportId: string): () => void {
+    this.publishSaved()
+    return this.page.presentation.mount(viewportId)
   }
 
   /**
-   * Validate and load one address, replacing a same-address load with Reload.
-   * @param value - address-bar or typed-tab value.
+   * Consume initial navigation once; a saved checkpoint alone never starts a page.
+   * @param initialUrl - explicit typed-open address, or absence.
+   */
+  start(initialUrl: string | undefined): void {
+    if (this.started || this.disposed) return
+    this.started = true
+    if (initialUrl !== undefined) this.loadUrl(initialUrl)
+  }
+
+  /** Load the saved address only after an explicit restore action. */
+  restore(): void {
+    const target = this.store.getSnapshot().restoreTarget
+    if (target !== undefined) this.loadUrl(target.url)
+  }
+
+  /**
+   * Validate an address before navigation, publishing invalid input for correction.
+   * @param value - address-bar or typed-open input.
    */
   loadUrl(value: string): void {
     if (this.disposed) return
     const parsed = parseBrowserAddress(value, this.options.applicationOrigin)
-    if (!parsed.ok) {
-      this.navigation.addressFailed(parsed.reason)
-      this.publish()
-      return
-    }
-    const current = BrowserNavigation.current(this.navigation.snapshot)
-    if (current?.url === parsed.target.url) {
-      this.reload()
-      return
-    }
-    this.start(this.navigation.navigate(parsed.target))
+    if (!parsed.ok) { this.addressFailed(parsed.reason); return }
+    this.command(() => { this.page.frame.loadUrl(parsed.target) })
   }
 
-  /** Move to the preceding application-known address when Web history remains usable. */
-  goBack(): void {
-    if (this.disposed) return
-    const request = this.navigation.back()
-    if (request !== undefined) this.start(request)
-  }
-
-  /** Move to the following application-known address when Web history remains usable. */
-  goForward(): void {
-    if (this.disposed) return
-    const request = this.navigation.forward()
-    if (request !== undefined) this.start(request)
-  }
-
-  /** Reload the last application-known address without adding history. */
+  /** Delegate Back to the page's navigation provider. */
+  goBack(): void { this.command(() => { this.page.frame.goBack() }) }
+  /** Delegate Forward to the page's navigation provider. */
+  goForward(): void { this.command(() => { this.page.frame.goForward() }) }
+  /** Restore a saved address, or reload the already requested page. */
   reload(): void {
-    if (this.disposed) return
-    const request = this.navigation.reload()
-    if (request !== undefined) this.start(request)
+    if (this.store.getSnapshot().restoreTarget !== undefined) this.restore()
+    else this.command(() => { this.page.frame.reload() })
   }
 
-  private start(request: NonNullable<BrowserTabState['request']>): void {
-    this.publish()
-    this.frame.clearDocument()
-    this.frame.setDocument({ target: request.target, src: request.target.url, revision: request.revision })
+  /**
+   * Apply the optional embedding-sandbox control; unsupported providers remain unchanged.
+   * @param enabled - whether to enforce the provider's embedding sandbox.
+   */
+  setSandbox(enabled: boolean): void {
+    const sandbox = this.page.frame.sandbox
+    if (sandbox !== undefined) this.command(() => { sandbox.setEnabled(enabled) })
   }
 
-  private frameLoaded(revision: number): void {
-    if (this.disposed) return
-    const previous = this.navigation.snapshot
-    this.navigation.frameLoaded(revision)
-    if (this.navigation.snapshot !== previous) this.publish()
-  }
+  /**
+   * Redirect future checkpoint writes to a replacement Session binding.
+   * @param actions - replacement persistence writer.
+   */
+  rebind(actions: BoundActions<BrowserStore>): void { this.actions = actions }
 
-  private publish(): void {
-    this.options.actions.replace(this.options.tabId, this.navigation.snapshot)
-  }
-
-  private dispose(): void {
+  /**
+   * Release the page and detach occurrence and state listeners.
+   * @returns after page teardown; repeated callers join the same disposal.
+   */
+  dispose(): Promise<void> {
+    if (this.disposal !== undefined) return this.disposal
     this.disposed = true
-    this.frame.clearDocument()
+    this.options.signal.removeEventListener('abort', this.abort)
+    this.unsubscribe()
+    this.disposal = this.page.frame.dispose()
+    return this.disposal
+  }
+
+  private publishSaved(): void {
+    if (this.checkpoint !== undefined) this.actions.replace(this.options.tabId, this.checkpoint)
+  }
+
+  private addressFailed(reason: BrowserAddressFailure): void {
+    this.store.set({ ...this.store.getSnapshot(), addressFailure: reason })
+  }
+
+  private command(run: () => void): void {
+    if (this.disposed) return
+    const current = this.store.getSnapshot()
+    this.store.set({ ...current, addressFailure: undefined, addressRevision: current.addressRevision + 1 })
+    run()
   }
 }
 
-/** Browser commands and keyed frame state injected into the tab body. */
+/** Values available once a Sidebar body has committed its content container. */
+export interface BrowserMountRequest {
+  readonly tabId: TabId
+  readonly signal: AbortSignal
+  readonly viewportId: string
+  readonly applicationOrigin: string
+  readonly initial: BrowserTabState | undefined
+  readonly initialUrl: string | undefined
+  readonly openTab: (url: string) => void
+}
+
+/** Plain Slot callbacks and a framework-bound state source, not a desktop protocol. */
 export interface BrowserInjected {
   readonly keyedHooks: {
-    readonly browserFrame: (key: string) => HostObservable<BrowserFrameState> | undefined
+    readonly browserState: (key: string) => HostObservable<BrowserControllerState> | undefined
   }
-  /**
-   * @param tabId - tab occurrence.
-   * @param signal - occurrence lifetime.
-   * @param applicationOrigin - current application origin.
-   * @param initial - persisted tab state.
-   */
-  mount(tabId: TabId, signal: AbortSignal, applicationOrigin: string, initial?: BrowserTabState): void
-  /** @param tabId - tab occurrence. @param value - address-bar or typed-open value. */
+  /** @param request - committed tab and container. @returns ends physical attachment without closing the tab. */
+  mount(request: BrowserMountRequest): () => void
+  /** @returns after every page has been disposed. */
+  dispose(): Promise<void>
+  /** @param actions - writer from a recreated Session binding. */
+  rebind(actions: BoundActions<BrowserStore>): void
+  /** @param tabId - owning tab. @param value - address input. */
   loadUrl(tabId: TabId, value: string): void
-  /** @param tabId - tab occurrence. */
+  /** @param tabId - tab whose saved address the user requested to restore. */
+  restore(tabId: TabId): void
+  /** @param tabId - owning tab. */
   goBack(tabId: TabId): void
-  /** @param tabId - tab occurrence. */
+  /** @param tabId - owning tab. */
   goForward(tabId: TabId): void
-  /** @param tabId - tab occurrence. */
+  /** Restore a saved address or reload its page. @param tabId - owning tab. */
   reload(tabId: TabId): void
-  /** @param tabId - tab occurrence. */
-  toggleSandbox(tabId: TabId): void
-  /** @param tabId - tab occurrence. @param revision - rendered document revision. */
-  reportLoaded(tabId: TabId, revision: number): void
-  /** @param tabId - tab occurrence. @param revision - rendered document revision that emitted `error`. */
-  reportLoadFailed(tabId: TabId, revision: number): void
+  /** @param tabId - owning tab. @param enabled - provider's optional sandbox control. */
+  setSandbox(tabId: TabId, enabled: boolean): void
 }
 
 /**
- * Bind Browser controllers to one Session and its persistence writer.
- * @param actions - Browser store mutation face.
- * @returns a per-tab controller registry exposed as plain Slot callbacks.
+ * Own tab-occurrence controllers behind Session-scoped callbacks.
+ * @param actions - persisted view-state writer.
+ * @param createPage - composition-selected provider.
+ * @param isTabOpen - authoritative layout membership, independent of mounted bodies and plugin lifetime.
+ * @returns tab callbacks.
  */
-export function createBrowserControllers(
-  actions: BoundActions<BrowserStore>,
-): BrowserInjected {
-  const controllers = new Map<TabId, { readonly signal: AbortSignal; readonly controller: BrowserController }>()
-  const controller = (tabId: TabId): BrowserController | undefined => controllers.get(tabId)?.controller
+export function createBrowserControllers(actions: BoundActions<BrowserStore>, createPage: BrowserPageFactory,
+  isTabOpen: (tabId: TabId) => boolean): BrowserInjected {
+  let currentActions = actions
+  const controllers = new Map<TabId, {
+    readonly signal: AbortSignal
+    readonly controller: BrowserController
+    readonly forget: () => void
+  }>()
+  const controller = (id: TabId): BrowserController | undefined => controllers.get(id)?.controller
   return {
-    keyedHooks: { browserFrame: key => controller(key as TabId)?.frame },
-    mount(tabId, signal, applicationOrigin, initial) {
-      const held = controllers.get(tabId)
-      if (held?.signal === signal) return
-      const created = new BrowserController({
-        tabId, signal, applicationOrigin, actions,
-        ...(initial === undefined ? {} : { initial }),
-      })
-      controllers.set(tabId, { signal, controller: created })
-      signal.addEventListener('abort', () => {
-        if (controllers.get(tabId)?.controller !== created) return
-        controllers.delete(tabId)
-        actions.forget(tabId)
-      }, { once: true })
+    keyedHooks: { browserState: key => controller(key as TabId) },
+    mount(request) {
+      const { tabId, signal } = request
+      if (signal.aborted) return () => {}
+      let held = controllers.get(tabId)
+      if (held?.signal !== signal) {
+        if (held !== undefined) {
+          held.signal.removeEventListener('abort', held.forget)
+          void held.controller.dispose()
+        }
+        const created = new BrowserController({ ...request, actions: currentActions, createPage })
+        const forget = (): void => {
+          controllers.delete(tabId)
+          // Plugin unload also aborts occurrences; only layout removal deletes saved navigation.
+          if (!isTabOpen(tabId)) currentActions.forget(tabId)
+        }
+        held = { signal, controller: created, forget }
+        controllers.set(tabId, held)
+        signal.addEventListener('abort', forget, { once: true })
+      }
+      const hide = held.controller.mount(request.viewportId)
+      held.controller.start(request.initialUrl)
+      return hide
     },
-    loadUrl: (tabId, value) => { controller(tabId)?.loadUrl(value) },
-    goBack: (tabId) => { controller(tabId)?.goBack() },
-    goForward: (tabId) => { controller(tabId)?.goForward() },
-    reload: (tabId) => { controller(tabId)?.reload() },
-    toggleSandbox: (tabId) => { controller(tabId)?.frame.toggleSandbox() },
-    reportLoaded: (tabId, revision) => { controller(tabId)?.frame.reportLoaded(revision) },
-    reportLoadFailed: (tabId, revision) => { controller(tabId)?.frame.reportLoadFailed(revision) },
+    dispose: async () => {
+      const pending = [...controllers.values()].map(({ signal, controller, forget }) => {
+        signal.removeEventListener('abort', forget)
+        return controller.dispose()
+      })
+      controllers.clear()
+      await Promise.all(pending)
+    },
+    rebind: (actions) => {
+      currentActions = actions
+      for (const { controller } of controllers.values()) controller.rebind(actions)
+    },
+    loadUrl: (id, value) => { controller(id)?.loadUrl(value) },
+    restore: (id) => { controller(id)?.restore() },
+    goBack: (id) => { controller(id)?.goBack() },
+    goForward: (id) => { controller(id)?.goForward() },
+    reload: (id) => { controller(id)?.reload() },
+    setSandbox: (id, enabled) => { controller(id)?.setSandbox(enabled) },
   }
 }
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/BrowserFrame.ts b/packages/client/ui-sidebar-browser/src/client/browser/BrowserFrame.ts
index f26b983050..6c24081a8e 100644
--- a/packages/client/ui-sidebar-browser/src/client/browser/BrowserFrame.ts
+++ b/packages/client/ui-sidebar-browser/src/client/browser/BrowserFrame.ts
@@ -1,98 +1,51 @@
-/** BrowserFrame interface and the current iframe implementation. */
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
+/** Carrier-neutral page navigation and observable state. */
 import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
 import type { BrowserTarget } from './url.ts'
 
-/** One prepared document rendered by a BrowserFrame implementation. */
-export interface BrowserDocument {
-  readonly target: BrowserTarget
-  readonly src: string
-  readonly revision: number
+/** A loading failure, optionally carrying the underlying browser's diagnostic. */
+export interface BrowserLoadError {
+  readonly code: number | undefined
+  readonly description: string | undefined
 }
 
-/** Current renderer-facing state for one Browser tab. */
+/** State consumed by common browser chrome, without DOM or carrier identifiers. */
 export interface BrowserFrameState {
-  readonly document: BrowserDocument | undefined
-  readonly sandboxed: boolean
-  readonly loadFailed: boolean
+  readonly target: BrowserTarget | undefined
+  readonly address: 'empty' | 'requested' | 'observed' | 'unknown'
+  readonly loading: boolean
+  readonly canGoBack: boolean
+  readonly canGoForward: boolean
+  readonly error: BrowserLoadError | undefined
+  /** Undefined when this provider does not expose a sandbox control. */
+  readonly sandboxEnabled: boolean | undefined
 }
 
-/** Browser rendering operations shared by Web and future Electron implementations. */
+/** Optional iframe policy control, not an Electron process-sandbox switch. */
+export interface BrowserSandboxControl {
+  /** @param enabled - whether the provider's embedding sandbox is enforced. */
+  setEnabled(enabled: boolean): void
+}
+
+/** Navigation owns page lifetime; mounting and hiding belong to BrowserPresentation. */
 export interface BrowserFrame extends HostObservable<BrowserFrameState> {
-  /** Toggle sandbox enforcement for this tab occurrence. */
-  toggleSandbox(): void
-  /** @param document - current prepared document. */
-  setDocument(document: BrowserDocument): void
-  /** Remove the current prepared document. */
-  clearDocument(): void
-  /** @param revision - rendered document revision reported by the carrier. */
-  reportLoaded(revision: number): void
-  /** @param revision - rendered document revision whose carrier reported an error. */
-  reportLoadFailed(revision: number): void
+  readonly sandbox?: BrowserSandboxControl
+  /** @param target - validated HTTP(S) address; loading failures are published in state. */
+  loadUrl(target: BrowserTarget): void
+  /** Move backward when the provider reports an available entry. */
+  goBack(): void
+  /** Move forward when the provider reports an available entry. */
+  goForward(): void
+  /** Reload the current address without creating a new history entry. */
+  reload(): void
+  /** @returns after the page, listeners and pending initialization have been released; repeated calls join disposal. */
+  dispose(): Promise<void>
 }
 
-/** Owns transient iframe and sandbox-toggle state independently from URL navigation. */
-export class IframeImpl implements BrowserFrame {
-  private readonly store: SnapshotStore<BrowserFrameState> = createSnapshotStore({
-    document: undefined,
-    sandboxed: true,
-    loadFailed: false,
-  })
-
-  /**
-   * @param sandboxChanged - applies the new policy to the current controlled target.
-   * @param documentLoaded - reports an iframe load to the navigation state machine.
-   */
-  constructor(
-    private readonly sandboxChanged: (sandboxed: boolean) => void,
-    private readonly documentLoaded: (revision: number) => void,
-  ) {}
-
-  /** @returns the immutable renderer snapshot. */
-  getSnapshot = (): BrowserFrameState => this.store.getSnapshot()
-
-  /**
-   * Subscribe to iframe or sandbox-mode changes.
-   * @param listener - invalidation callback.
-   * @returns the unsubscribe function.
-   */
-  subscribe = (listener: () => void): (() => void) => this.store.subscribe(listener)
-
-  /** Toggle sandbox enforcement for this tab occurrence. */
-  toggleSandbox(): void {
-    const current = this.store.getSnapshot()
-    const sandboxed = !current.sandboxed
-    this.store.set({ ...current, sandboxed })
-    this.sandboxChanged(sandboxed)
-  }
-
-  /**
-   * Publish a prepared frame from the owning controller.
-   * @param document - current prepared document.
-   */
-  setDocument(document: BrowserDocument): void {
-    this.store.set({ ...this.store.getSnapshot(), document, loadFailed: false })
-  }
-
-  /** Remove the current prepared frame and transient load failure. */
-  clearDocument(): void {
-    const current = this.store.getSnapshot()
-    const { document } = current
-    if (document !== undefined) {
-      this.store.set({ ...current, document: undefined, loadFailed: false })
-    }
-  }
-
-  /** @param revision - rendered document revision reported by the iframe. */
-  reportLoaded(revision: number): void {
-    this.documentLoaded(revision)
-  }
-
-  /** @param revision - rendered document revision whose iframe emitted `error`. */
-  reportLoadFailed(revision: number): void {
-    const current = this.store.getSnapshot()
-    if (current.document?.revision !== revision || current.loadFailed) return
-    this.store.set({ ...current, loadFailed: true })
-  }
+/**
+ * Create idle navigation state without a page target.
+ * @returns state before any page has been requested.
+ */
+export function emptyBrowserFrame(): BrowserFrameState {
+  return { target: undefined, address: 'empty', loading: false, canGoBack: false, canGoForward: false,
+    error: undefined, sandboxEnabled: undefined }
 }
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/BrowserNavigation.ts b/packages/client/ui-sidebar-browser/src/client/browser/BrowserNavigation.ts
index d8f8508a0e..d0401a5a5f 100644
--- a/packages/client/ui-sidebar-browser/src/client/browser/BrowserNavigation.ts
+++ b/packages/client/ui-sidebar-browser/src/client/browser/BrowserNavigation.ts
@@ -1,33 +1,10 @@
-/** URL, history, and observability state for one Browser tab. */
-import type { BrowserAddressFailure, BrowserTarget } from './url.ts'
+/** Bounded, application-known history used only by the iframe provider. */
+import type { BrowserTarget } from './url.ts'
+import type { BrowserHistoryEntry, BrowserTabState } from './BrowserPersistence.ts'
 
 /** Maximum retained application-known navigation entries per tab. */
 export const MAX_BROWSER_HISTORY = 100
 
-/** One canonical address in the application-managed Web history. */
-export type BrowserHistoryEntry = BrowserTarget
-
-/** Whether the current carrier document still corresponds to an application-known URL. */
-export type BrowserNavigationStatus =
-  | { readonly status: 'empty' }
-  | { readonly status: 'loading'; readonly revision: number }
-  | { readonly status: 'known'; readonly revision: number }
-  | { readonly status: 'unknown'; readonly revision: number }
-
-/** Address-policy or loading failure shown below the toolbar. */
-export type BrowserFailure =
-  { readonly kind: 'address'; readonly reason: BrowserAddressFailure }
-
-/** One Browser tab's serializable URL state. */
-export interface BrowserTabState {
-  readonly entries: readonly BrowserHistoryEntry[]
-  readonly index: number
-  /** Last application-directed load; carrier observations do not rewrite it. */
-  readonly request: { readonly revision: number; readonly target: BrowserTarget } | undefined
-  readonly navigation: BrowserNavigationStatus
-  readonly failure: BrowserFailure | undefined
-}
-
 /**
  * Owns the application-known URL history and the iframe observation state machine.
  * The first load for a request keeps its URL authoritative; another load marks it unknown.
@@ -136,14 +113,6 @@ export class BrowserNavigation {
     return target === undefined ? undefined : this.request(target, this.value)
   }
 
-  /**
-   * Record an invalid address without changing the active document state.
-   * @param reason - parser refusal.
-   */
-  addressFailed(reason: BrowserAddressFailure): void {
-    this.value = { ...this.value, failure: { kind: 'address', reason } }
-  }
-
   /**
    * Record a frame load for its captured revision.
    * @param revision - revision bound to the rendered frame.
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/BrowserPage.ts b/packages/client/ui-sidebar-browser/src/client/browser/BrowserPage.ts
new file mode 100644
index 0000000000..c235126cf6
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/browser/BrowserPage.ts
@@ -0,0 +1,20 @@
+/** Composition of one navigation provider and its presentation. */
+import type { BrowserPresentation } from '../view/BrowserPresentation.ts'
+import type { BrowserFrame } from './BrowserFrame.ts'
+import type { BrowserTabState } from './BrowserPersistence.ts'
+
+/** Provider construction inputs; persistence does not enter the live navigation interface. */
+export interface BrowserPageOptions {
+  readonly initial: BrowserTabState | undefined
+  readonly persist: (state: BrowserTabState) => void
+  readonly openRequested: (url: string) => void
+}
+
+/** The owning controller disposes frame; UI mounts only presentation. */
+export interface BrowserPage {
+  readonly frame: BrowserFrame
+  readonly presentation: BrowserPresentation
+}
+
+/** Construct an idle provider without attaching DOM; saved navigation waits for an explicit frame command. */
+export type BrowserPageFactory = (options: BrowserPageOptions) => BrowserPage
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/BrowserPersistence.ts b/packages/client/ui-sidebar-browser/src/client/browser/BrowserPersistence.ts
new file mode 100644
index 0000000000..3153ee3136
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/browser/BrowserPersistence.ts
@@ -0,0 +1,44 @@
+/** Existing browser-local navigation records, independent from live frame state. */
+import type { BrowserAddressFailure, BrowserTarget } from './url.ts'
+
+/** One retained address. */
+export type BrowserHistoryEntry = BrowserTarget
+
+/** Observability recorded for a controlled navigation. */
+export type BrowserNavigationStatus =
+  | { readonly status: 'empty' }
+  | { readonly status: 'loading'; readonly revision: number }
+  | { readonly status: 'known'; readonly revision: number }
+  | { readonly status: 'unknown'; readonly revision: number }
+
+/** Address refusal carried by existing browser-local records. */
+export type BrowserFailure = { readonly kind: 'address'; readonly reason: BrowserAddressFailure }
+
+/** Serializable record; providers retain the history they can restore. */
+export interface BrowserTabState {
+  readonly entries: readonly BrowserHistoryEntry[]
+  readonly index: number
+  readonly request: { readonly revision: number; readonly target: BrowserTarget } | undefined
+  readonly navigation: BrowserNavigationStatus
+  readonly failure: BrowserFailure | undefined
+}
+
+/**
+ * Read the selected address from a saved navigation record.
+ * @param state - saved navigation.
+ * @returns its last selected address, if any.
+ */
+export function currentBrowserTarget(state: BrowserTabState | undefined): BrowserTarget | undefined {
+  return state === undefined || state.index < 0 ? undefined : state.entries[state.index]
+}
+
+/**
+ * Checkpoint an observed address without serializing native history.
+ * @param target - current address.
+ * @param revision - navigation generation.
+ * @returns an address-only checkpoint.
+ */
+export function browserAddressCheckpoint(target: BrowserTarget, revision: number): BrowserTabState {
+  return { entries: [target], index: 0, request: { target, revision },
+    navigation: { status: 'known', revision }, failure: undefined }
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/IframeImpl.ts b/packages/client/ui-sidebar-browser/src/client/browser/IframeImpl.ts
new file mode 100644
index 0000000000..0692b80997
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/browser/IframeImpl.ts
@@ -0,0 +1,104 @@
+/** Iframe navigation provider with bounded application-known history. */
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { IframePresentation } from '../view/IframePresentation.ts'
+import { emptyBrowserFrame, type BrowserFrame, type BrowserFrameState, type BrowserLoadError, type BrowserSandboxControl } from './BrowserFrame.ts'
+import type { BrowserPageOptions } from './BrowserPage.ts'
+import { BrowserNavigation } from './BrowserNavigation.ts'
+import type { BrowserTarget } from './url.ts'
+
+/** Owns iframe navigation; the view reports loads without reading cross-origin content. */
+export class IframeImpl implements BrowserFrame {
+  readonly sandbox: BrowserSandboxControl = { setEnabled: (enabled) => { this.setSandbox(enabled) } }
+  private readonly navigation: BrowserNavigation
+  private readonly store: SnapshotStore<BrowserFrameState>
+  private sandboxed = true
+  private error: BrowserLoadError | undefined
+  private disposed = false
+  private disposal: Promise<void> | undefined
+
+  /** @param options - initial checkpoint and persistence writer. @param presentation - iframe DOM adapter. */
+  constructor(private readonly options: BrowserPageOptions, private readonly presentation: IframePresentation) {
+    this.navigation = new BrowserNavigation(options.initial)
+    this.store = createSnapshotStore({ ...emptyBrowserFrame(), sandboxEnabled: this.sandboxed })
+  }
+
+  /**
+   * Record a controlled load or a later navigation to an unreadable address.
+   * @param revision - document generation whose iframe emitted load.
+   */
+  handleLoaded(revision: number): void {
+    if (this.disposed) return
+    this.navigation.frameLoaded(revision)
+    this.publish()
+  }
+
+  /**
+   * Publish a failure only for the current document generation.
+   * @param revision - document generation whose iframe reported failure.
+   */
+  handleLoadFailed(revision: number): void {
+    if (this.disposed || this.navigation.snapshot.request?.revision !== revision) return
+    this.error = { code: undefined, description: undefined }
+    this.publish()
+  }
+
+  /** @returns immutable navigation state. */
+  getSnapshot = (): BrowserFrameState => this.store.getSnapshot()
+  /** @param listener - state invalidation. @returns unsubscribe callback. */
+  subscribe = (listener: () => void): (() => void) => this.store.subscribe(listener)
+
+  /** @param target - validated address; submitting the current address reloads it. */
+  loadUrl(target: BrowserTarget): void {
+    if (this.disposed) return
+    const request = BrowserNavigation.current(this.navigation.snapshot)?.url === target.url
+      ? this.navigation.reload() : this.navigation.navigate(target)
+    this.load(request)
+  }
+
+  /** Move through application-known history while the iframe address remains known. */
+  goBack(): void { if (!this.disposed) this.load(this.navigation.back()) }
+  /** Move through application-known history while the iframe address remains known. */
+  goForward(): void { if (!this.disposed) this.load(this.navigation.forward()) }
+  /** Reload the last application-known address. */
+  reload(): void { if (!this.disposed) this.load(this.navigation.reload()) }
+
+  /** @returns after the presentation has been removed; repeated calls join disposal. */
+  dispose(): Promise<void> {
+    if (this.disposal !== undefined) return this.disposal
+    this.disposed = true
+    this.presentation.dispose()
+    this.disposal = Promise.resolve()
+    return this.disposal
+  }
+
+  private setSandbox(enabled: boolean): void {
+    if (this.disposed || enabled === this.sandboxed) return
+    this.sandboxed = enabled
+    if (this.store.getSnapshot().target === undefined) {
+      this.store.set({ ...this.store.getSnapshot(), sandboxEnabled: enabled })
+      return
+    }
+    this.load(this.navigation.reload())
+  }
+
+  private load(request: ReturnType<BrowserNavigation['navigate']> | undefined): void {
+    if (request === undefined) return
+    this.error = undefined
+    this.publish()
+    this.presentation.show({ target: request.target, revision: request.revision, sandboxed: this.sandboxed })
+  }
+
+  private snapshot(): BrowserFrameState {
+    const state = this.navigation.snapshot
+    const target = BrowserNavigation.current(state)
+    return { target, address: target === undefined ? 'empty' : state.navigation.status === 'unknown' ? 'unknown' : 'requested',
+      loading: state.navigation.status === 'loading' && this.error === undefined,
+      canGoBack: this.navigation.canGoBack, canGoForward: this.navigation.canGoForward,
+      error: this.error, sandboxEnabled: this.sandboxed }
+  }
+
+  private publish(): void {
+    this.store.set(this.snapshot())
+    this.options.persist(this.navigation.snapshot)
+  }
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/browser/store.ts b/packages/client/ui-sidebar-browser/src/client/browser/store.ts
index 4702f7c7c1..cd0c38aa04 100644
--- a/packages/client/ui-sidebar-browser/src/client/browser/store.ts
+++ b/packages/client/ui-sidebar-browser/src/client/browser/store.ts
@@ -1,7 +1,7 @@
 /** Persisted Browser tab snapshots shared by the body and title slots. */
 import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-store'
 import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
-import type { BrowserTabState } from './BrowserNavigation.ts'
+import type { BrowserTabState } from './BrowserPersistence.ts'
 
 /** All Browser tabs in one Session-scoped store. */
 export interface BrowserState {
diff --git a/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebViewImpl.ts b/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebViewImpl.ts
new file mode 100644
index 0000000000..b6987bbc8f
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebViewImpl.ts
@@ -0,0 +1,271 @@
+/** Electron navigation and guest lifetime, independent from DOM placement. */
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { DesktopBrowserBridge, DesktopBrowserLeaseId } from '../../types.ts'
+import type { ElectronWebviewPresentation, WebviewElement } from './ElectronWebviewPresentation.ts'
+import { emptyBrowserFrame, type BrowserFrame, type BrowserFrameState, type BrowserLoadError } from '../browser/BrowserFrame.ts'
+import type { BrowserPageOptions } from '../browser/BrowserPage.ts'
+import { browserAddressCheckpoint, currentBrowserTarget } from '../browser/BrowserPersistence.ts'
+import { parseBrowserAddress, type BrowserTarget } from '../browser/url.ts'
+
+interface NavigationEvent extends Event { readonly isMainFrame: boolean }
+interface LoadFailureEvent extends NavigationEvent {
+  readonly errorCode: number
+  readonly errorDescription: string
+}
+
+/** Owns native history and translates Electron observations into common frame state. */
+export class ElectronWebViewImpl implements BrowserFrame {
+  private readonly store: SnapshotStore<BrowserFrameState>
+  private readonly lifetime = new AbortController()
+  private guestLifetime: AbortController | undefined
+  private element: WebviewElement | undefined
+  private lease: DesktopBrowserLeaseId | undefined
+  private workspaceKey: string | undefined
+  private initializing: Promise<void> | undefined
+  private ready = false
+  private pending: BrowserTarget | undefined
+  private revision = 0
+  private firstDocument = true
+  private checkpoint: BrowserTarget | undefined
+  private disposal: Promise<void> | undefined
+  private attachment: AbortController | undefined
+  private readonly releases = new Set<Promise<void>>()
+
+  /**
+   * @param options - saved address, persistence and source-tab opening callback.
+   * @param bridge - main-process guest operations.
+   * @param workspace - resolves the storage account once for this frame lifetime.
+   * @param presentation - tag and Sidebar placement adapter.
+   */
+  constructor(private readonly options: BrowserPageOptions, private readonly bridge: DesktopBrowserBridge,
+    private readonly workspace: (signal: AbortSignal) => Promise<string>,
+    private readonly presentation: ElectronWebviewPresentation) {
+    this.checkpoint = currentBrowserTarget(options.initial)
+    this.store = createSnapshotStore(emptyBrowserFrame())
+  }
+
+  /** @returns immutable carrier-neutral navigation state. */
+  getSnapshot = (): BrowserFrameState => this.store.getSnapshot()
+  /** @param listener - state invalidation. @returns unsubscribe callback. */
+  subscribe = (listener: () => void): (() => void) => this.store.subscribe(listener)
+
+  /** A physical mount may recreate a lost guest; ordinary Sidebar hiding never calls this. */
+  attach(): void {
+    if (this.lifetime.signal.aborted) return
+    this.attachment = new AbortController()
+    this.pending ??= this.store.getSnapshot().target
+    if (this.pending !== undefined) {
+      this.store.set({ ...this.store.getSnapshot(), address: 'requested', loading: true,
+        canGoBack: false, canGoForward: false, error: undefined })
+      this.initialize()
+    }
+  }
+
+  /** Invalidate pending attachment before the containing DOM is removed. */
+  detach(): void {
+    this.attachment?.abort()
+    this.attachment = undefined
+    this.pending = this.store.getSnapshot().target
+    void this.dropGuest()
+  }
+
+  /** @param target - validated address, loaded without replacing the guest. */
+  loadUrl(target: BrowserTarget): void {
+    if (this.lifetime.signal.aborted) return
+    const current = this.store.getSnapshot()
+    if (this.ready && current.address === 'observed' && current.target?.url === target.url) {
+      this.reload()
+      return
+    }
+    this.revision++
+    this.pending = target
+    this.store.set({ ...current, target, address: 'requested', loading: true, error: undefined })
+    this.persist(target)
+    if (this.ready) this.loadPending()
+    else this.initialize()
+  }
+
+  /** Move backward through Chromium history. */
+  goBack(): void {
+    if (this.store.getSnapshot().canGoBack) this.navigate('goBack')
+  }
+
+  /** Move forward through Chromium history. */
+  goForward(): void {
+    if (this.store.getSnapshot().canGoForward) this.navigate('goForward')
+  }
+
+  /** Reload the actual current page, or retry failed guest creation. */
+  reload(): void {
+    const current = this.store.getSnapshot()
+    if (this.lifetime.signal.aborted || current.target === undefined) return
+    if (!this.ready || current.error !== undefined) {
+      this.revision++
+      this.pending = current.target
+      this.store.set({ ...current, loading: true, error: undefined })
+      if (this.ready) this.loadPending()
+      else this.initialize()
+    } else this.navigate('reload')
+  }
+
+  /** @returns after pending initialization and the owned guest have been released. */
+  dispose(): Promise<void> {
+    if (this.disposal !== undefined) return this.disposal
+    this.lifetime.abort()
+    this.pending = undefined
+    this.disposal = Promise.all([this.dropGuest(), this.initializing])
+      .then(() => Promise.all(this.releases)).then(() => {})
+    this.presentation.dispose()
+    return this.disposal
+  }
+
+  private navigate(command: 'goBack' | 'goForward' | 'reload'): void {
+    if (this.lifetime.signal.aborted || !this.ready || this.element === undefined) return
+    this.revision++
+    this.pending = undefined
+    this.store.set({ ...this.store.getSnapshot(), loading: true, error: undefined })
+    try { this.element[command]() }
+    catch (error) { this.commandFailed(error) }
+  }
+
+  private initialize(): void {
+    const attachment = this.attachment
+    if (attachment === undefined || this.initializing !== undefined || this.element !== undefined || this.lifetime.signal.aborted) return
+    const signal = AbortSignal.any([this.lifetime.signal, attachment.signal])
+    this.initializing = this.createGuest(signal).catch(async (error: unknown) => {
+      await this.dropGuest()
+      if (!signal.aborted) this.commandFailed(error)
+    }).finally(() => {
+      this.initializing = undefined
+      if (this.attachment !== attachment && this.pending !== undefined) this.initialize()
+    })
+  }
+
+  private async createGuest(attachmentSignal: AbortSignal): Promise<void> {
+    this.workspaceKey ??= await this.workspace(attachmentSignal)
+    if (attachmentSignal.aborted) return
+    const reservation = await this.bridge.acquire(this.workspaceKey)
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- The signal can abort while acquire is pending.
+    if (attachmentSignal.aborted) { await this.release(reservation.lease); return }
+    this.lease = reservation.lease
+    this.guestLifetime = new AbortController()
+    const signal = AbortSignal.any([attachmentSignal, this.guestLifetime.signal])
+    const element = this.presentation.createElement(reservation)
+    this.element = element
+    const unsubscribeOpen = this.bridge.onOpenRequested(reservation.lease, (url) => {
+      if (this.element === element && !signal.aborted) this.options.openRequested(url)
+    })
+    signal.addEventListener('abort', unsubscribeOpen, { once: true })
+    element.addEventListener('dom-ready', () => {
+      this.ready = true
+      this.observe(this.store.getSnapshot().address !== 'requested')
+      this.loadPending()
+    }, { signal })
+    element.addEventListener('did-navigate', () => { this.observe(true) }, { signal })
+    element.addEventListener('did-navigate-in-page', (event) => {
+      if ((event as NavigationEvent).isMainFrame) this.observe(true)
+    }, { signal })
+    element.addEventListener('did-start-navigation', (event) => {
+      if ((event as NavigationEvent).isMainFrame) {
+        this.store.set({ ...this.store.getSnapshot(), loading: true, error: undefined })
+      }
+    }, { signal })
+    for (const name of ['did-start-loading', 'did-stop-loading', 'page-title-updated']) {
+      element.addEventListener(name, () => {
+        this.observe(name === 'page-title-updated' && this.store.getSnapshot().address === 'observed')
+      }, { signal })
+    }
+    element.addEventListener('did-fail-load', (event) => {
+      const failure = event as LoadFailureEvent
+      if (failure.isMainFrame && failure.errorCode !== -3) {
+        this.failed({ code: failure.errorCode, description: failure.errorDescription })
+      }
+    }, { signal })
+    for (const name of ['render-process-gone', 'destroyed']) {
+      element.addEventListener(name, () => { void this.dropGuest(); this.failed() }, { signal })
+    }
+    this.presentation.present(element)
+  }
+
+  private loadPending(): void {
+    const target = this.pending
+    const element = this.element
+    if (!this.ready || target === undefined || element === undefined) return
+    const revision = this.revision
+    this.pending = undefined
+    void element.loadURL(target.url).catch((error: unknown) => {
+      if (this.element !== element || this.lifetime.signal.aborted || this.revision !== revision) return
+      if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ERR_ABORTED') return
+      if (this.store.getSnapshot().error === undefined) this.commandFailed(error)
+    })
+  }
+
+  private observe(committed: boolean): void {
+    if (!this.ready || this.element === undefined || this.lifetime.signal.aborted) return
+    try { this.observeReady(this.element, committed) }
+    catch (error) { this.commandFailed(error) }
+  }
+
+  private observeReady(element: WebviewElement, committed: boolean): void {
+    const current = this.store.getSnapshot()
+    const parsed = committed ? parseBrowserAddress(element.getURL()) : undefined
+    if (parsed?.ok && this.firstDocument) {
+      // The lease-bearing bootstrap document is not a user history entry.
+      element.clearHistory()
+      this.firstDocument = false
+    }
+    let target = current.target
+    let address = current.address
+    if (parsed?.ok) {
+      target = { ...parsed.target, title: element.getTitle() || parsed.target.title }
+      address = 'observed'
+      this.presentation.show(target.title)
+    }
+    const loading = current.error === undefined && element.isLoading()
+    const canGoBack = element.canGoBack()
+    const canGoForward = element.canGoForward()
+    if (target?.url !== current.target?.url || target?.title !== current.target?.title || address !== current.address
+      || loading !== current.loading || canGoBack !== current.canGoBack || canGoForward !== current.canGoForward) {
+      this.store.set({ ...current, target, address, loading, canGoBack, canGoForward })
+    }
+    if (parsed?.ok && target !== undefined) this.persist(target)
+  }
+
+  private persist(target: BrowserTarget): void {
+    if (target.url === this.checkpoint?.url && target.title === this.checkpoint.title) return
+    this.checkpoint = target
+    this.options.persist(browserAddressCheckpoint(target, this.revision))
+  }
+
+  private failed(error: BrowserLoadError = { code: undefined, description: undefined }): void {
+    if (this.lifetime.signal.aborted) return
+    const current = this.store.getSnapshot()
+    this.store.set({ ...current, loading: false, error,
+      canGoBack: this.ready && current.canGoBack, canGoForward: this.ready && current.canGoForward })
+  }
+
+  private commandFailed(error: unknown): void {
+    console.error('Desktop browser operation failed', error)
+    this.failed()
+  }
+
+  private dropGuest(): Promise<void> {
+    this.guestLifetime?.abort()
+    this.guestLifetime = undefined
+    this.presentation.clear()
+    this.element = undefined
+    this.ready = false
+    this.firstDocument = true
+    const lease = this.lease
+    this.lease = undefined
+    return lease === undefined ? Promise.resolve() : this.release(lease)
+  }
+
+  private release(lease: DesktopBrowserLeaseId): Promise<void> {
+    const released = this.bridge.release(lease)
+      .catch((error: unknown) => { console.error('Desktop browser guest release failed', error) })
+      .finally(() => { this.releases.delete(released) })
+    this.releases.add(released)
+    return released
+  }
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts b/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts
new file mode 100644
index 0000000000..4fc6798e50
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/electron/ElectronWebviewPresentation.ts
@@ -0,0 +1,93 @@
+/** Electron tag DOM inside a Sidebar-owned, stable content container. */
+import type { DesktopBrowserReservation } from '../../types.ts'
+import type { BrowserPresentation } from '../view/BrowserPresentation.ts'
+import css from '../view/Browser.module.css'
+
+/** The Electron tag API used by its navigation provider. */
+export interface WebviewElement extends HTMLElement {
+  loadURL(url: string): Promise<void>
+  getURL(): string
+  getTitle(): string
+  canGoBack(): boolean
+  canGoForward(): boolean
+  clearHistory(): void
+  goBack(): void
+  goForward(): void
+  reload(): void
+  isLoading(): boolean
+}
+
+/** Physical attachment notifications; hiding a retained Sidebar body emits neither. */
+export interface ElectronPresentationEvents {
+  readonly mounted: () => void
+  readonly unmounted: () => void
+}
+
+/** Owns tag creation and attachment, without measuring or following another element. */
+export class ElectronWebviewPresentation implements BrowserPresentation {
+  private element: WebviewElement | undefined
+  private host: HTMLElement | undefined
+
+  constructor(private readonly events: ElectronPresentationEvents) {}
+
+  /** @param viewportId - committed content container. @returns ends attachment and releases its guest. */
+  mount(viewportId: string): () => void {
+    const host = document.getElementById(viewportId)
+    if (host === null) throw new Error('Electron presentation: content container is not mounted')
+    if (this.host !== undefined) this.events.unmounted()
+    this.host = host
+    this.events.mounted()
+    return () => {
+      if (this.host !== host) return
+      this.events.unmounted()
+      this.host = undefined
+    }
+  }
+
+  /**
+   * Configure a detached webview for an approved guest reservation.
+   * @param reservation - main-approved partition and bootstrap lease.
+   * @returns a detached, configured webview.
+   */
+  createElement(reservation: DesktopBrowserReservation): WebviewElement {
+    const element = document.createElement('webview') as WebviewElement
+    element.className = css.webview as string
+    element.dataset.sidebarBrowserFrame = 'webview'
+    element.setAttribute('partition', reservation.partition)
+    element.setAttribute('allowpopups', '')
+    element.setAttribute('src', 'about:blank#' + reservation.lease)
+    return element
+  }
+
+  /**
+   * Attach a prepared guest, removing any previous guest DOM from the container.
+   * @param element - configured guest with its navigation listeners already installed.
+   * @throws when no content container is mounted.
+   */
+  present(element: WebviewElement): void {
+    if (this.host === undefined) throw new Error('Electron presentation: cannot attach without a content container')
+    this.clear()
+    this.element = element
+    this.host.append(element)
+  }
+
+  /**
+   * Set the guest element's accessible label.
+   * @param title - observed document title.
+   */
+  show(title: string): void {
+    this.element?.setAttribute('aria-label', title)
+  }
+
+  /** Destroy only the guest DOM; a replacement may use the same mounted container. */
+  clear(): void {
+    this.element?.remove()
+    this.element = undefined
+  }
+
+  /** Destroy the guest DOM and release its content container. */
+  dispose(): void {
+    this.clear()
+    this.host = undefined
+  }
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/electron/pages.ts b/packages/client/ui-sidebar-browser/src/client/electron/pages.ts
new file mode 100644
index 0000000000..d2430ad019
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/electron/pages.ts
@@ -0,0 +1,22 @@
+/** Assemble Electron navigation and presentation behind the shared BrowserPage interface. */
+import type { DesktopBrowserBridge } from '../../types.ts'
+import type { BrowserPage, BrowserPageOptions } from '../browser/BrowserPage.ts'
+import { ElectronWebViewImpl } from './ElectronWebViewImpl.ts'
+import { ElectronWebviewPresentation } from './ElectronWebviewPresentation.ts'
+
+/**
+ * Assemble an idle Electron provider; guest creation waits for mounting and navigation.
+ * @param options - checkpoint and source-tab callbacks.
+ * @param bridge - desktop-only transport.
+ * @param workspace - storage account resolver.
+ * @returns separate navigation and presentation faces.
+ */
+export function createElectronPage(options: BrowserPageOptions, bridge: DesktopBrowserBridge,
+  workspace: (signal: AbortSignal) => Promise<string>): BrowserPage {
+  const presentation = new ElectronWebviewPresentation({
+    mounted: () => { frame.attach() },
+    unmounted: () => { frame.detach() },
+  })
+  const frame = new ElectronWebViewImpl(options, bridge, workspace, presentation)
+  return { frame, presentation }
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/electron/workspace.ts b/packages/client/ui-sidebar-browser/src/client/electron/workspace.ts
new file mode 100644
index 0000000000..85cd73de20
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/electron/workspace.ts
@@ -0,0 +1,33 @@
+/** Resolve CWD-keyed Electron storage after the authoritative Workspace list has arrived. */
+import type { WorkspaceSource } from '@deepseek-ai/dsh-api-workspace-controller/client'
+
+/**
+ * Use the Workspace's canonical CWD, not its record id; ungrouped Sessions remain isolated.
+ * @param source - authoritative Workspace membership.
+ * @param sessionId - owning DSH Session.
+ * @param signal - guest initialization lifetime.
+ * @returns the storage account for this occurrence.
+ */
+export async function browserWorkspace(source: WorkspaceSource, sessionId: string, signal: AbortSignal): Promise<string> {
+  signal.throwIfAborted()
+  if (source.getSnapshot().phase !== 'ready') {
+    await new Promise<void>((resolve, reject) => {
+      const abort = (): void => {
+        stop()
+        const reason: unknown = signal.reason
+        // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- Preserve the caller-owned AbortSignal reason.
+        reject(reason)
+      }
+      const stop = source.subscribe(() => {
+        if (source.getSnapshot().phase !== 'ready') return
+        stop()
+        signal.removeEventListener('abort', abort)
+        resolve()
+      })
+      signal.addEventListener('abort', abort, { once: true })
+    })
+  }
+  signal.throwIfAborted()
+  const workspace = source.getSnapshot().items.find(item => item.sessionIds.some(id => id === sessionId))
+  return workspace === undefined ? `session:${sessionId}` : `cwd:${workspace.path}`
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/index.ts b/packages/client/ui-sidebar-browser/src/client/index.ts
index 8a301255ba..780f7f2d85 100644
--- a/packages/client/ui-sidebar-browser/src/client/index.ts
+++ b/packages/client/ui-sidebar-browser/src/client/index.ts
@@ -4,17 +4,26 @@ import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-session/client'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
-import { BrowserBody } from './view/BrowserBody.tsx'
+import type {} from '@deepseek-ai/dsh-api-workspace-controller/client'
+import { BrowserBody, type BrowserBodyProps } from './view/BrowserBody.tsx'
 import { BrowserTitle } from './view/BrowserTitle.tsx'
 import { createBrowserControllers } from './browser/BrowserController.ts'
+import type { BrowserInjected } from './browser/BrowserController.ts'
+import { createIframePage } from './pages.ts'
+import { createElectronPage } from './electron/pages.ts'
+import type { DesktopBrowserBridge } from '../types.ts'
+import { browserWorkspace } from './electron/workspace.ts'
+import type { BrowserPageFactory } from './browser/BrowserPage.ts'
 import { BROWSER_ID, browserDefinition } from './definition.tsx'
 import { en, zh } from './locales.ts'
 import { createBrowserStore } from './browser/store.ts'
 
 export type { BrowserBodyProps } from './view/BrowserBody.tsx'
-export type { BrowserInjected } from './browser/BrowserController.ts'
-export type { BrowserDocument, BrowserFrame, BrowserFrameState } from './browser/BrowserFrame.ts'
-export type { BrowserFailure, BrowserHistoryEntry, BrowserNavigationStatus, BrowserTabState } from './browser/BrowserNavigation.ts'
+export type { BrowserControllerState, BrowserInjected, BrowserMountRequest } from './browser/BrowserController.ts'
+export type { BrowserFrame, BrowserFrameState, BrowserLoadError, BrowserSandboxControl } from './browser/BrowserFrame.ts'
+export type { BrowserPage, BrowserPageFactory, BrowserPageOptions } from './browser/BrowserPage.ts'
+export type { BrowserPresentation } from './view/BrowserPresentation.ts'
+export type { BrowserFailure, BrowserHistoryEntry, BrowserNavigationStatus, BrowserTabState } from './browser/BrowserPersistence.ts'
 export type { SidebarBrowserKey } from './locales.ts'
 export type { BrowserState } from './browser/store.ts'
 export type { BrowserAddressFailure, BrowserAddressResult, BrowserTarget } from './browser/url.ts'
@@ -27,19 +36,47 @@ declare module '@deepseek-ai/dsh-client-ui-sidebar-right/client' {
 }
 
 /** Required Browser services. */
-export const inject = ['slots', 'locale', 'sidebarRightTabs']
+export const inject = ['slots', 'locale', 'sidebarRight', 'sidebarRightTabs']
 
 /** Register the Browser type, localized guide entry, body, and title. */
 export function apply(ctx: Context): void {
   const namespace = 'sidebarBrowser'
   const t = ctx.locale.bind(namespace)
   const store = createBrowserStore()
+  const openTabs = ctx.sidebarRight.openTabs
+  const carrier = (globalThis as typeof globalThis & {
+    dshDesktop?: { readonly protocolVersion: number; readonly browser?: DesktopBrowserBridge }
+  }).dshDesktop
+  const desktop = carrier?.protocolVersion === 1 ? carrier.browser : undefined
   ctx.effect(() => ctx.locale.register(namespace, { zh, en }), 'ui-sidebar-browser.copy')
-  ctx.effect(() => ctx.sidebarRightTabs.register(browserDefinition(t)), 'ui-sidebar-browser.type')
-  ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
-    name: 'sidebar.right.pane.tab', key: BROWSER_ID, locale: namespace, store,
-    inject: (_sessionId, actions) => createBrowserControllers(actions),
-  }, BrowserBody)), 'ui-sidebar-browser.body')
+  ctx.effect(() => ctx.sidebarRightTabs.register({ ...browserDefinition(t), keepMounted: desktop !== undefined }), 'ui-sidebar-browser.type')
+  const installFrames = (scope: Context, factory: (sessionId: BrowserBodyProps['sessionId']) => BrowserPageFactory): void => {
+    const controllers = new Map<BrowserBodyProps['sessionId'], BrowserInjected>()
+    scope.effect(() => async () => {
+      const pending = [...controllers.values()].map(controller => controller.dispose())
+      controllers.clear()
+      await Promise.all(pending)
+    }, 'ui-sidebar-browser.frames')
+    scope.effect(() => scope.slots.inject('sidebar.right.pane.tab', () => scope.slots.register({
+      name: 'sidebar.right.pane.tab', key: BROWSER_ID, locale: namespace, store,
+      inject: (sessionId, actions) => {
+        const existing = controllers.get(sessionId)
+        if (existing !== undefined) {
+          existing.rebind(actions)
+          return existing
+        }
+        const controller = createBrowserControllers(actions, factory(sessionId), tabId =>
+          openTabs.getSnapshot().some(tab => tab.sessionId === sessionId && tab.tabId === tabId))
+        controllers.set(sessionId, controller)
+        return controller
+      },
+    }, BrowserBody)), 'ui-sidebar-browser.body')
+  }
+  if (desktop === undefined) installFrames(ctx, () => createIframePage)
+  else ctx.inject(['workspaces'], (scope) => {
+    installFrames(scope, sessionId => options => createElectronPage(options, desktop,
+      signal => browserWorkspace(scope.workspaces.list, sessionId, signal)))
+  })
   ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab.title', () => ctx.slots.register({
     name: 'sidebar.right.pane.tab.title', key: BROWSER_ID, store,
   }, BrowserTitle)), 'ui-sidebar-browser.title')
diff --git a/packages/client/ui-sidebar-browser/src/client/locales.ts b/packages/client/ui-sidebar-browser/src/client/locales.ts
index 4c551b123e..3c0d305b66 100644
--- a/packages/client/ui-sidebar-browser/src/client/locales.ts
+++ b/packages/client/ui-sidebar-browser/src/client/locales.ts
@@ -15,13 +15,16 @@ export const zh = {
   'sandbox.warning': '沙箱限制已关闭；页面可以导航顶层应用，并使用下载、模态对话框与输入锁定。',
   start: '输入 HTTP(S) 地址开始浏览',
   loading: '正在打开…',
+  'restore.previous': '上次打开',
+  'restore.action': '恢复页面',
   'error.empty': '请输入地址。',
   'error.invalid': '这个地址无效或过长。',
   'error.protocol': '只支持 HTTP 和 HTTPS 地址；本地文件请使用文档预览。',
   'error.credentials': '地址不能包含用户名或密码。',
   'error.application-origin': '不能在嵌入浏览器中打开 DSH 应用自身。',
-  'web.loadFailed': '页面报告加载失败或可能禁止嵌入；可尝试在系统浏览器中打开。',
-  'web.unknown': '页面已在 iframe 内跳转；Web 模式无法读取当前 URL。',
+  'load.failed': '页面加载失败；请刷新重试或在系统浏览器中打开。',
+  'load.failed.detail': '页面加载失败 ({code}): {description}',
+  'address.unknown': '页面已跳转；当前载体无法读取新的 URL。',
 } satisfies Record<string, string>
 
 /** Browser dictionary key union. */
@@ -44,13 +47,16 @@ export const en = {
   'sandbox.warning': 'Sandbox restrictions are disabled; the page can navigate the top-level app and use downloads, modal dialogs, and input locks.',
   start: 'Enter an HTTP(S) address to start browsing',
   loading: 'Opening…',
+  'restore.previous': 'Previously opened',
+  'restore.action': 'Restore page',
   'error.empty': 'Enter an address.',
   'error.invalid': 'That address is invalid or too long.',
   'error.protocol': 'Only HTTP and HTTPS addresses are supported; use Document Preview for local files.',
   'error.credentials': 'Addresses cannot contain a username or password.',
   'error.application-origin': 'The embedded browser cannot open the DSH application itself.',
-  'web.loadFailed': 'The page reported a load failure or may block embedding; try opening it in the system browser.',
-  'web.unknown': 'The page navigated inside the iframe; Web mode cannot read its current URL.',
+  'load.failed': 'The page could not load; reload or open it in the system browser.',
+  'load.failed.detail': 'Page load failed ({code}): {description}',
+  'address.unknown': 'The page navigated; this carrier cannot read its new URL.',
 } satisfies Record<SidebarBrowserKey, string>
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
diff --git a/packages/client/ui-sidebar-browser/src/client/pages.ts b/packages/client/ui-sidebar-browser/src/client/pages.ts
new file mode 100644
index 0000000000..220616b4bd
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/pages.ts
@@ -0,0 +1,19 @@
+/** Assemble iframe navigation and presentation without platform branches in consumers. */
+import type { BrowserPage, BrowserPageOptions } from './browser/BrowserPage.ts'
+import { IframeImpl } from './browser/IframeImpl.ts'
+import { IframePresentation } from './view/IframePresentation.ts'
+
+/**
+ * Assemble an idle iframe provider and its DOM presentation.
+ * @param options - saved navigation and callbacks.
+ * @returns the Web page's navigation and presentation objects.
+ */
+export function createIframePage(options: BrowserPageOptions): BrowserPage {
+  const presentation = new IframePresentation({
+    loaded: (revision) => { frame.handleLoaded(revision) },
+    failed: (revision) => { frame.handleLoadFailed(revision) },
+    remounted: () => { frame.reload() },
+  })
+  const frame = new IframeImpl(options, presentation)
+  return { frame, presentation }
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/view/Browser.module.css b/packages/client/ui-sidebar-browser/src/client/view/Browser.module.css
index 0914d8e6f5..ed6d2cd882 100644
--- a/packages/client/ui-sidebar-browser/src/client/view/Browser.module.css
+++ b/packages/client/ui-sidebar-browser/src/client/view/Browser.module.css
@@ -81,6 +81,9 @@
 }
 
 .addressUnknown {
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+
   color: var(--dsw-alias-label-tertiary);
   background: var(--dsw-alias-bg-layer-2);
 }
@@ -121,6 +124,83 @@
   background: var(--dsw-alias-bg-base);
 }
 
+.content {
+  position: relative;
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+}
+
+.viewport {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+}
+
+.placeholder {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  pointer-events: none;
+}
+
+.restore {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  padding: 24px;
+  overflow: auto;
+  text-align: center;
+}
+
+.restoreLabel {
+  margin: auto 0 0;
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xxs-12);
+}
+
+.restoreTitle {
+  max-width: 100%;
+  margin: 0;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  font-weight: 500;
+}
+
+.restoreUrl {
+  max-width: 100%;
+  margin: 0;
+  overflow-wrap: anywhere;
+  color: var(--dsw-alias-label-secondary);
+  font: var(--dsw-font-xxs-12);
+}
+
+.restore > :last-child {
+  flex-shrink: 0;
+  margin-bottom: auto;
+}
+
+.webview {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  -webkit-app-region: no-drag;
+}
+
+/* Native guest input must not consume a docking gesture's window events. */
+:global(html:has([data-dockkit-pointer])) .webview {
+  pointer-events: none;
+}
+
 .start {
   display: flex;
   flex: 1 1 auto;
diff --git a/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx b/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx
index 5c11a1f374..7c5a7e455b 100644
--- a/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx
+++ b/packages/client/ui-sidebar-browser/src/client/view/BrowserBody.tsx
@@ -1,7 +1,8 @@
-/** Browser toolbar and Web iframe renderer. */
-import { useEffect, useRef, useState } from 'react'
+/** Common browser chrome; a presentation adapter attaches the page inside its content container. */
+import { useId, useLayoutEffect, useRef, useState } from 'react'
 import type { FormEvent, ReactNode } from 'react'
 import {
+  Button,
   IconChevronLeftOutlineRegular,
   IconChevronRightOutlineRegular,
   IconLinkOutlineRegular,
@@ -12,16 +13,12 @@ import {
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
 import type { BrowserInjected } from '../browser/BrowserController.ts'
-import type { BrowserFrameState } from '../browser/BrowserFrame.ts'
-import { BrowserNavigation } from '../browser/BrowserNavigation.ts'
-import type { BrowserAddressFailure } from '../browser/url.ts'
+import { emptyBrowserFrame } from '../browser/BrowserFrame.ts'
+import { currentBrowserTarget } from '../browser/BrowserPersistence.ts'
 import type { BrowserStore } from '../browser/store.ts'
 import css from './Browser.module.css'
 
-/** Fixed Web iframe sandbox; popups escape the sandbox while top navigation remains absent. */
-export const WEB_BROWSER_SANDBOX = 'allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox'
-
-const INITIAL_BROWSER_FRAME: BrowserFrameState = { document: undefined, sandboxed: true, loadFailed: false }
+const EMPTY_FRAME = emptyBrowserFrame()
 
 function SandboxPolicyIcon({ sandboxed }: { readonly sandboxed: boolean }): ReactNode {
   return (
@@ -40,116 +37,94 @@ export type BrowserBodyProps = PropsRuntime<'sidebar.right.pane.tab'>
   & PropsLocale<'sidebarBrowser'>
   & InjectFace<BrowserInjected>
 
-/** Translate one parser refusal without matching display strings in logic. */
-function failureText(reason: BrowserAddressFailure, t: BrowserBodyProps['t']): string {
-  return t(`error.${reason}`)
+function useBrowserDraft(url: string | undefined, revision: number): readonly [string, (value: string) => void] {
+  const [edit, setEdit] = useState<{ readonly revision: number; readonly value: string }>()
+  return [edit?.revision === revision ? edit.value : url ?? '',
+    (value) => { setEdit({ revision, value }) }]
 }
 
-function useBrowserDraft(
-  controlledUrl: string | undefined,
-  requestId: number | undefined,
-): readonly [string, (value: string) => void] {
-  const [edit, setEdit] = useState<{ readonly requestId: number | undefined; readonly value: string }>()
-  const value = edit !== undefined && edit.requestId === requestId ? edit.value : controlledUrl ?? ''
-  return [value, (draft) => { setEdit({ requestId, value: draft }) }]
-}
-
-/** Browser tab renderer for a controller-owned URL state and Web iframe carrier. */
+/** Render provider-neutral navigation state and optional controls. */
 export function BrowserBody(props: BrowserBodyProps): ReactNode {
-  const {
-    goBack, goForward, loadUrl, mount, reload, reportLoaded, reportLoadFailed, toggleSandbox,
-    useBrowserFrame, useStore, useTabInfo, t,
-  } = props
+  const { mount, loadUrl, restore, goBack, goForward, reload, setSandbox, useBrowserState, useStore, useTabInfo, t } = props
   const { tab } = useTabInfo()
-  const state = useStore(snapshot => snapshot.byTab[tab.id]) ?? BrowserNavigation.empty()
-  const initialState = useRef(state)
+  const saved = useStore(state => state.byTab[tab.id])
+  const initial = useRef(saved)
   const initialUrl = useRef(tab.navigation.params?.url)
-  const current = BrowserNavigation.current(state)
-  const [draft, setDraft] = useBrowserDraft(current?.url ?? initialUrl.current, state.request?.revision)
-  const [mountCount, setMountCount] = useState(0)
+  const viewportId = useId()
+  const [mountEpoch, setMountEpoch] = useState(0)
+  const state = useBrowserState(tab.id)
+  const frame = state?.frame ?? EMPTY_FRAME
+  const restoreTarget = state === undefined ? currentBrowserTarget(initial.current) : state.restoreTarget
+  const target = frame.target ?? restoreTarget
+  const [draft, setDraft] = useBrowserDraft(target?.url ?? initialUrl.current, state?.addressRevision ?? 0)
 
-  useEffect(() => {
-    mount(tab.id, tab.signal, window.location.origin, initialState.current)
-    setMountCount(count => count + 1)
-  }, [mount, tab.id, tab.signal])
+  useLayoutEffect(() => {
+    const hide = mount({
+      tabId: tab.id, signal: tab.signal, viewportId, applicationOrigin: window.location.origin,
+      initial: initial.current, initialUrl: initialUrl.current,
+      openTab: (url) => { tab.actions.openTab('browser', { params: { url }, revealIfOpened: false }) },
+    })
+    setMountEpoch(value => value + 1)
+    return hide
+  }, [mount, tab.id, tab.signal, tab.actions, viewportId, props.actions])
 
-  useEffect(() => {
-    if (mountCount === 0) return
-    const resumed = BrowserNavigation.current(initialState.current)
-    if (resumed !== undefined) {
-      reload(tab.id)
-      return
-    }
-    const url = initialUrl.current
-    if (url !== undefined) loadUrl(tab.id, url)
-  }, [loadUrl, mountCount, reload, tab.id])
-
-  const frameState = useBrowserFrame(tab.id) ?? INITIAL_BROWSER_FRAME
-  const { document, sandboxed, loadFailed } = frameState
-
-  const navigationUnknown = state.navigation.status === 'unknown'
-  const externalUrl = navigationUnknown ? undefined : current?.url
+  const unknown = frame.address === 'unknown'
+  const externalUrl = unknown ? undefined : target?.url
+  const sandboxed = frame.sandboxEnabled
+  const failure = state?.addressFailure
+  const error = frame.error
   const submit = (event: FormEvent): void => { event.preventDefault(); loadUrl(tab.id, draft) }
-  const failure = state.failure === undefined ? undefined : failureText(state.failure.reason, t)
-  const placeholder = current === undefined ? t('start') : t('loading')
 
   return (
     <div className={css.root}>
       <form className={css.toolbar} onSubmit={submit}>
-        <button type="button" className={css.tool} aria-label={t('back')} title={t('back')} disabled={!BrowserNavigation.canGoBack(state)} onClick={() => { goBack(tab.id) }}><IconChevronLeftOutlineRegular /></button>
-        <button type="button" className={css.tool} aria-label={t('forward')} title={t('forward')} disabled={!BrowserNavigation.canGoForward(state)} onClick={() => { goForward(tab.id) }}><IconChevronRightOutlineRegular /></button>
-        <button type="button" className={css.tool} aria-label={t('reload')} title={t('reload')} disabled={current === undefined} onClick={() => { reload(tab.id) }}><IconRefreshOutlineRegular /></button>
+        <button type="button" className={css.tool} aria-label={t('back')} title={t('back')} disabled={!frame.canGoBack} onClick={() => { goBack(tab.id) }}><IconChevronLeftOutlineRegular /></button>
+        <button type="button" className={css.tool} aria-label={t('forward')} title={t('forward')} disabled={!frame.canGoForward} onClick={() => { goForward(tab.id) }}><IconChevronRightOutlineRegular /></button>
+        <button type="button" className={css.tool} aria-label={t('reload')} title={t('reload')} disabled={target === undefined || mountEpoch === 0} onClick={() => { reload(tab.id) }}><IconRefreshOutlineRegular /></button>
         <div className={css.addressBox}>
           <input
-            className={`${css.address} ${navigationUnknown ? css.addressUnknown : ''}`}
+            className={[css.address, unknown ? css.addressUnknown : ''].join(' ')}
             value={draft}
             aria-label={t('address.placeholder')}
             placeholder={t('address.placeholder')}
             spellCheck={false}
             onChange={(event) => { setDraft(event.currentTarget.value) }}
           />
-          {navigationUnknown && <span className={css.addressChanged}>{t('address.changed')}</span>}
-          <button type="submit" className={`${css.tool} ${css.addressGo}`} aria-label={t('go')} title={t('go')}><IconLinkOutlineRegular /></button>
+          {unknown && <span className={css.addressChanged}>{t('address.changed')}</span>}
+          <button type="submit" className={[css.tool, css.addressGo].join(' ')} aria-label={t('go')} title={t('go')}><IconLinkOutlineRegular /></button>
         </div>
-        <button
-          type="button"
-          className={css.tool}
-          aria-label={t('external')}
-          title={t('external')}
-          disabled={externalUrl === undefined}
-          onClick={() => {
-            /* v8 ignore next -- React does not dispatch clicks from this disabled button. */
-            if (externalUrl !== undefined) window.open(externalUrl, '_blank', 'noopener,noreferrer')
-          }}
+        <button type="button" className={css.tool} aria-label={t('external')} title={t('external')} disabled={externalUrl === undefined}
+          onClick={externalUrl === undefined ? undefined : () => { window.open(externalUrl, '_blank', 'noopener,noreferrer') }}
         ><IconRightUpOutlineRegular size={14} /></button>
-        <button
+        {sandboxed !== undefined && <button
           type="button"
-          className={`${css.tool} ${sandboxed ? '' : css.sandboxOff}`}
+          className={[css.tool, sandboxed ? '' : css.sandboxOff].join(' ')}
           aria-label={t(sandboxed ? 'sandbox.disable' : 'sandbox.enable')}
           title={t(sandboxed ? 'sandbox.disable' : 'sandbox.enable')}
           aria-pressed={!sandboxed}
-          disabled={mountCount === 0}
-          onClick={() => { toggleSandbox(tab.id) }}
-        ><SandboxPolicyIcon sandboxed={sandboxed} /></button>
+          onClick={() => { setSandbox(tab.id, !sandboxed) }}
+        ><SandboxPolicyIcon sandboxed={sandboxed} /></button>}
       </form>
-      {!sandboxed && <div className={css.sandboxWarning} role="status">{t('sandbox.warning')}</div>}
-      {loadFailed && <div className={css.failure} role="status">{t('web.loadFailed')}</div>}
-      {failure !== undefined && <div className={css.failure} role="alert">{failure}</div>}
-      {document === undefined
-        ? <div className={css.start}>{placeholder}</div>
-        : <iframe
-          key={`${document.target.url}:${String(document.revision)}`}
-          className={css.frame}
-          src={document.src}
-          sandbox={sandboxed ? WEB_BROWSER_SANDBOX : undefined}
-          referrerPolicy="no-referrer"
-          title={document.target.title}
-          onLoad={() => { reportLoaded(tab.id, document.revision) }}
-          /* v8 ignore next -- jsdom does not dispatch React iframe error events; BrowserFrame owns the tested behavior. */
-          onError={() => { reportLoadFailed(tab.id, document.revision) }}
-          data-sidebar-browser-frame
-        />}
-      {navigationUnknown && <p className={css.limit}>{t('web.unknown')}</p>}
+      {sandboxed === false && <div className={css.sandboxWarning} role="status">{t('sandbox.warning')}</div>}
+      {error !== undefined && <div className={css.failure} role="status">{error.code !== undefined && error.description !== undefined
+        ? t('load.failed.detail', { code: String(error.code), description: error.description })
+        : t('load.failed')}</div>}
+      {failure !== undefined && <div className={css.failure} role="alert">{t(`error.${failure}`)}</div>}
+      <div className={css.content} aria-busy={frame.loading}>
+        <div id={viewportId} className={css.viewport} aria-label={t('type.label')} />
+        {restoreTarget !== undefined && <section className={css.restore} aria-label={t('restore.previous')}>
+          <p className={css.restoreLabel}>{t('restore.previous')}</p>
+          <p className={css.restoreTitle}>{restoreTarget.title}</p>
+          <p className={css.restoreUrl}>{restoreTarget.url}</p>
+          <Button variant="primary" size="sm" disabled={mountEpoch === 0} onClick={() => { restore(tab.id) }}>
+            {t('restore.action')}
+          </Button>
+        </section>}
+        {restoreTarget === undefined && (target === undefined || frame.loading) && error === undefined && <div className={css.placeholder}>
+          <div className={css.start}>{t(target === undefined ? 'start' : 'loading')}</div>
+        </div>}
+      </div>
+      {unknown && <p className={css.limit}>{t('address.unknown')}</p>}
     </div>
   )
 }
diff --git a/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts b/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts
new file mode 100644
index 0000000000..dadf0dc478
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/view/BrowserPresentation.ts
@@ -0,0 +1,9 @@
+/** The presentation face is separate from page navigation and terminal disposal. */
+export interface BrowserPresentation {
+  /**
+   * Attach the page inside a committed content container.
+   * @param viewportId - content element id; its DOM ancestors must remain connected for page retention.
+   * @returns ends physical attachment, without disposing the navigation model; a later mount may reload the page.
+   */
+  mount(viewportId: string): () => void
+}
diff --git a/packages/client/ui-sidebar-browser/src/client/view/BrowserTitle.tsx b/packages/client/ui-sidebar-browser/src/client/view/BrowserTitle.tsx
index 55d479d5ae..6a3c54c7f5 100644
--- a/packages/client/ui-sidebar-browser/src/client/view/BrowserTitle.tsx
+++ b/packages/client/ui-sidebar-browser/src/client/view/BrowserTitle.tsx
@@ -2,7 +2,7 @@
 import type { ReactNode } from 'react'
 import { IconGlobeOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
-import { BrowserNavigation } from '../browser/BrowserNavigation.ts'
+import { currentBrowserTarget } from '../browser/BrowserPersistence.ts'
 import type { BrowserStore } from '../browser/store.ts'
 import css from './Browser.module.css'
 
@@ -12,6 +12,6 @@ export type BrowserTitleProps = PropsRuntime<'sidebar.right.pane.tab.title'> & P
 /** Browser icon and current host name. */
 export function BrowserTitle({ useTabInfo, useStore }: BrowserTitleProps): ReactNode {
   const { tab } = useTabInfo()
-  const entry = useStore(state => BrowserNavigation.current(state.byTab[tab.id]))
+  const entry = useStore(state => currentBrowserTarget(state.byTab[tab.id]))
   return <><IconGlobeOutlineRegular className={css.titleIcon} />{entry?.title ?? tab.title}</>
 }
diff --git a/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts b/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts
new file mode 100644
index 0000000000..fc064f5ca7
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/client/view/IframePresentation.ts
@@ -0,0 +1,88 @@
+/** Iframe DOM and revision-tagged load observations. */
+import type { BrowserTarget } from '../browser/url.ts'
+import type { BrowserPresentation } from './BrowserPresentation.ts'
+import css from './Browser.module.css'
+
+/** Fixed iframe policy; top navigation and downloads are not granted directly. */
+export const WEB_BROWSER_SANDBOX = 'allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox'
+
+interface IframeDocument {
+  readonly target: BrowserTarget
+  readonly revision: number
+  readonly sandboxed: boolean
+}
+
+/** Reports only what an iframe can observe without inspecting cross-origin content. */
+export interface IframePresentationEvents {
+  readonly loaded: (revision: number) => void
+  readonly failed: (revision: number) => void
+  readonly remounted: () => void
+}
+
+/** Owns the iframe element; navigation and history remain in IframeImpl. */
+export class IframePresentation implements BrowserPresentation {
+  private host: HTMLElement | undefined
+  private element: HTMLIFrameElement | undefined
+  private document: IframeDocument | undefined
+  private rendered = false
+
+  /** @param events - provider-owned load and remount callbacks. */
+  constructor(private readonly events: IframePresentationEvents) {}
+
+  /** @param viewportId - mounted placeholder. @returns removes only the iframe presentation. */
+  mount(viewportId: string): () => void {
+    const host = document.getElementById(viewportId)
+    if (host === null) throw new Error('iframe presentation: viewport is not mounted')
+    this.element?.remove()
+    this.element = undefined
+    this.host = host
+    if (this.rendered) this.events.remounted()
+    else this.render()
+    return () => {
+      if (this.host !== host) return
+      this.element?.remove()
+      this.element = undefined
+      this.host = undefined
+    }
+  }
+
+  /**
+   * Retain the prepared document and render it when a container is mounted.
+   * @param value - prepared document and event generation.
+   */
+  show(value: IframeDocument): void {
+    this.document = value
+    this.render()
+  }
+
+  /** Remove the owned DOM and retained presentation data. */
+  dispose(): void {
+    this.element?.remove()
+    this.element = undefined
+    this.host = undefined
+    this.document = undefined
+  }
+
+  private render(): void {
+    const current = this.document
+    const host = this.host
+    if (current === undefined || host === undefined) return
+    this.element?.remove()
+    const element = document.createElement('iframe')
+    element.className = css.frame as string
+    element.src = current.target.url
+    element.title = current.target.title
+    element.referrerPolicy = 'no-referrer'
+    element.dataset.sidebarBrowserFrame = 'iframe'
+    if (current.sandboxed) element.setAttribute('sandbox', WEB_BROWSER_SANDBOX)
+    element.addEventListener('load', () => {
+      if (this.element === element) this.events.loaded(current.revision)
+    })
+    element.addEventListener('error', () => {
+      if (this.element === element) this.events.failed(current.revision)
+    })
+    this.element = element
+    this.rendered = true
+    host.append(element)
+  }
+}
diff --git a/packages/client/ui-sidebar-browser/src/types.ts b/packages/client/ui-sidebar-browser/src/types.ts
new file mode 100644
index 0000000000..932211e13b
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/src/types.ts
@@ -0,0 +1,27 @@
+/** Type-only Electron bridge declarations shared by the desktop shell and browser provider. */
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Main-issued identity of one guest reservation. */
+export type DesktopBrowserLeaseId = Branded<'DesktopBrowserLeaseId'>
+
+/** A guest's approved, process-local storage partition. */
+export interface DesktopBrowserReservation {
+  readonly lease: DesktopBrowserLeaseId
+  readonly partition: string
+}
+
+/** Main-approved request to open an HTTP(S) page from an existing guest. */
+export interface DesktopBrowserOpenRequest {
+  readonly lease: DesktopBrowserLeaseId
+  readonly url: string
+}
+
+/** Origin-scoped operations; no Electron objects or arbitrary IPC cross this interface. */
+export interface DesktopBrowserBridge {
+  /** @param workspace - resolved storage account. @returns one approved guest reservation. */
+  acquire(workspace: string): Promise<DesktopBrowserReservation>
+  /** @param lease - the caller's reservation. @returns after its guest has been destroyed. */
+  release(lease: DesktopBrowserLeaseId): Promise<void>
+  /** @param lease - originating guest. @param listener - approved URL consumer. @returns unsubscribe callback. */
+  onOpenRequested(lease: DesktopBrowserLeaseId, listener: (url: string) => void): () => void
+}
diff --git a/packages/client/ui-sidebar-browser/tests/apply.client.spec.ts b/packages/client/ui-sidebar-browser/tests/apply.client.spec.ts
index f14dee3038..311138f63e 100644
--- a/packages/client/ui-sidebar-browser/tests/apply.client.spec.ts
+++ b/packages/client/ui-sidebar-browser/tests/apply.client.spec.ts
@@ -1,6 +1,8 @@
+// @vitest-environment jsdom
 /** Browser type, Slot, locale, and HMR disposal through the real registries. */
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { SidebarRightTabRegistry } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/tab-registry.ts'
 import { BrowserBody } from '../src/client/view/BrowserBody.tsx'
 import { BrowserTitle } from '../src/client/view/BrowserTitle.tsx'
@@ -8,7 +10,16 @@ import type { BrowserInjected } from '../src/client/browser/BrowserController.ts
 import { BROWSER_ID, BROWSER_KIND } from '../src/client/definition.tsx'
 import { apply, inject } from '../src/client/index.ts'
 import { en, zh } from '../src/client/locales.ts'
-import { apply as hostApply } from '../src/index.ts'
+import { createBrowserStore } from '../src/client/browser/store.ts'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { DesktopBrowserBridge, DesktopBrowserLeaseId } from '../src/types.ts'
+
+const contexts: Context[] = []
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  vi.unstubAllGlobals()
+})
 
 interface Recorded {
   name: string
@@ -21,6 +32,7 @@ interface Recorded {
 
 async function boot() {
   const ctx = new Context()
+  contexts.push(ctx)
   const tabs = new SidebarRightTabRegistry(ctx)
   const registered: Recorded[] = []
   const slots = {
@@ -40,16 +52,63 @@ async function boot() {
     }),
   }
   ctx.provide('sidebarRightTabs', tabs as never)
+  const openTabs = createSnapshotStore<readonly { sessionId: string; tabId: TabId }[]>([])
+  ctx.provide('sidebarRight', { openTabs } as never)
+  ctx.provide('workspaces', { list: createSnapshotStore({ phase: 'ready', items: [] }) } as never)
   ctx.provide('slots', slots as never)
   ctx.provide('locale', locale as never)
   const fiber = ctx.plugin({ inject: [...inject], apply })
   await fiber.await()
-  return { tabs, registered, dictionaries, fiber }
+  return { tabs, registered, dictionaries, fiber, openTabs }
 }
 
 describe('ui-sidebar-browser apply', () => {
-  it('keeps the Host Loader entry inert', () => {
-    expect(hostApply).not.toThrow()
+  it.each([0, 1])('binds and rebinds session controllers under desktop protocol %s', async (protocolVersion) => {
+    const acquire = vi.fn(async () => ({ lease: 'test-lease' as DesktopBrowserLeaseId, partition: 'test-partition' }))
+    const bridge: DesktopBrowserBridge = {
+      acquire,
+      release: vi.fn(async () => {}),
+      onOpenRequested: vi.fn(() => () => {}),
+    }
+    vi.stubGlobal('dshDesktop', { protocolVersion, browser: bridge })
+    const h = await boot()
+    expect(h.tabs.get(BROWSER_KIND)?.keepMounted).toBe(protocolVersion === 1)
+    const injectFace = h.registered.find(entry => entry.name === 'sidebar.right.pane.tab')!.inject as
+      (sessionId: string, actions: Parameters<BrowserInjected['rebind']>[0]) => BrowserInjected
+    const firstStore = createBrowserStore().create(`apply-first-${protocolVersion}`)
+    const replacementStore = createBrowserStore().create(`apply-replacement-${protocolVersion}`)
+    const controller = injectFace('session', firstStore.actions)
+    expect(injectFace('session', replacementStore.actions)).toBe(controller)
+    const host = document.createElement('div')
+    host.id = `browser-apply-${protocolVersion}`
+    document.body.append(host)
+    const signal = new AbortController()
+    const tabId = 'apply-tab' as TabId
+    try {
+      controller.mount({ tabId, signal: signal.signal, viewportId: host.id, applicationOrigin: 'https://dsh.example',
+        initial: undefined, initialUrl: 'https://example.test/', openTab: vi.fn() })
+      expect(replacementStore.getSnapshot().byTab[tabId]).toBeDefined()
+      expect(firstStore.getSnapshot().byTab[tabId]).toBeUndefined()
+      if (protocolVersion === 1) await vi.waitFor(() => { expect(acquire).toHaveBeenCalledWith('session:session') })
+      else expect(host.querySelector('iframe')).not.toBeNull()
+      h.openTabs.set([{ sessionId: 'other', tabId }, { sessionId: 'session', tabId: 'other-tab' as TabId }])
+      signal.abort()
+      expect(replacementStore.getSnapshot().byTab[tabId]).toBeUndefined()
+      const reopened = new AbortController()
+      controller.mount({ tabId, signal: reopened.signal, viewportId: host.id, applicationOrigin: 'https://dsh.example',
+        initial: undefined, initialUrl: 'https://retained.example/', openTab: vi.fn() })
+      h.openTabs.set([{ sessionId: 'session', tabId }])
+      reopened.abort()
+      expect(replacementStore.getSnapshot().byTab[tabId]).toBeDefined()
+      const active = new AbortController()
+      controller.mount({ tabId, signal: active.signal, viewportId: host.id, applicationOrigin: 'https://dsh.example',
+        initial: undefined, initialUrl: undefined, openTab: vi.fn() })
+      await h.fiber.dispose()
+      expect(controller.keyedHooks.browserState(tabId)).toBeUndefined()
+    } finally {
+      await h.fiber.dispose()
+      host.remove()
+    }
   })
 
   it('registers a multi-instance builtin and its body and title', async () => {
@@ -72,7 +131,7 @@ describe('ui-sidebar-browser apply', () => {
     expect(registered[0]?.inject).toBeTypeOf('function')
     const injectFace = registered[0]?.inject as ((sessionId: string, actions: unknown) => unknown)
     const browser = injectFace('session', { replace: vi.fn(), forget: vi.fn() }) as BrowserInjected
-    expect(browser.keyedHooks.browserFrame('missing')).toBeUndefined()
+    expect(browser.keyedHooks.browserState('missing')).toBeUndefined()
     expect(typeof browser.mount).toBe('function')
   })
 
diff --git a/packages/client/ui-sidebar-browser/tests/apply.host.spec.ts b/packages/client/ui-sidebar-browser/tests/apply.host.spec.ts
new file mode 100644
index 0000000000..419889503c
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tests/apply.host.spec.ts
@@ -0,0 +1,6 @@
+import { expect, it } from 'vitest'
+import { apply } from '../src/index.ts'
+
+it('keeps the Browser Host Loader entry inert', () => {
+  expect(apply).not.toThrow()
+})
diff --git a/packages/client/ui-sidebar-browser/tests/browser-body.client.spec.tsx b/packages/client/ui-sidebar-browser/tests/browser-body.client.spec.tsx
index 4615a0a0d4..09ca4e75d1 100644
--- a/packages/client/ui-sidebar-browser/tests/browser-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-browser/tests/browser-body.client.spec.tsx
@@ -3,17 +3,24 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
 import { useSyncExternalStore } from 'react'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
-import { createBrowserControllers } from '../src/client/browser/BrowserController.ts'
-import type { BrowserFrameState } from '../src/client/browser/BrowserFrame.ts'
+import type { PaneId, TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { createBrowserControllers, type BrowserControllerState, type BrowserInjected } from '../src/client/browser/BrowserController.ts'
 import { createBrowserStore } from '../src/client/browser/store.ts'
 import type { BrowserBodyProps } from '../src/client/view/BrowserBody.tsx'
-import { BrowserBody, WEB_BROWSER_SANDBOX } from '../src/client/view/BrowserBody.tsx'
+import { BrowserBody } from '../src/client/view/BrowserBody.tsx'
+import { WEB_BROWSER_SANDBOX } from '../src/client/view/IframePresentation.ts'
+import { createIframePage } from '../src/client/pages.ts'
 import { zh } from '../src/client/locales.ts'
+import { browserAddressCheckpoint, type BrowserTabState } from '../src/client/browser/BrowserPersistence.ts'
+import type { BrowserPageFactory, BrowserPageOptions } from '../src/client/browser/BrowserPage.ts'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { emptyBrowserFrame, type BrowserFrameState } from '../src/client/browser/BrowserFrame.ts'
 
 const SESSION = 'session' as SessionId
 const TAB = 'tab' as TabId
+const messages: Readonly<Record<string, string>> = zh
 const lifetimes = new Set<AbortController>()
+const controllers: BrowserInjected[] = []
 let mountSequence = 0
 
 function hookOf<T>(store: { subscribe(listener: () => void): () => void; getSnapshot(): T }) {
@@ -25,51 +32,54 @@ function hookOf<T>(store: { subscribe(listener: () => void): () => void; getSnap
   }
 }
 
-const absentFrame = {
+const absentState = {
   subscribe: (_listener: () => void): (() => void) => () => {},
-  getSnapshot: (): BrowserFrameState | undefined => undefined,
+  getSnapshot: (): BrowserControllerState | undefined => undefined,
 }
 
-function mountBrowser(navigation?: { readonly url?: string }) {
+function mountBrowser(navigation?: { readonly url?: string },
+  options: { initial?: BrowserTabState; createPage?: BrowserPageFactory } = {}) {
   const store = createBrowserStore().create(`browser-body-test-${String(++mountSequence)}`)
+  if (options.initial !== undefined) store.actions.replace(TAB, options.initial)
   const lifetime = new AbortController()
   lifetimes.add(lifetime)
-  const injected = createBrowserControllers(store.actions)
+  const injected = createBrowserControllers(store.actions, options.createPage ?? createIframePage, () => true)
+  controllers.push(injected)
   const { keyedHooks, ...commands } = injected
-  const props = {
-    sessionId: SESSION,
-    useSessions: vi.fn(),
-    useResource: vi.fn(),
-    useWorkspaces: vi.fn(),
-    usePanelInfo: vi.fn(),
-    useSessionPendingInteraction: vi.fn(),
-    useTabInfo: () => ({
-      sidebar: { expanded: true, fullscreen: false }, panel: { id: 'pane' },
-      tab: {
-        id: TAB, kind: 'browser', title: 'Browser', contentId: 'sidebar://browser/1', visible: true,
-        navigation: { address: 'sidebar://browser/1', params: navigation, revision: 0 },
-        signal: lifetime.signal,
-        actions: { openResource: vi.fn(), openTab: vi.fn(), close: vi.fn() },
+  const tabActions = { openResource: vi.fn(), openTab: vi.fn(), close: vi.fn() }
+  const props: Pick<BrowserBodyProps, 'sessionId' | 'useTabInfo' | 'useStore' | 'actions' | 't' | 'useBrowserState'>
+    & Omit<BrowserInjected, 'keyedHooks'> = {
+      sessionId: SESSION,
+      useTabInfo: () => ({
+        sidebar: { expanded: true, fullscreen: false }, panel: { id: 'pane' as PaneId },
+        tab: {
+          id: TAB, kind: 'browser', title: 'Browser', contentId: 'sidebar://browser/1', visible: true,
+          navigation: { address: 'sidebar://browser/1', params: navigation, revision: 0 },
+          signal: lifetime.signal,
+          actions: tabActions,
+        },
+      }),
+      useStore: hookOf(store),
+      actions: store.actions,
+      t: (key, params) => {
+        const template = messages[key] ?? key
+        return params === undefined ? template : template.replace(/\{(\w+)\}/g, (_match, name: string) => String(params[name]))
       },
-    }),
-    useStore: hookOf(store),
-    actions: store.actions,
-    t: (key: keyof typeof zh, params?: Record<string, unknown>) => params === undefined
-      ? zh[key] : zh[key].replace('{message}', String(params.message)),
-    ...commands,
-    useBrowserFrame: (key: string) => {
-      const frame = keyedHooks.browserFrame(key) ?? absentFrame
-      return useSyncExternalStore(frame.subscribe, frame.getSnapshot)
-    },
-  } as unknown as BrowserBodyProps
-  const renderBody = () => render(<BrowserBody {...props} />)
+      ...commands,
+      useBrowserState: (key: string) => {
+        const state = keyedHooks.browserState(key) ?? absentState
+        return useSyncExternalStore(state.subscribe, state.getSnapshot)
+      },
+    }
+  const renderBody = () => render(<BrowserBody {...props as BrowserBodyProps} />)
   return {
-    view: renderBody(), remount: renderBody, store, lifetime, injected,
+    view: renderBody(), remount: renderBody, store, lifetime, injected, tabActions,
   }
 }
 
-afterEach(() => {
+afterEach(async () => {
   cleanup()
+  await Promise.all(controllers.splice(0).map(controller => controller.dispose()))
   for (const lifetime of lifetimes) lifetime.abort()
   lifetimes.clear()
   localStorage.clear()
@@ -77,6 +87,39 @@ afterEach(() => {
 })
 
 describe('BrowserBody', () => {
+  it('shows the saved title and URL without loading until Restore is clicked', async () => {
+    const target = { kind: 'https' as const, url: 'https://saved.example/page', title: 'Saved title' }
+    const mounted = mountBrowser(undefined, { initial: browserAddressCheckpoint(target, 1) })
+    expect(mounted.view.getByText(target.title)).toBeDefined()
+    expect(mounted.view.getByText(target.url)).toBeDefined()
+    expect(mounted.view.container.querySelector('iframe')).toBeNull()
+    expect(mounted.view.getByRole('button', { name: zh.reload })).toHaveProperty('disabled', false)
+    fireEvent.click(mounted.view.getByRole('button', { name: zh['restore.action'] }))
+    await waitFor(() => { expect(mounted.view.container.querySelector('iframe')?.src).toBe(target.url) })
+    expect(mounted.view.queryByText(target.title)).toBeNull()
+  })
+
+  it('renders native error details and routes provider open requests through the source tab', () => {
+    const state = createSnapshotStore<BrowserFrameState>({ ...emptyBrowserFrame(), error: { code: -105, description: 'DNS failure' } })
+    const providers: BrowserPageOptions[] = []
+    const mounted = mountBrowser(undefined, { createPage: (options) => {
+      providers.push(options)
+      return {
+        presentation: { mount: () => () => {} },
+        frame: { getSnapshot: () => state.getSnapshot(), subscribe: listener => state.subscribe(listener),
+          loadUrl: vi.fn(), goBack: vi.fn(), goForward: vi.fn(), reload: vi.fn(), dispose: async () => {} },
+      }
+    } })
+    expect(mounted.view.getByRole('status').textContent).toContain('DNS failure')
+    expect(mounted.view.getByRole('status').textContent).toContain('-105')
+    act(() => { state.set({ ...state.getSnapshot(), error: { code: -105, description: undefined } }) })
+    expect(mounted.view.getByRole('status').textContent).toBe(zh['load.failed'])
+    act(() => { providers[0]!.openRequested('https://new.example/') })
+    expect(mounted.tabActions.openTab).toHaveBeenCalledExactlyOnceWith('browser', {
+      params: { url: 'https://new.example/' }, revealIfOpened: false,
+    })
+  })
+
   it('routes address input to the controller and renders parser failures', async () => {
     const mounted = mountBrowser()
     const input = mounted.view.getByRole('textbox')
@@ -101,7 +144,8 @@ describe('BrowserBody', () => {
     expect(frame.getAttribute('src')).toBe('https://example.com/one')
     expect(frame.getAttribute('sandbox')).toBe(WEB_BROWSER_SANDBOX)
     expect(frame.getAttribute('allow')).toBeNull()
-    expect(frame.getAttribute('referrerpolicy')).toBe('no-referrer')
+    // jsdom does not reflect the iframe referrerPolicy property to its attribute.
+    expect(frame.referrerPolicy).toBe('no-referrer')
     const disableSandbox = mounted.view.getByRole('button', { name: zh['sandbox.disable'] })
     const protectedMark = disableSandbox.querySelector('svg path:last-child')?.getAttribute('d')
     fireEvent.click(disableSandbox)
@@ -169,15 +213,15 @@ describe('BrowserBody', () => {
     fireEvent.change(input, { target: { value: 'https://example.com/one' } })
     fireEvent.submit(input.closest('form')!)
     await waitFor(() => { expect(mounted.view.container.querySelector('iframe')).not.toBeNull() })
-    const failedRevision = mounted.store.getSnapshot().byTab[TAB]!.request!.revision
+    const failedFrame = mounted.view.container.querySelector('iframe')!
 
-    act(() => { mounted.injected.reportLoadFailed(TAB, failedRevision) })
-    expect(mounted.injected.keyedHooks.browserFrame(TAB)?.getSnapshot().loadFailed).toBe(true)
-    await waitFor(() => { expect(mounted.view.getByText(zh['web.loadFailed'])).toBeDefined() })
+    fireEvent.error(failedFrame)
+    expect(mounted.injected.keyedHooks.browserState(TAB)?.getSnapshot().frame.error).toBeDefined()
+    await waitFor(() => { expect(mounted.view.getByText(zh['load.failed'])).toBeDefined() })
     fireEvent.click(mounted.view.getByRole('button', { name: zh.reload }))
-    await waitFor(() => { expect(mounted.view.queryByText(zh['web.loadFailed'])).toBeNull() })
-    act(() => { mounted.injected.reportLoadFailed(TAB, failedRevision) })
-    expect(mounted.view.queryByText(zh['web.loadFailed'])).toBeNull()
+    await waitFor(() => { expect(mounted.view.queryByText(zh['load.failed'])).toBeNull() })
+    fireEvent.error(failedFrame)
+    expect(mounted.view.queryByText(zh['load.failed'])).toBeNull()
   })
 
   it('loads loopback under the default sandbox and keeps it across sandbox changes', async () => {
diff --git a/packages/client/ui-sidebar-browser/tests/browser-controller.client.spec.ts b/packages/client/ui-sidebar-browser/tests/browser-controller.client.spec.ts
index 3801351adb..f3b09fb9e5 100644
--- a/packages/client/ui-sidebar-browser/tests/browser-controller.client.spec.ts
+++ b/packages/client/ui-sidebar-browser/tests/browser-controller.client.spec.ts
@@ -3,10 +3,18 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
 import { BrowserController, createBrowserControllers } from '../src/client/browser/BrowserController.ts'
 import { createBrowserStore } from '../src/client/browser/store.ts'
+import { createIframePage } from '../src/client/pages.ts'
+import type { BrowserPageFactory, BrowserPageOptions } from '../src/client/browser/BrowserPage.ts'
+import { browserAddressCheckpoint } from '../src/client/browser/BrowserPersistence.ts'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { emptyBrowserFrame, type BrowserFrameState } from '../src/client/browser/BrowserFrame.ts'
 
 const TAB = 'tab' as TabId
 const APP = 'https://dsh.example'
 const lifetimes = new Set<AbortController>()
+const disposables: { dispose(): Promise<void> }[] = []
+const hosts: HTMLElement[] = []
+let sequence = 0
 
 function lifetime(): AbortController {
   const controller = new AbortController()
@@ -14,49 +22,159 @@ function lifetime(): AbortController {
   return controller
 }
 
-afterEach(() => {
+function harness() {
+  const id = `browser-controller-test-${String(++sequence)}`
+  const store = createBrowserStore().create(id)
+  let open = true
+  const face = createBrowserControllers(store.actions, createIframePage, () => open)
+  disposables.push(face)
+  const host = document.createElement('div')
+  host.id = id
+  hosts.push(host)
+  document.body.append(host)
+  const mount = (signal: AbortSignal): (() => void) => face.mount({
+    tabId: TAB, signal, viewportId: id, applicationOrigin: APP,
+    initial: store.getSnapshot().byTab[TAB], initialUrl: undefined, openTab: vi.fn(),
+  })
+  const iframe = (): HTMLIFrameElement => {
+    const element = host.querySelector('iframe')
+    if (element === null) throw new Error('expected a mounted iframe')
+    return element
+  }
+  return { store, face, mount, iframe, close: () => { open = false } }
+}
+
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map(value => value.dispose()))
   for (const controller of lifetimes) controller.abort()
   lifetimes.clear()
+  for (const host of hosts.splice(0)) host.remove()
   localStorage.clear()
   vi.restoreAllMocks()
 })
 
 describe('BrowserController', () => {
-  it('ignores navigation commands after its tab occurrence ends', () => {
+  it('restores only on request and redirects saved checkpoints to a replacement binding', () => {
+    const h = harness()
+    const saved = browserAddressCheckpoint({ kind: 'https', url: 'https://saved.example/', title: 'Saved page' }, 2)
+    h.store.actions.replace(TAB, saved)
+    const tabLifetime = lifetime()
+    h.mount(tabLifetime.signal)
+    const state = h.face.keyedHooks.browserState(TAB)!
+    expect(state.getSnapshot().restoreTarget?.title).toBe('Saved page')
+    expect(state.getSnapshot().frame.target).toBeUndefined()
+    const rebound = createBrowserStore().create('rebound-browser-controller')
+    h.face.rebind(rebound.actions)
+    h.mount(tabLifetime.signal)
+    expect(rebound.getSnapshot().byTab[TAB]).toEqual(saved)
+    h.face.restore(TAB)
+    expect(h.iframe().src).toBe('https://saved.example/')
+    h.face.restore(TAB)
+    h.face.loadUrl(TAB, 'https://next.example/')
+    expect(rebound.getSnapshot().byTab[TAB]?.entries.at(-1)?.url).toBe('https://next.example/')
+    expect(h.store.getSnapshot().byTab[TAB]).toEqual(saved)
+    tabLifetime.abort()
+    expect(rebound.getSnapshot().byTab[TAB]).toBeDefined()
+    h.face.restore(TAB)
+    h.face.setSandbox(TAB, false)
+    h.mount(tabLifetime.signal)()
+    expect(h.face.keyedHooks.browserState(TAB)).toBeUndefined()
+  })
+
+  it('refresh restores a saved page and ignores cancellation from a retired physical mount', () => {
+    const h = harness()
+    h.store.actions.replace(TAB, browserAddressCheckpoint({ kind: 'https', url: 'https://saved.example/', title: 'Saved' }, 1))
+    const tabLifetime = lifetime()
+    const oldMount = h.mount(tabLifetime.signal)
+    h.face.reload(TAB)
+    const secondHost = document.createElement('div')
+    secondHost.id = 'replacement-browser-host'
+    document.body.append(secondHost)
+    hosts.push(secondHost)
+    h.face.mount({ tabId: TAB, signal: tabLifetime.signal, viewportId: secondHost.id,
+      applicationOrigin: APP, initial: undefined, initialUrl: undefined, openTab: vi.fn() })
+    oldMount()
+    expect(secondHost.querySelector('iframe')?.src).toBe('https://saved.example/')
+    expect(() => h.face.mount({ tabId: TAB, signal: tabLifetime.signal, viewportId: 'missing-browser-host',
+      applicationOrigin: APP, initial: undefined, initialUrl: undefined, openTab: vi.fn() })).toThrow('not mounted')
+  })
+
+  it('validates provider open requests and ignores late provider callbacks after disposal', async () => {
+    const saved = browserAddressCheckpoint({ kind: 'https', url: 'https://saved.example/', title: 'Saved' }, 1)
+    const frames = createSnapshotStore<BrowserFrameState>(emptyBrowserFrame())
+    const callbacks: BrowserPageOptions[] = []
+    const pendingNotifications: (() => void)[] = []
+    const pageFactory: BrowserPageFactory = (options) => {
+      callbacks.push(options)
+      return {
+        frame: { getSnapshot: () => frames.getSnapshot(), subscribe: (listener) => {
+          pendingNotifications.push(listener)
+          return frames.subscribe(listener)
+        }, loadUrl: vi.fn(), goBack: vi.fn(), goForward: vi.fn(), reload: vi.fn(), dispose: async () => {} },
+        presentation: { mount: () => () => {}, dispose: () => {} },
+      }
+    }
+    const store = createBrowserStore().create('provider-callbacks')
+    const openTab = vi.fn()
+    const controller = new BrowserController({ tabId: TAB, signal: lifetime().signal, applicationOrigin: APP,
+      actions: store.actions, initial: saved, createPage: pageFactory, openTab })
+    disposables.push(controller)
+    const provider = callbacks[0]!
+    provider.openRequested('file:/secret')
+    expect(controller.getSnapshot().addressFailure).toBe('protocol')
+    provider.openRequested('https://new.example/path')
+    expect(openTab).toHaveBeenCalledExactlyOnceWith('https://new.example/path')
+    controller.setSandbox(false)
+    frames.set({ ...emptyBrowserFrame(), loading: true })
+    expect(controller.getSnapshot().restoreTarget?.title).toBe('Saved')
+    expect(controller.getSnapshot().addressFailure).toBe('protocol')
+    const before = controller.getSnapshot()
+    await controller.dispose()
+    controller.start('https://ignored.example/')
+    provider.persist(saved)
+    provider.openRequested('https://ignored.example/')
+    for (const notify of pendingNotifications) notify()
+    expect(controller.getSnapshot()).toBe(before)
+    expect(store.getSnapshot().byTab[TAB]).toBeUndefined()
+    expect(openTab).toHaveBeenCalledOnce()
+  })
+
+  it('ignores navigation commands after its tab occurrence ends', async () => {
     const store = createBrowserStore().create('browser-controller-ended-test')
     const tabLifetime = lifetime()
     const controller = new BrowserController({
       tabId: TAB, signal: tabLifetime.signal, applicationOrigin: APP, actions: store.actions,
+      initial: undefined, createPage: createIframePage, openTab: vi.fn(),
     })
+    disposables.push(controller)
     tabLifetime.abort()
+    await controller.dispose()
 
     controller.loadUrl('https://ignored.example/')
     controller.goBack()
     controller.goForward()
     controller.reload()
-    controller.frame.reportLoaded(1)
+    expect(controller.getSnapshot().frame.target).toBeUndefined()
     expect(store.getSnapshot().byTab[TAB]).toBeUndefined()
   })
 
   it('owns the four navigation commands and frame load state', () => {
-    const store = createBrowserStore().create('browser-controller-test')
-    const face = createBrowserControllers(store.actions)
+    const { store, face, mount, iframe, close } = harness()
     const tabLifetime = lifetime()
-    face.mount(TAB, tabLifetime.signal, APP)
-    const frame = face.keyedHooks.browserFrame(TAB)!
-    face.mount(TAB, tabLifetime.signal, APP)
-    expect(face.keyedHooks.browserFrame(TAB)).toBe(frame)
+    mount(tabLifetime.signal)
+    const state = face.keyedHooks.browserState(TAB)!
+    mount(tabLifetime.signal)
+    expect(face.keyedHooks.browserState(TAB)).toBe(state)
     face.goBack(TAB)
     face.goForward(TAB)
     face.reload(TAB)
 
     face.loadUrl(TAB, 'https://example.test/one')
-    const first = frame.getSnapshot().document!
+    const first = iframe()
     expect(first.src).toBe('https://example.test/one')
-    face.reportLoaded(TAB, first.revision - 1)
-    face.reportLoaded(TAB, first.revision)
+    first.dispatchEvent(new Event('load'))
     expect(store.getSnapshot().byTab[TAB]?.navigation.status).toBe('known')
-    face.reportLoaded(TAB, first.revision)
+    first.dispatchEvent(new Event('load'))
     expect(store.getSnapshot().byTab[TAB]?.navigation.status).toBe('unknown')
     face.goBack(TAB)
     face.goForward(TAB)
@@ -64,79 +182,86 @@ describe('BrowserController', () => {
 
     face.loadUrl(TAB, 'https://example.test/two')
     face.goBack(TAB)
-    expect(frame.getSnapshot().document?.target.url).toBe('https://example.test/one')
+    expect(state.getSnapshot().frame.target?.url).toBe('https://example.test/one')
     face.goForward(TAB)
-    expect(frame.getSnapshot().document?.target.url).toBe('https://example.test/two')
+    expect(state.getSnapshot().frame.target?.url).toBe('https://example.test/two')
     const beforeReload = store.getSnapshot().byTab[TAB]!.request!.revision
     face.reload(TAB)
     expect(store.getSnapshot().byTab[TAB]?.request?.revision).toBe(beforeReload + 1)
     face.loadUrl(TAB, 'https://example.test/two')
     expect(store.getSnapshot().byTab[TAB]?.request?.revision).toBe(beforeReload + 2)
 
+    close()
     tabLifetime.abort()
     expect(store.getSnapshot().byTab[TAB]).toBeUndefined()
-    face.reportLoaded(TAB, first.revision)
+    first.dispatchEvent(new Event('load'))
     face.loadUrl(TAB, 'https://ignored.example/')
     face.goBack(TAB)
     face.goForward(TAB)
     face.reload(TAB)
+    expect(store.getSnapshot().byTab[TAB]).toBeUndefined()
+    expect(face.keyedHooks.browserState(TAB)).toBeUndefined()
   })
 
   it('does not let an old occurrence delete a replacement controller', () => {
-    const store = createBrowserStore().create('browser-controller-replacement-test')
-    const face = createBrowserControllers(store.actions)
+    const { store, face, mount } = harness()
     const first = lifetime()
     const second = lifetime()
-    face.mount(TAB, first.signal, APP)
-    const original = face.keyedHooks.browserFrame(TAB)
-    face.mount(TAB, second.signal, APP)
-    const replacement = face.keyedHooks.browserFrame(TAB)
+    mount(first.signal)
+    const original = face.keyedHooks.browserState(TAB)
+    mount(second.signal)
+    const replacement = face.keyedHooks.browserState(TAB)
     expect(replacement).not.toBe(original)
     first.abort()
     expect(store.getSnapshot().byTab[TAB]).toBeUndefined()
     face.loadUrl(TAB, 'https://example.test/')
     expect(store.getSnapshot().byTab[TAB]).toBeDefined()
-    face.mount(TAB, second.signal, APP)
-    expect(face.keyedHooks.browserFrame(TAB)).toBe(replacement)
+    mount(second.signal)
+    expect(face.keyedHooks.browserState(TAB)).toBe(replacement)
   })
 
   it('loads loopback under sandbox and reloads it across sandbox changes', () => {
-    const store = createBrowserStore().create('browser-controller-loopback-test')
-    const face = createBrowserControllers(store.actions)
+    const { store, face, mount, iframe } = harness()
     const tabLifetime = lifetime()
-    face.mount(TAB, tabLifetime.signal, APP)
-    const frame = face.keyedHooks.browserFrame(TAB)!
+    mount(tabLifetime.signal)
+    const state = face.keyedHooks.browserState(TAB)!
 
     face.loadUrl(TAB, 'http://localhost:5173/app')
-    expect(frame.getSnapshot()).toMatchObject({
-      sandboxed: true,
-      document: { src: 'http://localhost:5173/app' },
+    expect(state.getSnapshot().frame).toMatchObject({
+      sandboxEnabled: true,
+      target: { url: 'http://localhost:5173/app' },
     })
     const beforeToggle = store.getSnapshot().byTab[TAB]!.request!.revision
 
-    face.toggleSandbox(TAB)
-    expect(frame.getSnapshot().sandboxed).toBe(false)
-    expect(frame.getSnapshot().document?.src).toBe('http://localhost:5173/app')
+    face.setSandbox(TAB, false)
+    expect(state.getSnapshot().frame.sandboxEnabled).toBe(false)
+    expect(iframe().src).toBe('http://localhost:5173/app')
     expect(store.getSnapshot().byTab[TAB]?.request?.revision).toBe(beforeToggle + 1)
 
-    face.toggleSandbox(TAB)
-    expect(frame.getSnapshot()).toMatchObject({
-      sandboxed: true,
-      document: { src: 'http://localhost:5173/app' },
+    face.setSandbox(TAB, true)
+    expect(state.getSnapshot().frame).toMatchObject({
+      sandboxEnabled: true,
+      target: { url: 'http://localhost:5173/app' },
     })
     expect(store.getSnapshot().byTab[TAB]?.request?.revision).toBe(beforeToggle + 2)
   })
 
   it('loads public HTTP without changing the sandbox policy', () => {
-    const store = createBrowserStore().create('browser-controller-http-test')
-    const face = createBrowserControllers(store.actions)
+    const { face, mount } = harness()
     const tabLifetime = lifetime()
-    face.mount(TAB, tabLifetime.signal, APP)
+    mount(tabLifetime.signal)
 
     face.loadUrl(TAB, 'http://example.test/path')
-    expect(face.keyedHooks.browserFrame(TAB)?.getSnapshot()).toMatchObject({
-      sandboxed: true,
-      document: { src: 'http://example.test/path' },
+    const state = face.keyedHooks.browserState(TAB)!
+    expect(state.getSnapshot().frame).toMatchObject({
+      sandboxEnabled: true,
+      target: { url: 'http://example.test/path' },
     })
+    const beforeFailure = state.getSnapshot().frame
+    face.loadUrl(TAB, 'javascript:alert(1)')
+    expect(state.getSnapshot().addressFailure).toBe('protocol')
+    expect(state.getSnapshot().frame).toBe(beforeFailure)
+    face.reload(TAB)
+    expect(state.getSnapshot().addressFailure).toBeUndefined()
   })
 })
diff --git a/packages/client/ui-sidebar-browser/tests/browser-frame.client.spec.ts b/packages/client/ui-sidebar-browser/tests/browser-frame.client.spec.ts
index 5660e586c0..8ef82c7665 100644
--- a/packages/client/ui-sidebar-browser/tests/browser-frame.client.spec.ts
+++ b/packages/client/ui-sidebar-browser/tests/browser-frame.client.spec.ts
@@ -1,41 +1,58 @@
-import { describe, expect, it, vi } from 'vitest'
-import { IframeImpl } from '../src/client/browser/BrowserFrame.ts'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { IframeImpl } from '../src/client/browser/IframeImpl.ts'
+import { IframePresentation } from '../src/client/view/IframePresentation.ts'
+
+const frames: IframeImpl[] = []
+
+afterEach(async () => {
+  await Promise.all(frames.splice(0).map(frame => frame.dispose()))
+})
 
 describe('IframeImpl', () => {
-  it('owns transient sandbox mode and prepared document state', () => {
-    const changed = vi.fn<(sandboxed: boolean) => void>()
-    const loaded = vi.fn<(revision: number) => void>()
-    const frame = new IframeImpl(changed, loaded)
+  it('owns transient sandbox mode and revision-scoped load state', async () => {
+    const persist = vi.fn()
+    const presentation = new IframePresentation({ loaded: vi.fn(), failed: vi.fn(), remounted: vi.fn() })
+    const frame = new IframeImpl({ initial: undefined, persist, openRequested: vi.fn() }, presentation)
+    frames.push(frame)
     const listener = vi.fn()
     const unsubscribe = frame.subscribe(listener)
+    try {
+      frame.handleLoaded(0)
+      expect(frame.getSnapshot().address).toBe('empty')
+      frame.sandbox.setEnabled(false)
+      frame.sandbox.setEnabled(false)
+      expect(frame.getSnapshot().sandboxEnabled).toBe(false)
+      expect(frame.getSnapshot().target).toBeUndefined()
 
-    frame.toggleSandbox()
-    expect(frame.getSnapshot().sandboxed).toBe(false)
-    expect(changed).toHaveBeenCalledWith(false)
+      const target = { kind: 'https' as const, url: 'https://example.test/', title: 'example.test' }
+      frame.handleLoadFailed(1)
+      expect(frame.getSnapshot().error).toBeUndefined()
+      frame.loadUrl(target)
+      frame.handleLoadFailed(0)
+      expect(frame.getSnapshot().error).toBeUndefined()
+      frame.handleLoadFailed(1)
+      frame.handleLoadFailed(1)
+      expect(frame.getSnapshot()).toMatchObject({ target, error: { code: undefined, description: undefined }, loading: false })
+      frame.handleLoaded(1)
+      expect(persist).toHaveBeenLastCalledWith(expect.objectContaining({ navigation: { status: 'known', revision: 1 } }))
+      frame.reload()
+      expect(frame.getSnapshot()).toMatchObject({ target, error: undefined, loading: true })
+      frame.handleLoadFailed(1)
+      expect(frame.getSnapshot().error).toBeUndefined()
+      expect(listener).toHaveBeenCalled()
 
-    const document = {
-      target: { kind: 'https' as const, url: 'https://example.test/', title: 'example.test' },
-      src: 'https://example.test/',
-      revision: 4,
+      await frame.dispose()
+      const stopped = frame.getSnapshot()
+      frame.handleLoadFailed(2)
+      frame.handleLoaded(2)
+      frame.reload()
+      frame.loadUrl(target)
+      frame.goBack()
+      frame.goForward()
+      frame.sandbox.setEnabled(true)
+      expect(frame.getSnapshot()).toBe(stopped)
+    } finally {
+      unsubscribe()
     }
-    frame.reportLoadFailed(4)
-    expect(frame.getSnapshot().loadFailed).toBe(false)
-    frame.setDocument(document)
-    frame.reportLoadFailed(3)
-    expect(frame.getSnapshot().loadFailed).toBe(false)
-    frame.reportLoadFailed(4)
-    frame.reportLoadFailed(4)
-    expect(frame.getSnapshot().loadFailed).toBe(true)
-    frame.reportLoaded(4)
-    expect(loaded).toHaveBeenCalledWith(4)
-    frame.setDocument({ ...document, revision: 5 })
-    expect(frame.getSnapshot().loadFailed).toBe(false)
-    frame.clearDocument()
-    expect(frame.getSnapshot().document).toBeUndefined()
-    frame.reportLoadFailed(5)
-    expect(frame.getSnapshot().loadFailed).toBe(false)
-    frame.clearDocument()
-    expect(listener).toHaveBeenCalled()
-    unsubscribe()
   })
 })
diff --git a/packages/client/ui-sidebar-browser/tests/browser-navigation.client.spec.ts b/packages/client/ui-sidebar-browser/tests/browser-navigation.client.spec.ts
index cce1f9a0a1..d6d2b36762 100644
--- a/packages/client/ui-sidebar-browser/tests/browser-navigation.client.spec.ts
+++ b/packages/client/ui-sidebar-browser/tests/browser-navigation.client.spec.ts
@@ -51,19 +51,14 @@ describe('BrowserNavigation', () => {
     expect(navigation.snapshot.navigation).toEqual({ status: 'loading', revision: reload.revision })
   })
 
-  it('leaves address failures outside navigation', () => {
+  it('ignores frame observations before a controlled request', () => {
     const navigation = new BrowserNavigation()
     navigation.frameLoaded(1)
+    expect(navigation.snapshot).toEqual(BrowserNavigation.empty())
     navigation.navigate(httpsTarget(1))
     const revision = navigation.snapshot.request!.revision
     expect(navigation.snapshot.failure).toBeUndefined()
     navigation.frameLoaded(revision)
     expect(navigation.snapshot.navigation).toEqual({ status: 'known', revision })
-
-    navigation.addressFailed('invalid')
-    expect(navigation.snapshot).toMatchObject({
-      navigation: { status: 'known', revision },
-      failure: { kind: 'address', reason: 'invalid' },
-    })
   })
 })
diff --git a/packages/client/ui-sidebar-browser/tests/electron-frame.client.spec.ts b/packages/client/ui-sidebar-browser/tests/electron-frame.client.spec.ts
new file mode 100644
index 0000000000..20480c615b
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tests/electron-frame.client.spec.ts
@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+import { expect, it, vi } from 'vitest'
+import { ElectronWebViewImpl } from '../src/client/electron/ElectronWebViewImpl.ts'
+import { ElectronWebviewPresentation, type WebviewElement } from '../src/client/electron/ElectronWebviewPresentation.ts'
+import type { DesktopBrowserBridge, DesktopBrowserLeaseId } from '../src/types.ts'
+
+it('clears a failed load when the main page retries without a toolbar command', async () => {
+  let url = 'about:blank'
+  let loading = true
+  const element: WebviewElement = Object.assign(document.createElement('div'), {
+    loadURL: vi.fn(async () => {}), getURL: () => url, getTitle: () => 'Recovered',
+    canGoBack: () => false, canGoForward: () => false, clearHistory: vi.fn(),
+    goBack: vi.fn(), goForward: vi.fn(), reload: vi.fn(), isLoading: () => loading,
+  })
+  const bridge: DesktopBrowserBridge = {
+    acquire: vi.fn(async () => ({ lease: 'lease' as DesktopBrowserLeaseId, partition: 'partition' })),
+    release: vi.fn(async () => {}), onOpenRequested: () => () => {},
+  }
+  const presentation = new ElectronWebviewPresentation({ mounted: () =>{  frame.attach() }, unmounted: () =>{  frame.detach() } })
+  const frame = new ElectronWebViewImpl({ initial: undefined, persist: vi.fn(), openRequested: vi.fn() },
+    bridge, async () => 'cwd:/workspace', presentation)
+  const createElement = vi.spyOn(presentation, 'createElement').mockReturnValue(element)
+  const host = document.createElement('div')
+  host.id = 'electron-frame-retry'
+  document.body.append(host)
+  try {
+    presentation.mount(host.id)
+    frame.loadUrl({ kind: 'https', url: 'https://example.test/', title: 'Example' })
+    await vi.waitFor(() => { expect(host.firstElementChild).toBe(element) })
+    element.dispatchEvent(new Event('dom-ready'))
+    element.dispatchEvent(Object.assign(new Event('did-fail-load'), {
+      isMainFrame: true, errorCode: -105, errorDescription: 'ERR_NAME_NOT_RESOLVED',
+    }))
+    expect(frame.getSnapshot().error?.code).toBe(-105)
+    element.dispatchEvent(new Event('page-title-updated'))
+    element.dispatchEvent(Object.assign(new Event('did-start-navigation'), { isMainFrame: false }))
+    expect(frame.getSnapshot().error?.code).toBe(-105)
+
+    element.dispatchEvent(Object.assign(new Event('did-start-navigation'), { isMainFrame: true }))
+    expect(frame.getSnapshot()).toMatchObject({ error: undefined, loading: true })
+    url = 'https://example.test/recovered'
+    element.dispatchEvent(new Event('did-navigate'))
+    loading = false
+    element.dispatchEvent(new Event('did-stop-loading'))
+    expect(frame.getSnapshot()).toMatchObject({ error: undefined, loading: false, target: { url, title: 'Recovered' } })
+  } finally {
+    await frame.dispose()
+    createElement.mockRestore()
+    host.remove()
+  }
+})
diff --git a/packages/client/ui-sidebar-browser/tests/electron-harness.client.ts b/packages/client/ui-sidebar-browser/tests/electron-harness.client.ts
new file mode 100644
index 0000000000..bebfb96c53
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tests/electron-harness.client.ts
@@ -0,0 +1,66 @@
+/** Native webview events controlled by each test; presentation and navigation stay real. */
+import { vi } from 'vitest'
+import type { DesktopBrowserBridge, DesktopBrowserLeaseId, DesktopBrowserReservation } from '../src/types.ts'
+import type { BrowserTabState } from '../src/client/browser/BrowserPersistence.ts'
+import { createElectronPage } from '../src/client/electron/pages.ts'
+import { ElectronWebviewPresentation } from '../src/client/electron/ElectronWebviewPresentation.ts'
+
+let sequence = 0
+
+/** @returns one isolated, explicitly mounted page with native operations replaced by spies. */
+export function electronFixture(initial?: BrowserTabState) {
+  const opens = new Set<(url: string) => void>()
+  const reservation: DesktopBrowserReservation = { lease: `lease-${++sequence}` as DesktopBrowserLeaseId, partition: 'partition' }
+  const bridge = {
+    acquire: vi.fn(async (_workspace: string) => reservation),
+    release: vi.fn(async (_lease: DesktopBrowserLeaseId) => {}),
+    onOpenRequested: vi.fn((_lease: DesktopBrowserLeaseId, listener: (url: string) => void) => {
+      opens.add(listener)
+      return () => { opens.delete(listener) }
+    }),
+  } satisfies DesktopBrowserBridge
+  const workspace = vi.fn(async (_signal: AbortSignal) => 'cwd:/workspace')
+  const persist = vi.fn()
+  const openRequested = vi.fn()
+  const page = createElectronPage({ initial, persist, openRequested }, bridge, workspace)
+  const presentation = page.presentation
+  if (!(presentation instanceof ElectronWebviewPresentation)) throw new Error('expected the Electron presentation')
+  const create = presentation.createElement.bind(presentation)
+  const guests: ReturnType<typeof prepareGuest>[] = []
+  function prepareGuest(approved: DesktopBrowserReservation) {
+    const element = create(approved)
+    const state = { url: 'about:blank', title: '', loading: true, back: false, forward: false }
+    const methods = {
+      loadURL: vi.fn(async (_url: string) => {}), getURL: vi.fn(() => state.url), getTitle: vi.fn(() => state.title),
+      canGoBack: () => state.back, canGoForward: () => state.forward, clearHistory: vi.fn(),
+      goBack: vi.fn(), goForward: vi.fn(), reload: vi.fn(), isLoading: () => state.loading,
+    }
+    Object.assign(element, methods)
+    const emit = (type: string, fields: object = {}): void => { element.dispatchEvent(Object.assign(new Event(type), fields)) }
+    return { element, state, emit, ...methods }
+  }
+  const createElement = vi.spyOn(presentation, 'createElement').mockImplementation((approved) => {
+    const guest = prepareGuest(approved)
+    guests.push(guest)
+    return guest.element
+  })
+  const host = document.createElement('div')
+  host.id = `electron-fixture-${sequence}`
+  document.body.append(host)
+  return {
+    ...page, presentation, bridge, workspace, persist, openRequested, opens, guests, host, reservation,
+    mount: () => presentation.mount(host.id),
+    async guest() {
+      await vi.waitFor(() => { expectGuest() })
+      return guests.at(-1)!
+    },
+    async dispose() {
+      await page.frame.dispose()
+      createElement.mockRestore()
+      host.remove()
+    },
+  }
+  function expectGuest(): void {
+    if (host.firstElementChild === null || guests.length === 0) throw new Error('guest has not attached')
+  }
+}
diff --git a/packages/client/ui-sidebar-browser/tests/electron-lifecycle.client.spec.ts b/packages/client/ui-sidebar-browser/tests/electron-lifecycle.client.spec.ts
new file mode 100644
index 0000000000..ef14e6de07
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tests/electron-lifecycle.client.spec.ts
@@ -0,0 +1,179 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest'
+import type { DesktopBrowserReservation } from '../src/types.ts'
+import { electronFixture } from './electron-harness.client.ts'
+
+const target = { kind: 'https' as const, url: 'https://example.test/', title: 'Example' }
+const fixtures: ReturnType<typeof electronFixture>[] = []
+function fixture() {
+  const h = electronFixture()
+  fixtures.push(h)
+  return h
+}
+afterEach(async () => {
+  for (const h of fixtures.splice(0)) await h.dispose()
+  vi.restoreAllMocks()
+})
+
+it('waits for a mounted container and observes native history, titles and new-tab requests', async () => {
+  const h = fixture()
+  h.frame.goBack()
+  h.frame.goForward()
+  h.frame.reload()
+  h.frame.loadUrl(target)
+  expect(h.bridge.acquire).not.toHaveBeenCalled()
+  h.mount()
+  const guest = await h.guest()
+  expect(guest.element.getAttribute('partition')).toBe(h.reservation.partition)
+  expect(guest.element.getAttribute('src')).toBe(`about:blank#${h.reservation.lease}`)
+  guest.emit('dom-ready')
+  expect(guest.loadURL).toHaveBeenCalledWith(target.url)
+  guest.state.url = target.url
+  guest.state.title = 'Title'
+  guest.state.back = true
+  guest.state.forward = true
+  guest.emit('did-navigate')
+  expect(guest.clearHistory).toHaveBeenCalledOnce()
+  expect(h.frame.getSnapshot()).toMatchObject({ address: 'observed', target: { ...target, title: 'Title' } })
+  expect(guest.element.getAttribute('aria-label')).toBe('Title')
+  const writes = h.persist.mock.calls.length
+  guest.emit('page-title-updated')
+  expect(h.persist).toHaveBeenCalledTimes(writes)
+  h.frame.loadUrl(target)
+  h.frame.goBack()
+  h.frame.goForward()
+  expect(guest.reload).toHaveBeenCalledOnce()
+  expect(guest.goBack).toHaveBeenCalledOnce()
+  expect(guest.goForward).toHaveBeenCalledOnce()
+  guest.state.url = `${target.url}next`
+  guest.emit('did-navigate-in-page', { isMainFrame: false })
+  expect(h.frame.getSnapshot().target?.url).toBe(target.url)
+  guest.emit('did-navigate-in-page', { isMainFrame: true })
+  guest.state.title = ''
+  guest.state.loading = false
+  guest.emit('page-title-updated')
+  guest.emit('did-stop-loading')
+  expect(h.frame.getSnapshot()).toMatchObject({ loading: false, target: { url: guest.state.url, title: 'example.test' } })
+  const open = h.bridge.onOpenRequested.mock.calls[0]![1]
+  open('https://new.example/')
+  expect(h.openRequested).toHaveBeenCalledOnce()
+  await h.frame.dispose()
+  open('https://late.example/')
+  guest.emit('did-navigate')
+  h.frame.loadUrl(target)
+  h.frame.reload()
+  h.frame.goBack()
+  expect(h.openRequested).toHaveBeenCalledOnce()
+  expect(h.opens.size).toBe(0)
+  expect(h.bridge.release).toHaveBeenCalledExactlyOnceWith(h.reservation.lease)
+})
+
+it('releases an acquisition that finishes after attachment cancellation', async () => {
+  const h = fixture()
+  const pending = Promise.withResolvers<DesktopBrowserReservation>()
+  h.bridge.acquire.mockReturnValueOnce(pending.promise)
+  const unmount = h.mount()
+  h.frame.loadUrl(target)
+  try {
+    await vi.waitFor(() => { expect(h.bridge.acquire).toHaveBeenCalledOnce() })
+    unmount()
+    const disposed = h.frame.dispose()
+    expect(h.frame.dispose()).toBe(disposed)
+    pending.resolve(h.reservation)
+    await disposed
+    expect(h.guests).toHaveLength(0)
+    expect(h.bridge.release).toHaveBeenCalledExactlyOnceWith(h.reservation.lease)
+  } finally {
+    pending.resolve(h.reservation)
+  }
+})
+
+it('does not acquire a guest when Workspace resolution finishes after disposal', async () => {
+  const h = fixture()
+  const pending = Promise.withResolvers<string>()
+  h.workspace.mockReturnValueOnce(pending.promise)
+  h.mount()
+  h.frame.loadUrl(target)
+  try {
+    const disposed = h.frame.dispose()
+    pending.resolve('cwd:/late')
+    await disposed
+    expect(h.bridge.acquire).not.toHaveBeenCalled()
+    h.mount()
+    expect(h.guests).toHaveLength(0)
+  } finally {
+    pending.resolve('cwd:/late')
+  }
+})
+
+it('recreates the guest after physical remount or crash without resolving Workspace again', async () => {
+  const h = fixture()
+  const unmount = h.mount()
+  h.frame.loadUrl(target)
+  const first = await h.guest()
+  first.emit('dom-ready')
+  unmount()
+  h.mount()
+  const second = await h.guest()
+  expect(second.element).not.toBe(first.element)
+  expect(h.workspace).toHaveBeenCalledOnce()
+  second.emit('dom-ready')
+  expect(second.loadURL).toHaveBeenCalledWith(target.url)
+  second.emit('render-process-gone')
+  expect(h.frame.getSnapshot().error).toBeDefined()
+  h.frame.reload()
+  const third = await h.guest()
+  third.emit('dom-ready')
+  expect(third.loadURL).toHaveBeenCalledWith(target.url)
+  expect(h.frame.getSnapshot().error).toBeUndefined()
+  third.emit('destroyed')
+  expect(h.frame.getSnapshot().error).toBeDefined()
+})
+
+it('contains acquisition, native command and release failures and keeps retry available', async () => {
+  const h = fixture()
+  const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+  h.bridge.acquire.mockRejectedValueOnce(new Error('acquire failed'))
+  h.mount()
+  h.frame.loadUrl(target)
+  await vi.waitFor(() => { expect(h.frame.getSnapshot().error).toBeDefined() })
+  h.frame.reload()
+  const guest = await h.guest()
+  guest.emit('dom-ready')
+  guest.state.url = target.url
+  guest.emit('did-navigate')
+  guest.reload.mockImplementationOnce(() => { throw new Error('command failed') })
+  h.frame.reload()
+  expect(h.frame.getSnapshot().error).toBeDefined()
+  h.frame.reload()
+  expect(h.frame.getSnapshot().error).toBeUndefined()
+  guest.getURL.mockImplementationOnce(() => { throw new Error('observation failed') })
+  guest.emit('did-navigate')
+  expect(h.frame.getSnapshot().error).toBeDefined()
+  h.bridge.release.mockRejectedValueOnce(new Error('release failed'))
+  await h.frame.dispose()
+  expect(error.mock.calls.some(call => call[0] === 'Desktop browser guest release failed')).toBe(true)
+})
+
+it('ignores superseded and aborted load promises, but publishes an active navigation rejection', async () => {
+  const h = fixture()
+  const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+  h.mount()
+  h.frame.loadUrl(target)
+  const guest = await h.guest()
+  const stale = Promise.withResolvers<undefined>()
+  guest.loadURL.mockReturnValueOnce(stale.promise)
+  guest.emit('dom-ready')
+  h.frame.loadUrl({ ...target, url: 'https://example.test/new' })
+  stale.reject(new Error('old navigation failed'))
+  await expect(stale.promise).rejects.toThrow('old navigation')
+  expect(h.frame.getSnapshot().error).toBeUndefined()
+  guest.loadURL.mockRejectedValueOnce(Object.assign(new Error('aborted'), { code: 'ERR_ABORTED' }))
+  h.frame.loadUrl({ ...target, url: 'https://example.test/cancelled' })
+  await Promise.resolve()
+  expect(h.frame.getSnapshot().error).toBeUndefined()
+  guest.loadURL.mockRejectedValueOnce(new Error('active navigation failed'))
+  h.frame.loadUrl(target)
+  await vi.waitFor(() => { expect(h.frame.getSnapshot().error).toBeDefined() })
+  expect(error).toHaveBeenCalledOnce()
+})
diff --git a/packages/client/ui-sidebar-browser/tests/workspace.client.spec.ts b/packages/client/ui-sidebar-browser/tests/workspace.client.spec.ts
new file mode 100644
index 0000000000..236e306ea9
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tests/workspace.client.spec.ts
@@ -0,0 +1,57 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import type { WorkspaceId, WorkspaceSnapshot, WorkspaceView } from '@deepseek-ai/dsh-api-workspace-controller/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { browserWorkspace } from '../src/client/electron/workspace.ts'
+
+const SESSION = 'session' as SessionId
+const workspace = (id: string, path: string, sessionIds: readonly SessionId[]): WorkspaceView => ({
+  workspaceId: id as WorkspaceId, path, title: path, sessionIds, createdAt: '', updatedAt: '',
+})
+const snapshot = (phase: WorkspaceSnapshot['phase'], items: readonly WorkspaceView[] = []): WorkspaceSnapshot => ({
+  phase, items, state: 'idle', error: null, archivedSessionIds: [], pinnedSessionIds: [],
+})
+
+afterEach(() => { vi.restoreAllMocks() })
+
+it('groups resolved Sessions by canonical CWD rather than Workspace identity', async () => {
+  const source = createSnapshotStore(snapshot('ready', [
+    workspace('other', '/other', ['other' as SessionId]), workspace('first', '/canonical', [SESSION]),
+  ]))
+  const signal = new AbortController().signal
+  await expect(browserWorkspace(source, SESSION, signal)).resolves.toBe('cwd:/canonical')
+  source.set(snapshot('ready', [workspace('renamed', '/canonical', [SESSION])]))
+  await expect(browserWorkspace(source, SESSION, signal)).resolves.toBe('cwd:/canonical')
+  await expect(browserWorkspace(source, 'unaccounted', signal)).resolves.toBe('session:unaccounted')
+})
+
+it('waits for an authoritative baseline and removes the readiness subscription', async () => {
+  const source = createSnapshotStore(snapshot('pending'))
+  const subscribe = source.subscribe.bind(source)
+  const stopped = vi.fn()
+  vi.spyOn(source, 'subscribe').mockImplementation((listener) => {
+    const stop = subscribe(listener)
+    return () => { stop(); stopped() }
+  })
+  const lifetime = new AbortController()
+  const result = browserWorkspace(source, SESSION, lifetime.signal)
+  source.set(snapshot('pending', [workspace('partial', '/partial', [SESSION])]))
+  expect(stopped).not.toHaveBeenCalled()
+  source.set(snapshot('ready', [workspace('ready', '/ready', [SESSION])]))
+  await expect(result).resolves.toBe('cwd:/ready')
+  expect(stopped).toHaveBeenCalledOnce()
+  lifetime.abort()
+  expect(stopped).toHaveBeenCalledOnce()
+})
+
+it('rejects cancellation before and during readiness without retaining a listener', async () => {
+  const source = createSnapshotStore(snapshot('pending'))
+  const lifetime = new AbortController()
+  const failure = new Error('tab closed')
+  const result = browserWorkspace(source, SESSION, lifetime.signal)
+  const rejected = expect(result).rejects.toBe(failure)
+  lifetime.abort(failure)
+  await rejected
+  source.set(snapshot('ready'))
+  await expect(browserWorkspace(source, SESSION, lifetime.signal)).rejects.toBe(failure)
+})
diff --git a/packages/client/ui-sidebar-browser/tsconfig.client.json b/packages/client/ui-sidebar-browser/tsconfig.client.json
new file mode 100644
index 0000000000..82b0c48f2c
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tsconfig.client.json
@@ -0,0 +1,26 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo"
+  },
+  "include": [
+    "src/client",
+    "src/types.ts",
+    "src/css-modules.d.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../api/workspace-controller/tsconfig.client.json" },
+    { "path": "../../util/brand" },
+    { "path": "../locale" },
+    { "path": "../store" },
+    { "path": "../ui-dockkit" },
+    { "path": "../ui-primitives" },
+    { "path": "../ui-renderer" },
+    { "path": "../ui-session" },
+    { "path": "../ui-sidebar-right" },
+    { "path": "../ui-slots" }
+  ]
+}
diff --git a/packages/client/ui-sidebar-browser/tsconfig.host.json b/packages/client/ui-sidebar-browser/tsconfig.host.json
new file mode 100644
index 0000000000..20cb732d2f
--- /dev/null
+++ b/packages/client/ui-sidebar-browser/tsconfig.host.json
@@ -0,0 +1,16 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo"
+  },
+  "files": [
+    "src/index.ts",
+    "src/types.ts"
+  ],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../util/brand" }
+  ]
+}
diff --git a/packages/client/ui-sidebar-browser/tsconfig.json b/packages/client/ui-sidebar-browser/tsconfig.json
index d9c72fa907..2a0b0e33f7 100644
--- a/packages/client/ui-sidebar-browser/tsconfig.json
+++ b/packages/client/ui-sidebar-browser/tsconfig.json
@@ -1,21 +1,7 @@
 {
-  "extends": "../../../tsconfig.base.client.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
+  "files": [],
   "references": [
-    { "path": "../../../vendor/cordis" },
-    { "path": "../locale" },
-    { "path": "../store" },
-    { "path": "../ui-dockkit" },
-    { "path": "../ui-primitives" },
-    { "path": "../ui-renderer" },
-    { "path": "../ui-session" },
-    { "path": "../ui-sidebar-right" },
-    { "path": "../ui-slots" }
+    { "path": "./tsconfig.host.json" },
+    { "path": "./tsconfig.client.json" }
   ]
 }
diff --git a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
index 6f0e375dcb..faad4651ee 100644
--- a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
+++ b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-documentpreview/README.md
-README.md: e7360434961ce480d2e97cb2ef41685b8cd8e14f
-README.zh.md: 7a60e3a94b931ed50e37214a9c2c63ed5ce6cbbb
+README.md: 79c7253887cd580bdcc725054c0bbf5b2877e90b
+README.zh.md: 77847e8ce7a9203a85fee360ec8a481e32e7e871
diff --git a/packages/client/ui-sidebar-documentpreview/README.md b/packages/client/ui-sidebar-documentpreview/README.md
index e736043496..79c7253887 100644
--- a/packages/client/ui-sidebar-documentpreview/README.md
+++ b/packages/client/ui-sidebar-documentpreview/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Preview files in the right Sidebar and choose among registered renderers. Markdown and code support paged text; PDF, HTML, and common images receive complete bytes; unknown extensions use plain text. Office documents convert locally to PDF. The tab provides file status, renderer selection, wrap, and automatic or manual reload. Plugins can add local opening controls to the header and unsupported-preview empty state.
+Preview files in the right Sidebar and choose among registered renderers. Markdown and code support paged text; PDF, HTML, and common images receive complete bytes; unknown extensions use plain text. Word and PowerPoint documents convert locally to PDF; Excel workbooks use the unsupported-preview state. The tab provides file status, renderer selection, wrap, and automatic or manual reload. Plugins can add local opening controls to the header and unsupported-preview empty state.
 
 ## Table of Contents
 
@@ -51,10 +51,10 @@ The body reads its record, navigation and lifetime through `useTabInfo().tab`. `
 
 - The resource snapshot contains only `status`, `value`, and `failure`; `value` is `WorkspaceFileStat` metadata. Content reads do not wait for the first metadata frame once the provider is available. Observation failures take precedence over Preview's change notice; loaded content remains while metadata is unavailable.
 - **Text pages** — plain text, Markdown, and code read through an inject callback to `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`. The first mount reads page one; scrolling to the body end or **Load more** requests the next page until `eof`. The owner delivers the accumulated prefix as `{ kind: 'text', text, pages, eof }`, including source offsets and line counts. Markdown and code render that prefix incrementally; they do not render each page as a separate document. A newer-version page past page one restarts from the beginning rather than mixing versions. A failure before any content fills the body with the file-type icon, the explanation, and the recourse the failure names (Retry, the unpreviewable child slot, or nothing); a later failure retains loaded content and adds the retry below it.
-- **Complete bytes** — PDF, HTML, and common images use an inject callback to `remote.workspaceFiles.readAll(sessionId, path, signal)`. `rpc.ts` decodes the wire base64 into `data: Uint8Array<ArrayBuffer>` for `{ kind: 'bytes', data }`. The Host's `maxFileBytes` cap rejects oversized files rather than truncating them. PDF copies retained bytes before worker transfer, keeping the Preview buffer usable. Bytes stay in transient view state, never persisted layouts or Session JSONL. Loading-mode changes retire previous results.
-- **Reload** — manual reload rereads only the current Preview tab through its Remote callbacks, preserving its scroll preference and retiring older requests. Automatic refresh uses the same callbacks after a ResourceGroup member changes. Each member's first metadata establishes a baseline without triggering reload or first-read version reconciliation; later changes received during a read remain pending for another refresh. Reads neither refresh shared metadata nor clear another tab's notice.
+- **Complete bytes** — PDF, HTML, and common images call `remote.workspaceFiles.readBytes(sessionId, path, {}, signal)`. The binary Remote returns `data: Uint8Array<ArrayBuffer>` directly for `{ kind: 'bytes', data }`. The Host's `maxFileBytes` cap rejects oversized files rather than truncating them. PDF copies retained bytes before worker transfer, keeping the Preview buffer usable. Bytes stay in transient view state, never persisted layouts or Session JSONL. Loading-mode changes retire previous results.
+- **Reload** — manual reload rereads only the current Preview tab through its Remote callbacks, preserving its scroll preference and retiring older requests. Automatic refresh uses the same callbacks after a `ResourceGroup` member changes. Each member's first metadata establishes a baseline without triggering reload or first-read version reconciliation; later changes received during a read remain pending for another refresh. Reads neither refresh shared metadata nor clear another tab's notice.
 
-When Developer tools is enabled, HTML fills the body edge to edge in a Blob iframe with exactly `sandbox="allow-scripts"`, without `allow-same-origin`; scripts cannot access the parent application's origin or file reader. The renderer loads directly declared relative `.js` classic scripts and `.css` stylesheets through its ordinary inject callback to `remote.workspaceFiles.readRelated`, with fixed safety limits of 4 MiB per asset, 32 MiB total, and 64 distinct assets. Host code resolves the related path; `rpc.ts` decodes the returned bytes. The dependency Resource is added after `readRelated` returns, using its `absolutePath` or a string `error.details.path` on failure; without a Host path, the Client does not guess one. Inside the renderer, base64 is used only to embed the iframe bootstrap payload in script text. A `<base href>` leaves dependency resolution to the browser, as do HTTPS resources. Local module imports, CSS `url()`/`@import`, and dynamic `fetch` do not use Host file access. Read failures, invalid UTF-8, or exceeded limits fail the preview rather than publishing a partial asset package. Replacing or unmounting the document releases its Blob URL.
+When Developer tools is enabled, HTML fills the body edge to edge in a Blob iframe with exactly `sandbox="allow-scripts"`, without `allow-same-origin`; scripts cannot access the parent application's origin or file reader. The renderer loads directly declared relative `.js` classic scripts and `.css` stylesheets through its injected Remote callback, with fixed safety limits of 4 MiB per asset, 32 MiB total, and 64 distinct assets. Host code resolves the related path, and `readBytes` with `baseFile` returns native bytes. The dependency Resource is added after the read returns, using its `absolutePath` or a string `error.details.path` on failure; without a Host path, the Client does not guess one. Inside the renderer, base64 is used only to embed the iframe bootstrap payload in script text. A `<base href>` leaves dependency resolution to the browser, as do HTTPS resources. Local module imports, CSS `url()`/`@import`, and dynamic `fetch` do not use Host file access. Read failures, invalid UTF-8, or exceeded limits fail the preview rather than publishing a partial asset package. Replacing or unmounting the document releases its Blob URL.
 
 PNG, JPEG, GIF, WebP, BMP, ICO, and SVG render through Blob URLs in an `<img>` static-image context, rounded inside a 12px inset. A wider image scales down to the pane's width at its intrinsic aspect ratio, a smaller image centres at its intrinsic CSS-pixel dimensions, and a taller image scrolls vertically. The renderer provides neither zoom nor drag-to-pan. SVG markup never enters the application DOM or an iframe, so its scripts cannot execute or reach the parent page. Replacing or unmounting the image revokes its Blob URL.
 
@@ -65,7 +65,7 @@ Initial reads, additional pages, and HTML/PDF/image preparation share the ongoin
 <a id="office-preview"></a>
 ## Office preview
 
-Open `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, and `.pptx` as PDF previews with the same loading state, controls, cancellation, and selectable text as PDF files. The [Host provider](../../document/office-to-pdf/README.md) performs local conversion; invalid files, conversion failures, and timeouts receive localized messages. Missing Host services show configuration guidance.
+Open `.doc`, `.docx`, `.ppt`, and `.pptx` as PDF previews with the same loading state, controls, cancellation, and selectable text as PDF files. `.xls` and `.xlsx` do not register a Sidebar renderer: they show the unsupported-preview message without requesting conversion and offer the system default application when the Host reports a desktop. The [Host provider](../../document/office-to-pdf/README.md) retains its spreadsheet conversion API for other consumers. Invalid supported files, conversion failures, and timeouts receive localized messages. Missing Host services show configuration guidance.
 
 The [Web bundle](../../bundle/web-app/README.md) mounts this package as `ui-sidebar-documentpreview`. Configure its transient Office cache through that entry's `office` settings; the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-client-ui-sidebar-documentpreview) defines accepted values. Settings are embedded in each served page; reload the browser page after changing YAML.
 
@@ -86,7 +86,7 @@ A yellow rounded-triangle warning appears before Reload in the document toolbar
 
 Office registration, loading, caching, and font notices live in `src/client/office/`. The Office body owns converted PDF bytes and font metadata, and declares a nested PDF slot that reuses the lazy PDF body and its tab viewing state. The keyed `sidebar.right.tab.document.action` slot places renderer controls before Reload. The Office action shares the body’s store and reads only the current revision’s font metadata. Registration remains available without the Host renderer; optional `remote.officeToPdf` and `remote.workspaceFiles` injections supply conversion and freshness callbacks, and their removal restores unavailable guidance. Registrations and tab retention follow effect lifetimes. The [conversion service](../../document/office-to-pdf/README.md) owns the Host Remote methods, mounted by `api/remotes`.
 
-The shared `documentFileBytes()` helper decodes ordinary file and converted PDF responses into one owned byte buffer without expanding bytes into JavaScript array elements. Renderers borrow retained bytes read-only and copy them before Worker transfer.
+The `documentFileBytes()` helper decodes converted Office PDF responses into one owned byte buffer without expanding bytes into JavaScript array elements. Renderers borrow retained bytes read-only and copy them before Worker transfer.
 
 </details>
 
@@ -108,7 +108,7 @@ No direct effect; what the user reads here never enters a model request.
 
 <a id="known-limitations-and-deferred-work"></a>
 - **Preview, not editing.** The viewers provide no file editing or shared search interface; a directory address fails with `not-regular-file`. Unknown extensions use the plain-text reader and remain subject to its UTF-8/NUL checks.
-- **Office conversion limits.** The preview does not launch native Office editors or download an engine. Binary `.doc`, `.xls`, and `.ppt` files return no missing-font diagnostics. Conversion fidelity and resource limits belong to the [LibreOffice provider](../../document/office-to-pdf/README.md).
+- **Office conversion limits.** The preview does not launch native Office editors or download an engine. Excel workbooks are not previewed and instead offer the system default application on desktop Hosts. Binary `.doc` and `.ppt` files return no missing-font diagnostics. Conversion fidelity and resource limits belong to the [LibreOffice provider](../../document/office-to-pdf/README.md).
 - **Sequential text and bounded complete files.** Deep source lines require the preceding pages; PDF, HTML, and images require a complete result within the Host's `maxFileBytes` cap.
 - **Byte-view scroll state is not restored.** PDF, HTML, and images can return to the top when their renderer remounts or reloads; images fit the pane's width and never scroll horizontally, and HTML iframe scrolling belongs to its opaque browsing context.
 - **Finite local HTML dependencies.** Only direct classic `.js` and stylesheet `.css` references are packed. Browser-resolved resources retain browser origin and network restrictions; no runtime file-read bridge is exposed to the iframe.
diff --git a/packages/client/ui-sidebar-documentpreview/README.zh.md b/packages/client/ui-sidebar-documentpreview/README.zh.md
index 7a60e3a94b..77847e8ce7 100644
--- a/packages/client/ui-sidebar-documentpreview/README.zh.md
+++ b/packages/client/ui-sidebar-documentpreview/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-在右侧 Sidebar 预览文件，并切换已注册的渲染器。Markdown 和代码支持分页文本；PDF、HTML 和常见图片接收完整字节；未知扩展名使用纯文本。Office 文档在本地转换为 PDF。tab 提供文件状态、渲染器选择、换行以及自动或手动重新载入。插件可在头部和不支持预览的空态中添加本地打开控件。
+在右侧 Sidebar 预览文件，并切换已注册的渲染器。Markdown 和代码支持分页文本；PDF、HTML 和常见图片接收完整字节；未知扩展名使用纯文本。Word 与 PowerPoint 文档在本地转换为 PDF；Excel 工作簿使用不支持预览的空态。tab 提供文件状态、渲染器选择、换行以及自动或手动重新载入。插件可在头部和不支持预览的空态中添加本地打开控件。
 
 ## 目录
 
@@ -51,10 +51,10 @@ Web 和桌面端均通过开发者工具选择 HTML 预览策略。渲染器从
 
 - 资源快照仅包含 `status`、`value` 和 `failure`；`value` 是 `WorkspaceFileStat` 元数据。提供方可用后，内容读取无需等待首个元数据帧。观察失败优先于 Preview 的变更提示显示；元数据不可用时保留已加载内容。
 - **文本页** —— 纯文本、Markdown 和代码通过 inject 回调调用 `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`。首次挂载读取第一页；滚动到正文末尾或点击 **加载更多** 会读取下一页，直到 `eof`。owner 以 `{ kind: 'text', text, pages, eof }` 提供累计前缀，包含源码偏移和行数。Markdown 和代码增量渲染此前缀，不把每页当成独立文档。第一页之后到达的更新版本页会使读取从头开始，避免混合版本。尚无内容时，失败会以文件类型图标、说明和该失败对应的出路（重试、unpreviewable 子 slot，或什么都不给）填满正文；较晚的失败保留已有内容并在其下提供重试。
-- **完整字节** —— PDF、HTML 和常见图片通过 inject 回调调用 `remote.workspaceFiles.readAll(sessionId, path, signal)`。`rpc.ts` 将线路上的 base64 解码为 `data: Uint8Array<ArrayBuffer>`，供 `{ kind: 'bytes', data }` 使用。Host 的 `maxFileBytes` 上限拒绝超大文件，不截断。PDF 在传给 worker 前复制保留的字节，使 Preview 缓冲区仍可使用。字节仅保存在临时视图状态中，绝不进入持久布局或 Session JSONL。加载模式变化会淘汰先前结果。
-- **重新载入** —— 手动重新载入仅让当前 Preview tab 通过自己的 Remote 回调重读，保留滚动偏好并淘汰旧请求。ResourceGroup 成员变化后，自动刷新使用相同回调。各成员首次元数据仅建立基线，不触发重新载入或首读版本对账；后续在读取期间收到的变化仍会留待下一次刷新。读取既不刷新共享元数据，也不清除其它 tab 的提示。
+- **完整字节** —— PDF、HTML 和常见图片调用 `remote.workspaceFiles.readBytes(sessionId, path, {}, signal)`。二进制 Remote 直接返回 `data: Uint8Array<ArrayBuffer>`，供 `{ kind: 'bytes', data }` 使用。Host 的 `maxFileBytes` 上限拒绝超大文件，不截断。PDF 在传给 worker 前复制保留的字节，使 Preview 缓冲区仍可使用。字节仅保存在临时视图状态中，绝不进入持久布局或 Session JSONL。加载模式变化会淘汰先前结果。
+- **重新载入** —— 手动重新载入仅让当前 Preview tab 通过自己的 Remote 回调重读，保留滚动偏好并淘汰旧请求。`ResourceGroup` 成员变化后，自动刷新使用相同回调。各成员首次元数据仅建立基线，不触发重新载入或首读版本对账；后续在读取期间收到的变化仍会留待下一次刷新。读取既不刷新共享元数据，也不清除其它 tab 的提示。
 
-开启开发者工具时，HTML 以贴合正文四边的 Blob iframe 运行，沙箱属性严格为 `sandbox="allow-scripts"`，不含 `allow-same-origin`；脚本无法访问父应用的源或文件读取接口。渲染器通过普通 inject 回调调用 `remote.workspaceFiles.readRelated`，加载直接声明的相对 `.js` 经典脚本和 `.css` 样式表；固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径，`rpc.ts` 解码返回的字节。依赖 Resource 在 `readRelated` 返回后加入，使用返回的 `absolutePath`，失败时则使用字符串类型的 `error.details.path`；没有 Host 路径时，Client 不自行猜测。在渲染器内部，base64 仅用于把 iframe 引导载荷嵌入脚本文本。`<base href>` 将依赖解析交给浏览器，HTTPS 资源也由浏览器处理。本地模块 import、CSS `url()`/`@import` 和动态 `fetch` 不使用 Host 文件访问。读取失败、无效 UTF-8 或超出上限都使预览失败，不发布部分资源包。替换或卸载文档会释放其 Blob URL。
+开启开发者工具时，HTML 以贴合正文四边的 Blob iframe 运行，沙箱属性严格为 `sandbox="allow-scripts"`，不含 `allow-same-origin`；脚本无法访问父应用的源或文件读取接口。渲染器通过注入的 Remote 回调，加载直接声明的相对 `.js` 经典脚本和 `.css` 样式表；固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径，带 `baseFile` 的 `readBytes` 返回原生字节。依赖 Resource 在读取返回后加入，使用返回的 `absolutePath`，失败时则使用字符串类型的 `error.details.path`；没有 Host 路径时，Client 不自行猜测。在渲染器内部，base64 仅用于把 iframe 引导载荷嵌入脚本文本。`<base href>` 将依赖解析交给浏览器，HTTPS 资源也由浏览器处理。本地模块 import、CSS `url()`/`@import` 和动态 `fetch` 不使用 Host 文件访问。读取失败、无效 UTF-8 或超出上限都使预览失败，不发布部分资源包。替换或卸载文档会释放其 Blob URL。
 
 PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态图片上下文中渲染，带 12px 内边距和圆角。宽图按固有纵横比缩小到面板宽度，小图按固有 CSS 像素尺寸居中，超高图纵向滚动。渲染器既不提供缩放，也不提供拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此其中的脚本无法执行，也无法访问父页面。替换或卸载图片会撤销其 Blob URL。
 
@@ -65,7 +65,7 @@ PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态
 <a id="office-preview"></a>
 ## Office 预览
 
-将 `.doc`、`.docx`、`.xls`、`.xlsx`、`.ppt` 和 `.pptx` 打开为 PDF 预览，使用与 PDF 文件相同的加载状态、控件、取消和文本选择能力。[Host 提供方](../../document/office-to-pdf/README.zh.md)负责本地转换；无效文件、转换失败和超时会显示本地化消息。缺少 Host 服务时显示配置引导。
+将 `.doc`、`.docx`、`.ppt` 和 `.pptx` 打开为 PDF 预览，使用与 PDF 文件相同的加载状态、控件、取消和文本选择能力。`.xls` 与 `.xlsx` 不注册 Sidebar 渲染器：它们不请求转换，直接显示不支持预览的提示；Host 报告存在桌面时，还提供用系统默认应用打开的控件。[Host 提供方](../../document/office-to-pdf/README.zh.md)仍为其他消费者保留电子表格转换 API。受支持的无效文件、转换失败和超时会显示本地化消息。缺少 Host 服务时显示配置引导。
 
 [Web bundle](../../bundle/web-app/README.zh.md) 以 `ui-sidebar-documentpreview` 挂载本包。通过该条目的 `office` 设置配置临时 Office 缓存；[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-client-ui-sidebar-documentpreview)定义可接受的值。设置注入到每个页面；修改 YAML 后重新加载浏览器页面。
 
@@ -86,7 +86,7 @@ PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态
 
 Office 注册、加载、缓存和字体提示位于 `src/client/office/`。Office 正文持有转换后的 PDF 字节和字体元数据，并声明嵌套 PDF slot，复用惰性 PDF 正文及其 tab 阅读状态。keyed slot `sidebar.right.tab.document.action` 将渲染器操作放在刷新按钮前。Office 操作与正文共享 store，仅读取当前 revision 的字体元数据。Host 渲染器缺失时，注册仍然可用；可选的 `remote.officeToPdf` 和 `remote.workspaceFiles` 注入提供转换与版本检查回调，移除后恢复不可用提示。注册和 tab 状态保留都遵循 effect 生命周期。[转换服务](../../document/office-to-pdf/README.zh.md)拥有 Host Remote 方法，由 `api/remotes` 挂载。
 
-共享 `documentFileBytes()` 辅助函数将普通文件与转换后 PDF 的响应解码到一个独立持有的字节缓冲区，不会将字节展开为 JavaScript 数组元素。渲染器以只读方式借用保留的字节，并在传给 Worker 前复制。
+`documentFileBytes()` 辅助函数将 Office 转换后的 PDF 响应解码到一个独立持有的字节缓冲区，不会将字节展开为 JavaScript 数组元素。渲染器以只读方式借用保留的字节，并在传给 Worker 前复制。
 
 </details>
 
@@ -108,7 +108,7 @@ Office 注册、加载、缓存和字体提示位于 `src/client/office/`。Offi
 
 <a id="known-limitations-and-deferred-work"></a>
 - **预览而非编辑。** 查看器不提供文件编辑或共享搜索接口；目录地址以 `not-regular-file` 失败。未知扩展名使用纯文本读取，仍受其 UTF-8/NUL 检查限制。
-- **Office 转换限制。** 预览不启动原生 Office 编辑器，也不下载引擎。二进制 `.doc`、`.xls` 和 `.ppt` 文件不返回缺失字体诊断。转换保真度与资源限制由 [LibreOffice 提供方](../../document/office-to-pdf/README.zh.md)负责。
+- **Office 转换限制。** 预览不启动原生 Office 编辑器，也不下载引擎。Excel 工作簿不提供预览，在桌面 Host 上改为提供用系统默认应用打开的控件。二进制 `.doc` 和 `.ppt` 文件不返回缺失字体诊断。转换保真度与资源限制由 [LibreOffice 提供方](../../document/office-to-pdf/README.zh.md)负责。
 - **文本顺序分页，完整文件受限。** 定位到较深处的源码行需要先加载此前各页；PDF、HTML 和图片必须取得 Host `maxFileBytes` 上限内的完整结果。
 - **字节视图不恢复滚动位置。** PDF、HTML 与图片的渲染器重新挂载或重新载入时可能回到顶部；图片适配面板宽度、不产生横向滚动，HTML iframe 的滚动属于其不透明浏览上下文。
 - **本地 HTML 依赖集合有限。** 只打包直接引用的经典 `.js` 脚本和 `.css` 样式表。浏览器解析的资源仍受浏览器源与网络规则限制；iframe 不获得运行时文件读取桥接。
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/face.ts b/packages/client/ui-sidebar-documentpreview/src/client/face.ts
index 17dda43da3..914c754278 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/face.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/face.ts
@@ -101,7 +101,7 @@ interface TabReads {
 /**
  * Bind the preview's face to one paged read and one complete-byte read.
  * @param read - the bound `workspaceFiles.read` call.
- * @param readAll - ordinary complete-byte Remote read.
+ * @param readAll - complete-byte workspace Remote read.
  * @param resources - shared metadata sources for the document and its dependencies.
  * @returns the Slot `inject` factory: bound actions in, face out. The slot's session id is unused because the address carries its own.
  */
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts
index 50672fc97b..88ebcfda78 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts
@@ -35,7 +35,7 @@ export function apply(ctx: Context): void {
         hooks: { interactivePreview: ctx.settingsScope.developerTools.enabled },
         readRelated: (address, relativePath, signal) => {
           const file = hostFileOf(address)
-          return ctx.remote.workspaceFiles.readRelated(file.sessionId, file.path, relativePath, signal)
+          return ctx.remote.workspaceFiles.readBytes(file.sessionId, relativePath, { baseFile: file.path }, signal)
         },
       }),
     }, HtmlBody,
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts b/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts
index 5bbf23c94e..8421a1ab29 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts
@@ -1,7 +1,6 @@
-/** Adapt a Remote relative read without changing its Session or Host path authority. */
+/** Adapt a relative workspace read without changing its Session or Host path authority. */
 import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
-import type { WorkspaceFileBytes } from '@deepseek-ai/dsh-api-workspace-files/types'
-import { documentFileBytes } from '../rpc.ts'
+import type { DocumentFileBytes } from '../rpc.ts'
 import type { ReadHtmlRelative } from './pack.ts'
 import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
 import { hostFileOf } from '../rpc.ts'
@@ -11,13 +10,13 @@ import { hostFileOf } from '../rpc.ts'
  * @param address - root HTML file address.
  * @param relativePath - decoded dependency path, resolved only by the Host.
  * @param signal - cancellation shared by the tab and packing operation.
- * @returns the Remote complete-byte result, including declared failures.
+ * @returns the complete-byte result, including declared failures.
  */
-export type ReadHtmlRelated = (address: string, relativePath: string, signal: AbortSignal) => Promise<RemoteResult<WorkspaceFileBytes>>
+export type ReadHtmlRelated = (address: string, relativePath: string, signal: AbortSignal) => Promise<RemoteResult<DocumentFileBytes>>
 
 /**
  * Bind a package reader to the original HTML file's address.
- * @param readRelated - Remote reader using the Session in the root HTML address.
+ * @param readRelated - workspace reader using the Session in the root HTML address.
  * @param address - root HTML file address.
  * @param lifetime - tab lifetime.
  * @param addResource - subscribes to the dependency path reported by the Host.
@@ -47,6 +46,6 @@ export function createReadHtmlRelative(
       throw new Error(result.error.message)
     }
     addResource(sessionFileAddress(file.sessionId, result.value.absolutePath))
-    return documentFileBytes(result.value)
+    return result.value
   }
 }
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/index.ts
index c5edbc05a5..7c8b6907b2 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/index.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/index.ts
@@ -25,7 +25,7 @@ import type { TextPreviewInjected } from './TextPreview.tsx'
 import { TextTitle } from './TextTitle.tsx'
 import { TEXTPREVIEW_ID, textDefinition } from './definition.ts'
 import { textFace } from './face.ts'
-import { createReadPage, documentFileBytes } from './rpc.ts'
+import { createReadPage } from './rpc.ts'
 import { createTextStore } from './store.ts'
 import { en, zh } from './locales.ts'
 import { DocumentPreviewRegistry } from './document/registry.ts'
@@ -76,13 +76,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 
 /**
  * Required browser services: the tab registry, the slot registry, copy, and the
- * Remote carrier with its `workspaceFiles` namespace.
+ * workspace Remote for bytes and paged text reads.
  */
 export const inject = ['slots', 'locale', 'sidebarRightTabs', 'remote', 'remote.workspaceFiles', 'settingsScope', 'resources']
 
 /**
  * Client plugin body: register the type, its dictionaries, its body, and its chip title.
- * @param ctx - client root context carrying the registry, the slots, copy, and the Remote face.
+ * @param ctx - client root context carrying the registry, slots, copy, and file readers.
  */
 export function apply(ctx: ClientContext): void {
   const config = Config((globalThis as { __DSH_DOCUMENT_PREVIEW_CONFIG__?: unknown }).__DSH_DOCUMENT_PREVIEW_CONFIG__ ?? {})
@@ -95,10 +95,7 @@ export function apply(ctx: ClientContext): void {
   const store = createTextStore()
   const face = textFace(
     createReadPage(ctx.remote),
-    async (file, signal) => {
-      const result = await ctx.remote.workspaceFiles.readAll(file.sessionId, file.path, signal)
-      return result.ok ? { ok: true, value: documentFileBytes(result.value) } : result
-    },
+    (file, signal) => ctx.remote.workspaceFiles.readBytes(file.sessionId, file.path, {}, signal),
     ctx.resources,
   )
   const source = { getSnapshot: previews.getSnapshot, subscribe: previews.subscribe }
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts
index 66b24e0db1..098e5dd06c 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts
@@ -5,7 +5,6 @@ import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-office-to-pdf/remote'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-api-workspace-files/remote'
-import type {} from '@deepseek-ai/dsh-client-connection/client'
 import { documentFileBytes } from '../rpc.ts'
 import { failureLine } from '../failure-line.ts'
 import { documentTabInfoFactory } from '../document/contract.ts'
@@ -31,7 +30,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
  */
 export function apply(ctx: Context, config: Config['office']): void {
   const id = '@deepseek-ai/dsh-client-ui-sidebar-documentpreview/office'
-  const extensions = ['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx']
+  const extensions = ['doc', 'docx', 'ppt', 'pptx']
   ctx.effect(() => ctx.locale.register('sidebarOffice', { zh, en }))
   const t = ctx.locale.bind('sidebarOffice')
   const unavailable: ReadOfficeDocument = (_file, signal) => {
@@ -81,7 +80,9 @@ export function apply(ctx: Context, config: Config['office']): void {
     }
     const createCache = () => new OfficePreviewCache(
       async (file, signal) => {
-        const authorized = await scope.remote.workspaceFiles.readBytes(file.sessionId, file.path, { offset: 0, length: 1 }, signal)
+        const authorized = await scope.remote.workspaceFiles.readBytes(
+          file.sessionId, file.path, { range: { offset: 0, length: 1 } }, signal,
+        )
         signal.throwIfAborted()
         if (!authorized.ok) return authorized
         const metadata = await scope.remote.workspaceFiles.stat(file.sessionId, file.path, signal)
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts b/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts
index d609278c4f..8289374cdc 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts
@@ -81,23 +81,23 @@ export function createReadPage(remote: WorkspaceFilesReadRemote): ReadWorkspaceF
   return (sessionId, path, offset, signal) => remote.workspaceFiles.read(sessionId, path, { offset }, signal)
 }
 
-/** Complete document bytes borrowed read-only by renderers; copy before transferring to a Worker. */
-export type DocumentFileBytes = Omit<WorkspaceFileBytes, 'data'> & { readonly data: Uint8Array<ArrayBuffer> }
+/** Document bytes borrowed read-only by renderers; copy before transferring to a Worker. */
+export type DocumentFileBytes = WorkspaceFileBytes<Uint8Array<ArrayBuffer>>
 
 /**
  * Read a complete file through the Host endpoint.
  * @param file - Session and path decoded from the tab address.
  * @param signal - owning tab lifetime.
- * @returns complete binary bytes, including declared failures.
+ * @returns complete native bytes, including declared failures.
  */
 export type ReadDocumentBytes = (file: SessionFile, signal: AbortSignal) => Promise<RemoteResult<DocumentFileBytes>>
 
 /**
- * Decode one successful Remote byte result for document renderers.
- * @param file - Host byte result with base64 data.
+ * Decode the Office conversion Remote's base64 PDF response.
+ * @param file - converted PDF metadata and base64 contents.
  * @returns the same metadata with native bytes; malformed base64 throws.
  */
-export function documentFileBytes(file: WorkspaceFileBytes): DocumentFileBytes {
+export function documentFileBytes(file: Omit<WorkspaceFileBytes, 'data'> & { readonly data: string }): DocumentFileBytes {
   const binary = atob(file.data)
   const data = new Uint8Array(binary.length)
   for (let index = 0; index < binary.length; index++) data[index] = binary.charCodeAt(index)
diff --git a/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts
index 976da58bbc..5e82256d60 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts
@@ -7,6 +7,8 @@
  * and face — and that every registration is gone after dispose, which is what
  * makes a reload safe.
  */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client'
+import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
@@ -29,10 +31,9 @@ import { LazyPdfBody } from '../src/client/pdf/LazyPdfBody.tsx'
 import { PDF_BODY_ID } from '../src/client/pdf/index.ts'
 import { CodeBody } from '../src/client/code/CodeBody.tsx'
 import { en, zh } from '../src/client/locales.ts'
-import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
 import type { textFace } from '../src/client/face.ts'
 import type { TextStore } from '../src/client/store.ts'
-import { FILE, SESSION, TAB_ID, createResources, page } from './fixtures.client.ts'
+import { FILE, SESSION, TAB_ID, byteResult, createResources, page } from './fixtures.client.ts'
 
 interface Recorded {
   name: string
@@ -65,21 +66,17 @@ async function boot() {
       return () => { dictionaries.delete(ns) }
     }),
   }
-  const workspaceFiles = {
-    read: vi.fn().mockResolvedValue(page(1, ['first'], true)),
-    readAll: vi.fn().mockResolvedValue({
-      ok: true, value: { absolutePath: '/workspace/notes.md', version: 'v1', offset: 0, data: 'AAH/', eof: true },
-    }),
-  }
+  const read = vi.fn().mockResolvedValue(page(1, ['first'], true))
+  const readBytes = vi.fn<ClientRemote['workspaceFiles']['readBytes']>(async () => byteResult())
   ctx.provide('sidebarRightTabs', tabs as never)
   ctx.provide('slots', slots as never)
   ctx.provide('locale', locale as never)
-  ctx.provide('remote', { workspaceFiles } as never)
-  ctx.provide('remote.workspaceFiles', workspaceFiles as never)
+  ctx.provide('remote', { workspaceFiles: { read, readBytes } } as never)
+  ctx.provide('remote.workspaceFiles', { read, readBytes } as never)
   const fiber = ctx.plugin({ inject: [...inject], apply })
   onTestFinished(async () => { await fiber.dispose() })
   await fiber.await()
-  return { tabs, registered, dictionaries, fiber, workspaceFiles }
+  return { tabs, registered, dictionaries, fiber, read, readBytes }
 }
 
 describe('ui-sidebar-documentpreview apply', () => {
@@ -115,8 +112,8 @@ describe('ui-sidebar-documentpreview apply', () => {
     expect(dictionaries.size).toBe(0)
   })
 
-  it('injects ordinary Remote reads independently of resource metadata', async () => {
-    const { registered, workspaceFiles } = await boot()
+  it('injects paged and byte Remote reads independently of resource metadata', async () => {
+    const { registered, read, readBytes } = await boot()
     const registration = registered.find(entry => entry.component === TextPreview)
     if (registration === undefined) throw new Error('missing preview registration')
     const instance = (registration.store as TextStore).create()
@@ -124,17 +121,16 @@ describe('ui-sidebar-documentpreview apply', () => {
     const controller = new AbortController()
     onTestFinished(() => { controller.abort() })
     face.loadPage(TAB_ID, FILE, 1, controller.signal, 'v1')
-    await workspaceFiles.read.mock.results[0]?.value
-    expect(workspaceFiles.read).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, { offset: 1 }, controller.signal)
+    await read.mock.results[0]?.value
+    expect(read).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, { offset: 1 }, controller.signal)
     expect(instance.getSnapshot().byTab[TAB_ID]?.pages[1]?.text).toBe('first')
     face.loadAll(TAB_ID, FILE, controller.signal, 'v1')
-    await workspaceFiles.readAll.mock.results[0]?.value
-    expect(workspaceFiles.readAll).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, expect.any(AbortSignal))
-    await expect.poll(() => instance.getSnapshot().byTab[TAB_ID]?.complete?.data).toEqual(new Uint8Array([0, 1, 255]))
-    const failure = new RemoteError('workspace-file/not-found', 'File missing', { path: FILE.path })
-    workspaceFiles.readAll.mockResolvedValueOnce({ ok: false, error: failure })
+    await vi.waitFor(() => { expect(instance.getSnapshot().byTab[TAB_ID]?.complete).toBeDefined() })
+    expect(readBytes).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, {}, expect.any(AbortSignal))
+    expect(instance.getSnapshot().byTab[TAB_ID]?.complete?.data).toEqual(new Uint8Array([0, 1, 255]))
+    readBytes.mockResolvedValueOnce({ ok: false, error: new RemoteError('workspace-file/not-found', 'File missing', { path: FILE.path }) })
     face.reloadAll(TAB_ID, FILE, controller.signal, 'v2')
-    await expect.poll(() => instance.getSnapshot().byTab[TAB_ID]?.failure).toBe(failure)
+    await expect.poll(() => instance.getSnapshot().byTab[TAB_ID]?.failure).toMatchObject({ code: 'workspace-file/not-found', message: 'File missing' })
     expect(instance.getSnapshot().byTab[TAB_ID]?.complete).toBeUndefined()
   })
 })
diff --git a/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx
index f938754af5..f3eeace3c8 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx
@@ -1,18 +1,19 @@
 // @vitest-environment jsdom
 /** Document extension registration and dispatch through the production Sidebar and Slot renderer. */
+import { byteResult } from './fixtures.client.ts'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, fireEvent, screen, waitFor } from '@testing-library/react'
 import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
-import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client'
 import { absoluteFileAddress, sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
 import { apply as resourcesApply, inject as resourcesInject } from '@deepseek-ai/dsh-client-resources/src/client/index.ts'
 import { apply as sidebarApply, inject as sidebarInject } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/index.ts'
 import { apply, inject } from '../src/client/index.ts'
 import type { DocumentPreviewProps } from '../src/client/document/contract.ts'
 import type { DocumentLoadMode } from '../src/client/document/registry.ts'
+import type { WorkspaceFilesReadRemote } from '../src/client/rpc.ts'
 import { PLAIN_BODY_ID } from '../src/client/text/index.ts'
 
 const SESSION = 'documents' as SessionId
@@ -49,15 +50,12 @@ async function boot() {
   await rt.sessions.add({ id: SESSION })
   await rt.sessions.retainFor(rt.ctx, SESSION, { source: 'mainView' }).ready
   await rt.mount({ inject: [...resourcesInject], apply: resourcesApply })
-  const read = vi.fn<ClientRemote['workspaceFiles']['read']>().mockImplementation(async (_sessionId, _path, range) => ({
+  const read = vi.fn<WorkspaceFilesReadRemote['workspaceFiles']['read']>().mockImplementation(async (_sessionId, _path, range) => ({
     ok: true,
     value: { absolutePath: '/host/notes', version: 'v1', bytes: 18, offset: range.offset ?? 1, text: range.offset === 3 ? 'third' : 'first\nsecond', lines: range.offset === 3 ? 1 : 2, eof: range.offset === 3 },
   }))
-  const bytes = vi.fn<ClientRemote['workspaceFiles']['readAll']>().mockResolvedValue({
-    ok: true, value: { absolutePath: '/host/notes', version: 'v1', offset: 0, data: btoa('all'), bytes: 3, eof: true },
-  })
-  const workspaceFiles = { read, readAll: bytes }
-  rt.remote.provideNamespaces({ workspaceFiles })
+  const bytes = vi.fn(async () => byteResult(new TextEncoder().encode('all')))
+  rt.remote.provideNamespaces({ workspaceFiles: { read, readBytes: bytes } })
   rt.ctx.effect(() => rt.ctx.resources.register({
     protocol: 'file',
     open: async function* (_address, { signal }) {
diff --git a/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts
index 2a8a85e183..0eead1b061 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts
@@ -237,6 +237,7 @@ describe('textFace', () => {
     expect(tab()?.complete).toBeUndefined()
     await settleAll(result)
     expect(tab()).toMatchObject({ mode: 'bytes-complete', loading: false, complete: result.value, version: 'v1', eof: true, pages: {} })
+    expect(tab()?.complete?.data).toBe(result.value.data)
   })
 
   it('records a complete-read failure and clears it when the read is retried', async () => {
diff --git a/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts b/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts
index d34bd4bc5a..d71d1167b1 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts
@@ -21,7 +21,7 @@ import type { WorkspaceFileStat, WorkspaceFileText } from '@deepseek-ai/dsh-api-
 import type { TextPreviewProps } from '../src/client/TextPreview.tsx'
 import { textFace } from '../src/client/face.ts'
 import type { TextInjected } from '../src/client/face.ts'
-import type { ReadDocumentBytes, ReadWorkspaceFilePage, SessionFile } from '../src/client/rpc.ts'
+import type { DocumentFileBytes, ReadDocumentBytes, ReadWorkspaceFilePage, SessionFile } from '../src/client/rpc.ts'
 import { createTextStore } from '../src/client/store.ts'
 import type { TextStore } from '../src/client/store.ts'
 import type { DocumentPreviewProps } from '../src/client/document/contract.ts'
@@ -189,3 +189,8 @@ export function harness(script: Record<number, RemoteResult<WorkspaceFileText>>
     setFailure(failure) { current.failure = failure; refresh() },
   }
 }
+
+/** Native byte result returned by the generated workspace Remote. */
+export function byteResult(data = new Uint8Array([0, 1, 255])): RemoteResult<DocumentFileBytes> {
+  return { ok: true, value: { absolutePath: '/host/notes', version: 'v1', offset: 0, eof: true, bytes: data.byteLength, data } }
+}
diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts
index bcf14b5c6a..e2f7a2eff6 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts
@@ -1,3 +1,4 @@
+import { byteResult } from './fixtures.client.ts'
 /** HTML metadata and keyed slot contributions share one identity and unwind with their fiber. */
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -36,8 +37,8 @@ describe('HTML registration', () => {
     const registry = new DocumentPreviewRegistry()
     const dictionaries = new Map<string, unknown>()
     const bodies = new Map<string, unknown>()
-    const readRelated = vi.fn().mockResolvedValue({ ok: true, value: { data: '' } })
-    ctx.provide('remote', { workspaceFiles: { readRelated } } as never)
+    const readRelated = vi.fn(async () => byteResult())
+    ctx.provide('remote', { workspaceFiles: { readBytes: readRelated } } as never)
     const register = vi.fn((options: Registration, body: unknown) => {
       bodies.set(options.key, body)
       return () => { bodies.delete(options.key) }
@@ -62,9 +63,9 @@ describe('HTML registration', () => {
     expect(typeof injected?.readRelated).toBe('function')
     const signal = new AbortController().signal
     await injected?.readRelated('dsh-resource://file/session/explicit-session/sub/index.html', '../app.js', signal)
-    expect(readRelated).toHaveBeenLastCalledWith('explicit-session', 'sub/index.html', '../app.js', signal)
+    expect(readRelated).toHaveBeenLastCalledWith('explicit-session', '../app.js', { baseFile: 'sub/index.html' }, signal)
     await injected?.readRelated(sessionFileAddress('absolute-session', '/workspace/index.html'), './app.js', signal)
-    expect(readRelated).toHaveBeenLastCalledWith('absolute-session', '/workspace/index.html', './app.js', signal)
+    expect(readRelated).toHaveBeenLastCalledWith('absolute-session', './app.js', { baseFile: '/workspace/index.html' }, signal)
     expect(() => injected?.readRelated('dsh-resource://file/absolute/workspace/index.html', './app.js', signal))
       .toThrow('not a session file address')
     expect(readRelated).toHaveBeenCalledTimes(2)
diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
index be3a1a7869..8ed6f439a2 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
@@ -3,6 +3,9 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, render, screen, waitFor } from '@testing-library/react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { bindSnapshotSelector, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
+import { DeveloperToolsPreference } from '@deepseek-ai/dsh-client-ui-settings/src/client/developer-tools.ts'
+import type { DeveloperToolsSettings } from '@deepseek-ai/dsh-client-ui-settings/src/developer-tools-settings.ts'
 import type { Resources, ResourceSnapshot } from '@deepseek-ai/dsh-client-resources/client'
 import type { WorkspaceFileStat } from '@deepseek-ai/dsh-api-workspace-files/types'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -87,7 +90,7 @@ describe('HtmlBody', () => {
     h.bytes.mockResolvedValue({ ok: true, value: { absolutePath: ABSOLUTE_PATH, version: 'root-v1', data, offset: 0, eof: true } })
     const readRelated = vi.fn<HtmlBodyProps['readRelated']>().mockResolvedValue({ ok: true, value: {
       absolutePath: `/workspace/asset.${extension}`, version: 'asset-v1', offset: 0, eof: true,
-      data: btoa(extension === 'css' ? 'body { color: red }' : 'window.loaded = true'),
+      data: utf8(extension === 'css' ? 'body { color: red }' : 'window.loaded = true'),
     } })
     const definition = { ...htmlBodyDefinition(() => 'HTML'), extensions: ['md'] }
     let interactive = true
@@ -108,7 +111,7 @@ describe('HtmlBody', () => {
     expect(create).toHaveBeenCalledOnce()
     readRelated.mockResolvedValueOnce({ ok: true, value: {
       absolutePath: `/workspace/asset.${extension}`, version: 'asset-v2', offset: 0, eof: true,
-      data: btoa(extension === 'css' ? 'body { color: blue }' : 'window.loaded = false'),
+      data: utf8(extension === 'css' ? 'body { color: blue }' : 'window.loaded = false'),
     } })
     act(() => { dependency.set(metadata('asset-v2')) })
     await waitFor(() => { expect(screen.getByTitle(en.frame)).not.toBe(previous) })
@@ -153,6 +156,31 @@ describe('HtmlBody', () => {
     expect(screen.getByRole('alert').textContent).toBe(en.failed)
   })
 
+  it('follows the shared developer-tools preference from loading through a stored false to enabled', async () => {
+    const host = stubSettingsScope<DeveloperToolsSettings>()
+    const preference = new DeveloperToolsPreference(host.scope)
+    const readRelated = vi.fn<HtmlBodyProps['readRelated']>().mockResolvedValue({ ok: true, value: {
+      absolutePath: '/workspace/asset.js', version: 'asset-v1', offset: 0, eof: true,
+      data: utf8('window.loaded = true'),
+    } })
+    const scripted: HtmlBodyProps = {
+      ...props('<p>Preview</p><script src="./asset.js"></script>'),
+      useInteractivePreview: bindSnapshotSelector(preference.enabled),
+      readRelated,
+    }
+    const view = render(<HtmlBody {...scripted} />)
+    expect(screen.getByTitle(en.frame).getAttribute('sandbox')).toBe('')
+    expect(readRelated).not.toHaveBeenCalled()
+    act(() => { host.publish({ status: 'ready', value: { enabled: false } }) })
+    expect(screen.getByTitle(en.frame).getAttribute('sandbox')).toBe('')
+    expect(readRelated).not.toHaveBeenCalled()
+    act(() => { host.publish({ value: { enabled: true } }) })
+    const advanced = await screen.findByTitle(en.frame)
+    expect(advanced.getAttribute('sandbox')).toBe('allow-scripts')
+    expect(readRelated).toHaveBeenCalledOnce()
+    view.unmount()
+  })
+
   it('renders a Blob iframe with only scripts allowed, keeping it mounted for unrelated props', async () => {
     const initial = props()
     const view = render(<HtmlBody {...initial} />)
@@ -224,7 +252,7 @@ describe('HtmlBody', () => {
     const signal = new AbortController().signal
     const bytes = vi.fn().mockResolvedValue({
       ok: true,
-      value: { absolutePath: '/workspace/app.js', data: btoa('window.ready=true'), version: 'v1', offset: 0, eof: true },
+      value: { absolutePath: '/workspace/app.js', data: utf8('window.ready=true'), version: 'v1', offset: 0, eof: true },
     })
     const useResource = vi.fn().mockReturnValue({ value: undefined })
     const initial = {
@@ -247,7 +275,7 @@ describe('HtmlBody', () => {
     const signal = new AbortController().signal
     const bytes = vi.fn().mockResolvedValue({
       ok: true,
-      value: { absolutePath: '/workspace/app.js', version: 'v1', bytes: 16, offset: 0, data: btoa('window.ready=1'), eof: true },
+      value: { absolutePath: '/workspace/app.js', version: 'v1', bytes: 16, offset: 0, data: utf8('window.ready=1'), eof: true },
     })
     const useResource = vi.fn(() => ({ value: { version: 'v1' } }))
     const initial = {
diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts
index d043a1a579..3c6e65e2ec 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts
@@ -1,4 +1,4 @@
-/** HTML URL decoding stays local; ordinary Remote reads leave path resolution and authorization to the Host. */
+/** HTML URL decoding stays local; workspace reads leave path resolution and authorization to the Host. */
 import { describe, expect, it, vi } from 'vitest'
 import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
 import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
@@ -8,14 +8,14 @@ import type { ReadHtmlRelated } from '../src/client/html/read-relative.ts'
 const ADDRESS = 'dsh-resource://file/session/html/sub/index.html'
 
 describe('HTML relative file reader', () => {
-  it('decodes a relative URL once and converts the Remote result to native bytes', async () => {
-    const value = { absolutePath: '/workspace/a b.js', data: btoa('x'), version: 'v1', offset: 0, bytes: 1, eof: true }
+  it('decodes a relative URL once and preserves the returned bytes', async () => {
+    const value = { absolutePath: '/workspace/a b.js', data: new Uint8Array([120]), version: 'v1', offset: 0, bytes: 1, eof: true }
     const readRelated = vi.fn<ReadHtmlRelated>().mockResolvedValue({ ok: true, value })
     const tab = new AbortController()
     const loading = new AbortController()
     const addResource = vi.fn()
     const read = createReadHtmlRelative(readRelated, ADDRESS, tab.signal, addResource)
-    await expect(read('../a%20b.js?v=1#fragment', loading.signal)).resolves.toEqual({ ...value, data: new Uint8Array([120]) })
+    await expect(read('../a%20b.js?v=1#fragment', loading.signal)).resolves.toBe(value)
     const signal = readRelated.mock.calls[0]?.[2]
     expect(readRelated).toHaveBeenCalledExactlyOnceWith(ADDRESS, '../a b.js', signal)
     expect(addResource).toHaveBeenCalledExactlyOnceWith(sessionFileAddress('html', value.absolutePath))
@@ -25,7 +25,7 @@ describe('HTML relative file reader', () => {
   })
 
   it('observes the Host-resolved dependency instead of a symlink and parent-segment spelling', async () => {
-    const value = { absolutePath: '/workspace/style.css', data: btoa('x'), version: 'v1', offset: 0, eof: true }
+    const value = { absolutePath: '/workspace/style.css', data: new TextEncoder().encode('x'), version: 'v1', offset: 0, bytes: 1, eof: true }
     const readRelated = vi.fn<ReadHtmlRelated>().mockResolvedValue({ ok: true, value })
     const addResource = vi.fn()
     const signal = new AbortController().signal
@@ -85,7 +85,7 @@ describe('HTML relative file reader', () => {
     const result = read('./late.js', loading.signal)
     const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' })
     loading.abort()
-    pending.resolve({ ok: true, value: { absolutePath: '/workspace/late.js', version: 'v1', bytes: 1, offset: 0, data: 'AQ==', eof: true } })
+    pending.resolve({ ok: true, value: { absolutePath: '/workspace/late.js', version: 'v1', bytes: 1, offset: 0, data: new Uint8Array([1]), eof: true } })
     await rejected
   })
 })
diff --git a/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts
index 22bd4da75b..ffa492509f 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts
@@ -55,7 +55,7 @@ async function harness(config: Partial<Config['office']> = {}, missing?: 'remote
   const render = vi.fn<ClientRemote['officeToPdf']['render']>().mockResolvedValue(converted)
   const rendererGeneration = vi.fn<ClientRemote['officeToPdf']['generation']>().mockResolvedValue({ ok: true, value: generation })
   const stat = vi.fn<ClientRemote['workspaceFiles']['stat']>().mockResolvedValue({ ok: true, value: source })
-  const readBytes = vi.fn<ClientRemote['workspaceFiles']['readBytes']>().mockResolvedValue({ ok: true, value: source })
+  const readBytes = vi.fn<ClientRemote['workspaceFiles']['readBytes']>().mockResolvedValue({ ok: true, value: { ...source, data: pdf.subarray(0, 1), eof: false } })
   const removeNotice = vi.fn()
   const recorded: { options: { name: string; store: OfficeStore; inject: (id: SessionId, actions: ReturnType<OfficeStore['create']>['actions']) => OfficeBodyInjected }; component: unknown }[] = []
   const register = vi.fn((options: typeof recorded[number]['options'], component: unknown) => { recorded.push({ options, component }); return removeNotice })
@@ -81,17 +81,18 @@ async function harness(config: Partial<Config['office']> = {}, missing?: 'remote
   }
 }
 
-it.each(['remote', 'render', 'files'] as const)('keeps Office registration and guidance when %s is absent', async (missing) => {
+it.each(['remote', 'render', 'files'] as const)('keeps Word and PowerPoint registration and guidance when %s is absent', async (missing) => {
   const h = await harness(undefined, missing)
   try {
     expect(h.locale.register).toHaveBeenCalledWith('sidebarOffice', { zh, en })
-    for (const path of ['a.DOC', 'b.DOCX', 'c.XLS', 'd.xlsx', 'e.PPT', 'f.pptx']) {
-      expect(h.registry.candidates(path)[0]!.binaryExtensions).toEqual(['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx'])
+    for (const path of ['a.DOC', 'b.DOCX', 'c.PPT', 'd.pptx']) {
+      expect(h.registry.candidates(path)[0]!.binaryExtensions).toEqual(['doc', 'docx', 'ppt', 'pptx'])
       expect(h.registry.candidates(path)[0]!.title()).toBe(en.title)
       expect(h.registry.candidates(path)[0]!.loading).toBe('renderer')
       expect(h.registry.candidates(path)[0]).not.toHaveProperty('read')
       await expect(h.read(undefined, path)).rejects.toThrow(en.unavailable)
     }
+    for (const path of ['sheet.XLS', 'sheet.xlsx']) expect(h.registry.candidates(path)).toEqual([])
     expect(h.render).not.toHaveBeenCalled()
   } finally { await h.close() }
   expect(h.registry.getSnapshot()).toEqual([])
@@ -111,7 +112,7 @@ it('requests a Host PDF with source identity and borrows the same binary cache r
     expect(await h.read()).toBe(result)
     expect(h.stat).toHaveBeenCalledTimes(2)
     expect(h.readBytes).toHaveBeenCalledTimes(2)
-    expect(h.readBytes).toHaveBeenCalledWith(file.sessionId, file.path, { offset: 0, length: 1 }, expect.any(AbortSignal))
+    expect(h.readBytes).toHaveBeenCalledWith(file.sessionId, file.path, { range: { offset: 0, length: 1 } }, expect.any(AbortSignal))
     expect(h.render).toHaveBeenCalledOnce()
   } finally { await h.close() }
 })
@@ -146,8 +147,8 @@ it('refuses Client cached bytes when metadata still succeeds but the read probe
   try {
     await h.read()
     const failure = new Error('read denied')
-    h.readBytes.mockRejectedValueOnce(failure)
-    await expect(h.read()).rejects.toBe(failure)
+    h.readBytes.mockResolvedValueOnce({ ok: false, error: new RemoteError('gateway/internal', failure.message, {}) })
+    expect(await h.read()).toMatchObject({ ok: false, error: { code: 'gateway/internal', message: failure.message } })
     expect(h.render).toHaveBeenCalledOnce()
     expect(h.stat).toHaveBeenCalledOnce()
   } finally { await h.close() }
@@ -159,7 +160,7 @@ it('returns a declared authorization failure without consulting metadata or cach
     await h.read()
     const denied = { ok: false as const, error: new RemoteError('workspace-file/not-found', 'File missing', { path: file.path }) }
     h.readBytes.mockResolvedValueOnce(denied)
-    expect(await h.read()).toBe(denied)
+    expect(await h.read()).toMatchObject(denied)
     expect(h.stat).toHaveBeenCalledOnce()
     expect(h.render).toHaveBeenCalledOnce()
   } finally { await h.close() }
diff --git a/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts
index 0657e1aaf4..a7a6a74f5e 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts
@@ -6,7 +6,7 @@
  */
 import { describe, expect, it, vi } from 'vitest'
 import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
-import { createReadPage, documentFileBytes, hostFileOf } from '../src/client/rpc.ts'
+import { createReadPage, hostFileOf } from '../src/client/rpc.ts'
 import type { ReadWorkspaceFilePage, WorkspaceFilesReadRemote } from '../src/client/index.ts'
 import { ADDRESS, FILE, PATH, SESSION, page } from './fixtures.client.ts'
 
@@ -39,17 +39,3 @@ describe('createReadPage', () => {
     expect(read).toHaveBeenCalledWith(SESSION, PATH, { offset: 4 }, signal)
   })
 })
-
-describe('documentFileBytes', () => {
-  it.each(['', 'AAH/'])('decodes complete Remote bytes without changing metadata (%j)', (data) => {
-    const file = { absolutePath: '/workspace/a.bin', version: 'v1', bytes: 3, offset: 0, data, eof: true }
-    const result = documentFileBytes(file)
-    expect(result).toEqual({ ...file, data: data === '' ? new Uint8Array() : new Uint8Array([0, 1, 255]) })
-    expect(result.data.buffer).toBeInstanceOf(ArrayBuffer)
-    expect(file.data).toBe(data)
-  })
-
-  it('rejects malformed wire base64', () => {
-    expect(() => documentFileBytes({ absolutePath: '/workspace/a.bin', version: 'v1', offset: 0, data: '!!!', eof: true })).toThrow()
-  })
-})
diff --git a/packages/client/ui-sidebar-right/README.i18n.yaml b/packages/client/ui-sidebar-right/README.i18n.yaml
index 8cfd6b578a..e5fef88086 100644
--- a/packages/client/ui-sidebar-right/README.i18n.yaml
+++ b/packages/client/ui-sidebar-right/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-right/README.md
-README.md: e9c143f34076c308f3afdb348cc09506f3983a35
-README.zh.md: 72d0c20817c690c1dcca5a97b67adbdfa1f11261
+README.md: 14014cb0986222a73e962e390c2675dd7354df1c
+README.zh.md: 7686d7afa8b164bf780b4ce6f927d8829e7b3a96
diff --git a/packages/client/ui-sidebar-right/README.md b/packages/client/ui-sidebar-right/README.md
index e9c143f340..14014cb098 100644
--- a/packages/client/ui-sidebar-right/README.md
+++ b/packages/client/ui-sidebar-right/README.md
@@ -56,7 +56,7 @@ While the panel is hidden, one button in the conversation header's corner seat (
 
 The panel takes the conversation's ground colour and content font sizes rather than a raised layer of its own: it is a column of the page, not a card over it.
 
-The `rightbar` entry is a root-scoped controller. It reads `usePanelInfo` and mounts the Session-scoped `rightbar.session` subtree only while the Conversation is selected. Switching to a global panel hides the right Sidebar and releases its frame track without deleting the Session's tab state.
+The root-scoped `rightbar` entry renders the selected Session and background Sessions with initialized `keepMounted` bodies through separate `rightbar.session` subtrees. Each View owns its Session reference. Only the foreground Conversation reports a frame track and binds public navigation; other subtrees stay hidden without deleting tab state.
 
 <a id="state"></a>
 ## State
@@ -67,9 +67,9 @@ Carrying the mint counter in the surface is what makes a recorded sequence repla
 
 After every action the kit's settle planner keeps the expanded surface populated: a docked pane whose last tab was moved out or floated is merged away, and an emptied root pane receives the default page. A collapsed surface holds no such backfill — a session starts collapsed and empty, and a close that collapses the column leaves it empty — the expansion that would first show an empty layout is what seeds the default page. Explicit closing follows [the default-page and close rules](#the-guide). While expanded there is always at least one tab, and never an empty pane — so there is no separate "close pane" gesture.
 
-The docked surface's last tab carries one more rule, decided in the store's `closeTab` and mirrored to the kit through `canCloseTab`: the guide standing as the only docked tab draws no close control and no menu close item — its chip sits quiet, and with no extension item contributed a secondary press opens no menu — and a programmatic close of it records nothing; any other tab standing alone closes together with the column in one entry — the layout stays empty until the next expansion seeds its current default page. Floating panels take no part in the rule: they render whether or not the column is expanded, and their tabs close freely.
+The docked surface's last tab carries one more rule, decided in the store's `closeTab` and mirrored to the kit through `canCloseTab`: the guide standing as the only docked tab draws no close control and no menu close item — its chip sits quiet, and with no extension item contributed a secondary press opens no menu — and a programmatic close of it records nothing; any other tab standing alone closes together with the column in one entry — the layout stays empty until the next expansion seeds its current default page. Floating panels take no part in the rule: the foreground Session's floats render whether or not the column is expanded, and their tabs close freely.
 
-The store saves each Session's layout, tab identities, selection, split ratios, floating rectangles, presentation and identity counter as JSON under `dsh.sidebar-right.v1.<sessionId>` in localStorage. Reload restores that layout before tab bodies render; switching Sessions keeps their layouts independent. Providers restore their own content from the retained tab identity and resource address, including [terminal reconnection](../ui-sidebar-terminal/README.md#use-this-package). Navigation parameters, resource contents and live connections are not layout state. Undo history stays in memory and resets on reload. Saved field types, node membership, selection and identity counters are validated before adoption or startup discovery; invalid data clears only its Session key. Storage failures leave the current layout usable in memory. Windows at the same origin share the last saved layout per Session; each active window keeps its own current layout until reload.
+The store saves each Session's layout, tab identities, selection, split ratios, floating rectangles, presentation and identity counter as JSON under `dsh.sidebar-right.v1.<sessionId>` in localStorage. Reload restores that layout before tab bodies render; switching Sessions keeps their layouts independent. Providers restore their own content from the retained tab identity and resource address, including [terminal reconnection](../ui-sidebar-terminal/README.md#use-this-package). Navigation parameters, resource contents and live connections are not layout state. Undo history stays in memory and resets on reload. Saved field types, node membership, selection, identity counters and the one-pane or two-horizontal-pane dock layout are validated before adoption or startup discovery; invalid data clears only its Session key. Storage failures leave the current layout usable in memory. Windows at the same origin share the last saved layout per Session; each active window keeps its own current layout until reload.
 
 `sidebarRight.openTabs` publishes stable metadata for every open tab across saved and adopted Sessions. Startup discovery reads the layout keys without mounting dormant content, pinning files or activating Agents. Adopted stores replace their own metadata on membership commits, and permanently cleared scopes remove it. Other windows' storage writes do not overwrite this window's live membership. Providers use this inventory to restore their own resource lifetimes.
 
@@ -78,7 +78,7 @@ The store saves each Session's layout, tab identities, selection, split ratios,
 
 A tab type registers in two stages, and the shipped guide type goes through exactly the same public path a type from another package does (`ui-sidebar-documentpreview` is the live proof). Both stages sit inside the type's own `ctx.effect`, so the registration lives exactly as long as the plugin that made it.
 
-1. **The type** — `ctx.sidebarRightTabs.register({ id, kind, patterns?, priority?, canOpen?, title, guide? })`, a static declaration with no runtime hook, returning a disposer. `id` is this implementation's identity in the tab system, unique across every registration (a package name is the natural value; the shipped guide is `@deepseek-ai/dsh-client-ui-sidebar-right/guide`): a kind is not unique once an extension may take a builtin's over, so the implementation names itself, and a second registration of an `id` throws. A resource type names `patterns`, globs over `dsh-resource://` addresses: one containing `:` matches the whole address (`dsh-resource://file/**`); one without matches the URI's path at any depth, ignoring case (`*.md`), and an address that is not a URI matches no such pattern. A page type — the guide, a file tree — names none and is opened by kind. `canOpen(address)` vetoes a match. `title(address)` is the tab chip's text, captured when the tab opens. `guide` lists entry boxes for the guide page; picking one opens the contributing type as a page. A `kind` carries at most one `builtin` and one `extension` registration (the extension is in force; the builtin resumes when it leaves); any other collision on a kind throws. The `id` is also the key the type's body and title register under, so an extension and the builtin it takes over hold distinct cells and the seat renders the one in force.
+1. **The type** — `ctx.sidebarRightTabs.register({ id, kind, patterns?, priority?, canOpen?, title, guide?, keepMounted? })`, a static declaration with no runtime hook, returning a disposer. `id` is this implementation's identity in the tab system, unique across every registration (a package name is the natural value; the shipped guide is `@deepseek-ai/dsh-client-ui-sidebar-right/guide`): a kind is not unique once an extension may take a builtin's over, so the implementation names itself, and a second registration of an `id` throws. A resource type names `patterns`, globs over `dsh-resource://` addresses: one containing `:` matches the whole address (`dsh-resource://file/**`); one without matches the URI's path at any depth, ignoring case (`*.md`), and an address that is not a URI matches no such pattern. A page type — the guide, a file tree — names none and is opened by kind. `canOpen(address)` vetoes a match. `title(address)` is the tab chip's text, captured when the tab opens. `guide` lists entry boxes for the guide page; picking one opens the contributing type as a page. A `kind` carries at most one `builtin` and one `extension` registration (the extension is in force; the builtin resumes when it leaves); any other collision on a kind throws. The `id` is also the key the type's body and title register under, so an extension and the builtin it takes over hold distinct cells and the seat renders the one in force.
 2. **The body** — `ctx.slots.register({ name: 'sidebar.right.pane.tab', key: definition.id }, Body)` reads `{ sidebar, panel, tab }` through the framework-injected `useTabInfo()`. `sidebar` supplies expansion and fullscreen information; `panel.id` identifies its pane; `tab` contains the record fields, `visible`, `navigation`, `signal`, and `actions`. These are not parallel owner props; the type's own store still uses `useStore`/`actions`. Optional title registrations and guide replacements share this hook; an absent title registration uses the text captured at open time.
 
 Which type opens a resource follows the editor-resolver convention: the types whose `patterns` match are ranked by `priority` band — `extension` (a type from outside the product, the highest, and the default when none is named), `builtin`, `fallback` (plain viewers anything more specific should beat) — then by the length of the matched pattern, then by registration order; `canOpen` removes a candidate. The bands are string literals so a type in another package needs no runtime import from here. `candidates(address)` returns the ranking, `claim(address, kind?)` the decision; naming a `kind` skips its globs but keeps its `canOpen`.
@@ -92,12 +92,14 @@ Two more seats extend what is already there: `sidebar.right.tab.guide` (chain) r
 
 `preferNewPane: true` first asks the target docked pane to split under the normal two-pane and room rules, then falls back to that pane when no split is available. `replaceTab` takes precedence and disables this preference.
 
-`close(tabId)` closes a tab; `active()` reads the active tab. `isExpanded()` and `toggleExpanded()` read and drive the column's expansion; the presentation switch is the panel's own control and not part of this face. Layout operations, for callers that arrange the column programmatically, each recorded like the gesture it stands in for: `focus(tabId)` focuses a tab and its pane; `split(paneId?)` splits a docked pane (the active one by default) under the same pane budget and room rule as the strip's control and returns the new pane's id, or `undefined` — recording nothing — when it cannot; `float(tabId, rect?)` takes a docked tab out into a panel; `dock(paneId)` returns a floating panel to the active docked pane. A tab or pane that does not exist, or already is where the call would put it, is left alone. The face exposes operations only: no layout snapshot, no operation log, no lookup by address. `_undo()` / `_redo()` step the mounted surface's history; they are `@internal` — the sequence has no user-facing control, and these exist for tests. Commands need a mounted session surface; with none, they throw rather than write into a surface nobody draws.
+`close(tabId)` closes a tab; `active()` reads the active tab. `isExpanded()` and `toggleExpanded()` read and drive the column's expansion; the presentation switch is the panel's own control and not part of this face. Layout operations, for callers that arrange the column programmatically, each recorded like the gesture it stands in for: `focus(tabId)` focuses a tab and its pane; `split(paneId?)` splits a docked pane (the active one by default) under the same pane budget and room rule as the strip's control and returns the new pane's id, or `undefined` — recording nothing — when it cannot; `float(tabId, rect?)` takes a docked tab out into a panel; `dock(paneId)` returns a floating panel to the active docked pane. A tab or pane that does not exist, or already is where the call would put it, is left alone. The face exposes operations only: no layout snapshot, no operation log, no lookup by address. `_undo()` / `_redo()` step the mounted surface's history; they are `@internal` — the sequence has no user-facing control, and these exist for tests. Commands need a mounted session surface; with none, they throw rather than write into a surface nobody draws. `mounted` is the observable of the session whose seat is on screen, `undefined` while a global panel replaces the Conversation or no session is selected. A component that opens content from its own mount effect reads it through a bound hook and acts once it is defined: the frame mounts the Conversation column ahead of this seat, and the seat publishes its binding from a passive effect of the same commit, so an effect that assumed a bound seat would run first and throw. The plan review's automatic open reads it this way.
 
 <a id="the-tab-domain"></a>
 ## The Tab domain
 
-The Tab domain retains navigation, an abort signal, and bound actions per (Session, tab id). A private assembly callback adopts each Session's store, reconciles restored records immediately, and follows its commits. Reconstructing a Session store replaces its adoption, releasing the old subscription and cleanup reference. Only record removal or plugin unload aborts the signal; closing the sidebar and switching Sessions retain records, while undo restores a new occurrence. `useTabInfo()` composes framework-bound store and navigation hooks without manual component subscriptions or render-time record creation. `tab.actions` always target their own Session; `tab.visible` distinguishes bodies from titles, and floating tabs remain visible when the sidebar closes. `adopt` is absent from the public controller.
+The Tab domain retains navigation, an abort signal, and bound actions per (Session, tab id). A private assembly callback adopts each Session's store, reconciles restored records immediately, and follows its commits. Reconstructing a Session store replaces its adoption, releasing the old subscription and cleanup reference. Only record removal or plugin unload aborts the signal; closing the sidebar and switching Sessions retain records, while undo restores a new occurrence. `useTabInfo()` composes framework-bound store and navigation hooks without manual component subscriptions or render-time record creation. `tab.actions` always target their own Session; `tab.visible` distinguishes bodies from titles and excludes background Sessions; foreground floating tabs remain visible when the sidebar closes. `adopt` is absent from the public controller.
+
+A type's `keepMounted: true` retains visited bodies across tab and Session changes, collapse, and docking. Each View supplies its stable hold callback through owner props, so rebuilding Session injection bindings does not release a body. Unvisited bodies are not mounted eagerly.
 
 Tab owners register `registerCloseHandler(kind, handler)` through an effect. A handler synchronously retains any background cleanup before allowing explicit close or replacement. The resource owner tracks completion and retry; the sidebar does not wait. A thrown handler preserves the tab. Collapse, presentation changes and plugin disposal do not invoke close handlers; the tab abort signal identifies occurrence disposal, not an explicit close.
 
@@ -132,7 +134,8 @@ None; this package neither assembles nor sends a provider request.
 
 - **Browser-local layout.** Layout does not synchronize between devices; provider-specific state requires its provider's recovery support.
 - **No surface without a session.** State is keyed by session id, so the hero screen shows nothing on the right.
-- **Hard-coded stacking.** The panel and the float host use fixed z-index values because the client has no z-index token layer yet.
+- **Hard-coded stacking.** The content tree uses a fixed stacking layer; floats reorder within it without raising that layer above menus.
+- **Retained Session deletion.** Catalog absence alone does not retire an initialized retained View; its tab lifetimes and plugin teardown own release.
 - **Undo is not exposed.** The recorded sequence is stepped only through the `@internal` service methods; product controls are deliberately absent.
 - **Titles are fixed at open time.** A type's `title(address)` is captured into the record; a live title comes only from the optional title seat.
 - **No content navigation stack.** Stepping back replays layout operations; an editor-style back/forward over visited content is not built.
diff --git a/packages/client/ui-sidebar-right/README.zh.md b/packages/client/ui-sidebar-right/README.zh.md
index 72d0c20817..7686d7afa8 100644
--- a/packages/client/ui-sidebar-right/README.zh.md
+++ b/packages/client/ui-sidebar-right/README.zh.md
@@ -56,7 +56,7 @@ kind: "package-reference"
 
 面板取会话区的底色与正文字号，而不是自成一层浮起的表面：它是页面的一列，不是压在页面上的卡片。
 
-`rightbar` 入口是 root 作用域的控制器。它读取 `usePanelInfo`，仅在选中会话界面时挂载 session 作用域的 `rightbar.session` 子树。切换到全局面板会隐藏右侧 Sidebar 并释放框架列宽，但不删除会话的 tab 状态。
+root 作用域的 `rightbar` 入口通过独立的 `rightbar.session` 子树渲染选中的 Session，以及拥有已初始化 `keepMounted` 正文的后台 Session。每个 View 拥有自身的 Session reference。只有前台 Conversation 上报框架列宽并绑定公共导航；其他子树保持隐藏，不删除 tab 状态。
 
 <a id="state"></a>
 ## 状态
@@ -67,9 +67,9 @@ kind: "package-reference"
 
 每个动作之后，套件的 settle planner 保证展开的停靠面有内容：最后一个 tab 被搬走或浮出的停靠格会被并掉；根格被清空时填入默认页。折叠的停靠面没有这种回填——会话以折叠且为空的停靠面开始，收起整列的关闭也让它保持为空——首次会展示空布局的那次展开才播种默认页。显式关闭遵循[默认页与关闭规则](#the-guide)。展开期间永远至少有一个 tab，永远没有空格——因此没有单独的「关闭格」手势。
 
-停靠面的最后一个 tab 还多带一条规则，由 store 的 `closeTab` 决定并经 `canCloseTab` 镜像给套件：作为唯一停靠 tab 的引导页不画关闭控件也不画菜单里的关闭项——它的 chip 呈安静样式，在没有扩展条目时次键按下也不弹出菜单——对它的编程式关闭什么都不记录；任何其它 tab 独自留下时，点击关闭会连同整列一起收起，记为一条历史，布局保持为空，直到下次展开时创建当时的默认页。浮动面板不参与这条规则：它们无论列是否展开都会渲染，其 tab 照常关闭。
+停靠面的最后一个 tab 还多带一条规则，由 store 的 `closeTab` 决定并经 `canCloseTab` 镜像给套件：作为唯一停靠 tab 的引导页不画关闭控件也不画菜单里的关闭项——它的 chip 呈安静样式，在没有扩展条目时次键按下也不弹出菜单——对它的编程式关闭什么都不记录；任何其它 tab 独自留下时，点击关闭会连同整列一起收起，记为一条历史，布局保持为空，直到下次展开时创建当时的默认页。浮动面板不参与这条规则：前台 Session 的浮窗无论列是否展开都会渲染，其 tab 照常关闭。
 
-store 将每个 Session 的布局、标签身份、选中项、分栏比例、浮窗矩形、呈现方式和身份计数以 JSON 保存到 localStorage 的 `dsh.sidebar-right.v1.<sessionId>`。刷新时在渲染标签正文前恢复布局；不同 Session 的布局独立。provider 根据保留的标签身份和资源地址恢复自身内容，包括[终端重连](../ui-sidebar-terminal/README.zh.md#use-this-package)。导航参数、资源内容和活动连接不属于布局状态。撤销历史只保留在内存中，刷新后清空。采用布局或启动探测前会校验保存字段类型、节点成员关系、选中项和身份计数；无效数据只清除对应 Session 的 key。存储失败时，当前布局仍可在内存中使用。同源窗口共享每个 Session 最后保存的布局；活动窗口在刷新前保留各自的当前布局。
+store 将每个 Session 的布局、标签身份、选中项、分栏比例、浮窗矩形、呈现方式和身份计数以 JSON 保存到 localStorage 的 `dsh.sidebar-right.v1.<sessionId>`。刷新时在渲染标签正文前恢复布局；不同 Session 的布局独立。provider 根据保留的标签身份和资源地址恢复自身内容，包括[终端重连](../ui-sidebar-terminal/README.zh.md#use-this-package)。导航参数、资源内容和活动连接不属于布局状态。撤销历史只保留在内存中，刷新后清空。采用布局或启动探测前会校验保存字段类型、节点成员关系、选中项、身份计数，以及单格或左右两格的停靠布局；无效数据只清除对应 Session 的 key。存储失败时，当前布局仍可在内存中使用。同源窗口共享每个 Session 最后保存的布局；活动窗口在刷新前保留各自的当前布局。
 
 `sidebarRight.openTabs` 发布所有已保存和已采用 Session 的打开标签元数据，并保持快照引用稳定。启动时读取布局 key，不挂载非当前内容、pin 文件或激活 Agent。已采用的 store 在标签成员变化时更新自己的元数据，永久清除的 scope 删除对应记录。其他窗口写入 storage 不会覆盖当前窗口的活动成员关系。provider 使用该清单恢复自己的资源生命周期。
 
@@ -78,7 +78,7 @@ store 将每个 Session 的布局、标签身份、选中项、分栏比例、
 
 tab 类型分两阶段注册，随包发布的引导类型走的正是别的包的类型走的同一条公开路径（`ui-sidebar-documentpreview` 是活的证明）。两个阶段都在类型自己的 `ctx.effect` 里，因此注册与创建它的插件同生共死。
 
-1. **类型**——`ctx.sidebarRightTabs.register({ id, kind, patterns?, priority?, canOpen?, title, guide? })`，一份没有运行时钩子的静态声明，返回 disposer。`id` 是这个实现在 tab 系统里的身份，在全部注册中唯一（包名是天然取值；随包引导页是 `@deepseek-ai/dsh-client-ui-sidebar-right/guide`）：一旦 extension 可以接管 builtin 的 kind，kind 就不再唯一，所以实现要自己命名，同一 `id` 的第二次注册会 throw。资源类型给出 `patterns`，即作用于 `dsh-resource://` 地址的 glob：含 `:` 的匹配整个地址（`dsh-resource://file/**`）；不含的匹配 URI 路径的任意深度且忽略大小写（`*.md`），不是 URI 的地址不匹配任何这类模式。页类型——引导页、文件树——不给出模式，按 kind 打开。`canOpen(address)` 否决一次命中。`title(address)` 是 tab chip 的文字，在 tab 打开时捕获。`guide` 列出引导页的入口框；选中一个即把贡献它的类型作为页打开。一个 `kind` 最多承载一份 `builtin` 与一份 `extension` 注册（extension 生效；它离开后 builtin 恢复）；kind 上的其它任何撞名都 throw。`id` 同时也是该类型正文与标题注册时用的 key，因此 extension 与它接管的 builtin 各占一个格位，席位渲染生效的那个。
+1. **类型**——`ctx.sidebarRightTabs.register({ id, kind, patterns?, priority?, canOpen?, title, guide?, keepMounted? })`，一份没有运行时钩子的静态声明，返回 disposer。`id` 是这个实现在 tab 系统里的身份，在全部注册中唯一（包名是天然取值；随包引导页是 `@deepseek-ai/dsh-client-ui-sidebar-right/guide`）：一旦 extension 可以接管 builtin 的 kind，kind 就不再唯一，所以实现要自己命名，同一 `id` 的第二次注册会 throw。资源类型给出 `patterns`，即作用于 `dsh-resource://` 地址的 glob：含 `:` 的匹配整个地址（`dsh-resource://file/**`）；不含的匹配 URI 路径的任意深度且忽略大小写（`*.md`），不是 URI 的地址不匹配任何这类模式。页类型——引导页、文件树——不给出模式，按 kind 打开。`canOpen(address)` 否决一次命中。`title(address)` 是 tab chip 的文字，在 tab 打开时捕获。`guide` 列出引导页的入口框；选中一个即把贡献它的类型作为页打开。一个 `kind` 最多承载一份 `builtin` 与一份 `extension` 注册（extension 生效；它离开后 builtin 恢复）；kind 上的其它任何撞名都 throw。`id` 同时也是该类型正文与标题注册时用的 key，因此 extension 与它接管的 builtin 各占一个格位，席位渲染生效的那个。
 2. **正文**——`ctx.slots.register({ name: 'sidebar.right.pane.tab', key: definition.id }, Body)` 通过框架注入的 `useTabInfo()` 读取 `{ sidebar, panel, tab }`。`sidebar` 提供开合与全屏信息，`panel.id` 命名所在格，`tab` 包含原记录字段、`visible`、`navigation`、`signal` 和 `actions`。这些字段不再作为平铺owner props传入；类型自己的store仍使用 `useStore`/`actions`。可选标题注册及引导替换共享该hook；未注册标题时使用打开时保存的文本。
 
 由哪个类型打开资源遵循编辑器解析器的惯例：`patterns` 命中的类型先按 `priority` 档排序——`extension`（产品外的类型，最高档，也是未命名时的默认）、`builtin`、`fallback`（任何更具体的类型都应胜过的通用查看器）——再按命中模式的长度，再按注册顺序；`canOpen` 会剔除候选。各档是字符串字面量，因此别的包里的类型不需要从这里做运行时导入。`candidates(address)` 返回排序，`claim(address, kind?)` 返回决定；指定 `kind` 时跳过它的 glob 但保留它的 `canOpen`。
@@ -92,12 +92,14 @@ tab 类型分两阶段注册，随包发布的引导类型走的正是别的包
 
 `preferNewPane: true` 会先按普通的两格上限与空间规则尝试分割目标停靠格，无法分栏时回退到该格。`replaceTab` 优先并会禁用这项偏好。
 
-`close(tabId)` 关闭一个 tab；`active()` 读取活动 tab。`isExpanded()` 与 `toggleExpanded()` 读取并驱动该列的展开；形态切换是面板自己的控件，不属于这个接口。布局操作供以编程方式安排该列的调用方使用，每个都像它替代的手势一样被记录：`focus(tabId)` 聚焦一个 tab 及其格；`split(paneId?)` 在与 tab 条控件相同的格预算与空间规则下分栏一个停靠格（默认活跃格），返回新格的 id，做不到时返回 `undefined`——且不记录任何东西；`float(tabId, rect?)` 把停靠 tab 浮出为浮窗；`dock(paneId)` 把浮窗放回活跃停靠格。不存在的 tab 或格、或已处于调用目标状态的，都原样不动。该接口只暴露操作：没有布局快照、没有操作日志、没有按地址查找。`_undo()` / `_redo()` 步进已挂载停靠面的历史；它们是 `@internal`——序列没有面向用户的控件，这两个只为测试存在。命令需要一个已挂载的会话停靠面；没有时它们 throw，而不是写进一个没人绘制的面里。
+`close(tabId)` 关闭一个 tab；`active()` 读取活动 tab。`isExpanded()` 与 `toggleExpanded()` 读取并驱动该列的展开；形态切换是面板自己的控件，不属于这个接口。布局操作供以编程方式安排该列的调用方使用，每个都像它替代的手势一样被记录：`focus(tabId)` 聚焦一个 tab 及其格；`split(paneId?)` 在与 tab 条控件相同的格预算与空间规则下分栏一个停靠格（默认活跃格），返回新格的 id，做不到时返回 `undefined`——且不记录任何东西；`float(tabId, rect?)` 把停靠 tab 浮出为浮窗；`dock(paneId)` 把浮窗放回活跃停靠格。不存在的 tab 或格、或已处于调用目标状态的，都原样不动。该接口只暴露操作：没有布局快照、没有操作日志、没有按地址查找。`_undo()` / `_redo()` 步进已挂载停靠面的历史；它们是 `@internal`——序列没有面向用户的控件，这两个只为测试存在。命令需要一个已挂载的会话停靠面；没有时它们 throw，而不是写进一个没人绘制的面里。`mounted` 是「席位正在屏幕上的那个会话」的可观察值，全局面板替代 Conversation 或没有选中会话时为 `undefined`。要在自己的挂载 effect 里打开内容的组件通过绑定的 hook 读取它，并在它有值后再行动：框架把 Conversation 列挂载在这个席位之前，而席位在同一次提交的 passive effect 里才发布绑定，一个假定席位已绑定的 effect 会先运行并 throw。计划审阅的自动打开就是这样读取它的。
 
 <a id="the-tab-domain"></a>
 ## Tab 域
 
-Tab 域按（Session，Tab id）保留导航、中止信号与绑定动作。私有装配回调采用各 Session 的 store，立即对齐恢复的记录，再跟随其提交。同一 Session 的 store 重建会替换其 `adopt` 注册，同时释放旧订阅与清理引用。记录消失或插件卸载才中止 signal，收起和切会话不销毁记录；undo 恢复的是新 occurrence。`useTabInfo()` 组合框架绑定的 store 与导航 hook，不在组件中手写订阅或在渲染时创建记录。`tab.actions` 始终作用于自己的会话；`tab.visible` 区分正文与标题，浮窗不受整栏收起影响。`adopt` 不在公开控制器上。
+Tab 域按（Session，Tab id）保留导航、中止信号与绑定动作。私有装配回调采用各 Session 的 store，立即对齐恢复的记录，再跟随其提交。同一 Session 的 store 重建会替换其 `adopt` 注册，同时释放旧订阅与清理引用。记录消失或插件卸载才中止 signal，收起和切会话不销毁记录；undo 恢复的是新 occurrence。`useTabInfo()` 组合框架绑定的 store 与导航 hook，不在组件中手写订阅或在渲染时创建记录。`tab.actions` 始终作用于自己的会话；`tab.visible` 区分正文与标题，并排除后台 Session；前台浮窗不受整栏收起影响。`adopt` 不在公开控制器上。
+
+类型声明 `keepMounted: true` 后，已访问正文会在切 tab、切 Session、收起和停靠切换期间保留。每个 View 通过 owner props 提供自身稳定的持有回调，因此 Session injection binding 重建不会释放正文。未访问的正文不会提前挂载。
 
 标签页所有者通过 effect 注册 `registerCloseHandler(kind, handler)`。handler 在允许显式关闭或替换前同步保存后台清理任务。资源所有者跟踪完成和重试，侧栏不等待清理。handler 抛错时保留标签页。折叠、展示方式改变和插件卸载不调用关闭 handler；tab abort signal 标识 occurrence 卸载，不代表显式关闭。
 
@@ -132,7 +134,8 @@ Tab 域按（Session，Tab id）保留导航、中止信号与绑定动作。私
 
 - **布局保存在当前浏览器。** 布局不跨设备同步；provider 专属状态需要由该 provider 支持恢复。
 - **没有会话就没有停靠面。** 状态按会话 id 键控，因此 hero 画面右侧什么都不显示。
-- **硬编码的层叠。** 面板与浮窗宿主使用固定的 z-index 值，因为客户端还没有 z-index token 层。
+- **硬编码的层叠。** 内容树使用固定层叠层；浮窗在该层内重排，不会把整层抬到菜单之上。
+- **保活 Session 的删除。** 仅从目录消失不会使已初始化的保活 View 退休；释放由 tab 生命周期和插件卸载负责。
 - **未暴露撤销。** 记录的序列只能通过 `@internal` 服务方法步进；产品控件是有意缺席的。
 - **标题在打开时固定。** 类型的 `title(address)` 被捕获进记录；会变的标题只来自可选的标题席位。
 - **没有内容导航栈。** 后退回放的是布局操作；编辑器式的「已访问内容」前进/后退尚未构建。
diff --git a/packages/client/ui-sidebar-right/src/client/contract/slots.ts b/packages/client/ui-sidebar-right/src/client/contract/slots.ts
index 6095752b27..28b026a3ad 100644
--- a/packages/client/ui-sidebar-right/src/client/contract/slots.ts
+++ b/packages/client/ui-sidebar-right/src/client/contract/slots.ts
@@ -25,7 +25,7 @@ import type { RightbarOwnerProps } from '@deepseek-ai/dsh-client-ui-layout/clien
 // The locale plugin's own merge carries the shared `common` vocabulary that the
 // lookup chain consults after this namespace misses.
 import type {} from '@deepseek-ai/dsh-client-locale/client'
-import type { PaneId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
+import type { PaneId, TabId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
 import type { SlotHookFactory } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TabHookContext } from '../tab-info.ts'
 import type { SidebarRightKey } from '../locales.ts'
@@ -39,7 +39,15 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 
   interface SlotMap {
     /** Session content selected by the root-scoped right Sidebar controller. */
-    'rightbar.session': { kind: 'single'; scope: 'session'; owner: RightbarOwnerProps }
+    'rightbar.session': {
+      kind: 'single'
+      scope: 'session'
+      owner: RightbarOwnerProps & {
+        readonly active: boolean
+        /** @param tabId - retained body. @param signal - tab occurrence lifetime. @returns releases the View-owned hold. */
+        readonly retainTab: (tabId: TabId, signal: AbortSignal) => () => void
+      }
+    }
     /**
      * One tab's body, dispatched with the `id` of the type in force for
      * `tab.kind`. A tab type registers here under its definition's `id` and
@@ -148,7 +156,7 @@ export interface SidebarRightTabInfo {
   }
   readonly panel: { readonly id: PaneId }
   readonly tab: TabRecord & {
-    /** Docked bodies need an expanded sidebar and an active tab; expanded titles include inactive tabs. Floats stay visible. */
+    /** Only the foreground Session is visible. Docked bodies also require expansion and selection; its floats survive collapse. */
     readonly visible: boolean
     readonly navigation: SidebarRightTabNavigation
     /** Aborted only when the record disappears or this plugin unloads, not on hide or session switch. */
diff --git a/packages/client/ui-sidebar-right/src/client/index.ts b/packages/client/ui-sidebar-right/src/client/index.ts
index c50c757f23..19c307c063 100644
--- a/packages/client/ui-sidebar-right/src/client/index.ts
+++ b/packages/client/ui-sidebar-right/src/client/index.ts
@@ -33,7 +33,8 @@ import { GuideBody, type GuideInjected } from './tabs/guide/GuideBody.tsx'
 import { GuideTitle } from './tabs/guide/GuideTitle.tsx'
 import { ExpandButton } from './shell/ExpandButton.tsx'
 import { RightbarSeat, type SidebarRightInjected } from './shell/SidebarRight.tsx'
-import { RightbarRoot } from './shell/RightbarRoot.tsx'
+import { RightbarRoot, type RightbarRootInjected } from './shell/RightbarRoot.tsx'
+import { SidebarSessionViews } from './session-views.ts'
 import { createSidebarRightController, type SidebarRightController } from './service.ts'
 import { SidebarRightTabRegistry } from './tab-registry.ts'
 import { createSidebarRightStore } from './stores.ts'
@@ -74,7 +75,7 @@ export type { SidebarRightOpenTab } from './tab-inventory.ts'
 const NS = 'sidebarRight'
 
 /** Required browser services: the slot registry, the frame's panel actions, copy, and the resource model. */
-export const inject = ['slots', 'layout', 'locale', 'resources']
+export const inject = ['slots', 'layout', 'locale', 'resources', 'sessions', 'uiSession']
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -102,6 +103,14 @@ export function apply(ctx: ClientContext): void {
   // its own apply top level for the same reason.
   const t = ctx.locale.bind(NS)
   const tabs = new SidebarRightTabRegistry(ctx)
+  const views = new SidebarSessionViews(ctx.sessions)
+  ctx.effect(() => {
+    const current = ctx.uiSession.adapter.current
+    const sync = (): void => { views.select(current.getSnapshot().key as SessionId | undefined) }
+    const unsubscribe = current.subscribe(sync)
+    sync()
+    return () => { unsubscribe(); views.dispose() }
+  }, 'ui-sidebar-right: retained Session views')
   const { controller, adopt, forget } = createSidebarRightController(
     tabs,
     (address, signal) => { ctx.resources.pin(address, signal) },
@@ -156,6 +165,10 @@ export function apply(ctx: ClientContext): void {
       yield ctx.slots.register({
         name: 'rightbar',
         children: { 'rightbar.session': { kind: 'single', scope: 'session' } },
+        inject: (): RightbarRootInjected => ({
+          hooks: { views: views.source },
+          mountView: reference => views.mount(reference),
+        }),
       }, RightbarRoot)
       yield ctx.slots.register({
         name: 'rightbar.session',
diff --git a/packages/client/ui-sidebar-right/src/client/persistence.ts b/packages/client/ui-sidebar-right/src/client/persistence.ts
index 9fc941a837..7335573d97 100644
--- a/packages/client/ui-sidebar-right/src/client/persistence.ts
+++ b/packages/client/ui-sidebar-right/src/client/persistence.ts
@@ -38,7 +38,8 @@ function validateReferences(value: z.infer<typeof surface>): void {
     if (visited.has(id) || entry === undefined) reject()
     visited.add(id)
     if (entry.kind === 'split') {
-      if (host !== 'dock' || entry.children.length !== entry.sizes.length
+      if (host !== 'dock' || id !== layout.rootId || entry.axis !== 'row' || entry.children.length !== 2
+        || entry.children.length !== entry.sizes.length
         || Math.abs(entry.sizes.reduce((sum, size) => sum + size, 0) - 1) > 1e-9) reject()
       pending.push(...entry.children.map(id => ({ id, host })))
     } else {
diff --git a/packages/client/ui-sidebar-right/src/client/service.ts b/packages/client/ui-sidebar-right/src/client/service.ts
index 9fb5aaf413..b7eaa2d4c8 100644
--- a/packages/client/ui-sidebar-right/src/client/service.ts
+++ b/packages/client/ui-sidebar-right/src/client/service.ts
@@ -7,7 +7,10 @@
  * session id, bound actions, its surface — for exactly as long as it is mounted,
  * and every command on the public face goes through that binding; a command
  * arriving with no seat mounted has no session to act on and fails loudly rather
- * than writing into a surface nobody is drawing. And the plugin adopts each
+ * than writing into a surface nobody is drawing. `mounted` publishes that
+ * binding's session as an observable, so a consumer that wants to open content
+ * as soon as a seat is on screen subscribes to it instead of assuming one is
+ * bound when its own effect runs. And the plugin adopts each
  * session's store instance as the runtime mints it, so the controller reaches
  * any session's store by id and syncs the Tab domain from that store's commits.
  *
@@ -28,6 +31,7 @@
  * callers use the service's navigation methods.
  */
 import { randomUUID } from '@deepseek-ai/dsh-util-crypto'
+import { createSnapshotStore, type ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
 import type { FloatRect, PaneId, TabId, TabRecord } from '@deepseek-ai/dsh-client-ui-dockkit'
 import { activeDockPaneId, canSplit, findContentTab, dockPaneIds, findTabPane, getPane } from '@deepseek-ai/dsh-client-ui-dockkit'
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
@@ -148,6 +152,15 @@ export type SidebarRightCloseHandler = (sessionId: SessionId, tab: TabRecord) =>
 
 /** The outward right-Sidebar face (`ctx.sidebarRight`). */
 export interface ISidebarRight {
+  /**
+   * The session whose seat is mounted, or `undefined` while no seat is on
+   * screen (a global panel is active, or no session is selected). Moves when a
+   * seat binds or releases, so a component that opens content from its own
+   * mount effect reads it through a bound hook and acts once it is defined:
+   * the frame mounts the Conversation column ahead of the seat, and the seat
+   * publishes its binding from a passive effect of the same commit.
+   */
+  readonly mounted: ObservableSnapshot<SessionId | undefined>
   /**
    * Open a resource: claim it, place it, reveal the column, record the navigation.
    *
@@ -216,6 +229,9 @@ export interface ISidebarRight {
 export class SidebarRightController implements ISidebarRight {
   /** Open tab metadata across saved and adopted Sessions, independent of visible seats. */
   readonly openTabs: SidebarTabInventory['source']
+  private readonly mountedSession = createSnapshotStore<SessionId | undefined>(undefined)
+  /** The mounted seat's session; see {@link ISidebarRight.mounted}. */
+  readonly mounted: ObservableSnapshot<SessionId | undefined> = this.mountedSession
   private binding: SidebarRightBinding | undefined
   private readonly closeHandlers = new Map<string, SidebarRightCloseHandler>()
 
@@ -271,13 +287,22 @@ export class SidebarRightController implements ISidebarRight {
    */
   bind(binding: SidebarRightBinding): () => void {
     this.binding = binding
+    this.publishMounted()
     return () => {
       // A newer seat may already have taken over; only the binding that is
       // still ours may be cleared.
-      if (this.binding === binding) this.binding = undefined
+      if (this.binding !== binding) return
+      this.binding = undefined
+      this.publishMounted()
     }
   }
 
+  /** Publish the mounted session only when it changes; a republished binding for the same session is silent. */
+  private publishMounted(): void {
+    const next = this.binding?.sessionId
+    if (this.mountedSession.getSnapshot() !== next) this.mountedSession.set(next)
+  }
+
   /**
    * Open a resource: claim it, place it, reveal the column, record the navigation.
    * @param address - a `dsh-resource://<type>/…` address.
@@ -426,7 +451,7 @@ export class SidebarRightController implements ISidebarRight {
    * @returns the record, or `undefined` with no mounted surface.
    */
   active(): TabRecord | undefined {
-    const layout = this.mounted()?.layout
+    const layout = this.mountedSurface()?.layout
     if (layout === undefined) return undefined
     const { activeTabId } = getPane(layout, layout.activePaneId)
     return Object.values(layout.tabs).find(tab => tab.id === activeTabId)
@@ -437,7 +462,7 @@ export class SidebarRightController implements ISidebarRight {
    * @returns `true` while expanded; `false` while collapsed or with no mounted surface.
    */
   isExpanded(): boolean {
-    return this.mounted()?.layout.expanded ?? false
+    return this.mountedSurface()?.layout.expanded ?? false
   }
 
   /** Collapse an expanded column, or expand a collapsed one. */
@@ -452,7 +477,7 @@ export class SidebarRightController implements ISidebarRight {
    */
   focus(tabId: TabId): void {
     const { sessionId, actions } = this.require()
-    if (this.mounted()?.layout.tabs[tabId] === undefined) return
+    if (this.mountedSurface()?.layout.tabs[tabId] === undefined) return
     actions.focusTab(sessionId, tabId)
   }
 
@@ -463,7 +488,7 @@ export class SidebarRightController implements ISidebarRight {
    */
   split(paneId?: PaneId): PaneId | undefined {
     const { sessionId, actions, canSplitPane } = this.require()
-    const layout = this.mounted()?.layout
+    const layout = this.mountedSurface()?.layout
     if (layout === undefined) return undefined
     const target = paneId ?? activeDockPaneId(layout)
     const node = layout.nodes[target]
@@ -481,7 +506,7 @@ export class SidebarRightController implements ISidebarRight {
    */
   float(tabId: TabId, rect?: FloatRect): void {
     const { sessionId, actions } = this.require()
-    const layout = this.mounted()?.layout
+    const layout = this.mountedSurface()?.layout
     if (layout === undefined || layout.tabs[tabId] === undefined) return
     if (findTabPane(layout, tabId).host !== 'dock') return
     actions.floatTab(sessionId, tabId, rect)
@@ -493,7 +518,7 @@ export class SidebarRightController implements ISidebarRight {
    */
   dock(paneId: PaneId): void {
     const { sessionId, actions } = this.require()
-    const node = this.mounted()?.layout.nodes[paneId]
+    const node = this.mountedSurface()?.layout.nodes[paneId]
     if (node === undefined || node.kind !== 'pane' || node.host !== 'float') return
     actions.unfloatPane(sessionId, paneId)
   }
@@ -520,7 +545,7 @@ export class SidebarRightController implements ISidebarRight {
   }
 
   /** The mounted session's surface; `undefined` without a seat or before its first open. */
-  private mounted(): SurfaceState | undefined {
+  private mountedSurface(): SurfaceState | undefined {
     const { binding } = this
     return binding === undefined ? undefined : binding.surfaces[binding.sessionId]
   }
diff --git a/packages/client/ui-sidebar-right/src/client/session-view.ts b/packages/client/ui-sidebar-right/src/client/session-view.ts
new file mode 100644
index 0000000000..f36bb3f977
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/session-view.ts
@@ -0,0 +1,91 @@
+/** One Sidebar view's Session reference, retained bodies and committed mount lifetime. */
+import type { ISessions, SessionReference } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+  interface SessionReferenceSourceMap {
+    sidebarView: unknown
+  }
+}
+
+/** Owns its reference until retirement finishes or the Sidebar plugin shuts down. */
+export class SidebarSessionView {
+  /** Session reference released exclusively by this View. */
+  readonly reference: SessionReference
+  private readonly tabs = new Map<TabId, number>()
+  private mounts = 0
+  private retired = false
+  private disposed = false
+
+  /**
+   * @param sessionId - Session displayed by this view.
+   * @param sessions - allocator for this view's independent reference.
+   * @param onDispose - removes this view from the collection's index before reference release.
+   * @param onTabRelease - reconsiders retention after a body releases its hold.
+   */
+  constructor(
+    readonly sessionId: SessionId,
+    sessions: ISessions,
+    private readonly onDispose: (view: SidebarSessionView) => void,
+    private readonly onTabRelease: (view: SidebarSessionView) => void,
+  ) {
+    this.reference = sessions.retain(sessionId, { source: 'sidebarView' })
+    void this.reference.ready.catch((error: unknown) => { console.error('Sidebar Session opening failed:', error) })
+  }
+
+  /** Whether an initialized retained body still needs this view. */
+  get hasRetainedTabs(): boolean {
+    return this.tabs.size > 0
+  }
+
+  /**
+   * Keep a retired View's reference until its committed roots finish unmounting.
+   * @returns cleanup to call once for this root; the final cleanup releases a retired View.
+   */
+  mount(): () => void {
+    this.mounts += 1
+    return () => {
+      this.mounts -= 1
+      if (this.retired && this.mounts === 0) this.dispose()
+    }
+  }
+
+  /**
+   * Hold an initialized body until unmount or occurrence cancellation.
+   * @param tabId - initialized body identity.
+   * @param signal - occurrence lifetime; closing and undoing a tab creates a new lifetime.
+   * @returns idempotent release of this body's hold.
+   */
+  readonly retainTab = (tabId: TabId, signal: AbortSignal): (() => void) => {
+    if (signal.aborted || this.disposed) return () => {}
+    this.tabs.set(tabId, (this.tabs.get(tabId) ?? 0) + 1)
+    let held = true
+    const release = (): void => {
+      if (!held) return
+      held = false
+      signal.removeEventListener('abort', release)
+      const count = this.tabs.get(tabId) as number
+      if (count === 1) this.tabs.delete(tabId)
+      else this.tabs.set(tabId, count - 1)
+      this.onTabRelease(this)
+    }
+    signal.addEventListener('abort', release, { once: true })
+    return release
+  }
+
+  /** End a withdrawn view after its existing committed mounts finish. */
+  retire(): void {
+    this.retired = true
+    if (this.mounts === 0) this.dispose()
+  }
+
+  /** Release once; plugin shutdown does not wait for remaining React mounts. */
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.retired = true
+    this.onDispose(this)
+    this.reference.release()
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/session-views.ts b/packages/client/ui-sidebar-right/src/client/session-views.ts
new file mode 100644
index 0000000000..232b310755
--- /dev/null
+++ b/packages/client/ui-sidebar-right/src/client/session-views.ts
@@ -0,0 +1,80 @@
+/** Selection and retention policy for independently owned Sidebar Session views. */
+import type { ISessions, SessionReference } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { SidebarSessionView } from './session-view.ts'
+
+/** The reference is exclusively a framework SessionProvider target, not a business-component service. */
+export interface SidebarSessionViewSnapshot {
+  readonly sessionId: SessionId
+  readonly reference: SessionReference
+  readonly selected: boolean
+  /** Stable for this View's lifetime, independently of Session injection bindings. */
+  readonly retainTab: SidebarSessionView['retainTab']
+}
+
+/** Selects and retires views; the Sidebar plugin's injected dependencies own global teardown. */
+export class SidebarSessionViews {
+  /** Selected and retained View targets observed by the root renderer. */
+  readonly source = createSnapshotStore<readonly SidebarSessionViewSnapshot[]>([])
+  private readonly views = new Map<SessionId, SidebarSessionView>()
+  private readonly viewsByReference = new Map<SessionReference, SidebarSessionView>()
+  private selected: SessionId | undefined
+  private closed = false
+
+  constructor(private readonly sessions: ISessions) {}
+
+  /**
+   * Change the foreground Session while preserving retained background Views.
+   * @param sessionId - main selection, or absence.
+   */
+  select(sessionId: SessionId | undefined): void {
+    if (this.closed || this.selected === sessionId) return
+    this.selected = sessionId
+    if (sessionId !== undefined && !this.views.has(sessionId)) {
+      const view = new SidebarSessionView(sessionId, this.sessions, (disposed) => {
+        this.viewsByReference.delete(disposed.reference)
+      }, (released) => { this.prune(released) })
+      this.views.set(sessionId, view)
+      this.viewsByReference.set(view.reference, view)
+    }
+    for (const view of this.views.values()) this.prune(view)
+    this.publish()
+  }
+
+  /**
+   * Bind a committed root; release retired references after that root unmounts.
+   * @param reference - framework target published by this owner.
+   * @returns releases this committed mount.
+   */
+  mount(reference: SessionReference): () => void {
+    const view = this.viewsByReference.get(reference)
+    if (view === undefined) {
+      if (this.closed) return () => {}
+      throw new Error('Sidebar Session view reference is no longer owned')
+    }
+    return view.mount()
+  }
+
+  /** Plugin shutdown releases every view, including any awaiting a React unmount. */
+  dispose(): void {
+    this.closed = true
+    this.views.clear()
+    this.source.set([])
+    for (const view of this.viewsByReference.values()) view.dispose()
+  }
+
+  private prune(view: SidebarSessionView): void {
+    if (view.sessionId === this.selected || view.hasRetainedTabs || this.views.get(view.sessionId) !== view) return
+    this.views.delete(view.sessionId)
+    // Render targets must be withdrawn before an unmounted view can release its reference.
+    this.publish()
+    view.retire()
+  }
+
+  private publish(): void {
+    this.source.set([...this.views.values()].sort((a, b) => a.sessionId.localeCompare(b.sessionId)).map(view => ({
+      sessionId: view.sessionId, reference: view.reference, selected: view.sessionId === this.selected, retainTab: view.retainTab,
+    })))
+  }
+}
diff --git a/packages/client/ui-sidebar-right/src/client/shell/RightbarRoot.tsx b/packages/client/ui-sidebar-right/src/client/shell/RightbarRoot.tsx
index 46420e5970..26bedb1d18 100644
--- a/packages/client/ui-sidebar-right/src/client/shell/RightbarRoot.tsx
+++ b/packages/client/ui-sidebar-right/src/client/shell/RightbarRoot.tsx
@@ -1,20 +1,38 @@
 /** Root-scoped controller for the right Sidebar's Session content. */
-import type { PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import { useLayoutEffect } from 'react'
+import type { HostObservable, InjectFace, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionReference } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SidebarSessionViewSnapshot } from '../session-views.ts'
 import type {} from '../contract/slots.ts'
+import css from './SidebarRight.module.css'
+
+/** Root-only retained Session targets and their committed mount lifetimes. */
+export interface RightbarRootInjected {
+  readonly hooks: { readonly views: HostObservable<readonly SidebarSessionViewSnapshot[]> }
+  readonly mountView: (reference: SessionReference) => () => void
+}
+
+type RootProps = PropsRuntime<'rightbar'> & PropsRenderSlots<'rightbar.session'> & InjectFace<RightbarRootInjected>
+
+function SessionView({ view, visible, SessionProvider, renderSlot, mountView, width, viewportWidth, canShow }:
+  Pick<RootProps, 'SessionProvider' | 'renderSlot' | 'mountView' | 'width' | 'viewportWidth' | 'canShow'>
+  & { readonly view: SidebarSessionViewSnapshot; readonly visible: boolean }) {
+  useLayoutEffect(() => mountView(view.reference), [mountView, view.reference])
+  const active = visible && view.selected
+  return <div className={css.session} hidden={!active} data-sidebar-right-session={view.sessionId}>
+    <SessionProvider session={view.reference}>
+      {renderSlot('rightbar.session', { width, viewportWidth, canShow, active, retainTab: view.retainTab })}
+    </SessionProvider>
+  </div>
+}
 
 /**
- * Render the Session-bound Sidebar only while the Conversation is selected.
- * @param props - frame geometry, panel selection, and the authorized Session renderer.
- * @returns the current Session's right Sidebar, or no content for a global panel.
+ * Keep independent Session subtrees and hide those outside the selected Conversation.
+ * @param props - frame geometry, view targets and the authorized Session renderer.
+ * @returns the foreground and retained background Sidebars.
  */
-export function RightbarRoot({
-  usePanelInfo, SessionProvider, renderSlot, width, viewportWidth, canShow,
-}: PropsRuntime<'rightbar'> & PropsRenderSlots<'rightbar.session'>) {
+export function RightbarRoot({ usePanelInfo, useViews, ...props }: RootProps) {
   const visible = usePanelInfo(info => info.activePanelId === null)
-  if (!visible) return null
-  return (
-    <SessionProvider>
-      {renderSlot('rightbar.session', { width, viewportWidth, canShow })}
-    </SessionProvider>
-  )
+  const views = useViews(value => value)
+  return <>{views.map(view => <SessionView key={view.sessionId} {...props} view={view} visible={visible} />)}</>
 }
diff --git a/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css
index 890b897cc8..7c7833556f 100644
--- a/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css
+++ b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.module.css
@@ -9,7 +9,7 @@
  * One content tree uses the frame's width normally and fills the viewport in
  * fullscreen. The frame retains a shown wide panel's track in both modes.
  *
- * Hidden, the panel is translated off the frame's right edge rather than
+ * Hidden, docked Grid items translate off the frame's right edge rather than
  * unmounted, so showing and hiding are one slide in both presentations. The
  * transform rides the same variables as the frame's track transition (ui-theme
  * base.css); while squeezing, the panel's left edge and the conversation's right
@@ -17,30 +17,45 @@
  * is out of reach once off-edge, and flips back before the slide starts.
  *
  * The normal panel is below frame overlays (20); fullscreen (40) covers the
- * frame and remains below independently floating panels (60).
+ * frame and remains below independently floating panels (60). The common
+ * content root owns no stacking context or transform.
  */
+.session {
+  display: contents;
+}
+
+.session[hidden] {
+  display: none;
+}
+
 .panel {
+  --dsh-dockkit-dock-layer: 10;
+  --dsh-dockkit-float-layer: 60;
   position: absolute;
   top: 0;
   right: 0;
   bottom: 0;
-  z-index: 10;
   display: flex;
   flex-direction: column;
   min-width: 0;
-  /* The same ground as the conversation: this is a column of the page, not a
-     raised surface. The edge is the weight of the kit's split dividers inside
-     (ui-dockkit `.divider`), so the panel's outline and its inner rules match. */
-  background: var(--dsw-alias-bg-base);
-  border-left: 0.5px solid var(--dsw-alias-border-l4);
-  transform: translateX(100%);
+  pointer-events: none;
+}
+
+/* Only docked Grid items slide. Their common ancestor remains untransformed,
+   unclipped and without a stacking context, so fixed floating children escape. */
+.panel :global([data-dockkit-host='dock']),
+.panel :global([data-dockkit-empty]),
+.panel :global([data-dockkit-divider]) {
+  transform: translateX(var(--dsh-sidebar-width));
   visibility: hidden;
   transition:
     transform var(--ds-transition-duration-slow) var(--ds-ease-in-out),
     visibility 0s linear var(--ds-transition-duration-slow);
 }
 
-.panel[data-sidebar-right-open] {
+.panel[data-sidebar-right-open] :global([data-dockkit-host='dock']),
+.panel[data-sidebar-right-open] :global([data-dockkit-empty]),
+.panel[data-sidebar-right-open] :global([data-dockkit-divider]) {
   transform: none;
   visibility: visible;
   transition: transform var(--ds-transition-duration-slow) var(--ds-ease-in-out);
@@ -60,15 +75,12 @@
 }
 
 .panel[data-sidebar-right-panel='fullscreen'] {
-  position: fixed;
-  inset: 0;
-  z-index: 40;
-  border: none;
+  --dsh-dockkit-dock-layer: 40;
 }
 
 /* No whole-box subtraction here: Electron drag regions are window geometry,
    not stacking, so the frame's leading band does keep acting through this
-   fixed overlay — but the kit already subtracts every box that must stay
+   fullscreen content — but the kit already subtracts every box that must stay
    usable (tabs, strip-end chrome, pane bodies, dividers; ui-dockkit), and
    ui-web base.css subtracts interactive elements and portalled overlays.
    What remains of the band under the strips' blank runs is the window drag
@@ -79,10 +91,10 @@
 
 /* Windows keeps caption controls above fullscreen file and terminal panels. */
 :global([data-windows-titlebar]) .panel[data-sidebar-right-panel='fullscreen'] {
-  overflow: hidden;
-  left: var(--dsh-windows-sidebar-width);
-  max-width: calc(100% - var(--dsh-windows-sidebar-width));
-  top: var(--dsh-windows-titlebar-height);
+  max-width: calc(100vw - var(--dsh-windows-sidebar-width));
+}
+
+:global([data-windows-titlebar]) .panel[data-sidebar-right-panel='fullscreen'] :global([data-dockkit-column='0'][data-dockkit-pane]) {
   border-radius: var(--dsh-windows-content-radius) 0 0 0;
   corner-shape: round;
 }
@@ -90,27 +102,27 @@
 /* macOS fullscreen: the panel reaches the window's top-left corner, where the
    hiddenInset traffic lights (x 16..~68) float over the first pane's tab
    strip. Widen that strip's start inset (dockkit publishes the variable);
-   panes below or right of a divider sit clear of the lights, and every
-   non-first split cell resets the inherited value for its whole subtree. */
-:global([data-platform='darwin']) .panel[data-sidebar-right-panel='fullscreen'] .panelBody {
+   the second Grid column sits clear of the lights and uses the ordinary inset. */
+:global([data-platform='darwin']) .panel[data-sidebar-right-panel='fullscreen'] :global([data-dockkit-host='dock'][data-dockkit-column='0']) {
   /* Lights end near x 68; 88 leaves the same 20px of air the conversation
      header's leading controls keep after them (ui-sidebar HeaderLeadingControls). */
   --dsh-dockkit-strip-inline-start: 88px;
 }
 
-:global([data-platform='darwin']) .panel[data-sidebar-right-panel='fullscreen'] .panelBody :global([data-dockkit-cell]):not(:first-child) {
+:global([data-platform='darwin']) .panel[data-sidebar-right-panel='fullscreen'] :global([data-dockkit-host='dock'][data-dockkit-column='1']) {
   --dsh-dockkit-strip-inline-start: 10px;
 }
 
 /* Window fullscreen hides the traffic lights (html[data-fullscreen], desktop
    preload); the first pane's strip keeps only the ordinary inset. */
-:global([data-platform='darwin'][data-fullscreen]) .panel[data-sidebar-right-panel='fullscreen'] .panelBody {
+:global([data-platform='darwin'][data-fullscreen]) .panel[data-sidebar-right-panel='fullscreen'] :global([data-dockkit-host='dock'][data-dockkit-column='0']) {
   --dsh-dockkit-strip-inline-start: 10px;
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .panel,
-  .panel[data-sidebar-right-open] {
+  .panel :global([data-dockkit-host='dock']),
+  .panel :global([data-dockkit-empty]),
+  .panel :global([data-dockkit-divider]) {
     transition: none;
   }
 }
@@ -159,17 +171,3 @@
   color: var(--dsw-alias-label-tertiary);
   font-size: var(--dsh-content-font-size-secondary, 13px);
 }
-
-/*
- * Host for the portalled floating panels. Panels leave the column so they can
- * cross it and the conversation, which puts them beside the app root rather than
- * inside it — and a sibling of the root does not inherit its stacking, so the
- * level is stated here. The value sits above the frame's own overlay layer;
- * there is no z-index token layer to draw from yet.
- */
-.floatHost {
-  position: fixed;
-  inset: 0;
-  z-index: 60;
-  pointer-events: none;
-}
diff --git a/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx
index f326717124..38a86eff2f 100644
--- a/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx
+++ b/packages/client/ui-sidebar-right/src/client/shell/SidebarRight.tsx
@@ -2,11 +2,11 @@
  * The Sidebar's seat in the frame, and the panel it draws.
  *
  * The frame owns the right column's geometry; this package owns one content
- * tree at the column width or fixed across the viewport. A shown wide panel
+ * tree at the column width or spanning the viewport. A shown wide panel
  * retains its track in fullscreen, preserving the conversation width. Below
  * 768px fullscreen is derived from viewport width, without changing manual mode.
  *
- * The panel stays mounted while collapsed, translated off the frame's right
+ * Docked content stays mounted while collapsed, translated off the frame's right
  * edge, so opening and closing are one gesture in both presentations: a slide
  * from and to that edge. Normal presentation moves the frame's tracks with
  * the panel. A fullscreen opening reserves its underlying track only after
@@ -17,8 +17,8 @@
  * pane's tab strip, so the strip is the panel's whole top edge. The way back in
  * while collapsed is not here either: it is one button in the conversation
  * header (`ExpandButton.tsx`), because it exists only while this panel is
- * hidden. Floating panels portal out because they must cross the column and the
- * conversation, and the kit already positions them in viewport coordinates.
+ * hidden. Floating panels remain in the same content tree; untransformed
+ * ancestors let their fixed-position frames cross the column and conversation.
  *
  * Tab bodies do not live here. Each one is a registration under its type's kind,
  * dispatched through the keyed `sidebar.right.pane.tab` seat (and a live chip
@@ -28,15 +28,14 @@
  * domain follows each session's store commits, including sessions off screen.
  */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
-import type { ReactNode, RefObject } from 'react'
-import { createPortal } from 'react-dom'
+import type { CSSProperties, ReactNode, RefObject } from 'react'
 import { IconPanelLeftOutlineRegular, Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {
   HostObservable, InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore,
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type {} from '../contract/slots.ts'
 import type { DockIntents, DockMode, FloatRect, TabId, TabRecord, TabRenderer } from '@deepseek-ai/dsh-client-ui-dockkit'
-import { canSplit, dockPaneIds, DockSurface, findPaneContentTab, FloatLayer } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { canSplit, dockPaneIds, DockLayout, findPaneContentTab } from '@deepseek-ai/dsh-client-ui-dockkit'
 import type { HalvesFit, LayoutState, PaneId } from '@deepseek-ai/dsh-client-ui-dockkit'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { GUIDE_KIND, pageAddress } from '../contract/seed.ts'
@@ -80,7 +79,8 @@ export interface SidebarRightInjected {
    * Publish this seat's session, actions, and the store's surfaces to `ctx.sidebarRight`.
    *
    * The service is root-scoped and cannot read a per-entry store, so the only
-   * honest source is the mounted seat. Held for as long as the seat is mounted.
+   * honest source is the mounted seat. Held for as long as the seat is mounted;
+   * the service publishes the bound session through `ctx.sidebarRight.mounted`.
    * @param binding - what a command needs to act on this session, and what a tab's own action needs to act on its.
    * @returns a release callback.
    */
@@ -132,6 +132,8 @@ interface PanelProps {
   readonly occurrence: SidebarRightInjected['occurrence']
   readonly fullscreen: boolean
   readonly autoFullscreen: boolean
+  readonly active: boolean
+  readonly retainTab: RightbarSeatProps['retainTab']
   /** Receives the kit's room-rule readings for the service's `split`. */
   readonly reportRoom: (fits: ReadonlyMap<PaneId, HalvesFit>) => void
 }
@@ -171,7 +173,7 @@ export function intentsFor(sessionId: SessionId, actions: Store['actions'], open
 }
 
 /** One tab's slot dispatch: which seat, and what to render when no type registered. */
-interface TabSlotProps extends Pick<PanelProps, 'renderSlot' | 'occurrence' | 'useTabTypes' | 'useTabNavigation' | 'useStore' | 'fullscreen'> {
+interface TabSlotProps extends Pick<PanelProps, 'renderSlot' | 'occurrence' | 'useTabTypes' | 'useTabNavigation' | 'useStore' | 'fullscreen' | 'active' | 'retainTab'> {
   readonly tab: TabRecord
   readonly seat: 'sidebar.right.pane.tab' | 'sidebar.right.pane.tab.title'
   readonly fallback: ReactNode
@@ -181,19 +183,22 @@ interface TabSlotProps extends Pick<PanelProps, 'renderSlot' | 'occurrence' | 'u
  * Dispatch one tab's body or title with stable framework hooks and record lifetime.
  */
 function TabSlot({
-  renderSlot, occurrence, useTabTypes, useTabNavigation, useStore, fullscreen, tab, seat, fallback,
+  renderSlot, occurrence, useTabTypes, useTabNavigation, useStore, fullscreen, active, retainTab, tab, seat, fallback,
 }: TabSlotProps): ReactNode {
   const { signal, tabActions } = occurrence(tab)
   const definition = useTabTypes(types => types.find(definition => definition.kind === tab.kind))
+  const retained = seat === 'sidebar.right.pane.tab' && definition?.keepMounted === true
+  useLayoutEffect(() => retained ? retainTab(tab.id, signal) : undefined, [retained, retainTab, tab.id, signal])
   const hookContext = useMemo((): TabHookContext => ({
     tabId: tab.id,
     title: seat === 'sidebar.right.pane.tab.title',
     fullscreen,
+    active,
     signal,
     actions: tabActions,
     useStore,
     useTabNavigation,
-  }), [tab.id, seat, fullscreen, signal, tabActions, useStore, useTabNavigation])
+  }), [tab.id, seat, fullscreen, active, signal, tabActions, useStore, useTabNavigation])
   return renderSlot(seat, {}, { entryKey: definition?.id ?? tab.kind, fallback, hookContext })
 }
 
@@ -206,9 +211,7 @@ function TabSlot({
  */
 function bodiesFor(panel: PanelProps): TabRenderer {
   const { t, ...rest } = panel
-  // Keyed by record: the kit draws one body per pane in one place, and the
-  // keyed slot below keys on the type, so two tabs of one kind would otherwise
-  // share a component instance and its local state (a scroll position, a ref).
+  // Slot dispatch selects a type; the record key separates bodies of that type.
   return tab => (
     <TabSlot
       key={tab.id}
@@ -286,20 +289,18 @@ function PanelChrome({ sessionId, fullscreen, autoFullscreen, actions, t }: Pick
 function SidebarPanel(panel: PanelProps & { width: number; panelRef: RefObject<HTMLDivElement> }): ReactNode {
   const { sessionId, surface, actions, t, renderSlot, openTab, width, reportRoom, fullscreen, autoFullscreen, panelRef } = panel
   const { expanded } = surface.layout
+  const types = panel.useTabTypes(value => value)
   return (
     <div
       ref={panelRef}
       className={css.panel}
-      style={{ width: fullscreen ? '100%' : width }}
+      style={{ width: fullscreen ? '100vw' : width,
+        '--dsh-sidebar-width': fullscreen ? '100vw' : `${width}px` } as CSSProperties}
       data-sidebar-right-panel={fullscreen ? 'fullscreen' : 'push'}
       data-sidebar-right-open={expanded || undefined}
-      // Off-edge is out of reach: the stylesheet's visibility flip takes the
-      // hidden panel out of the tab order, and this takes it out of the
-      // accessibility tree.
-      aria-hidden={!expanded || undefined}
     >
       <div className={css.panelBody}>
-        <DockSurface
+        <DockLayout
           state={surface.layout}
           canSplit={canSplit(surface.layout) && dockPaneIds(surface.layout).length < 2}
           hideSplitWhenBlocked
@@ -311,6 +312,8 @@ function SidebarPanel(panel: PanelProps & { width: number; panelRef: RefObject<H
           labels={dockLabels(t)}
           renderTab={bodiesFor(panel)}
           renderTabTitle={titlesFor(panel)}
+          active={panel.active}
+          keepMounted={tab => types.find(type => type.kind === tab.kind)?.keepMounted === true}
           renderTabMenuItems={(tab, dismiss) =>
             renderSlot('sidebar.right.tab.menu.item', { tab, dismiss })}
           chrome={<PanelChrome sessionId={sessionId} fullscreen={fullscreen} autoFullscreen={autoFullscreen} actions={actions} t={t} />}
@@ -321,34 +324,15 @@ function SidebarPanel(panel: PanelProps & { width: number; panelRef: RefObject<H
   )
 }
 
-/** Portal the floating layer out of whichever seat rendered it. */
-function Floats(panel: PanelProps): ReactNode {
-  const { sessionId, surface, actions, t, openTab } = panel
-  if (surface.layout.floats.length === 0) return null
-  return createPortal(
-    <div className={css.floatHost} data-sidebar-right-float-host>
-      <FloatLayer
-        state={surface.layout}
-        canCloseTab={tabId => canCloseTab(surface, tabId)}
-        intents={intentsFor(sessionId, actions, openTab, panel.closeTab)}
-        labels={dockLabels(t)}
-        renderTab={bodiesFor(panel)}
-        renderTabTitle={titlesFor(panel)}
-      />
-    </div>,
-    document.body,
-  )
-}
-
 /**
- * The right column's occupant: the panel, anchored to the column's edge and
- * shown or hidden by sliding, plus the floating layer. It is also where the
+ * The right column's occupant: stable tab containers, docked or floating.
+ * It is also where the
  * frame learns the panel's presentation, and where `ctx.sidebarRight` learns
  * which session it is acting on, because this is the seat that knows both.
  */
 export function RightbarSeat({
   sessionId, width, viewportWidth, canShow, useStore, actions, t, renderSlot, syncPresentation, bindService, openTab, closeTab,
-  useTabTypes, useTabNavigation, occurrence,
+  useTabTypes, useTabNavigation, occurrence, retainTab, active,
 }: RightbarSeatProps): ReactNode {
   // One store instance per session, so this map holds this session's surface.
   // The binding published below serves the public face's commands on the
@@ -356,7 +340,7 @@ export function RightbarSeat({
   // adopted stores instead.
   const surfaces = useStore(state => state.bySession)
   const surface = surfaces[sessionId]
-  const shown = surface !== undefined && surface.layout.expanded
+  const shown = active && surface !== undefined && surface.layout.expanded
   const autoFullscreen = viewportWidth < 768
   const fullscreen = autoFullscreen || surface?.layout.mode === 'fullscreen'
   const panelRef = useRef<HTMLDivElement | null>(null)
@@ -367,8 +351,8 @@ export function RightbarSeat({
   const track = shown && !autoFullscreen
 
   useEffect(() => {
-    if (surface === undefined) actions.open(sessionId)
-  }, [actions, sessionId, surface])
+    if (active && surface === undefined) actions.open(sessionId)
+  }, [actions, sessionId, surface, active])
 
   useLayoutEffect(() => {
     if (shown && !fullscreen && !canShow) actions.setExpanded(sessionId, false)
@@ -385,7 +369,7 @@ export function RightbarSeat({
   // of the gesture: once at the flip, once after the slide settles and the
   // stylesheet's delayed visibility flip (0.3s) has landed.
   useEffect(() => {
-    if (document.documentElement.dataset.platform !== 'darwin') return
+    if (!active || document.documentElement.dataset.platform !== 'darwin') return
     const panel = panelRef.current
     if (panel === null) return
     let raf: number | null = null
@@ -403,17 +387,18 @@ export function RightbarSeat({
       if (raf !== null) cancelAnimationFrame(raf)
       panel.removeAttribute('data-sidebar-right-region-nudge')
     }
-  }, [shown])
+  }, [shown, active])
 
   // Fullscreen leaves the previous column report in force until its own slide
   // completes. Normal presentation and zero-duration transitions report before paint.
   useLayoutEffect(() => {
+    if (!active) return
     let disposed = false
     const reportWhenCovered = (): void => {
       if (disposed) return
       // A shown panel renders unconditionally and attaches its ref before this effect.
       const entering = shown && fullscreen
-        ? (panelRef.current as HTMLDivElement).getAnimations().filter(animation =>
+        ? (panelRef.current as HTMLDivElement).getAnimations({ subtree: true }).filter(animation =>
           'transitionProperty' in animation && animation.transitionProperty === 'transform'
           && animation.playState !== 'finished' && animation.playState !== 'idle')
         : []
@@ -426,16 +411,20 @@ export function RightbarSeat({
     }
     reportWhenCovered()
     return () => { disposed = true }
-  }, [sessionId, shown, track, fullscreen, syncPresentation])
+  }, [sessionId, shown, track, fullscreen, syncPresentation, active])
   // Leaving is part of that report: a seat that unmounts with its session must
   // hand the track back rather than leave one sized for a surface nobody draws.
-  useLayoutEffect(() => () => { syncPresentation({ shown: false, track: false, fullscreen: false }) }, [syncPresentation])
+  useLayoutEffect(() => active
+    ? () => { syncPresentation({ shown: false, track: false, fullscreen: false }) }
+    : undefined, [syncPresentation, active])
 
   // Republished on every committed change: the service's readers answer from the
   // last commit, and its commands act on the session actually on screen.
   useEffect(
-    () => bindService({ sessionId, actions, surfaces, canSplitPane: paneId => room.current.get(paneId)?.row !== false }),
-    [bindService, sessionId, actions, surfaces],
+    () => active
+      ? bindService({ sessionId, actions, surfaces, canSplitPane: paneId => room.current.get(paneId)?.row !== false })
+      : undefined,
+    [bindService, sessionId, actions, surfaces, active],
   )
   // The Tab domain is not synced here: the controller adopted this session's
   // store as the runtime minted it and reconciles on the store's own commits,
@@ -444,12 +433,7 @@ export function RightbarSeat({
   if (surface === undefined) return null
   const panel: PanelProps = {
     sessionId, actions, t, renderSlot, surface, openTab, closeTab, useTabTypes, useTabNavigation, useStore, occurrence,
-    fullscreen, autoFullscreen, reportRoom,
+    fullscreen, autoFullscreen, reportRoom, active, retainTab,
   }
-  return (
-    <>
-      <SidebarPanel {...panel} width={width} panelRef={panelRef} />
-      <Floats {...panel} />
-    </>
-  )
+  return <SidebarPanel {...panel} width={width} panelRef={panelRef} />
 }
diff --git a/packages/client/ui-sidebar-right/src/client/tab-info.ts b/packages/client/ui-sidebar-right/src/client/tab-info.ts
index 940b86822a..8205bb95da 100644
--- a/packages/client/ui-sidebar-right/src/client/tab-info.ts
+++ b/packages/client/ui-sidebar-right/src/client/tab-info.ts
@@ -11,6 +11,7 @@ export interface TabHookContext {
   readonly tabId: TabId
   readonly title: boolean
   readonly fullscreen: boolean
+  readonly active: boolean
   readonly signal: AbortSignal
   readonly actions: SidebarRightTabActions
   readonly useStore: PropsStore<ReturnType<typeof createSidebarRightStore>>['useStore']
@@ -25,7 +26,7 @@ export interface TabHookContext {
  */
 export const tabInfoFactory: SlotHookFactory<'sidebar.right.pane.tab', UseSidebarRightTabInfo> = (standard, context) => {
   const { sessionId } = standard
-  const { tabId, title, fullscreen, signal, actions, useStore, useTabNavigation } = context
+  const { tabId, title, fullscreen, active, signal, actions, useStore, useTabNavigation } = context
   return function useTabInfo() {
     const layout = useStore(state => state.bySession[sessionId]?.layout)
     const navigation = useTabNavigation(tabId)
@@ -40,13 +41,13 @@ export const tabInfoFactory: SlotHookFactory<'sidebar.right.pane.tab', UseSideba
         panel: { id: pane.id },
         tab: {
           ...tab,
-          visible: pane.host === 'float' || (layout.expanded && (title || pane.activeTabId === tabId)),
+          visible: active && (pane.host === 'float' || (layout.expanded && (title || pane.activeTabId === tabId))),
           navigation,
           signal,
           actions,
         },
       }
-    }, [layout, navigation, tabId, title, fullscreen, signal, actions])
+    }, [layout, navigation, tabId, title, fullscreen, active, signal, actions])
   }
 }
 
diff --git a/packages/client/ui-sidebar-right/src/client/tab-registry.ts b/packages/client/ui-sidebar-right/src/client/tab-registry.ts
index 7961a5e4ad..76de73578a 100644
--- a/packages/client/ui-sidebar-right/src/client/tab-registry.ts
+++ b/packages/client/ui-sidebar-right/src/client/tab-registry.ts
@@ -101,6 +101,8 @@ export interface SidebarRightTabDefinition {
   readonly kind: string
   /** Each open by kind creates independent content; omission keeps one page per kind in each pane. */
   readonly multiple?: boolean
+  /** Lazily keep a visited body mounted through hiding, Session changes and docking; default false. */
+  readonly keepMounted?: boolean
   /**
    * Resource-address globs this type recognizes; omit for a page type, which is
    * opened by kind and recognizes no address.
diff --git a/packages/client/ui-sidebar-right/tests/apply.client.spec.ts b/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
index 530334eae2..7c3489931e 100644
--- a/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
+++ b/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
@@ -10,6 +10,7 @@
  */
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { apply, inject } from '../src/client/index.ts'
@@ -65,6 +66,8 @@ async function boot() {
   ctx.provide('locale', locale as never)
   ctx.provide('layout', layout as never)
   ctx.provide('resources', resources as never)
+  ctx.provide('sessions', { retain: vi.fn() } as never)
+  ctx.provide('uiSession', { adapter: { current: createSnapshotStore({ key: undefined }) } } as never)
   const fiber = ctx.plugin({ inject: [...inject], apply })
   await fiber.await()
   const seat = (name: string): Recorded => {
diff --git a/packages/client/ui-sidebar-right/tests/persistence-validation.client.spec.ts b/packages/client/ui-sidebar-right/tests/persistence-validation.client.spec.ts
index 43ca6f818e..bce86c42ea 100644
--- a/packages/client/ui-sidebar-right/tests/persistence-validation.client.spec.ts
+++ b/packages/client/ui-sidebar-right/tests/persistence-validation.client.spec.ts
@@ -37,6 +37,16 @@ it.each([
   ['split cycle', { minted: 4, layout: { ...splitLayout, nodes: { ...splitLayout.nodes, split3: { ...split, children: ['split3', 'pane1'] } } } }],
   ['invalid split sum', { minted: 4, layout: { ...splitLayout, nodes: { ...splitLayout.nodes, split3: { ...split, sizes: [0.4, 0.4] } } } }],
   ['mismatched split sizes', { minted: 4, layout: { ...splitLayout, nodes: { ...splitLayout.nodes, split3: { ...split, sizes: [0.2, 0.3, 0.5] } } } }],
+  ['vertical split', { minted: 4, layout: { ...splitLayout, nodes: { ...splitLayout.nodes, split3: { ...split, axis: 'column' } } } }],
+  ['three docked panes', { minted: 5, layout: { ...splitLayout, nodes: {
+    ...splitLayout.nodes, pane5: { ...otherPane, id: 'pane5' },
+    split3: { ...split, children: ['pane1', 'pane4', 'pane5'], sizes: [0.3, 0.3, 0.4] },
+  } } }],
+  ['nested split', { minted: 6, layout: { ...splitLayout, nodes: {
+    ...splitLayout.nodes, pane6: { ...otherPane, id: 'pane6' },
+    split3: { ...split, children: ['pane1', 'split5'] },
+    split5: { ...split, id: 'split5', children: ['pane4', 'pane6'] },
+  } } }],
   ['split as active pane', { minted: 4, layout: { ...splitLayout, activePaneId: 'split3' } }],
   ['floating split', { minted: 4, layout: { ...splitLayout, floats: ['split3'] } }],
   ['float without rectangle', { minted: 3, layout: { ...empty.layout, tabs: { tab2: tab }, floats: ['float3'], nodes: { ...empty.layout.nodes, float3: { ...pane, id: 'float3', host: 'float' } } } }],
diff --git a/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx b/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
index 322aa1d690..fd61162198 100644
--- a/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
+++ b/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
@@ -2,7 +2,7 @@
 /** Sidebar presentation and tab subscriptions through the production slot renderer. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, fireEvent } from '@testing-library/react'
-import { useState } from 'react'
+import { useEffect, useState, useSyncExternalStore } from 'react'
 import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
@@ -21,6 +21,13 @@ declare module '../src/client/contract/params.ts' {
   }
 }
 
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** A Conversation-column stand-in rendered before the seat, opening a resource as soon as a seat is mounted. */
+    'sidebar-right.test.opener': { kind: 'single'; scope: 'session'; owner: { armed: boolean } }
+  }
+}
+
 const SESSION = 's-test' as SessionId
 const OTHER = 's-other' as SessionId
 const runtimes: SlotTestRuntime[] = []
@@ -57,7 +64,7 @@ function transition(property = 'transform') {
   }
 }
 
-async function mountSeat(viewportWidth = 1440, canShow = true, entryCount = 0) {
+async function mountSeat(viewportWidth = 1440, canShow = true, entryCount = 0, opener = false, keepMounted = false) {
   const runtime = await SlotTestRuntime.create()
   runtimes.push(runtime)
   const frame = { openRightbar: vi.fn(), closeRightbar: vi.fn() }
@@ -68,12 +75,40 @@ async function mountSeat(viewportWidth = 1440, canShow = true, entryCount = 0) {
   runtime.ctx.provide('locale', locale)
   runtime.slots.installLocale(locale)
   await runtime.declare({
+    'sidebar-right.test.opener': { kind: 'single', scope: 'session' },
     'rightbar': { kind: 'single', scope: 'root' },
     'conversation.session.header.corner': { kind: 'single', scope: 'session' },
   })
   await runtime.sessions.add({ id: SESSION })
   let reference = runtime.sessions.retainFor(runtime.ctx, SESSION, { source: 'mainView' })
   const feature = await runtime.mount({ inject: [...inject], apply })
+  // The frame mounts the Conversation column before the right column, so a
+  // Conversation component's mount effect runs before the seat's. The opener
+  // stands in for one that opens a resource as soon as a seat is mounted — it
+  // reads `mounted` the way a slot component reads its bound hook — and shows
+  // only while the Conversation is selected, as the main panel does.
+  const opened: string[] = []
+  function OpenerMount() {
+    const { mounted } = runtime.ctx.sidebarRight
+    const seat = useSyncExternalStore(listener => mounted.subscribe(listener), () => mounted.getSnapshot())
+    useEffect(() => {
+      if (seat === undefined) return
+      const address = `dsh-resource://file/session/s-test/arrival-${opened.length + 1}.txt`
+      runtime.ctx.sidebarRight.openResource(address)
+      opened.push(address)
+    }, [seat])
+    return null
+  }
+  function Opener({ usePanelInfo, armed }: PropsRuntime<'sidebar-right.test.opener'>) {
+    const visible = usePanelInfo(info => info.activePanelId === null)
+    return armed && visible ? <OpenerMount /> : null
+  }
+  let arm = (_armed: boolean): void => { throw new Error('mountSeat(opener = true) renders the opener') }
+  if (opener) {
+    await act(async () => { runtime.slots.register({ name: 'sidebar-right.test.opener' }, Opener) })
+    const openerView = runtime.renderSlot('sidebar-right.test.opener', { armed: false }, { session: reference })
+    arm = (armed) => { openerView.update({ armed }) }
+  }
   const bodies = new Map<string, SidebarRightTabInfo>()
   const titles = new Map<string, SidebarRightTabInfo>()
   const hooks = new Map<string, PropsRuntime<'sidebar.right.pane.tab'>['useTabInfo']>()
@@ -95,6 +130,7 @@ async function mountSeat(viewportWidth = 1440, canShow = true, entryCount = 0) {
     runtime.ctx.sidebarRightTabs.register({
       id: 'test/text', kind: 'text', priority: 'builtin', patterns: ['dsh-resource://file/**'],
       title: address => address.slice(address.lastIndexOf('/') + 1),
+      keepMounted,
       guide: Array.from({ length: entryCount }, (_, order) => ({ id: String(order), order, title: () => 'Test', description: () => 'Test page' })),
     })
     runtime.slots.register({ name: 'sidebar.right.pane.tab', key: 'test/text' }, Body)
@@ -115,7 +151,7 @@ async function mountSeat(viewportWidth = 1440, canShow = true, entryCount = 0) {
   }
   return {
     runtime, feature, controller, instance, actions: instance.actions, layout,
-    open, selectSession, frame, pin, bodies, titles, hooks, view,
+    open, selectSession, frame, pin, bodies, titles, hooks, view, arm, opened,
   }
 }
 
@@ -126,12 +162,34 @@ function element(container: HTMLElement, selector: string): HTMLElement {
 }
 
 describe('RightbarSeat presentation', () => {
+  it('keeps a background retained body through standard-source registration and removal', async () => {
+    const h = await mountSeat(1440, true, 0, false, true)
+    const tab = h.open('retained.txt')
+    const body = element(h.view.container, `[data-tab-body="${tab.id}"]`)
+    await act(async () => { await h.runtime.sessions.add({ id: OTHER }) })
+    act(() => { h.selectSession(OTHER) })
+    expect(body.isConnected).toBe(true)
+    let withdraw = () => {}
+    act(() => {
+      withdraw = h.runtime.ctx.uiSession.provide({
+        props: ['sidebarRetentionProbe'],
+        resolve: () => ({ props: { sidebarRetentionProbe: true } }),
+      })
+    })
+    expect(element(h.view.container, `[data-tab-body="${tab.id}"]`)).toBe(body)
+    act(withdraw)
+    expect(element(h.view.container, `[data-tab-body="${tab.id}"]`)).toBe(body)
+    act(() => { h.selectSession(SESSION) })
+    expect(element(h.view.container, `[data-tab-body="${tab.id}"]`)).toBe(body)
+    expect(h.bodies.get(tab.id)?.tab.signal.aborted).toBe(false)
+  })
+
   it('hides for a global main panel and retains the Session sidebar state', async () => {
     const h = await mountSeat()
     h.open('retained.txt')
     const retained = h.layout()
     act(() => { h.runtime.panelInfo.set({ activePanelId: 'other-panel' as MainPanelId }) })
-    expect(h.view.container.querySelector('[data-sidebar-right-panel]')).toBeNull()
+    expect(element(h.view.container, '[data-sidebar-right-session]').hidden).toBe(true)
     expect(h.frame.closeRightbar).toHaveBeenCalled()
     expect(h.layout()).toBe(retained)
     act(() => { h.runtime.panelInfo.set({ activePanelId: null }) })
@@ -139,6 +197,28 @@ describe('RightbarSeat presentation', () => {
     expect(h.layout()).toBe(retained)
   })
 
+  it('publishes the mounted seat so a Conversation opener acts in the commit that returns from a global panel', async () => {
+    const h = await mountSeat(1440, true, 0, true)
+    const errors = vi.spyOn(console, 'error').mockImplementation(() => {})
+    expect(h.controller.mounted.getSnapshot()).toBe(SESSION)
+    // Armed while the seat is already bound: the ordinary case.
+    act(() => { h.arm(true) })
+    expect(h.opened).toHaveLength(1)
+    expect(Object.values(h.layout().tabs).map(tab => tab.contentId)).toEqual(h.opened)
+    // A global panel hides the Sidebar and releases its public navigation binding.
+    act(() => { h.runtime.panelInfo.set({ activePanelId: 'other-panel' as MainPanelId }) })
+    expect(element(h.view.container, '[data-sidebar-right-session]').hidden).toBe(true)
+    expect(h.controller.mounted.getSnapshot()).toBeUndefined()
+    // The opener waits until the foreground seat republishes its navigation binding.
+    act(() => { h.runtime.panelInfo.set({ activePanelId: null }) })
+    expect(h.controller.mounted.getSnapshot()).toBe(SESSION)
+    expect(h.opened).toHaveLength(2)
+    expect(Object.values(h.layout().tabs).map(tab => tab.contentId)).toEqual(h.opened)
+    expect(h.controller.active()?.contentId).toBe(h.opened[1])
+    expect(errors.mock.calls.map(call => String(call[0])).filter(text => text.includes('slot entry crashed'))).toEqual([])
+    expect(document.querySelector('[data-slot-error]')).toBeNull()
+  })
+
   it.each([0, 1, 2])('selects the default from %i guide entries and protects only a sole guide', async (entryCount) => {
     const h = await mountSeat(1440, true, entryCount)
     act(() => { h.controller.toggleExpanded() })
@@ -200,7 +280,7 @@ describe('RightbarSeat presentation', () => {
   it('keeps the panel mounted while collapsed and releases the frame on unmount', async () => {
     const h = await mountSeat()
     const panel = element(h.view.container, '[data-sidebar-right-panel]')
-    expect(panel.getAttribute('aria-hidden')).toBe('true')
+    expect(panel.hasAttribute('data-sidebar-right-open')).toBe(false)
     expect(h.frame.closeRightbar).toHaveBeenCalled()
     h.open()
     expect(element(h.view.container, '[data-sidebar-right-panel]')).toBe(panel)
@@ -259,7 +339,7 @@ describe('RightbarSeat presentation', () => {
     expect(panel.style.width).toBe('420px')
     fireEvent.click(element(h.view.container, '[data-sidebar-right-mode]'))
     expect(h.layout().mode).toBe('fullscreen')
-    expect(panel.style.width).toBe('100%')
+    expect(panel.style.width).toBe('100vw')
     expect(panel.dataset['sidebarRightPanel']).toBe('fullscreen')
     expect(element(h.view.container, '[data-tab-body]')).toBe(body)
     expect(h.frame.openRightbar).toHaveBeenLastCalledWith(true, true)
diff --git a/packages/client/ui-sidebar-right/tests/service.client.spec.ts b/packages/client/ui-sidebar-right/tests/service.client.spec.ts
index 889497fd2a..67d71124e8 100644
--- a/packages/client/ui-sidebar-right/tests/service.client.spec.ts
+++ b/packages/client/ui-sidebar-right/tests/service.client.spec.ts
@@ -111,6 +111,26 @@ describe('SidebarRightController — opening', () => {
     expect(() => { controller.dock('pane1' as PaneId) }).toThrow('no session surface is mounted')
   })
 
+  it('publishes the mounted session only on real transitions of the seat binding', () => {
+    const h = harness()
+    const seen: (string | undefined)[] = []
+    const unsubscribe = h.controller.mounted.subscribe(() => { seen.push(h.controller.mounted.getSnapshot()) })
+    try {
+      expect(h.controller.mounted.getSnapshot()).toBeUndefined()
+      const first = h.publish()
+      expect(h.controller.mounted.getSnapshot()).toBe(SESSION)
+      // The seat republishes on every store commit; the same session is silent.
+      const second = h.publish()
+      expect(seen).toEqual([SESSION])
+      // A stale release — the first seat's, after a newer one took over — changes nothing.
+      first()
+      expect(h.controller.mounted.getSnapshot()).toBe(SESSION)
+      second()
+      expect(h.controller.mounted.getSnapshot()).toBeUndefined()
+      expect(seen).toEqual([SESSION, undefined])
+    } finally { unsubscribe() }
+  })
+
   it('refuses an address no registered type claims, before touching the surface', () => {
     const { controller, publish, titles } = harness()
     publish()
diff --git a/packages/client/ui-sidebar-right/tests/session-views.client.spec.ts b/packages/client/ui-sidebar-right/tests/session-views.client.spec.ts
new file mode 100644
index 0000000000..1c11e825a7
--- /dev/null
+++ b/packages/client/ui-sidebar-right/tests/session-views.client.spec.ts
@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
+import { SidebarSessionView } from '../src/client/session-view.ts'
+import { SidebarSessionViews } from '../src/client/session-views.ts'
+
+const A = 'a' as SessionId
+const B = 'b' as SessionId
+const TAB = 'tab' as TabId
+const runtimes: SlotTestRuntime[] = []
+const owners: { dispose(): void }[] = []
+
+afterEach(async () => {
+  for (const owner of owners.splice(0)) owner.dispose()
+  for (const runtime of runtimes.splice(0)) await runtime.dispose()
+  vi.restoreAllMocks()
+})
+
+async function runtime() {
+  const runtime = await SlotTestRuntime.create()
+  runtimes.push(runtime)
+  await runtime.sessions.add({ id: A })
+  await runtime.sessions.add({ id: B })
+  return runtime
+}
+
+it('keeps one reference per View until the final committed root of a retired View unmounts', async () => {
+  const r = await runtime()
+  const disposed = vi.fn()
+  const changed = vi.fn()
+  const view = new SidebarSessionView(A, r.sessions, disposed, changed)
+  owners.push(view)
+  await view.reference.ready
+  const release = vi.spyOn(view.reference, 'release')
+  const firstMount = view.mount()
+  const secondMount = view.mount()
+  const first = new AbortController()
+  const second = new AbortController()
+  const firstHold = view.retainTab(TAB, first.signal)
+  const secondHold = view.retainTab(TAB, second.signal)
+  firstHold()
+  firstHold()
+  expect(view.hasRetainedTabs).toBe(true)
+  expect(changed).toHaveBeenCalledOnce()
+  second.abort()
+  secondHold()
+  expect(view.hasRetainedTabs).toBe(false)
+  view.retainTab(TAB, second.signal)()
+  view.retire()
+  firstMount()
+  expect(release).not.toHaveBeenCalled()
+  secondMount()
+  expect(release).toHaveBeenCalledOnce()
+  view.retainTab(TAB, first.signal)()
+  view.dispose()
+  expect(disposed).toHaveBeenCalledExactlyOnceWith(view)
+})
+
+it('retires only unselected Views without retained bodies and rejects released reference identities', async () => {
+  const r = await runtime()
+  const views = new SidebarSessionViews(r.sessions)
+  owners.push(views)
+  views.select(A)
+  const first = views.source.getSnapshot()
+  const a = first[0]!
+  views.select(A)
+  expect(views.source.getSnapshot()).toBe(first)
+  const unmount = views.mount(a.reference)
+  const lifetime = new AbortController()
+  const release = vi.spyOn(a.reference, 'release')
+  a.retainTab(TAB, lifetime.signal)
+  views.select(B)
+  expect(views.source.getSnapshot().map(view => [view.sessionId, view.selected])).toEqual([[A, false], [B, true]])
+  lifetime.abort()
+  expect(views.source.getSnapshot().map(view => view.sessionId)).toEqual([B])
+  expect(release).not.toHaveBeenCalled()
+  unmount()
+  expect(release).toHaveBeenCalledOnce()
+  expect(() => views.mount(a.reference)).toThrow('no longer owned')
+  views.select(undefined)
+  expect(views.source.getSnapshot()).toEqual([])
+  views.dispose()
+  views.select(A)
+  views.mount(a.reference)()
+  expect(views.source.getSnapshot()).toEqual([])
+})
+
+it('reports opening failure and releases Views even when committed roots are still present', async () => {
+  const r = await runtime()
+  const reference = r.sessions.retain(A, { source: 'sidebarView' })
+  const failure = new Error('opening failed')
+  const release = vi.fn(() => { reference.release() })
+  vi.spyOn(r.sessions, 'retain').mockReturnValueOnce({
+    sessionId: reference.sessionId,
+    get binding() { return reference.binding },
+    ready: Promise.reject(failure),
+    release,
+    [Symbol.dispose]: () => { reference.release() },
+  })
+  const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+  const views = new SidebarSessionViews(r.sessions)
+  owners.push(views)
+  views.select(A)
+  const view = views.source.getSnapshot()[0]!
+  const unmount = views.mount(view.reference)
+  await expect(view.reference.ready).rejects.toBe(failure)
+  expect(error).toHaveBeenCalledWith('Sidebar Session opening failed:', failure)
+  views.dispose()
+  expect(release).toHaveBeenCalledOnce()
+  unmount()
+  expect(release).toHaveBeenCalledOnce()
+})
diff --git a/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx b/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx
index 3f36395704..5ce30f033e 100644
--- a/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx
+++ b/packages/client/ui-sidebar-right/tests/tab-info.client.spec.tsx
@@ -40,7 +40,8 @@ function harness() {
     const occurrence = domain.occurrence(SESSION, { id: tabId })
     navigationSources.set(tabId, occurrence.navigation)
     return tabInfoFactory(standard, {
-      tabId, title: false, fullscreen: false, signal: occurrence.signal, actions: occurrence.tabActions, useStore, useTabNavigation,
+      tabId, title: false, fullscreen: false, active: true,
+      signal: occurrence.signal, actions: occurrence.tabActions, useStore, useTabNavigation,
     })
   }
   const open = (beforeCommit?: (tabId: TabId) => void): TabId => {
diff --git a/packages/client/ui-sidebar/README.i18n.yaml b/packages/client/ui-sidebar/README.i18n.yaml
index c837437b74..72b5b20666 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: 1c5306b8b3efa5d7908cfd33206acefef20fc3a8
-README.zh.md: d72da040252f391bcc1468c9e29adf6a5ef85ef0
+README.md: 94bb3a70ca8c06b5838f41436bb0f2ba2751501e
+README.zh.md: 86f54882ba1c96b9b50898993931757f7afef4e5
diff --git a/packages/client/ui-sidebar/README.md b/packages/client/ui-sidebar/README.md
index 1c5306b8b3..94bb3a70ca 100644
--- a/packages/client/ui-sidebar/README.md
+++ b/packages/client/ui-sidebar/README.md
@@ -41,7 +41,7 @@ The top expand button hosts the optional, non-interactive `sidebar.toggle.badge`
 
 During a live collapse, the expanded content fades out at its current width, the upper controls share one fade and leftward translation into the 56px rail, and the layout's column slide ends the motion. A page that starts collapsed renders the rail statically, and reduced-motion mode disables both transitions. The bottom-pinned `sidebar.settings` control shares the fade timing but has no horizontal translation.
 
-On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region.
+On Windows Electron, `html[data-windows-titlebar]` fixes the sidebar toggle in the caption's top-left corner in both states, aligned with New Session's left edge only when expanded. The expanded brand sits below the caption and above New Session, with 8px of extra space above that button. Collapsing hides the brand and sidebar content and places New Session between the sidebar toggle and the Desktop-owned menus. The sidebar sets the root `--dsh-windows-menu-start` to 84px when collapsed; the Desktop preload uses it to position its menu after New Session and defaults to 48px when expanded. Caption icon buttons use centered 16px glyphs in 28px circular controls and exclude themselves from the window drag region. The sidebar toggle and New Session bubbles open below the caption, where the Desktop-owned menu text cannot cover them; an occupying `sidebar.toggle.badge` chooses its own bubble side.
 
 ### macOS desktop
 
diff --git a/packages/client/ui-sidebar/README.zh.md b/packages/client/ui-sidebar/README.zh.md
index d72da04025..86f54882ba 100644
--- a/packages/client/ui-sidebar/README.zh.md
+++ b/packages/client/ui-sidebar/README.zh.md
@@ -41,7 +41,7 @@ dsh Web 客户端的侧边栏让用户识别当前构建、启动新会话、将
 
 实时收起时，展开内容在当前宽度淡出，上方控件共用同一段透明度渐变，并向左平移进入 56px 轨道，由布局的栏滑动结束整段动画。页面初始即为收起状态时会静态渲染轨道；减少动态效果模式会禁用两段过渡。固定在底部的 `sidebar.settings` 控件共用相同的透明度渐变时序，但不发生横向位移。
 
-在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。
+在 Windows Electron 中，`html[data-windows-titlebar]` 将两种状态下的侧栏开关固定在顶栏左上角，仅在展开态与新建会话按钮左边缘对齐。展开态品牌位于顶栏下方、新建会话按钮上方，按钮上方额外留出 8px。收起后，品牌和侧栏内容隐藏，新建会话按钮排在侧栏开关与 Desktop 菜单之间。侧栏在收起态将根元素的 `--dsh-windows-menu-start` 设为 84px；Desktop preload 使用它将菜单放在新建会话之后，展开态默认为 48px。顶栏图标按钮采用 28px 圆形控件中的居中 16px 图标，并从窗口拖拽区域中排除。侧栏开关与新建会话的悬停提示在顶栏下方展开，Desktop 菜单文字不会盖住它们；占用 `sidebar.toggle.badge` 的控件自行决定气泡展开方向。
 
 ### macOS 桌面
 
diff --git a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
index f58588feb1..12bcbe8ca8 100644
--- a/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
+++ b/packages/client/ui-sidebar/src/client/SidebarRoot.tsx
@@ -107,6 +107,10 @@ export function SidebarRoot({
   }, [collapsed])
   const windowsTitlebar = document.documentElement.hasAttribute('data-windows-titlebar')
   const wide = windowsTitlebar ? !collapsed : !collapsed || !settled
+  // The Windows caption menus occupy the strip to the right of these controls
+  // (that is what --dsh-windows-menu-start reserves), so a right-side bubble
+  // lands under their text. Below the caption is the only clear side.
+  const captionTooltipSide = windowsTitlebar ? 'bottom' : 'right'
 
   // Freeze the content at its expanded width while it fades out (collapsed
   // && wide): the sliding column then clips it instead of reflowing it. The
@@ -169,7 +173,7 @@ export function SidebarRoot({
   // (the expand affordance, figma sidebar-hover flow). Expanded it is a plain
   // panel icon.
   const toggle = (
-    <Tooltip label={collapsed ? t('toggle.open') : t('toggle.collapse')} delayMs={500}>
+    <Tooltip label={collapsed ? t('toggle.open') : t('toggle.collapse')} delayMs={500} side={captionTooltipSide}>
       <button
         type="button"
         className={clsx(css.iconButton, css.toggle)}
@@ -247,7 +251,7 @@ export function SidebarRoot({
       </div>
 
       {/* Expanded, the button carries its own label — tooltip only on the rail. */}
-      <Tooltip label={t('session.new.label')} delayMs={500} disabled={wide}>
+      <Tooltip label={t('session.new.label')} delayMs={500} disabled={wide} side={captionTooltipSide}>
         <button
           type="button"
           className={css.newSession}
diff --git a/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx b/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
index 18e7fbc5e1..80812a9173 100644
--- a/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
+++ b/packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx
@@ -245,3 +245,38 @@ it('wires the shell.leading controls to the shared sidebar actions', () => {
   expect(toggleSidebar).toHaveBeenCalledOnce()
   expect(startSession).toHaveBeenCalledOnce()
 })
+
+describe('Windows caption tooltips', () => {
+  afterEach(() => { document.documentElement.removeAttribute('data-windows-titlebar') })
+
+  const hover = (button: HTMLElement): void => {
+    fireEvent.mouseEnter(button)
+    act(() => { vi.advanceTimersByTime(500) })
+  }
+
+  it.each([false, true])(
+    'drops the sidebar toggle bubble below the caption (collapsed=%s)',
+    (collapsed) => {
+      vi.useFakeTimers()
+      document.documentElement.setAttribute('data-windows-titlebar', '')
+      mountShell({ collapsed, width: collapsed ? 0 : 300 })
+      hover(screen.getByRole('button', { name: collapsed ? 'Open sidebar' : 'Collapse sidebar' }))
+      expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('bottom')
+    },
+  )
+
+  it('drops the collapsed New Session bubble below the caption as well', () => {
+    vi.useFakeTimers()
+    document.documentElement.setAttribute('data-windows-titlebar', '')
+    mountShell({ collapsed: true, width: 0 })
+    hover(screen.getByRole('button', { name: 'New session' }))
+    expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('bottom')
+  })
+
+  it('keeps the ordinary Web bubble beside its anchor', () => {
+    vi.useFakeTimers()
+    mountShell({ collapsed: true, width: 0 })
+    hover(screen.getByRole('button', { name: 'Open sidebar' }))
+    expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('right')
+  })
+})
diff --git a/packages/client/ui-skill/README.i18n.yaml b/packages/client/ui-skill/README.i18n.yaml
index 83f8c75b1c..5885d41e4e 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: b2687d59fc6566d9ea8a0c0d4d5b16eea38282b5
-README.zh.md: 7e6c8a7ecee2fe10d5826b91c108733bb4d3746f
+README.md: fdd8cb7fddb54cf73d897bb278086428d0e41214
+README.zh.md: 2090711d5f91bf1efba2f8e19d8d361f9ffb99d9
diff --git a/packages/client/ui-skill/README.md b/packages/client/ui-skill/README.md
index b2687d59fc..fdd8cb7fdd 100644
--- a/packages/client/ui-skill/README.md
+++ b/packages/client/ui-skill/README.md
@@ -51,6 +51,8 @@ The source implements no adjudication hooks and no reference codec: the pick lan
 
 Catalogs cache per ordinary session with a single-flight fetch; the scope-birth `warm` hook prewarms the session's entry, the forwarded `agent-preset/selected` owner event drops that one session's entry (the catalog belongs to the preset, and a blank session may switch after the warm), and `connection/reset` clears everything. Catalog-addressed continuable children resolve no skill candidates locally because the existing skill RPC requires an attached session; viewing their persisted history must not activate them. The list RPC rides the plugin's root-context connection captured at registration; draft chip visuals derive from the `lexicon` scan.
 
+Each catalog fetch requires an existing retained Client Session and waits for its initial history open to succeed before sending `skills/list`. A temporary `skillCatalog` reference holds that Session until the fetch settles. An unretained Session or a failed open rejects without sending the RPC; preset invalidation, connection reset, and plugin disposal also cancel a pending history wait.
+
 ### Registration
 
 The `/client` exports are the plugin body (`apply`/`inject`) only; the source object is internal to the registration effect. The tool row registers the `skill` wire name in ui-tool's keyed `tool.call.toolview` slot.
diff --git a/packages/client/ui-skill/README.zh.md b/packages/client/ui-skill/README.zh.md
index 7e6c8a7ece..2090711d5f 100644
--- a/packages/client/ui-skill/README.zh.md
+++ b/packages/client/ui-skill/README.zh.md
@@ -51,6 +51,8 @@ source 不实现任何裁决钩子，也没有引用 codec：pick 落下字面
 
 目录按普通会话缓存，拉取走 single-flight；scope 创建时的 `warm` 钩子预热该会话的缓存项，转发的 owner 事件 `agent-preset/selected` 丢弃该会话这一项（目录属于 preset，而空会话可能在预热之后才切换），`connection/reset` 清空全部缓存。由目录寻址的可继续 subagent 在客户端解析为没有 skill 候选，因为现有 skill RPC 要求会话已挂载；查看其持久化历史不得激活它。列表 RPC 使用插件注册时捕获的根上下文连接；草稿 chip 视觉由 `lexicon` 扫描派生。
 
+每次目录拉取都要求客户端已持有该会话，并等待首次历史打开成功后才发送 `skills/list`。临时的 `skillCatalog` 引用持续持有会话，直到拉取结束。未被持有的会话或打开失败会直接拒绝，不发送 RPC；预设失效、连接重置和插件释放也会取消正在等待的历史打开。
+
 ### 注册
 
 `/client` 导出接口只有插件主体（`apply`／`inject`）；source 对象是注册 effect 的内部实现。工具行把 `skill` wire 名称注册进 ui-tool 的 keyed `tool.call.toolview` slot。
diff --git a/packages/client/ui-skill/src/client/index.ts b/packages/client/ui-skill/src/client/index.ts
index 65f2dee986..2b6cd12ea2 100644
--- a/packages/client/ui-skill/src/client/index.ts
+++ b/packages/client/ui-skill/src/client/index.ts
@@ -25,6 +25,8 @@
  * not kill the prewarm other consumers will hit, so it carries its own
  * abort (fired only on invalidation/teardown) while a candidates caller
  * with an aborted signal just returns early.
+ * Catalog RPCs retain an existing Client Session through completion and
+ * wait for its initial history open to succeed before contacting the Host.
  *
  * This browser half also owns the `skill` keyed toolview: a replay-stable
  * accent row derived only from each logged call/result slice.
@@ -45,6 +47,13 @@ import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { SkillRow } from './SkillRow.tsx'
 import { en, NS, zh, type SkillKey } from './locales.ts'
 
+declare module '@deepseek-ai/dsh-api-session-controller/client' {
+  interface SessionReferenceSourceMap {
+    /** A skill-catalog fetch waiting for initial history and its RPC result. */
+    skillCatalog: unknown
+  }
+}
+
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
     /** The dedicated skill tool row's copy. */
@@ -100,10 +109,20 @@ export function apply(ctx: ClientContext): void {
     if (existing !== undefined) return existing
     const abort = new AbortController()
     const promise = (async () => {
-      const result = await skills.list({ sessionId }, abort.signal)
-      abort.signal.throwIfAborted()
-      if (!result.ok) throw new Error(`skills/list failed: ${result.error.code}: ${result.error.message}`)
-      return result.value.skills
+      if (sessions.binding(sessionId) === undefined) {
+        throw new Error(`skill catalog requires a retained session "${sessionId}"`)
+      }
+      return sessions.using(sessionId, { source: 'skillCatalog', signal: abort.signal }, async (reference) => {
+        abort.signal.throwIfAborted()
+        const state = reference.binding.session.getSnapshot()
+        if (state.openState !== 'open') {
+          throw state.openError ?? new Error(`session "${sessionId}" is not open`)
+        }
+        const result = await skills.list({ sessionId }, abort.signal)
+        abort.signal.throwIfAborted()
+        if (!result.ok) throw new Error(`skills/list failed: ${result.error.code}: ${result.error.message}`)
+        return result.value.skills
+      })
     })()
     const entry: CatalogFetch = { promise, abort }
     fetches.set(sessionId, entry)
diff --git a/packages/client/ui-skill/src/client/locales.ts b/packages/client/ui-skill/src/client/locales.ts
index d7a9b94228..ebd0910324 100644
--- a/packages/client/ui-skill/src/client/locales.ts
+++ b/packages/client/ui-skill/src/client/locales.ts
@@ -5,7 +5,7 @@ export const NS = 'skill'
 
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
-  'row.title': 'Skill',
+  'row.title': '加载技能',
   'row.running': '正在加载 skill',
   'row.failed': 'skill 加载失败',
   'row.stopped': 'skill 加载已中止',
diff --git a/packages/client/ui-skill/tests/browser-plugin.client.spec.ts b/packages/client/ui-skill/tests/browser-plugin.client.spec.ts
index 189d961bcf..ead382b4ac 100644
--- a/packages/client/ui-skill/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-skill/tests/browser-plugin.client.spec.ts
@@ -18,7 +18,8 @@ import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { InputTriggerService } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
-import { RemoteError, TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
+import { RemoteError, TestRemote, TestSessions } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionFixture } from '@deepseek-ai/dsh-client-test-runtime'
 import type { RemoteFailure } from '@deepseek-ai/dsh-api-remotes/client'
 import type { ClientSessionContext, InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
 import { apply, inject } from '../src/client/index.ts'
@@ -60,24 +61,30 @@ function providePresentation(ctx: Context): PresentationCapture {
 }
 
 /** Boot the plugin over fake slash/connection faces; returns the captured source and its ctx. */
-async function bench(list: ListFn, addressed?: SessionId) {
+async function bench(list: ListFn, addressed?: SessionId, opening: Pick<SessionFixture, 'initialOpen' | 'snapshot'> = {}) {
   const ctx = new Context()
   const openResource = vi.fn()
   ctx.provide('sidebarRight', { openResource })
   let captured: InputTriggerSource | undefined
   ctx.provide('inputTriggers', { registerSource: (src: InputTriggerSource) => { captured = src; return () => {} } })
-  ctx.provide('sessions', {
-    list: { getSnapshot: () => ({ byId: {} }) },
-    subagentAddress: (id: SessionId) => id === addressed
-      ? { parentSessionId: sid('parent'), childSessionId: id, mode: 'continuable' as const }
-      : undefined,
+  const sessions = new TestSessions(async (action) => { await action() }, ctx)
+  ctx.provide('sessions', sessions)
+  onTestFinished(async () => {
+    await sessions.disposeScopes()
+    await ctx.fiber.dispose()
   })
+  for (const id of ['s1', 's2', 'preview', 'first', 'second', 'child']) {
+    await sessions.add({ id, ...opening })
+    sessions.retainFor(ctx, id === addressed
+      ? { parentSessionId: sid('parent'), childSessionId: addressed, mode: 'continuable' }
+      : sid(id))
+  }
   const remote = new TestRemote(ctx, { skills: { list } })
   providePresentation(ctx)
   const fiber = ctx.plugin({ inject: [...inject], apply })
   onTestFinished(async () => { await fiber.dispose() })
   await fiber.await()
-  return { ctx, source: captured!, remote, fiber, openResource }
+  return { ctx, source: captured!, remote, fiber, openResource, sessions }
 }
 
 const CATALOG: SkillRow[] = [
@@ -125,7 +132,7 @@ describe('apply', () => {
     expect(presentation.dictionaries).toEqual([{
       namespace: 'skill', dictionaries: {
         zh: {
-          'row.title': 'Skill',
+          'row.title': '加载技能',
           'row.running': '正在加载 skill',
           'row.failed': 'skill 加载失败',
           'row.stopped': 'skill 加载已中止',
@@ -174,6 +181,60 @@ describe('apply', () => {
 })
 
 describe('candidates: sessionId addressing', () => {
+  it('waits for history and retains the Session until the shared skill RPC settles', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const response = Promise.withResolvers<ListResult>()
+    const list = vi.fn(() => response.promise)
+    const b = await bench(list, undefined, { initialOpen: () => opened.promise })
+    try {
+      const pending = b.source.candidates(proj('s1'), req(''))
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().retainedBy.skillCatalog).toBe(1)
+      expect(list).not.toHaveBeenCalled()
+      opened.resolve(undefined)
+      await vi.waitFor(() => { expect(list).toHaveBeenCalledOnce() })
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(2)
+      response.resolve({ ok: true, value: { skills: CATALOG } })
+      await pending
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      opened.resolve(undefined)
+      response.resolve({ ok: true, value: { skills: CATALOG } })
+    }
+  })
+
+  it.each([true, false])('refuses an unsuccessful history open (reported error: %s)', async (reported) => {
+    const error = new RemoteError('gateway/internal', 'history unavailable', {})
+    const list = vi.fn(listOk(CATALOG))
+    const b = await bench(list, undefined, { snapshot: { openState: 'error', openError: reported ? error : null } })
+    await expect(b.source.candidates(proj('s1'), req(''))).rejects.toThrow(reported ? 'history unavailable' : 'is not open')
+    expect(list).not.toHaveBeenCalled()
+    expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+  })
+
+  it('does not reopen a released Session for skill discovery', async () => {
+    const list = vi.fn(listOk(CATALOG))
+    const b = await bench(list)
+    await b.sessions.binding(sid('s1'))!.ctx.fiber.dispose()
+    await expect(b.source.candidates(proj('s1'), req(''))).rejects.toThrow('requires a retained session')
+    expect(list).not.toHaveBeenCalled()
+    expect(b.sessions.binding(sid('s1'))).toBeUndefined()
+  })
+
+  it('releases the shared read when the plugin unloads before history is ready', async () => {
+    const opened = Promise.withResolvers<undefined>()
+    const list = vi.fn(listOk(CATALOG))
+    const b = await bench(list, undefined, { initialOpen: () => opened.promise })
+    try {
+      const pending = expect(b.source.candidates(proj('s1'), req(''))).rejects.toThrow()
+      await b.fiber.dispose()
+      await pending
+      expect(list).not.toHaveBeenCalled()
+      expect(b.sessions.retainInfo(sid('s1')).getSnapshot().referenceCount).toBe(1)
+    } finally {
+      opened.resolve(undefined)
+    }
+  })
+
   it('lists via {sessionId} and ranks case-insensitive subsequence matches with prefixes first', async () => {
     const { list, payloads } = countingList()
     const { source } = await bench(list)
@@ -406,7 +467,7 @@ describe('reference preview', () => {
     expect(source.openReference!(session, { ref: '/review' })).toBe(true)
     const candidates = source.candidates(session, req(''))
     expect(openResource).not.toHaveBeenCalled()
-    expect(list).toHaveBeenCalledTimes(1)
+    await vi.waitFor(() => { expect(list).toHaveBeenCalledTimes(1) })
     gate.resolve({ ok: true, value: { skills: rows } })
     await candidates
     expect(openResource).toHaveBeenCalledExactlyOnceWith('dsh-resource://file/session/preview//skills/review/SKILL.md')
diff --git a/packages/client/ui-skill/tests/skill-row.client.spec.tsx b/packages/client/ui-skill/tests/skill-row.client.spec.tsx
index da55917f84..053f78b4a9 100644
--- a/packages/client/ui-skill/tests/skill-row.client.spec.tsx
+++ b/packages/client/ui-skill/tests/skill-row.client.spec.tsx
@@ -51,7 +51,7 @@ describe('SkillRow', () => {
   it('renders a compact Bash-shaped summary and discloses the exact instructions', () => {
     const inspect = vi.fn()
     const view = render(<SkillRow {...props(settled(), inspect)} />)
-    const row = screen.getByRole('button', { name: 'Skilldsh-manage-issues' })
+    const row = screen.getByRole('button', { name: '加载技能dsh-manage-issues' })
     expect(row.getAttribute('aria-expanded')).toBe('false')
     expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('ok')
     expect(view.container.querySelector('[data-tool="skill"] svg')?.getAttribute('width')).toBe('14')
@@ -95,7 +95,7 @@ describe('SkillRow', () => {
       isError: true,
       error: { name: 'SkillError', code: 'missing' },
     }))} />)
-    const row = screen.getByRole('button', { name: 'skill 加载失败SkillSkillError: missing resource' })
+    const row = screen.getByRole('button', { name: 'skill 加载失败加载技能SkillError: missing resource' })
     expect(view.container.querySelector('[data-tool="skill"]')?.getAttribute('data-state')).toBe('error')
     expect(view.container.querySelector('[data-tool="skill"] > div > span:first-child svg')).not.toBeNull()
     expect(view.container.querySelector('[data-tool="skill"] [data-state]')).toBeNull()
@@ -128,7 +128,7 @@ describe('SkillRow', () => {
       isError: true,
       error: { name: 'SkillError', code: 'missing' },
     }))} />)
-    const errorRow = screen.getByRole('button', { name: 'skill 加载失败SkillSkillError: missing' })
+    const errorRow = screen.getByRole('button', { name: 'skill 加载失败加载技能SkillError: missing' })
     fireEvent.click(errorRow)
     expect(screen.getAllByText('SkillError: missing')).toHaveLength(2)
   })
diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml
index 45a496719c..271593d30b 100644
--- a/packages/client/ui-subagent/README.i18n.yaml
+++ b/packages/client/ui-subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-subagent/README.md
-README.md: 1404e893add386b88a24d78675a4f0be06f497a0
-README.zh.md: 97c743b580e25cd50bcb01a3a7547cb7415a0e08
+README.md: b3dfb4a3aa56dbf240f4b76db410d45cc6ae5651
+README.zh.md: a6ebd6da3c3caba2a3bd015da450b5a33ab79d67
diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md
index 1404e893ad..b3dfb4a3aa 100644
--- a/packages/client/ui-subagent/README.md
+++ b/packages/client/ui-subagent/README.md
@@ -25,9 +25,9 @@ Use this package to browse every subagent conversation beneath a parent session,
 <a id="use-this-package"></a>
 ## Use this package
 
-The session header keeps the current session title as the lineage breadcrumb and appends a `/` count trigger when its direct catalog has entries or a read has failed. An absent catalog, an empty loading catalog, or a successfully loaded empty catalog hides the count trigger. The trigger opens that direct catalog, reports its total and running counts, and loads nested catalogs only when their rows expand. Select any depth to open that child's conversation with its exact `{parentSessionId, childSessionId, mode}` address, or use the row's trailing arrow to open the same address in the right Sidebar, preferring a separate pane when room permits.
+The session header keeps the current session title as the lineage breadcrumb; when the session's direct catalog has entries or a read has failed, the descendant-count trigger renders in the header actions band after the task list, with no breadcrumb separator. An absent catalog, an empty loading catalog, or a successfully loaded empty catalog hides the count trigger. The trigger opens that direct catalog, reports its total and running counts, and loads nested catalogs only when their rows expand. Select any depth to open that child's conversation with its exact `{parentSessionId, childSessionId, mode}` address, or use the row's trailing arrow to open the same address in the right Sidebar, preferring a separate pane when room permits.
 
-This package registers the `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` resource and builtin Sidebar tab type. The resource refreshes the direct-parent catalog before it retains the child `SessionReference`, and releases the reference when the tab record closes. The tab renders the shared `conversation.content` Factory through `sidebar.chat.conversation`, fixes the local View to Chat, and omits the main Conversation header and width controls.
+This package registers the `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` resource and builtin Sidebar tab type. The resource retains the child `SessionReference` directly from its address without refreshing the parent catalog, and releases the reference when the tab record closes. The tab renders the shared `conversation.content` Factory through `sidebar.chat.conversation`, fixes the local View to Chat, and omits the main Conversation header and width controls.
 
 ### Browsing the tree
 
@@ -55,6 +55,8 @@ The catalog and composer behavior are specified by the [Web subagent conversatio
 
 The header lineage renderer reads `projectionsBySession` through the standard `useSessions` hook. The renderer selects `subagentCatalog` from each Session’s shared values for membership, disclosure, and counts; Activity prefers the unified UI status and falls back to Session summaries; summaries supply titles and usage. Expanding a row loads its initial catalog when needed. Live projection frames update every loaded level without menu subscriptions or repeated membership queries. A row remains expandable while its catalog is absent, loading, or failed, and becomes a known leaf after a ready empty catalog.
 
+Opening a catalog dropdown does not request its root catalog. Child-catalog expansion and failed-read retries call `refreshProjection`; shared projection-value changes update the display automatically.
+
 Breadcrumb addresses derive from the Provider-bound Session address and loaded parent catalogs, including never-selected ancestors.
 
 ### Duration, completion, and tokens
@@ -65,6 +67,8 @@ Each visible catalog level advances its own clock while it contains a running ch
 
 One-shot children always elect a read-only composer. A continuable child elects one only when its exact parent is unavailable and the child is not running; otherwise the ordinary composer's Session routes prompts through `subagents/prompt`. This package never receives host context or calls a model-facing tool.
 
+Unknown-mode catalog rows remain visible and clickable, using the child id when no label is available. Their composer is read-only until child history establishes a supported mode; a read failure is reported in the child conversation.
+
 </details>
 
 -----
diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md
index 97c743b580..a6ebd6da3c 100644
--- a/packages/client/ui-subagent/README.zh.md
+++ b/packages/client/ui-subagent/README.zh.md
@@ -25,9 +25,9 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-会话页头保留当前会话 title 作为谱系面包屑，并在直接目录有子项或读取失败时追加 `/` 数量触发器。目录缺席、空目录加载中或成功加载为空时，均隐藏数量触发器。触发器打开该直接目录，报告总数与运行数，并且只在行展开时加载嵌套目录。选择任意深度，即可用该子会话的确切 `{parentSessionId, childSessionId, mode}` 地址打开其对话；也可以使用行尾箭头在右侧 Sidebar 打开同一地址，并在空间允许时优先使用独立分栏。
+会话页头把当前会话标题作为谱系面包屑；当会话的直接目录有子项或读取失败时，后代数量触发器渲染在页头操作区、任务列表之后，不带任何面包屑分隔符。目录缺席、空目录加载中或成功加载为空时，均隐藏数量触发器。触发器打开该直接目录，报告总数与运行数，并且只在行展开时加载嵌套目录。选择任意深度，即可用该子会话的确切 `{parentSessionId, childSessionId, mode}` 地址打开其对话；也可以使用行尾箭头在右侧 Sidebar 打开同一地址，并在空间允许时优先使用独立分栏。
 
-本包注册 `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` 资源与 builtin Sidebar tab 类型。资源先刷新直接 parent 目录，再保留 child 的 `SessionReference`，并在 tab 记录关闭时释放 reference。tab 通过 `sidebar.chat.conversation` 渲染共享 `conversation.content` Factory，把局部 View 固定为 Chat，并省略主 Conversation 的 Header 与宽度控制。
+本包注册 `dsh-resource://subagentchat/session/<child>?parent=<parent>&mode=<mode>` 资源与 builtin Sidebar tab 类型。资源直接根据地址保留 child 的 `SessionReference`，不刷新 parent 目录，并在 tab 记录关闭时释放 reference。tab 通过 `sidebar.chat.conversation` 渲染共享 `conversation.content` Factory，把局部 View 固定为 Chat，并省略主 Conversation 的 Header 与宽度控制。
 
 ### 浏览目录
 
@@ -55,6 +55,8 @@ kind: "package-reference"
 
 页头谱系 renderer 通过标准 `useSessions` 钩子读取 `projectionsBySession`。renderer 从每个 Session 的共享值中选择 `subagentCatalog`，用于成员关系、展开控件与数量；活动状态优先使用统一 UI status，缺少时使用 Session 摘要；摘要提供标题与用量。展开行会按需加载初始目录。实时 projection 帧更新所有已加载层级，无需菜单订阅或重复成员查询。行在目录缺席、加载中或失败时保持可展开，并在目录就绪且为空后成为已知叶子。
 
+打开目录下拉菜单不会请求其根目录。展开子节点目录或重试失败读取时调用 `refreshProjection`；共享投影值的变化会自动更新显示。
+
 面包屑地址从 Provider 所绑定的 Session 地址和已加载的 parent 目录推导，也包括从未选中过的祖先。
 
 ### 耗时、完成状态与 token
@@ -65,6 +67,8 @@ kind: "package-reference"
 
 one-shot child 始终选用只读编辑器。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器；否则普通编辑器的会话会经 `subagents/prompt` 路由提示词。本包绝不接收宿主上下文，也不调用面向模型的工具。
 
+模式未知的目录项仍可见、可点击，没有标签时显示子会话 id。读取子历史并确认受支持模式前，输入区保持只读；读取失败在该子会话中报告。
+
 </details>
 
 -----
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
index b9a28a3781..46eda23205 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css
@@ -55,12 +55,6 @@
   flex: none;
 }
 
-.separator {
-  color: var(--dsw-alias-label-caption);
-  font-size: 14px;
-  line-height: 20px;
-}
-
 .activitySlot {
   display: inline-flex;
   flex: none;
diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
index 6dd416fb95..3f4190c94e 100644
--- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx
@@ -25,7 +25,7 @@ type Catalogs = Readonly<Record<SessionId, SubagentCatalogSnapshot>>
 export interface SubagentCatalogInjected {
   openChild: (address: SubagentAddress) => void
   openChildAside: (address: SubagentAddress) => void
-  refresh: (parentSessionId: SessionId) => void
+  refreshProjection: (parentSessionId: SessionId) => void
 }
 
 /** Full props for the session-header lineage renderer. */
@@ -42,7 +42,7 @@ interface CatalogRowsProps {
   level: number
   openChild: (address: SubagentAddress) => void
   openChildAside: (address: SubagentAddress) => void
-  refresh: (parentSessionId: SessionId) => void
+  refreshProjection: (parentSessionId: SessionId) => void
   toggleBranch: (childSessionId: SessionId) => void
   closeCatalog: () => void
 }
@@ -200,7 +200,7 @@ function isKnownLeaf(catalog: SubagentCatalogSnapshot | undefined): boolean {
 /** Render one catalog level and recurse only through explicitly expanded rows. */
 function CatalogRows({
   parentSessionId, currentSessionId, catalog, catalogs, summaries, expanded, level,
-  openChild, openChildAside, refresh, toggleBranch, closeCatalog, t,
+  openChild, openChildAside, refreshProjection, toggleBranch, closeCatalog, t,
 }: CatalogRowsProps & { t: TranslateNS<typeof NS> }) {
   const [now, setNow] = useState(() => Date.now())
   const running = catalog.entries.some(entry => entry.activity === 'running')
@@ -222,7 +222,7 @@ function CatalogRows({
           <button
             type="button"
             className={css.refresh}
-            onClick={() => { refresh(parentSessionId) }}
+            onClick={() => { refreshProjection(parentSessionId) }}
           >
             <IconRefreshOutlineRegular size={14} />
             {t('retry')}
@@ -238,7 +238,8 @@ function CatalogRows({
           || (childCatalog.state === 'loading' && childCatalog.entries.length === 0)
         const summary = summaries[entry.id]
         const label = entry.label ?? entry.id
-        const mode = entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
+        const mode = entry.mode === 'unknown' ? t('mode.unknown')
+          : entry.mode === 'one-shot' ? t('mode.oneShot') : t('mode.continuable')
         const completed = entry.activity === 'inactive'
           && summary?.projectionValues?.subagentTiming?.lastTurnCompleted === true
         const activity = entry.activity === 'running'
@@ -382,7 +383,7 @@ function CatalogRows({
                       level={level + 1}
                       openChild={openChild}
                       openChildAside={openChildAside}
-                      refresh={refresh}
+                      refreshProjection={refreshProjection}
                       toggleBranch={toggleBranch}
                       closeCatalog={closeCatalog}
                       t={t}
@@ -400,8 +401,6 @@ function CatalogRows({
 interface CatalogDropdownSharedProps extends SubagentCatalogInjected {
   /** Session whose direct catalog roots the tree. */
   rootSessionId: SessionId
-  /** Whether an ordinary title needs a breadcrumb separator before its count. */
-  separator?: boolean
   useSessions: SubagentHeaderLineageProps['useSessions']
   useSessionStatus: SubagentHeaderLineageProps['useSessionStatus']
   t: TranslateNS<typeof NS>
@@ -444,8 +443,8 @@ function catalogMenuPosition(trigger: HTMLButtonElement): CSSProperties {
 
 /** One trigger-plus-tree dropdown over the catalog rooted at `rootSessionId`. */
 function CatalogDropdown({
-  rootSessionId, currentSessionId, displayTitle, openTitle, variant, separator = false,
-  useSessions, useSessionStatus, openChild, openChildAside, refresh, t,
+  rootSessionId, currentSessionId, displayTitle, openTitle, variant,
+  useSessions, useSessionStatus, openChild, openChildAside, refreshProjection, t,
 }: CatalogDropdownProps) {
   const ancestorSwitcher = variant === 'switcher' && openTitle !== undefined
   const projections = useSessions(state => state.projectionsBySession)
@@ -505,7 +504,6 @@ function CatalogDropdown({
       if (trigger === null) return
       setOpen(true)
       setMenuPosition(catalogMenuPosition(trigger))
-      refresh(rootSessionId)
     }
     else {
       setOpen(false)
@@ -554,7 +552,7 @@ function CatalogDropdown({
       return
     }
     setExpanded(current => new Set(current).add(childSessionId))
-    refresh(childSessionId)
+    refreshProjection(childSessionId)
   }
 
   useEffect(() => {
@@ -645,7 +643,6 @@ function CatalogDropdown({
       onMouseEnter={scheduleHoverOpen}
       onMouseLeave={scheduleHoverClose}
     >
-      {separator && <span className={css.separator}>/</span>}
       <button
         ref={triggerRef}
         type="button"
@@ -710,7 +707,7 @@ function CatalogDropdown({
             level={1}
             openChild={openChild}
             openChildAside={openChildAside}
-            refresh={refresh}
+            refreshProjection={refreshProjection}
             toggleBranch={toggleBranch}
             closeCatalog={() => { changeOpen(false) }}
             t={t}
@@ -721,14 +718,46 @@ function CatalogDropdown({
   )
 }
 
+/** Full props for the root-session catalog entry in the header actions band. */
+export type SubagentCatalogActionProps =
+  PropsRuntime<'conversation.session.header.actions'> & SubagentCatalogInjected & PropsLocale<typeof NS>
+
+/**
+ * Session-header catalog action for root sessions: the descendant count and
+ * its dropdown, ordered after the task list. Child sessions render nothing
+ * here — their breadcrumb switcher in the lineage slot owns the same
+ * navigation.
+ * @param props - Session standard props plus the catalog actions and translator.
+ * @returns The count dropdown, or null on a child session.
+ */
+export function SubagentCatalogAction({
+  sessionId, useSessions, useSessionStatus, openChild, openChildAside, refreshProjection, t,
+}: SubagentCatalogActionProps) {
+  const isChild = useSessions(state => state.byId[sessionId]?.origin === 'subagent')
+  if (isChild) return null
+  return (
+    <CatalogDropdown
+      key={sessionId}
+      rootSessionId={sessionId}
+      variant="count"
+      useSessions={useSessions}
+      useSessionStatus={useSessionStatus}
+      openChild={openChild}
+      openChildAside={openChildAside}
+      refreshProjection={refreshProjection}
+      t={t}
+    />
+  )
+}
+
 /**
  * Render one breadcrumb title together with its subagent navigation.
  * @param props - Breadcrumb title, session standard props, and catalog actions.
- * @returns An ordinary-title direct-child count, or a title-and-chevron sibling switcher.
+ * @returns A title-and-chevron sibling switcher, or nothing on a root session.
  */
 export function SubagentHeaderLineage({
   lineageSessionId, displayTitle, openTitle,
-  useSessions, useSession, useSessionStatus, openChild, openChildAside, refresh, t,
+  useSessions, useSession, useSessionStatus, openChild, openChildAside, refreshProjection, t,
 }: SubagentHeaderLineageProps) {
   const address = useSession(session => session.subagent?.address)
   const parentId = useSessions((state) => {
@@ -738,18 +767,10 @@ export function SubagentHeaderLineage({
     }
     return undefined
   })
-  const shared = { useSessions, useSessionStatus, openChild, openChildAside, refresh, t }
-  if (parentId === undefined) {
-    return (
-      <CatalogDropdown
-        key={lineageSessionId}
-        rootSessionId={lineageSessionId}
-        variant="count"
-        separator
-        {...shared}
-      />
-    )
-  }
+  const shared = { useSessions, useSessionStatus, openChild, openChildAside, refreshProjection, t }
+  // Root sessions carry no breadcrumb; their descendant count lives in the
+  // header actions band (SubagentCatalogAction), after the task list.
+  if (parentId === undefined) return null
   return (
     <>
       <CatalogDropdown
diff --git a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
index 158e8cb77b..07feb84f55 100644
--- a/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
+++ b/packages/client/ui-subagent/src/client/SubagentReadOnlyComposer.tsx
@@ -4,7 +4,7 @@ import css from './SubagentReadOnlyComposer.module.css'
 
 /** Why a catalog-addressed conversation cannot accept human input. */
 export interface SubagentReadOnlyMatch {
-  reason: 'one-shot' | 'parent-unavailable'
+  reason: 'one-shot' | 'parent-unavailable' | 'unknown'
 }
 
 /** Full chain props after the read-only subagent selector accepts the owner currency. */
@@ -24,7 +24,7 @@ export function SubagentReadOnlyComposer({
     <div className={css.frame} role="status">
       <strong>{t(oneShot ? 'readonly.oneShot.title' : 'readonly.title')}</strong>
       <span>
-        {t(oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
+        {t(matched.reason === 'unknown' ? 'readonly.unknown.body' : oneShot ? 'readonly.oneShot.body' : 'readonly.body')}
       </span>
     </div>
   )
diff --git a/packages/client/ui-subagent/src/client/index.ts b/packages/client/ui-subagent/src/client/index.ts
index 0055ea8c3f..fc70c93abf 100644
--- a/packages/client/ui-subagent/src/client/index.ts
+++ b/packages/client/ui-subagent/src/client/index.ts
@@ -3,7 +3,7 @@ import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import type { SubagentAddress } from '@deepseek-ai/dsh-subagent/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { SubagentHeaderLineage, type SubagentCatalogInjected } from './SubagentHeaderLineage.tsx'
+import { SubagentCatalogAction, SubagentHeaderLineage, type SubagentCatalogInjected } from './SubagentHeaderLineage.tsx'
 import {
   SubagentReadOnlyComposer, type SubagentReadOnlyMatch,
 } from './SubagentReadOnlyComposer.tsx'
@@ -24,7 +24,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 export type {
-  SubagentCatalogInjected, SubagentHeaderLineageProps,
+  SubagentCatalogActionProps, SubagentCatalogInjected, SubagentHeaderLineageProps,
 } from './SubagentHeaderLineage.tsx'
 export type {
   SubagentReadOnlyComposerProps, SubagentReadOnlyMatch,
@@ -37,6 +37,7 @@ export const inject = ['sessions', 'uiWorkspace', 'slots', 'locale', 'sidebarRig
 function selectReadOnlySubagent(owner: ComposerChainProps): SubagentReadOnlyMatch | null {
   const subagent = owner.session?.subagent
   if (subagent === undefined || subagent === null) return null
+  if (subagent.address.mode === 'unknown') return { reason: 'unknown' }
   if (subagent.address.mode === 'one-shot') return { reason: 'one-shot' }
   // Until a Host summary establishes parent availability, keep the normal
   // disabled composer instead of claiming that the parent is offline.
@@ -56,7 +57,6 @@ export function apply(ctx: ClientContext): void {
   ctx.inject(['resources', 'sidebarRightTabs'], (scope) => {
     registerSidebarChat(scope, ctx.locale.bind(NS))
   })
-  const sessions = ctx.sessions
   const catalogActions = (_parentSessionId: SessionId): SubagentCatalogInjected => ({
     openChild(address: SubagentAddress) {
       ctx.uiWorkspace.openSession(address)
@@ -67,8 +67,8 @@ export function apply(ctx: ClientContext): void {
         preferNewPane: true,
       })
     },
-    refresh(parentSessionId: SessionId) {
-      void sessions.refreshProjections(parentSessionId)
+    refreshProjection(parentSessionId: SessionId) {
+      void ctx.sessions.refreshProjections(parentSessionId)
     },
   })
   ctx.slots.inject(
@@ -79,6 +79,18 @@ export function apply(ctx: ClientContext): void {
       inject: catalogActions,
     }, SubagentHeaderLineage),
   )
+  ctx.slots.inject(
+    'conversation.session.header.actions',
+    () => ctx.slots.register({
+      name: 'conversation.session.header.actions',
+      id: 'subagent-catalog',
+      // After the task list: the preset label leads, running work follows,
+      // and delegation navigation closes the band.
+      order: 30,
+      locale: NS,
+      inject: catalogActions,
+    }, SubagentCatalogAction),
+  )
   ctx.slots.inject(
     'conversation.composer',
     () => ctx.slots.register({
diff --git a/packages/client/ui-subagent/src/client/locales.ts b/packages/client/ui-subagent/src/client/locales.ts
index cc966d411c..c17a2f3cb1 100644
--- a/packages/client/ui-subagent/src/client/locales.ts
+++ b/packages/client/ui-subagent/src/client/locales.ts
@@ -24,6 +24,8 @@ export const zh = {
   'retry': '重试',
   'mode.oneShot': '一次性',
   'mode.continuable': '可继续',
+  'mode.unknown': '模式未知',
+  'readonly.unknown.body': '读取子会话后才能确定是否可继续。',
   'activity.running': '正在运行',
   'activity.completed': '已完成',
   'activity.inactive': '当前未运行',
@@ -64,6 +66,8 @@ export const en: Record<SubagentKey, string> = {
   'retry': 'Retry',
   'mode.oneShot': 'one-shot',
   'mode.continuable': 'continuable',
+  'mode.unknown': 'unknown mode',
+  'readonly.unknown.body': 'Read the child session to determine whether it can be continued.',
   'activity.running': 'running',
   'activity.completed': 'completed',
   'activity.inactive': 'not running',
diff --git a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
index a4fe489714..ddc5bed7f9 100644
--- a/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
+++ b/packages/client/ui-subagent/src/client/sidebar-chat/index.tsx
@@ -73,7 +73,7 @@ export function parseSubagentChatAddress(value: string): SubagentAddress | undef
   if (parts.length !== 2 || parts[0] !== 'session') return undefined
   const parentSessionId = url.searchParams.get('parent')
   const mode = url.searchParams.get('mode')
-  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable')) {
+  if (parentSessionId === null || parentSessionId === '' || (mode !== 'one-shot' && mode !== 'continuable' && mode !== 'unknown')) {
     return undefined
   }
   try {
@@ -106,8 +106,6 @@ function subagentChatResourceProvider(sessions: ISessions): ResourceProvider<'su
       const address = parseSubagentChatAddress(resourceAddress)
       if (address === undefined) throw new Error(`ui-subagent: invalid chat resource address "${resourceAddress}"`)
       if (isAbortRequested(signal)) return
-      await sessions.refreshProjections(address.parentSessionId)
-      if (isAbortRequested(signal)) return
       const reference = sessions.retain(address, { source: 'sidebarChat', signal })
       try {
         yield { ok: true, value: { address, reference } }
diff --git a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
index 49b2ac6016..d5fe68c02b 100644
--- a/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.client.spec.ts
@@ -35,7 +35,7 @@ const sid = (id: string) => id as SessionId
 function sessionsWith(sessions: SessionSummary[]) {
   const byId: Record<string, SessionSummary> = {}
   for (const s of sessions) byId[s.id] = s
-  const snapshot: SessionListState = { ids: sessions.map(s => s.id), byId, phase: 'ready', projectionsBySession: {}, jobsBySession: {} }
+  const snapshot: SessionListState = { ids: sessions.map(s => s.id), byId, phase: 'ready', projectionsBySession: {} }
   const actionCalls: { method: string; args: unknown[] }[] = []
   const address: SubagentAddress = {
     parentSessionId: sid('parent'),
@@ -64,6 +64,7 @@ async function provideSlotFaces(ctx: Context): Promise<void> {
     name: 'root',
     children: {
       'conversation.session.header.lineage': { kind: 'single', scope: 'session' },
+      'conversation.session.header.actions': { kind: 'list', scope: 'session' },
       'conversation.composer': { kind: 'chain', scope: 'session' },
     },
   } as never, () => null)
@@ -119,7 +120,7 @@ describe('apply', () => {
     }
     actions.openChild(address)
     actions.openChildAside(address)
-    actions.refresh(sid('parent'))
+    actions.refreshProjection(sid('parent'))
     expect(face.actionCalls).toEqual([
       { method: 'openSession', args: [address] },
       {
@@ -132,6 +133,13 @@ describe('apply', () => {
       { method: 'refreshProjections', args: [sid('parent')] },
     ])
 
+    // The root-session catalog seat registers in the actions band with the
+    // same business face, ordered after the task list.
+    const actionEntry = ctx.slots.entries('conversation.session.header.actions')
+      .find(entry => entry.options.id === 'subagent-catalog')!
+    expect(actionEntry.options.order).toBe(30)
+    expect(actionEntry.inject).toBe(catalogEntry.inject)
+
     const composerEntry = ctx.slots.entries('conversation.composer')
       .find(entry => entry.component === SubagentReadOnlyComposer)!
     const select = composerEntry.select as (owner: ComposerChainProps) => SubagentReadOnlyMatch | null
@@ -152,6 +160,8 @@ describe('apply', () => {
     // One-shot stays read-only even while running: it has no stop action.
     expect(select(owner({ address: { ...address, mode: 'one-shot' }, parentAvailable: true }, true)))
       .toEqual({ reason: 'one-shot' })
+    expect(select(owner({ address: { ...address, mode: 'unknown' }, parentAvailable: true })))
+      .toEqual({ reason: 'unknown' })
     expect(select(owner({ address }))).toBeNull()
     expect(select(owner({ address, parentAvailable: true }))).toBeNull()
     expect(select(owner({ address, parentAvailable: false })))
diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
index 626026fe54..381d7523fb 100644
--- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx
@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react'
-import { makeTranslate, RemoteError } from '@deepseek-ai/dsh-client-test-runtime'
+import { makeTranslate, RemoteError, sessionSnapshot } from '@deepseek-ai/dsh-client-test-runtime'
 import type {
   SessionListState, SessionSummary, SessionSnapshot,
 } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -9,7 +9,8 @@ import type { SubagentAddress, SubagentCatalogRow } from '@deepseek-ai/dsh-subag
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SessionStatusSnapshot } from '@deepseek-ai/dsh-client-ui-session/client'
 import {
-  SubagentHeaderLineage, type SubagentHeaderLineageProps,
+  SubagentCatalogAction, SubagentHeaderLineage,
+  type SubagentCatalogActionProps, type SubagentHeaderLineageProps,
 } from '../src/client/SubagentHeaderLineage.tsx'
 import { SubagentReadOnlyComposer } from '../src/client/SubagentReadOnlyComposer.tsx'
 import { zh } from '../src/client/locales.ts'
@@ -25,7 +26,7 @@ const CHILD = 'child' as SessionId
 const GRANDCHILD = 'grandchild' as SessionId
 const t: SubagentHeaderLineageProps['t'] = makeTranslate(zh)
 
-type CatalogFixture = { entries: readonly SubagentCatalogRow[]; parentAvailable: boolean; state: 'loading' | 'ready' | 'error'; error: SessionListState['projectionsBySession'][SessionId]['error'] }
+type CatalogFixture = { entries: readonly (SubagentCatalogRow | { id: SessionId; mode: 'unknown'; label?: string; activity: 'inactive' })[]; parentAvailable: boolean; state: 'loading' | 'ready' | 'error'; error: SessionListState['projectionsBySession'][SessionId]['error'] }
 
 function catalog(over: Partial<CatalogFixture> = {}): CatalogFixture {
   return {
@@ -75,25 +76,48 @@ function props(
       state: catalog.state, error: catalog.error,
       values: { subagentCatalog: catalog.entries.map(({ activity: _activity, ...entry }) => ({ ...entry, createdAt: 1 })) },
     }])) ,
-    jobsBySession: {},
   } satisfies SessionListState
   function useSessions<T>(select: (snapshot: SessionListState) => T): T {
     return select(state)
   }
+  const snapshot: SessionSnapshot = {
+    ...sessionSnapshot(PARENT),
+    subagent: boundAddress === undefined ? null : { address: boundAddress },
+  }
+  const unused = (): never => { throw new Error('Subagent header fixture does not provide this slot source or action') }
+  const standard = {
+    usePanelInfo: unused,
+    useSessionRetainInfo: unused,
+    useWorkspaces: unused,
+    useResource: unused,
+    useProjection: unused,
+    useConversation: unused,
+    useInput: unused,
+    useChat: unused,
+    useTrajectory: unused,
+    inputActions: {
+      captureInsertion: unused,
+      insertText: unused,
+      setDraft: unused,
+      addAttachments: unused,
+      removeAttachment: unused,
+      pruneAttachments: unused,
+      submit: unused,
+    },
+  }
   return {
+    ...standard,
     sessionId: PARENT,
     useSessions,
     useSessionStatus: <T,>(select: (snapshot: SessionStatusSnapshot) => T): T => select(statuses),
-    useSession: <T,>(select: (snapshot: SessionSnapshot) => T): T => select({
-      subagent: boundAddress === undefined ? undefined : { address: boundAddress },
-    } as SessionSnapshot),
+    useSession: <T,>(select: (snapshot: SessionSnapshot) => T): T => select(snapshot),
     openChild: vi.fn(),
     openChildAside: vi.fn(),
-    refresh: vi.fn(),
+    refreshProjection: vi.fn(),
     lineageSessionId: PARENT,
     displayTitle: 'Parent title',
     t,
-  } as unknown as SubagentHeaderLineageProps
+  } satisfies SubagentHeaderLineageProps
 }
 
 function summary(id: SessionId, updatedAt: number): SessionSummary {
@@ -115,6 +139,22 @@ function hoverCatalog(trigger: HTMLElement): void {
   act(() => { vi.advanceTimersByTime(150) })
 }
 
+/**
+ * Both header seats as the real header composes them: the breadcrumb switcher
+ * (child sessions, lineage slot) and the actions-band catalog entry (root
+ * sessions) — exactly one renders per form. The actions seat sees the same
+ * session the lineage renders.
+ */
+function HeaderCatalog(props: SubagentHeaderLineageProps) {
+  const actionProps: SubagentCatalogActionProps = { ...props, sessionId: props.lineageSessionId }
+  return (
+    <>
+      <SubagentHeaderLineage {...props} />
+      <SubagentCatalogAction {...actionProps} />
+    </>
+  )
+}
+
 describe('SubagentHeaderLineage', () => {
   it('shows current catalog-only child status before Host list discovery', () => {
     const input = props(catalog({ entries: [{ id: CHILD, mode: 'continuable', label: 'worker', activity: 'inactive' }] }))
@@ -122,7 +162,7 @@ describe('SubagentHeaderLineage', () => {
     const statuses: SessionStatusSnapshot = new Map([[CHILD, {
       running: true, completionUnread: false, pendingInteraction: undefined,
     }]])
-    render(<SubagentHeaderLineage {...input}
+    render(<HeaderCatalog {...input}
       useSessions={select => select({ ...initial, ids: [] })}
       useSessionStatus={select => select(statuses)}
     />)
@@ -139,13 +179,13 @@ describe('SubagentHeaderLineage', () => {
       ...injected,
       useSessions: select => select({ ...initial, projectionsBySession: projections }),
     }
-    const view = render(<SubagentHeaderLineage {...current} />)
+    const view = render(<HeaderCatalog {...current} />)
     expect(screen.queryByRole('button')).toBeNull()
 
     projections = {
       [PARENT]: { ...initial.projectionsBySession[PARENT]!, state: 'idle' },
     }
-    view.rerender(<SubagentHeaderLineage {...current} />)
+    view.rerender(<HeaderCatalog {...current} />)
     hoverCatalog(screen.getByRole('button'))
     expect(screen.getByRole('treeitem', { name: /worker/ })).toBeTruthy()
     expect(screen.getByRole('treeitem', { name: /reviewer/ })).toBeTruthy()
@@ -170,12 +210,12 @@ describe('SubagentHeaderLineage', () => {
         origin: 'subagent',
       },
     }
-    const view = render(<SubagentHeaderLineage {...props(catalog(), {}, summaries)} />)
+    const view = render(<HeaderCatalog {...props(catalog(), {}, summaries)} />)
 
     const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
     expect(trigger.querySelector('[data-state="ongoing"]')).not.toBeNull()
 
-    view.rerender(<SubagentHeaderLineage {...props(catalog(), {}, {
+    view.rerender(<HeaderCatalog {...props(catalog(), {}, {
       ...summaries, [CHILD]: { ...summaries[CHILD]!, running: false },
     })} />)
     const inactiveTrigger = screen.getByRole('button', { name: '2 个子代理' })
@@ -185,7 +225,7 @@ describe('SubagentHeaderLineage', () => {
   it('does not count Sessions outside projected membership', () => {
     const fork = 'fork' as SessionId
     const forkChild = 'fork-child' as SessionId
-    render(<SubagentHeaderLineage {...props(catalog({
+    render(<HeaderCatalog {...props(catalog({
       entries: [{
         id: CHILD, mode: 'continuable', label: 'worker', activity: 'inactive',
       }],
@@ -204,11 +244,11 @@ describe('SubagentHeaderLineage', () => {
 
   it('renders stable rows and catalog-addressed navigation', () => {
     const input = props(catalog())
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     hoverCatalog(trigger)
 
-    expect(input.refresh).toHaveBeenCalledWith(PARENT)
+    expect(input.refreshProjection).not.toHaveBeenCalled()
     expect(screen.getAllByRole('treeitem')).toHaveLength(2)
     expect(screen.getByText('正在扫描项目文件 · 可继续 · 正在运行')).toBeTruthy()
     expect(screen.getByText('一次性 · 当前未运行')).toBeTruthy()
@@ -242,14 +282,14 @@ describe('SubagentHeaderLineage', () => {
       },
     })
     const translate = vi.fn(base.t)
-    render(<SubagentHeaderLineage {...base} t={translate} />)
+    render(<HeaderCatalog {...base} t={translate} />)
 
     expect(translate).toHaveBeenCalledWith('count.running.one', { count: 1 })
     expect(translate).toHaveBeenCalledWith('count.total.one', { count: 1 })
   })
 
   it('removes the disclosure column from branchless catalog levels', () => {
-    render(<SubagentHeaderLineage {...props(catalog({
+    render(<HeaderCatalog {...props(catalog({
       entries: catalog().entries.slice(0, 1),
     }), { [CHILD]: catalog({ entries: [] }) })} />)
     hoverCatalog(screen.getByRole('button', { name: /1 个子代理/ }))
@@ -258,7 +298,7 @@ describe('SubagentHeaderLineage', () => {
   })
 
   it('aligns a known leaf with siblings whose child catalog is still unknown', () => {
-    render(<SubagentHeaderLineage {...props(catalog(), { [CHILD]: catalog({ entries: [] }) })} />)
+    render(<HeaderCatalog {...props(catalog(), { [CHILD]: catalog({ entries: [] }) })} />)
     hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
 
     expect(screen.getByRole('treeitem', { name: /worker/ }).children).toHaveLength(2)
@@ -267,7 +307,7 @@ describe('SubagentHeaderLineage', () => {
 
   it('supports trigger/menu keyboard traversal, Escape focus restore, and outside close', async () => {
     const input = props(catalog())
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     fireEvent.keyDown(trigger, { key: 'ArrowDown' })
     await Promise.resolve()
@@ -296,7 +336,7 @@ describe('SubagentHeaderLineage', () => {
     const advance = async (duration: number): Promise<void> => {
       await act(async () => { await vi.advanceTimersByTimeAsync(duration) })
     }
-    const view = render(<SubagentHeaderLineage {...props(catalog())} />)
+    const view = render(<HeaderCatalog {...props(catalog())} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     const triggerRect = vi.spyOn(trigger, 'getBoundingClientRect')
       .mockReturnValue({ bottom: 40, left: 50 } as DOMRect)
@@ -333,7 +373,7 @@ describe('SubagentHeaderLineage', () => {
   })
 
   it('repositions an open catalog after viewport resize and document scroll', () => {
-    const view = render(<SubagentHeaderLineage {...props(catalog())} />)
+    const view = render(<HeaderCatalog {...props(catalog())} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     const bounds = vi.spyOn(trigger, 'getBoundingClientRect')
     bounds.mockReturnValue({ bottom: 20, left: 30 } as DOMRect)
@@ -356,12 +396,12 @@ describe('SubagentHeaderLineage', () => {
 
   it('cancels a pending hover when the trigger becomes hidden', async () => {
     vi.useFakeTimers()
-    const view = render(<SubagentHeaderLineage {...props(catalog())} />)
+    const view = render(<HeaderCatalog {...props(catalog())} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
 
     fireEvent.mouseEnter(trigger.parentElement!)
     await vi.advanceTimersByTimeAsync(149)
-    view.rerender(<SubagentHeaderLineage {...props(catalog({ entries: [] }))} />)
+    view.rerender(<HeaderCatalog {...props(catalog({ entries: [] }))} />)
     expect(screen.queryByRole('button')).toBeNull()
 
     await vi.advanceTimersByTimeAsync(1)
@@ -383,7 +423,7 @@ describe('SubagentHeaderLineage', () => {
         },
       ],
     }))
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     fireEvent.keyDown(trigger, { key: 'Tab' })
     expect(screen.queryByRole('tree')).toBeNull()
@@ -402,6 +442,16 @@ describe('SubagentHeaderLineage', () => {
     })
   })
 
+  it('keeps unknown catalog children clickable by their durable parent address', () => {
+    const input = props(catalog({ entries: [{ id: CHILD, mode: 'unknown', activity: 'inactive' }] }))
+    render(<HeaderCatalog {...input} />)
+    hoverCatalog(screen.getByRole('button', { name: /子代理/ }))
+    const row = screen.getByRole('treeitem', { name: new RegExp(CHILD) })
+    expect(row.textContent).toContain('模式未知')
+    fireEvent.keyDown(row, { key: 'Enter' })
+    expect(input.openChild).toHaveBeenCalledWith({ parentSessionId: PARENT, childSessionId: CHILD, mode: 'unknown' })
+  })
+
   it('shows durable completion and token totals, ticks active duration, and freezes inactive rows', async () => {
     const now = 2_000_000_000_000
     const minute = 60_000
@@ -474,7 +524,7 @@ describe('SubagentHeaderLineage', () => {
       }]
     })) as Record<SessionId, SessionSummary>
     const input = props(catalog({ entries }), {}, summaries)
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     const trigger = screen.getByRole('button', { name: '1 个子代理，正在运行' })
     expect(within(trigger).getByText('9 个子代理')).toBeTruthy()
     hoverCatalog(trigger)
@@ -528,7 +578,7 @@ describe('SubagentHeaderLineage', () => {
         },
       },
     })
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     hoverCatalog(screen.getByRole('button', { name: '1 个子代理' }))
     const beforeExpand = vi.getTimerCount()
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
@@ -556,11 +606,11 @@ describe('SubagentHeaderLineage', () => {
       [CHILD]: childCatalog,
       [GRANDCHILD]: grandchildCatalog,
     })
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
 
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
-    expect(input.refresh).toHaveBeenCalledWith(CHILD)
+    expect(input.refreshProjection).toHaveBeenCalledWith(CHILD)
     const nested = screen.getByRole('treeitem', { name: /indexer/ })
     expect(nested.getAttribute('aria-level')).toBe('2')
 
@@ -584,11 +634,11 @@ describe('SubagentHeaderLineage', () => {
       },
     }
     const deferred = props(catalog(), {}, summaries)
-    const view = render(<SubagentHeaderLineage {...deferred} />)
+    const view = render(<HeaderCatalog {...deferred} />)
     hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
 
-    expect(deferred.refresh).toHaveBeenCalledWith(CHILD)
+    expect(deferred.refreshProjection).toHaveBeenCalledWith(CHILD)
     expect(screen.getByRole('group').getAttribute('aria-busy')).toBe('true')
     expect(screen.getByText('正在加载子代理…')).toBeTruthy()
     expect(screen.queryByRole('treeitem', { name: '正在加载子代理' })).toBeNull()
@@ -596,7 +646,7 @@ describe('SubagentHeaderLineage', () => {
     const loading = props(catalog(), {
       [CHILD]: catalog({ entries: [], state: 'loading' }),
     }, summaries)
-    view.rerender(<SubagentHeaderLineage {...loading} />)
+    view.rerender(<HeaderCatalog {...loading} />)
     expect(screen.getByText('正在加载子代理…')).toBeTruthy()
 
     const ready = props(catalog(), {
@@ -613,7 +663,7 @@ describe('SubagentHeaderLineage', () => {
         ],
       }),
     }, summaries)
-    view.rerender(<SubagentHeaderLineage {...ready} />)
+    view.rerender(<HeaderCatalog {...ready} />)
     expect(screen.getByRole('group').getAttribute('aria-busy')).toBeNull()
     expect(screen.getByRole('treeitem', { name: /indexer/ }).querySelector('[data-state="idle"]')).not.toBeNull()
     expect(screen.getByRole('treeitem', { name: /critic/ }).querySelector('[data-state="ongoing"]')).not.toBeNull()
@@ -629,7 +679,7 @@ describe('SubagentHeaderLineage', () => {
         }],
       }),
     })
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     fireEvent.keyDown(trigger, { key: 'ArrowDown' })
     await Promise.resolve()
@@ -649,7 +699,7 @@ describe('SubagentHeaderLineage', () => {
         }],
       }),
     })
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
     hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
     fireEvent.click(screen.getByRole('button', { name: '展开 indexer 的下级子代理' }))
@@ -659,12 +709,12 @@ describe('SubagentHeaderLineage', () => {
   })
 
   it('hides an arrived empty catalog and exposes retry for a failed one', () => {
-    const absent = render(<SubagentHeaderLineage {...props(undefined)} />)
+    const absent = render(<HeaderCatalog {...props(undefined)} />)
     expect(screen.queryByRole('button')).toBeNull()
     absent.unmount()
 
     const empty = props(catalog({ entries: [] }))
-    const view = render(<SubagentHeaderLineage {...empty} />)
+    const view = render(<HeaderCatalog {...empty} />)
     expect(screen.queryByRole('button')).toBeNull()
     view.unmount()
 
@@ -673,11 +723,11 @@ describe('SubagentHeaderLineage', () => {
       state: 'error',
       error: new RemoteError('gateway/internal', 'index down', {}),
     }))
-    render(<SubagentHeaderLineage {...failed} />)
+    render(<HeaderCatalog {...failed} />)
     hoverCatalog(screen.getByRole('button', { name: /0 个子代理/ }))
     expect(screen.getByText('index down')).toBeTruthy()
     fireEvent.click(screen.getByRole('button', { name: /重试/ }))
-    expect(failed.refresh).toHaveBeenCalledWith(PARENT)
+    expect(failed.refreshProjection).toHaveBeenCalledWith(PARENT)
   })
 
   it('does not expose summary-only descendants as catalog rows', () => {
@@ -691,24 +741,23 @@ describe('SubagentHeaderLineage', () => {
       },
     }
     const absent = props(undefined, {}, summaries)
-    const view = render(<SubagentHeaderLineage {...absent} />)
+    const view = render(<HeaderCatalog {...absent} />)
     expect(screen.queryByRole('button')).toBeNull()
 
     const staleEmpty = props(catalog({ entries: [] }), {}, summaries)
-    view.rerender(<SubagentHeaderLineage {...staleEmpty} />)
+    view.rerender(<HeaderCatalog {...staleEmpty} />)
     expect(screen.queryByRole('button')).toBeNull()
   })
 
   it('hides a bare loading catalog and keeps the error fallback without focusable rows', async () => {
-    // Selecting any session schedules a catalog refresh; a loading snapshot
-    // with no other evidence of children must not flash the action in.
+    // A loading snapshot without evidence of children must not flash the action in.
     const loading = props(catalog({ entries: [], state: 'loading' }))
-    const view = render(<SubagentHeaderLineage {...loading} />)
+    const view = render(<HeaderCatalog {...loading} />)
     expect(screen.queryByRole('button')).toBeNull()
     view.unmount()
 
     const failed = props(catalog({ entries: [], state: 'error', error: null }))
-    render(<SubagentHeaderLineage {...failed} />)
+    render(<HeaderCatalog {...failed} />)
     const trigger = screen.getByRole('button', { name: /0 个子代理/ })
     hoverCatalog(trigger)
     expect(screen.getByText('无法加载子代理')).toBeTruthy()
@@ -720,7 +769,7 @@ describe('SubagentHeaderLineage', () => {
 
   it('navigates from outside the tree and tolerates a deferred focus after unmount', async () => {
     const input = props(catalog())
-    const view = render(<SubagentHeaderLineage {...input} />)
+    const view = render(<HeaderCatalog {...input} />)
     const trigger = screen.getByRole('button', { name: /1 个子代理，正在运行/ })
     hoverCatalog(trigger)
     fireEvent.keyDown(screen.getByRole('tree'), { key: 'ArrowUp' })
@@ -739,23 +788,23 @@ describe('SubagentHeaderLineage', () => {
         }],
       }),
     })
-    const view = render(<SubagentHeaderLineage {...populated} />)
+    const view = render(<HeaderCatalog {...populated} />)
     hoverCatalog(screen.getByRole('button', { name: /1 个子代理，正在运行/ }))
     fireEvent.click(screen.getByRole('button', { name: '展开 worker 的下级子代理' }))
 
     const empty = props(catalog({ entries: [] }))
-    view.rerender(<SubagentHeaderLineage {...empty} />)
+    view.rerender(<HeaderCatalog {...empty} />)
     expect(screen.queryByRole('button')).toBeNull()
   })
 
-  it('places a separator before a visible ordinary-session direct-child count', () => {
-    const view = render(<SubagentHeaderLineage {...props(catalog())} />)
+  it('renders an ordinary-session direct-child count in the actions seat with no separator', () => {
+    const view = render(<HeaderCatalog {...props(catalog())} />)
 
-    expect(screen.getByText('/')).toBeTruthy()
+    expect(screen.queryByText('/')).toBeNull()
     expect(screen.getByRole('button', { name: /1 个子代理，正在运行/ })).toBeTruthy()
 
-    view.rerender(<SubagentHeaderLineage {...props(catalog({ entries: [] }))} />)
-    expect(screen.queryByText('/')).toBeNull()
+    view.rerender(<HeaderCatalog {...props(catalog({ entries: [] }))} />)
+    expect(screen.queryByRole('button')).toBeNull()
   })
 
   it('combines the current subagent title and chevron into the parent-catalog trigger', () => {
@@ -773,7 +822,7 @@ describe('SubagentHeaderLineage', () => {
       lineageSessionId: CHILD,
       displayTitle: 'worker',
     }
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
 
     const switcher = screen.getByRole('button', { name: '切换子代理：worker' })
     expect(switcher.className).toContain('switcherTrigger')
@@ -785,7 +834,7 @@ describe('SubagentHeaderLineage', () => {
     expect(switcherIcon?.getAttribute('height')).toBe('16')
 
     hoverCatalog(switcher)
-    expect(input.refresh).toHaveBeenCalledWith(PARENT)
+    expect(input.refreshProjection).not.toHaveBeenCalled()
     const current = screen.getByRole('treeitem', { name: /worker/ })
     expect(current.getAttribute('aria-current')).toBe('true')
     expect(within(current).getByText('worker').className).toContain('currentLabel')
@@ -806,7 +855,7 @@ describe('SubagentHeaderLineage', () => {
       lineageSessionId: CHILD,
       displayTitle: 'worker',
     }
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
 
     expect(screen.queryByRole('button', { name: '切换子代理：worker' })).toBeNull()
   })
@@ -825,7 +874,7 @@ describe('SubagentHeaderLineage', () => {
       lineageSessionId: CHILD,
       displayTitle: 'summary title',
     }
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
 
     expect(screen.getByRole('button', { name: `切换子代理：${CHILD}` })).toBeTruthy()
   })
@@ -849,7 +898,7 @@ describe('SubagentHeaderLineage', () => {
       displayTitle: '正在扫描项目文件',
       openTitle: vi.fn(),
     }
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
 
     const switcher = screen.getByRole('button', { name: '切换子代理：worker' })
     expect(switcher.className).toContain('ancestorSwitcherTrigger')
@@ -883,10 +932,10 @@ describe('SubagentHeaderLineage', () => {
       displayTitle: '正在扫描项目文件',
       ...(openTitle === undefined ? {} : { openTitle }),
     }
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
 
     expect(screen.getByRole('button', { name: '切换子代理：正在扫描项目文件' })).toBeTruthy()
-    expect(input.refresh).not.toHaveBeenCalled()
+    expect(input.refreshProjection).not.toHaveBeenCalled()
   })
 
   it('keeps a nested title switcher scoped to its direct-parent catalog', () => {
@@ -908,11 +957,11 @@ describe('SubagentHeaderLineage', () => {
       lineageSessionId: GRANDCHILD,
       displayTitle: 'indexer',
     }
-    render(<SubagentHeaderLineage {...input} />)
+    render(<HeaderCatalog {...input} />)
 
     hoverCatalog(screen.getByRole('button', { name: '切换子代理：indexer' }))
 
-    expect(input.refresh).toHaveBeenCalledWith(CHILD)
+    expect(input.refreshProjection).not.toHaveBeenCalled()
     const current = screen.getByRole('treeitem', { name: /indexer/ })
     expect(current.getAttribute('aria-current')).toBe('true')
     expect(within(current).getByText('indexer').className).toContain('currentLabel')
@@ -926,6 +975,11 @@ describe('SubagentReadOnlyComposer', () => {
     expect(screen.getByRole('status').textContent).toContain('父会话当前不在线')
   })
 
+  it('keeps an unknown child read-only until its descriptor is available', () => {
+    render(<SubagentReadOnlyComposer matched={{ reason: 'unknown' }} t={t} />)
+    expect(screen.getByRole('status').textContent).toContain('读取子会话后才能确定是否可继续')
+  })
+
   it('explains that one-shot histories never accept follow-ups', () => {
     render(<SubagentReadOnlyComposer matched={{ reason: 'one-shot' }} t={t} />)
     expect(screen.getByRole('status').textContent).toContain('一次性任务不支持后续消息')
diff --git a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
index 143a0cb595..7b67420498 100644
--- a/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
+++ b/packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx
@@ -38,6 +38,8 @@ describe('Sidebar chat address', () => {
     expect(parseSubagentChatAddress(resource)).toEqual(ADDRESS)
     expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'one-shot' })))
       .toEqual({ ...ADDRESS, mode: 'one-shot' })
+    expect(parseSubagentChatAddress(subagentChatAddress({ ...ADDRESS, mode: 'unknown' })))
+      .toEqual({ ...ADDRESS, mode: 'unknown' })
   })
 
   it.each([
@@ -47,7 +49,7 @@ describe('Sidebar chat address', () => {
     'dsh-resource://subagentchat/other/child?parent=parent&mode=continuable',
     'dsh-resource://subagentchat/session/child?mode=continuable',
     'dsh-resource://subagentchat/session/child?parent=&mode=continuable',
-    'dsh-resource://subagentchat/session/child?parent=parent&mode=unknown',
+    'dsh-resource://subagentchat/session/child?parent=parent&mode=invalid',
     'dsh-resource://subagentchat/session/%?parent=parent&mode=continuable',
   ])('rejects %s', (address) => {
     expect(parseSubagentChatAddress(address)).toBeUndefined()
@@ -114,7 +116,7 @@ describe('Sidebar chat registration', () => {
     const controller = new AbortController()
     const stream = provider!.open(subagentChatAddress(ADDRESS), { signal: controller.signal })[Symbol.asyncIterator]()
     expect(await stream.next()).toEqual({ done: false, value: { ok: true, value: { address: ADDRESS, reference } } })
-    expect(refreshProjections).toHaveBeenCalledWith(PARENT)
+    expect(refreshProjections).not.toHaveBeenCalled()
     expect(retain).toHaveBeenCalledWith(ADDRESS, { source: 'sidebarChat', signal: controller.signal })
     const completion = stream.next()
     await Promise.resolve()
@@ -129,17 +131,6 @@ describe('Sidebar chat registration', () => {
     expect(await yielded.next()).toEqual({ done: true, value: undefined })
     expect(release).toHaveBeenCalledTimes(2)
 
-    let finishRefresh: (() => void) | undefined
-    refreshProjections.mockImplementationOnce(() => new Promise<void>((resolve) => { finishRefresh = resolve }))
-    const abortedDuringRefresh = new AbortController()
-    const pending = provider!.open(
-      subagentChatAddress(ADDRESS), { signal: abortedDuringRefresh.signal },
-    )[Symbol.asyncIterator]().next()
-    await vi.waitFor(() => { expect(finishRefresh).toBeTypeOf('function') })
-    abortedDuringRefresh.abort()
-    finishRefresh?.()
-    expect(await pending).toEqual({ done: true, value: undefined })
-
     const alreadyAborted = new AbortController()
     alreadyAborted.abort()
     const stopped = provider!.open(subagentChatAddress(ADDRESS), { signal: alreadyAborted.signal })[Symbol.asyncIterator]()
diff --git a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
index 6f36e9fe6a..75fcdcd0d2 100644
--- a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
+++ b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
@@ -26,7 +26,7 @@ const COPY: Record<string, string> = {
 
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
-    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {} })
+    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {} })
   return bindSnapshotSelector(store)
 }
 function emptyWorkspaces() {
diff --git a/packages/client/ui-theme/tests/font-size-row.client.spec.tsx b/packages/client/ui-theme/tests/font-size-row.client.spec.tsx
index ded9cc0377..f75138b44a 100644
--- a/packages/client/ui-theme/tests/font-size-row.client.spec.tsx
+++ b/packages/client/ui-theme/tests/font-size-row.client.spec.tsx
@@ -28,7 +28,7 @@ const COPY: Record<string, string> = {
 /** Empty global standard-kit hooks (the row reads neither). */
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
-    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {} })
+    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {} })
   return bindSnapshotSelector(store)
 }
 function emptyWorkspaces() {
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index ce636be50c..72abda5bc3 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-tool/README.md
-README.md: 6a63c14d163742b1818320925248405831bd87b6
-README.zh.md: e53a97404ae17f0e93242c11dcc0b1f066542c12
+README.md: 3e216d9670f4fa58b0590f8cede54927d947d56d
+README.zh.md: 6445ee9d62555de36901300809955b7cb227f66f
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index 6a63c14d16..3e216d9670 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -27,6 +27,8 @@ English | [中文](README.zh.md)
 
 Tool calls appear in the conversation as cards: a root call tree with its nested subcalls, each atomic call rendered by its owning view. Every lifecycle state retains the tool's ordinary business glyph; failure and interruption remain explicit through the frozen call/result state, accessible status text, and failure summary. Users can open files or inspect calls through the Host callbacks.
 
+Shared Tool rows and Bash rows retain error and warning colors for failed and stopped summaries, including on hover. Hover darkens only summaries without those states.
+
 ### Registering a business tool view
 
 An owning business package registers its wire Tool name into `tool.call.toolview`:
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index e53a97404a..6445ee9d62 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -27,6 +27,8 @@ kind: "package-reference"
 
 工具调用在对话中显示为卡片：一个根调用树带其嵌套子调用，每个原子调用由所属视图渲染。所有生命周期状态都保留工具的普通业务图标；失败与中断仍通过冻结调用／结果状态、无障碍状态文本和失败摘要明确表达。用户可通过宿主回调打开文件或检查调用。
 
+共享工具行和 Bash 行的失败、停止摘要在悬停时仍保留错误色和警告色；只有不处于这两种状态的摘要会在悬停时加深。
+
 ### 注册业务工具视图
 
 拥有该视图的业务包将其 wire 工具名称注册进 `tool.call.toolview`：
diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
index 520e800a3a..1478b06961 100644
--- a/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.module.css
@@ -11,37 +11,6 @@
   flex-direction: column;
 }
 
-.row {
-  position: relative; /* sweep-glare overlay anchor */
-  overflow: hidden;
-}
-
-/* Running sweep (deepsuite ShimmerText pattern): a fixed-width glare band —
-   theme background at 60% — glides over the row content from off-left to
-   off-right, washing glyphs and icon toward the background as it passes.
-   ease-out with a 10% end hold gives each pass a beat before the next. */
-.root[data-state='running'] .row::after {
-  content: '';
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  left: 0;
-  width: 300px;
-  background: linear-gradient(
-    90deg,
-    transparent 0%,
-    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
-    transparent 100%
-  );
-  animation: dsh-tool-row-sweep 2.6s ease-out infinite;
-  pointer-events: none;
-}
-
-@keyframes dsh-tool-row-sweep {
-  0% { left: -300px; }
-  90%, 100% { left: 100%; }
-}
-
 .leading {
   flex-shrink: 0;
 }
@@ -67,6 +36,7 @@
 
 .title {
   font-weight: 400;
+  transition: color 100ms ease;
 }
 
 .sep {
@@ -87,6 +57,7 @@
   font-size: var(--dsh-content-font-size-secondary, 13px);
   line-height: calc(24px + var(--dsh-content-font-delta, 0px));
   color: var(--dsw-alias-label-tertiary);
+  transition: color 100ms ease;
 }
 
 /* Trailing summary fragment kept out of .summary's ellipsis, for a count whose
@@ -101,6 +72,13 @@
   font-size: var(--dsh-content-font-size-secondary, 13px);
   line-height: calc(24px + var(--dsh-content-font-delta, 0px));
   color: var(--dsw-alias-label-tertiary);
+  transition: color 100ms ease;
+}
+
+.row:hover .title,
+.row:hover .summary:not(.errorSummary):not(.stoppedSummary),
+.row:hover .summarySuffix {
+  color: var(--dsw-alias-label-primary);
 }
 
 /* Diff-row +/- totals: the code font, matching the diff body the numbers
@@ -143,8 +121,10 @@
   text-decoration-thickness: 1px;
   text-underline-offset: 3px;
   cursor: pointer;
+  transition: color 100ms ease;
 }
 
+.row:hover .fileLink,
 .fileLink:hover {
   color: var(--dsw-alias-label-primary);
   text-decoration-color: currentColor;
@@ -360,8 +340,9 @@
   border: 0.5px solid var(--dsw-alias-border-l1);
 }
 
-/* Visually hidden run-state label for assistive technology: the running sweep
-   and settlement summary tones are color-only. */
+/* Visually hidden run-state label for assistive technology: the business icon
+   and animated text treatment do not name the state, so this text carries the
+   running/failed/interrupted state to a screen reader. */
 .visuallyHidden {
   position: absolute;
   width: 1px;
diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
index 3799370527..62b91189fc 100644
--- a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
@@ -1,8 +1,8 @@
-import { useMemo, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import { memo, useCallback, useMemo, useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
 import {
   CodeBlock, DiffBlock, DisclosureRow, IconInspectOutlineRegular, ReadBlock, SearchBlock,
-  TerminalBlock, WebBlock,
+  TerminalBlock, TextShimmer, WebBlock,
   diffTotals,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsRenderSlots, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
@@ -101,7 +101,12 @@ function stateStatus(state: ToolRowState, t: TranslateNS<'conversation'>): strin
   }
 }
 
-export function ToolRow({
+/**
+ * Render one localized tool summary and lazily mounted result card.
+ * @param props - tool state, summary, output, and navigation callbacks.
+ * @returns the tool disclosure.
+ */
+export const ToolRow = memo(function ToolRow({
   t,
   variant,
   toolName,
@@ -134,9 +139,9 @@ export function ToolRow({
   const readLabels = useMemo(() => readBlockLabels(t), [t])
   const searchLabels = useMemo(() => searchBlockLabels(t), [t])
   const webLabels = useMemo(() => webBlockLabels(t), [t])
-  const terminalBody = terminal === undefined || terminal === null
+  const terminalBody = useMemo(() => terminal === undefined || terminal === null
     ? null
-    : localizeTerminalCardModel(terminal, t)
+    : localizeTerminalCardModel(terminal, t), [terminal, t])
   const diffBody = diff ?? null
   const readBody = read ?? null
   const imageBody = image !== undefined && image !== null && renderSlot !== undefined && loadImage !== undefined
@@ -156,6 +161,7 @@ export function ToolRow({
     [card, inputRaw, open, variant],
   )
   const status = stateStatus(state, t)
+  const running = state === 'running'
   const normalSummary = terminalBody?.description ?? (open ? detailsBody?.expandedSummary ?? summary : summary)
   // A failure keeps its first result line when available and otherwise turns
   // the ordinary summary red. An interruption turns the tool-owned summary
@@ -172,26 +178,159 @@ export function ToolRow({
   }, [diffBody])
   const settledWithCue = state === 'error' || state === 'stopped'
   const suffix = settledWithCue ? null : summarySuffix ?? diffStat
-  const toggleExpand = () => {
+  const toggleExpand = useCallback(() => {
     setExpanded(v => !v)
-  }
-  const openFile = filePath !== undefined && onOpenFile !== undefined && !settledWithCue
+  }, [])
+  const openFile = useMemo(() => filePath !== undefined && onOpenFile !== undefined && !settledWithCue
     ? (event: MouseEvent<HTMLButtonElement>) => {
       event.stopPropagation()
       if (filePathLine === undefined) onOpenFile(filePath)
       else onOpenFile(filePath, { line: filePathLine })
     }
-    : undefined
+    : undefined, [filePath, filePathLine, onOpenFile, settledWithCue])
   // Keep Enter/Space on the focused path link from bubbling to the row's
   // keydown handler, which would preventDefault() the key and toggle expand
   // instead of activating the link — the keyboard analogue of openFile's
   // stopPropagation. The native button still fires its own onClick from the key.
-  const fileLinkKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
+  const fileLinkKeyDown = useCallback((event: KeyboardEvent<HTMLButtonElement>) => {
     if (event.key === 'Enter' || event.key === ' ') event.stopPropagation()
-  }
+  }, [])
   // The code variant's program renders through CodeBlock (shiki), so only its
   // output joins the IN/OUT card; every other variant's input does too.
   const cardBody = variant === 'code' ? null : bodyText
+  const collapsedContent = useMemo(() => summaryText !== '' && (
+    /* An empty summary drops the separator with it (a row that is only
+       its title shows no trailing dot). */
+    <>
+      <span className={css.sep} aria-hidden />
+      {openFile !== undefined ? (
+        <button
+          type="button"
+          className={css.fileLink}
+          onClick={openFile}
+          onKeyDown={fileLinkKeyDown}
+        >
+          <TextShimmer active={running}>{summaryText}</TextShimmer>
+        </button>
+      ) : (
+        <span
+          className={clsx(
+            css.summary,
+            state === 'error' && css.errorSummary,
+            state === 'stopped' && css.stoppedSummary,
+          )}
+        >
+          <TextShimmer active={running}>{summaryText}</TextShimmer>
+        </span>
+      )}
+      {suffix !== null && (
+        <TextShimmer className={clsx(css.summarySuffix, suffix === diffStat && css.diffStat)} active={running}>{suffix}</TextShimmer>
+      )}
+    </>
+  ), [diffStat, fileLinkKeyDown, openFile, running, state, suffix, summaryText])
+  const expandedContent = useMemo(() => open ? (
+    <div className={clsx(css.bodyWrap, detailsBody !== null && css.detailsBodyWrap)}>
+      {askQuestionBody !== null
+        ? <AskQuestionCard card={askQuestionBody} />
+        : terminalBody !== null
+          ? (
+            <TerminalBlock
+              {...terminalBody.card}
+              maxLines={Infinity}
+              labels={terminalLabels}
+              className={css.terminalBody}
+            />
+          )
+          : diffBody !== null
+            ? <DiffBlock {...diffBody.card} labels={diffLabels} maxLines={CHAT_DIFF_MAX_LINES} className={css.diffBody} />
+            : readBody !== null
+              ? <ReadBlock {...readBody} labels={readLabels} maxLines={CHAT_READ_MAX_LINES} className={css.readBody} />
+              : imageBody !== null
+                ? (
+                  /* Label, gallery, then the result's OWN envelope text. The text
+                     comes from the image card model (which reads the result's text
+                     block), never from the row's flattened output: an image read's
+                     content is [text envelope, image block] and flattening
+                     JSON.stringifies the image block, printing the raw attachment
+                     object under the picture. It is not redundant either — the
+                     attachment slot can render nothing, and then this line is the
+                     only evidence an image was returned. */
+                  <div className={css.imageBody}>
+                    <div className={css.imageLabel}>{imageBody.label}</div>
+                    {renderSlot !== undefined && loadImage !== undefined && renderSlot('tool.call.images', {
+                      images: imageBody.images,
+                      loadImage,
+                      align: 'start',
+                    })}
+                    <div className={css.imageMeta}>{imageBody.text}</div>
+                  </div>
+                )
+                : searchBody !== null
+                  ? (
+                    <>
+                      <SearchBlock
+                        {...searchBody.card}
+                        labels={searchLabels}
+                        maxLines={CHAT_SEARCH_MAX_LINES}
+                        className={css.searchBody}
+                      />
+                      {/* A capped search's recovery locator lives only in the result
+                      text; show it below the card so the dropped rows survive. */}
+                      {searchBody.recovery !== undefined && (
+                        <div className={css.searchRecovery}>{searchBody.recovery}</div>
+                      )}
+                    </>
+                  )
+                  : webBody !== null
+                    ? <WebBlock {...webBody} labels={webLabels} className={css.webBody} />
+                    : detailsBody !== null
+                      ? <ToolDetails model={detailsBody} hasInspect={inspect !== undefined} t={t} onOpenFile={onOpenFile} />
+                      : (
+                        <>
+                          {variant === 'code' && bodyText !== null && (
+                            <div className={css.bodyScroll}>
+                              <CodeBlock code={bodyText} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
+                            </div>
+                          )}
+                          {(cardBody !== null || outputText !== null) && (
+                            <div className={css.ioCard}>
+                              {cardBody !== null && (
+                                <div className={css.ioSection}>
+                                  <span className={css.ioLabel}>{t('row.input')}</span>
+                                  <span className={css.ioText}>{cardBody}</span>
+                                </div>
+                              )}
+                              {cardBody !== null && outputText !== null && (
+                                <span className={css.ioDivider} aria-hidden />
+                              )}
+                              {outputText !== null && (
+                                <div className={css.ioSection}>
+                                  <span className={css.ioLabel}>{t('row.output')}</span>
+                                  <span className={css.ioText} data-error={state === 'error' || undefined}>
+                                    {outputText}
+                                  </span>
+                                </div>
+                              )}
+                            </div>
+                          )}
+                        </>
+                      )}
+      {inspect !== undefined && (
+        <button
+          type="button"
+          className={css.inspectButton}
+          onClick={inspect}
+        >
+          <IconInspectOutlineRegular />
+          {t('row.inspect')}
+        </button>
+      )}
+    </div>
+  ) : undefined, [
+    open, detailsBody, askQuestionBody, terminalBody, terminalLabels, diffBody, diffLabels, readBody, readLabels,
+    imageBody, renderSlot, loadImage, searchBody, searchLabels, webBody, webLabels, inspect, t, onOpenFile,
+    variant, bodyText, cardBody, outputText, state,
+  ])
   return (
     <div className={css.root} data-variant={variant} data-tool={toolName} data-state={state}>
       {status !== null && <span className={css.visuallyHidden}>{status}</span>}
@@ -202,140 +341,16 @@ export function ToolRow({
         chevronClassName={css.chevron}
         icon={icon}
         title={title}
+        running={running}
         open={open}
         expandable={expandable}
         expandOnRowClick
         keepContentWhenOpen
         onToggle={toggleExpand}
-        collapsedContent={summaryText !== '' && (
-          /* An empty summary drops the separator with it (a row that is only
-             its title shows no trailing dot). */
-          <>
-            <span className={css.sep} aria-hidden />
-            {openFile !== undefined ? (
-              <button
-                type="button"
-                className={css.fileLink}
-                onClick={openFile}
-                onKeyDown={fileLinkKeyDown}
-              >
-                {summaryText}
-              </button>
-            ) : (
-              <span
-                className={clsx(
-                  css.summary,
-                  state === 'error' && css.errorSummary,
-                  state === 'stopped' && css.stoppedSummary,
-                )}
-              >
-                {summaryText}
-              </span>
-            )}
-            {suffix !== null && (
-              <span className={clsx(css.summarySuffix, suffix === diffStat && css.diffStat)}>{suffix}</span>
-            )}
-          </>
-        )}
+        collapsedContent={collapsedContent}
       >
-        <div className={clsx(css.bodyWrap, detailsBody !== null && css.detailsBodyWrap)}>
-          {askQuestionBody !== null
-            ? <AskQuestionCard card={askQuestionBody} />
-            : terminalBody !== null
-              ? (
-                <TerminalBlock
-                  {...terminalBody.card}
-                  maxLines={Infinity}
-                  labels={terminalLabels}
-                  className={css.terminalBody}
-                />
-              )
-              : diffBody !== null
-                ? <DiffBlock {...diffBody.card} labels={diffLabels} maxLines={CHAT_DIFF_MAX_LINES} className={css.diffBody} />
-                : readBody !== null
-                  ? <ReadBlock {...readBody} labels={readLabels} maxLines={CHAT_READ_MAX_LINES} className={css.readBody} />
-                  : imageBody !== null
-                    ? (
-                      /* Label, gallery, then the result's OWN envelope text. The text
-                         comes from the image card model (which reads the result's text
-                         block), never from the row's flattened output: an image read's
-                         content is [text envelope, image block] and flattening
-                         JSON.stringifies the image block, printing the raw attachment
-                         object under the picture. It is not redundant either — the
-                         attachment slot can render nothing, and then this line is the
-                         only evidence an image was returned. */
-                      <div className={css.imageBody}>
-                        <div className={css.imageLabel}>{imageBody.label}</div>
-                        {renderSlot !== undefined && loadImage !== undefined && renderSlot('tool.call.images', {
-                          images: imageBody.images,
-                          loadImage,
-                          align: 'start',
-                        })}
-                        <div className={css.imageMeta}>{imageBody.text}</div>
-                      </div>
-                    )
-                    : searchBody !== null
-                      ? (
-                        <>
-                          <SearchBlock
-                            {...searchBody.card}
-                            labels={searchLabels}
-                            maxLines={CHAT_SEARCH_MAX_LINES}
-                            className={css.searchBody}
-                          />
-                          {/* A capped search's recovery locator lives only in the result
-                          text; show it below the card so the dropped rows survive. */}
-                          {searchBody.recovery !== undefined && (
-                            <div className={css.searchRecovery}>{searchBody.recovery}</div>
-                          )}
-                        </>
-                      )
-                      : webBody !== null
-                        ? <WebBlock {...webBody} labels={webLabels} className={css.webBody} />
-                        : detailsBody !== null
-                          ? <ToolDetails model={detailsBody} hasInspect={inspect !== undefined} t={t} onOpenFile={onOpenFile} />
-                          : (
-                            <>
-                              {variant === 'code' && bodyText !== null && (
-                                <div className={css.bodyScroll}>
-                                  <CodeBlock code={bodyText} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
-                                </div>
-                              )}
-                              {(cardBody !== null || outputText !== null) && (
-                                <div className={css.ioCard}>
-                                  {cardBody !== null && (
-                                    <div className={css.ioSection}>
-                                      <span className={css.ioLabel}>{t('row.input')}</span>
-                                      <span className={css.ioText}>{cardBody}</span>
-                                    </div>
-                                  )}
-                                  {cardBody !== null && outputText !== null && (
-                                    <span className={css.ioDivider} aria-hidden />
-                                  )}
-                                  {outputText !== null && (
-                                    <div className={css.ioSection}>
-                                      <span className={css.ioLabel}>{t('row.output')}</span>
-                                      <span className={css.ioText} data-error={state === 'error' || undefined}>
-                                        {outputText}
-                                      </span>
-                                    </div>
-                                  )}
-                                </div>
-                              )}
-                            </>
-                          )}
-          {inspect !== undefined && (
-            <button
-              type="button"
-              className={css.inspectButton}
-              onClick={inspect}
-            >
-              <IconInspectOutlineRegular />
-              {t('row.inspect')}
-            </button>
-          )}
-        </div>
+        {expandedContent}
       </DisclosureRow>
     </div>
   )
-}
+})
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
index ab8acd692c..9ef5b4b829 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
+++ b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.module.css
@@ -85,37 +85,12 @@
 }
 
 .root {
-  position: relative; /* sweep-glare overlay anchor */
-  overflow: hidden;
   display: flex;
   align-items: center;
   height: calc(24px + var(--dsh-content-font-delta, 0px));
   min-width: 0;
 }
 
-/* Running sweep glare — same deepsuite ShimmerText pattern as ToolRow. */
-.root[data-state='running']::after {
-  content: '';
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  left: 0;
-  width: 300px;
-  background: linear-gradient(
-    90deg,
-    transparent 0%,
-    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
-    transparent 100%
-  );
-  animation: dsh-bash-row-sweep 2.6s ease-out infinite;
-  pointer-events: none;
-}
-
-@keyframes dsh-bash-row-sweep {
-  0% { left: -300px; }
-  90%, 100% { left: 100%; }
-}
-
 .leading {
   position: relative; /* .chevronHover overlay anchor */
   flex: none;
@@ -172,6 +147,7 @@
   font-size: var(--dsh-content-font-size-secondary, 13px);
   line-height: calc(24px + var(--dsh-content-font-delta, 0px));
   color: var(--dsw-alias-label-secondary);
+  transition: color 100ms ease;
 }
 
 .sep {
@@ -192,6 +168,12 @@
   font-size: var(--dsh-content-font-size-secondary, 13px);
   line-height: calc(24px + var(--dsh-content-font-delta, 0px));
   color: var(--dsw-alias-label-tertiary);
+  transition: color 100ms ease;
+}
+
+.root:hover .title,
+.root:hover .summary:not(.errorSummary):not(.stoppedSummary) {
+  color: var(--dsw-alias-label-primary);
 }
 
 /* Error row's collapsed summary: the failure's first line in the error color. */
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
index 7b1f8653c5..ebbe18e532 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
@@ -1,8 +1,9 @@
-import { useMemo, useState, type KeyboardEvent } from 'react'
+import { memo, useCallback, useMemo, useState, type KeyboardEvent } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
 import clsx from 'clsx'
 import {
-  IconApiOutlineRegular, IconChevronDownOutlineRegular, IconInspectOutlineRegular, TerminalBlock,
+  IconApiOutlineRegular, IconChevronDownOutlineRegular, IconChevronUpOutlineRegular, IconInspectOutlineRegular,
+  TerminalBlock, TextShimmer,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ToolCallViewProps } from '../../contract/slots.ts'
@@ -20,23 +21,31 @@ import css from './bash-sample.module.css'
 
 type BashRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
+const BASH_ICON = <IconApiOutlineRegular size={14} />
+
 /** Visually hidden status for the color-only running sweep and error tone. */
 function stateStatus(state: ToolRowState, t: BashRowProps['t']): string | null {
   switch (state) {
     case 'running': return t('bash.running')
     case 'error': return t('bash.failed')
+    case 'stopped': return t('bash.stopped')
     default: return null
   }
 }
 
-/** Renders expandable Bash output with an accessible lifecycle label. */
-export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }: BashRowProps) {
-  const model = toolRowModel(toolName, block)
+/**
+ * Render expandable Bash output with an accessible lifecycle label.
+ * @param props - tool call, Session sources, locale, and inspection callback.
+ * @returns the Bash output row.
+ */
+export const BashRow = memo(function BashRow({ toolName, block, sessionId, useSessions, inspect, t }: BashRowProps) {
+  const model = useMemo(() => toolRowModel(toolName, block), [toolName, block])
   // An omitted shell workdir is the session workspace; relative values resolve
   // against it before reaching the terminal primitive.
   const cwd = useSessions(list => list.byId[sessionId]?.cwd)
-  const terminalModel = terminalCardModel(block, cwd)
-  const terminal = terminalModel === null ? null : localizeTerminalCardModel(terminalModel, t)
+  const terminalModel = useMemo(() => terminalCardModel(block, cwd), [block, cwd])
+  const terminal = useMemo(() => terminalModel === null ? null : localizeTerminalCardModel(terminalModel, t), [terminalModel, t])
+  const labels = useMemo(() => terminalBlockLabels(t), [t])
   // A failing exit status is the terminal card's own error signal (the call
   // itself settles isError:false), surfaced through the row's error summary.
   const state = model.state === 'ok' && terminalModel !== null && terminalFailed(terminalModel)
@@ -61,25 +70,25 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
   const settlementLine = state === 'error'
     ? model.errorSummary ?? normalSummary
     : state === 'stopped' ? t('bash.stopped') : null
-  const toggleExpand = () => {
+  const running = state === 'running'
+  const toggleExpand = useCallback(() => {
     setExpanded(v => !v)
-  }
-  const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
+  }, [])
+  const toggleFromKeyboard = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
     if (!expandable || (event.key !== 'Enter' && event.key !== ' ')) return
     event.preventDefault()
     toggleExpand()
-  }
-  const businessIcon = <IconApiOutlineRegular size={14} />
+  }, [expandable, toggleExpand])
   const leading = open
-    ? <IconChevronDownOutlineRegular className={css.chevron} />
+    ? <IconChevronUpOutlineRegular className={css.chevron} />
     : expandable
       ? (
         <>
-          <span className={css.iconIdle}>{businessIcon}</span>
+          <span className={css.iconIdle}>{BASH_ICON}</span>
           <IconChevronDownOutlineRegular className={clsx(css.chevron, css.chevronHover)} />
         </>
       )
-      : businessIcon
+      : BASH_ICON
   return (
     <div className={css.card}>
       <div
@@ -96,14 +105,14 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
       >
         <span className={css.leading}>{leading}</span>
         {status !== null && <span className={css.visuallyHidden}>{status}</span>}
-        <span className={css.title}>{t(model.titleKey)}</span>
+        <TextShimmer className={css.title} active={running}>{t(model.titleKey)}</TextShimmer>
         <span className={css.sep} aria-hidden />
         <span className={clsx(
           css.summary,
           state === 'error' && css.errorSummary,
           state === 'stopped' && css.stoppedSummary,
         )}>
-          {settlementLine ?? normalSummary}
+          <TextShimmer active={running}>{settlementLine ?? normalSummary}</TextShimmer>
         </span>
       </div>
       {open && (
@@ -113,7 +122,7 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
               <TerminalBlock
                 {...terminal.card}
                 maxLines={Infinity}
-                labels={terminalBlockLabels(t)}
+                labels={labels}
                 className={css.terminal}
               />
             )
@@ -148,7 +157,7 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
       )}
     </div>
   )
-}
+})
 
 /** Registers the standalone Bash conversation-row sample. */
 export const bashToolviewSample = {
diff --git a/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx
index 80615b752f..3f56f5f679 100644
--- a/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx
+++ b/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx
@@ -28,7 +28,7 @@ function listStore() {
       [SID]: { id: SID, title: 'r', displayTitle: 'r', running: false, retainedBy: {}, blank: false, updatedAt: 0 },
     },
     phase: 'ready',
-    projectionsBySession: {}, jobsBySession: {},
+    projectionsBySession: {},
   })
 }
 
@@ -48,7 +48,7 @@ describe('Tool presentation tails', () => {
     )
     expect(view.queryByTestId('icon')).not.toBeNull()
     const summary = view.getByText('s')
-    expect(summary.className).toContain('stoppedSummary')
+    expect(summary.parentElement?.className).toContain('stoppedSummary')
   })
 
   it('a settled others-variant row renders the sparkle icon in the leading slot', () => {
@@ -76,7 +76,7 @@ describe('Tool presentation tails', () => {
     }
     const view = render(<BashRow {...bashProps(settled)} />)
     const row = view.container.querySelector('[data-sample="bash"]')!
-    expect(row.textContent).toContain('Bash')
+    expect(row.textContent).toContain('运行命令')
     expect(row.textContent).toContain('Build')
     expect(row.getAttribute('data-clickable')).toBeNull()
   })
@@ -99,7 +99,7 @@ describe('Tool presentation tails', () => {
 
     const runningView = render(<BashRow {...bashProps(running)} />)
     expect(runningView.container.querySelector('[data-state="running"]')).not.toBeNull()
-    expect(runningView.getByText('Bash')).toBeTruthy()
+    expect(runningView.getByText('运行命令')).toBeTruthy()
     expect(runningView.getByText('List')).toBeTruthy()
     runningView.unmount()
 
@@ -107,14 +107,15 @@ describe('Tool presentation tails', () => {
     expect(errorView.container.querySelector('[data-sample="bash"]')).not.toBeNull()
     expect(errorView.container.querySelector('[data-state="error"]')).not.toBeNull()
     expect(errorView.container.querySelector('[data-state="error"] svg')).not.toBeNull()
-    expect(errorView.getByText('Bash')).toBeTruthy()
+    expect(errorView.getByText('运行命令')).toBeTruthy()
     expect(errorView.container.querySelector('[class*="_errorSummary_"]')).not.toBeNull()
     errorView.unmount()
 
     const stoppedView = render(<BashRow {...bashProps(stoppedResult)} />)
     expect(stoppedView.container.querySelector('[data-state="stopped"]')).not.toBeNull()
     expect(stoppedView.container.querySelector('[data-state="stopped"] svg')).not.toBeNull()
-    const stoppedSummary = stoppedView.getByText('已停止')
-    expect(stoppedSummary.className).toContain('stoppedSummary')
+    const stoppedSummary = stoppedView.getByRole('button').querySelector('[class*="_stoppedSummary_"]')
+    expect(stoppedSummary?.textContent).toBe('已停止')
+    expect(stoppedView.getAllByText('已停止')).toHaveLength(2)
   })
 })
diff --git a/packages/client/ui-tool/tests/details-models.client.spec.ts b/packages/client/ui-tool/tests/details-models.client.spec.ts
index 34c355b211..a38c41ff34 100644
--- a/packages/client/ui-tool/tests/details-models.client.spec.ts
+++ b/packages/client/ui-tool/tests/details-models.client.spec.ts
@@ -5,7 +5,7 @@ import type { ToolResultNode } from '@deepseek-ai/dsh-client-ui-chat/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { en } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
-import { statusLine } from '@deepseek-ai/dsh-tool-jobs/src/index.ts'
+import { statusLine } from '@deepseek-ai/dsh-tool-jobs/src/render.ts'
 import { presentation } from '@deepseek-ai/dsh-tool-session-query/src/presentation.ts'
 import { renderList, renderRead, renderSpawn } from '@deepseek-ai/dsh-tool-terminal/src/render.ts'
 import { formatSpillNotice } from '@deepseek-ai/dsh-spill-policy/notice'
diff --git a/packages/client/ui-tool/tests/diff-card.client.spec.tsx b/packages/client/ui-tool/tests/diff-card.client.spec.tsx
index d1b298c8fd..d7e37d6962 100644
--- a/packages/client/ui-tool/tests/diff-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.client.spec.tsx
@@ -202,7 +202,7 @@ describe('FileMutationRow diff card', () => {
     ids: [SID],
     byId: { [SID]: { id: SID, displayTitle: 'r', running: false, retainedBy: {}, blank: false, updatedAt: 0, cwd: '/w/app' } },
     phase: 'ready',
-    projectionsBySession: {}, jobsBySession: {},
+    projectionsBySession: {},
   })
 
   const rowProps = (block: RunningToolCall | ToolResultNode, toolName = 'edit'): FileMutationRowProps => ({
diff --git a/packages/client/ui-tool/tests/read-card.client.spec.tsx b/packages/client/ui-tool/tests/read-card.client.spec.tsx
index 366c4c69cb..f5ca38418e 100644
--- a/packages/client/ui-tool/tests/read-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.client.spec.tsx
@@ -206,7 +206,7 @@ describe('ReadRow keyed toolview', () => {
     ids: [SID],
     byId: { [SID]: { id: SID, displayTitle: 'r', running: false, retainedBy: {}, blank: false, updatedAt: 0, cwd: '/w/app' } },
     phase: 'ready',
-    projectionsBySession: {}, jobsBySession: {},
+    projectionsBySession: {},
   })
 
   const rowProps = (block: RunningToolCall | ToolResultNode): Parameters<typeof ReadRow>[0] => ({
diff --git a/packages/client/ui-tool/tests/search-card.client.spec.tsx b/packages/client/ui-tool/tests/search-card.client.spec.tsx
index ca8e8bde20..cee488b8b6 100644
--- a/packages/client/ui-tool/tests/search-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.client.spec.tsx
@@ -236,7 +236,7 @@ describe('SearchRow keyed card', () => {
 
   it('collapses to the summary row; expanding reveals the grep card', () => {
     const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
-    expect(view.getByText('Grep')).toBeTruthy()
+    expect(view.getByText('搜索文件内容')).toBeTruthy()
     expect(view.queryByText('Search')).toBeNull()
     // Collapsed: the card is not in the DOM until the row is expanded.
     expect(searchKindOf(view.container)).toBeNull()
@@ -250,7 +250,7 @@ describe('SearchRow keyed card', () => {
 
   it('expands to the glob path card', () => {
     const view = render(<SearchRow {...rowProps(settledGlob(), 'glob')} />)
-    expect(view.getByText('Glob')).toBeTruthy()
+    expect(view.getByText('查找文件')).toBeTruthy()
     expect(view.queryByText('Search')).toBeNull()
     expect(searchKindOf(view.container)).toBeNull()
     toggleRow(view)
diff --git a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
index bdeb4ee60e..d1087f7ce2 100644
--- a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
@@ -407,7 +407,7 @@ describe('BashRow terminal card', () => {
     ids: [SID],
     byId: { [SID]: { id: SID, displayTitle: 'r', running: false, retainedBy: {}, blank: false, updatedAt: 0 } },
     phase: 'ready',
-    projectionsBySession: {}, jobsBySession: {},
+    projectionsBySession: {},
   })
 
   const rowProps = (block: RunningToolCall | ToolResultNode): BashRowProps => ({
diff --git a/packages/client/ui-tool/tests/tool-row-styles.client.spec.ts b/packages/client/ui-tool/tests/tool-row-styles.client.spec.ts
index 28913a2939..db05c7f769 100644
--- a/packages/client/ui-tool/tests/tool-row-styles.client.spec.ts
+++ b/packages/client/ui-tool/tests/tool-row-styles.client.spec.ts
@@ -22,6 +22,14 @@ function declarations(selector: string): string[] {
 }
 
 describe('ToolRow.module.css summary line', () => {
+  it.each([
+    ['ToolRow', '../src/client/tool/components/ToolRow.module.css'],
+    ['BashRow', '../src/client/tool/toolviews/bash-sample.module.css'],
+  ] as const)('%s keeps stopped and error summaries outside hover darkening', (_name, path) => {
+    const sheet = readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+    expect(sheet).toContain('.summary:not(.errorSummary):not(.stoppedSummary)')
+  })
+
   it('keeps the summary suffix on one line and unshrunk', () => {
     // `flex: none` stops the box shrinking, not the text wrapping: without
     // `nowrap`, a row too narrow for title + separator + suffix wraps the `+n`
diff --git a/packages/client/ui-tool/tests/tool-row.client.spec.tsx b/packages/client/ui-tool/tests/tool-row.client.spec.tsx
index 6ef6cd713a..d4749831be 100644
--- a/packages/client/ui-tool/tests/tool-row.client.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.client.spec.tsx
@@ -81,10 +81,10 @@ describe('tool-call-model', () => {
     expect(t(toolRowModel('cordis_unmount', running({ name: 'cordis_unmount', argsRaw: '{}' })).titleKey)).toBe('工具调用')
   })
 
-  it('gives the pwsh shell row the bash family treatment with its own title', () => {
+  it('gives the pwsh shell row the bash family treatment and localized command title', () => {
     const m = toolRowModel('pwsh', running())
     expect(m.variant).toBe('bash')
-    expect(t(m.titleKey)).toBe('Pwsh')
+    expect(t(m.titleKey)).toBe('运行命令')
   })
 
   it('derives state across running/ok/error/interrupted', () => {
@@ -96,7 +96,7 @@ describe('tool-call-model', () => {
 
   it('derives the bash summary from description over command', () => {
     const m = toolRowModel('bash', running())
-    expect(t(m.titleKey)).toBe('Bash')
+    expect(t(m.titleKey)).toBe('运行命令')
     expect(m.summary).toBe('List files')
     expect(toolRowModel('bash', running({ argsRaw: '{"command":"pwd"}' })).summary).toBe('pwd')
   })
@@ -420,7 +420,7 @@ describe('ToolRow', () => {
   it('an error row without an error summary keeps the args summary', () => {
     const view = render(<ToolRow {...rowProps} state="error" errorSummary={null} />)
     const summary = view.getByText('List files')
-    expect(summary.className).toContain('errorSummary')
+    expect(summary.parentElement?.className).toContain('errorSummary')
   })
 
   it('renders summarySuffix outside the ellipsized summary span, and drops it on a failure line', () => {
@@ -499,7 +499,7 @@ describe('GenericToolCard', () => {
 
   it('renders the classified variant row from the frozen slice', () => {
     const view = render(<GenericToolCard {...props('bash', result())} />)
-    expect(view.getByText('Bash')).toBeTruthy()
+    expect(view.getByText('运行命令')).toBeTruthy()
     expect(view.getByText('List files')).toBeTruthy()
     expect(view.container.querySelector('[data-variant="bash"]')).not.toBeNull()
   })
@@ -556,7 +556,7 @@ describe('GenericToolCard', () => {
   it('passes the owner inspect callback through to the expanded row pill', () => {
     const inspect = vi.fn()
     const view = render(<GenericToolCard {...props('bash', result())} inspect={inspect} />)
-    fireEvent.click(view.getByRole('button', { name: /Bash/ }))
+    fireEvent.click(view.getByRole('button', { name: /运行命令/ }))
     fireEvent.click(view.getByText('查看'))
     expect(inspect).toHaveBeenCalledTimes(1)
   })
diff --git a/packages/client/ui-trajectory/tests/views.client.spec.tsx b/packages/client/ui-trajectory/tests/views.client.spec.tsx
index ea8641c0e2..ae5097476c 100644
--- a/packages/client/ui-trajectory/tests/views.client.spec.tsx
+++ b/packages/client/ui-trajectory/tests/views.client.spec.tsx
@@ -172,7 +172,7 @@ function standaloneDuration(): Pick<
 /** Empty sessions-list hook; breadcrumbs therefore fall back to the raw id. */
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
-    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {} })
+    { ids: [], byId: {}, phase: 'ready', projectionsBySession: {} })
   return bindSnapshotSelector(store)
 }
 
@@ -214,6 +214,8 @@ function standaloneProps(
     draft: '', attachmentIds: [], draftRev: 0, phase: 'plain', occurrences: [], queue: [],
   })
   const inputActions: InputActions = {
+    captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+    insertText: () => false,
     setDraft: () => {},
     addAttachments: () => false,
     removeAttachment: () => {},
@@ -339,6 +341,8 @@ function mount(fixture: Awaited<ReturnType<typeof bench>>) {
     draft: '', attachmentIds: [], draftRev: 0, phase: 'plain', occurrences: [], queue: [],
   }))
   const inputActions: InputActions = {
+    captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+    insertText: () => false,
     setDraft: vi.fn(),
     addAttachments: vi.fn(() => false),
     removeAttachment: vi.fn(),
diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
index 4daccc5a42..fff2d81a6b 100644
--- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
@@ -53,7 +53,6 @@ const sessionList = {
   byId: { [SID]: { id: SID, displayTitle: 'Session', running: false, retainedBy: {}, blank: false, updatedAt: 0 } },
   phase: 'ready' as const,
   projectionsBySession: {},
-  jobsBySession: {},
 }
 const attentionState: AttentionState = new Map()
 const workspaceState = {
@@ -127,6 +126,8 @@ const kit: Omit<QuestionComposerProps, 'matched'> = {
   useProjection: (() => undefined),
   useInput: selector => selector(inputState),
   inputActions: {
+    captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+    insertText: () => false,
     setDraft: () => { throw new Error('unused') },
     addAttachments: () => { throw new Error('unused') },
     removeAttachment: () => { throw new Error('unused') },
diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
index e119213f65..ac9fe34d22 100644
--- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
@@ -51,7 +51,6 @@ const sessionList = {
   byId: { [SID]: { id: SID, displayTitle: 'Session', running: false, retainedBy: {}, blank: false, updatedAt: 0 } },
   phase: 'ready' as const,
   projectionsBySession: {},
-  jobsBySession: {},
 }
 const attentionState: AttentionState = new Map()
 const workspaceState = {
@@ -125,6 +124,8 @@ const kitBase: Omit<QuestionComposerProps, 'matched' | 'useStore' | 'actions'> =
   useProjection: (() => undefined),
   useInput: selector => selector(inputState),
   inputActions: {
+    captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+    insertText: () => false,
     setDraft: () => { throw new Error('unused') },
     addAttachments: () => { throw new Error('unused') },
     removeAttachment: () => { throw new Error('unused') },
diff --git a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx
index 5f7df5979e..cd62e634bd 100644
--- a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx
+++ b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx
@@ -307,7 +307,6 @@ const listState = (overrides: Partial<SessionListState> = {}): SessionListState
   projectionsBySession: { [PARENT_ID]: { state: 'ready', error: null, values: { subagentCatalog: [
     { createdAt: 1, id: CHILD_ID, mode: 'one-shot' },
   ] } } },
-  jobsBySession: {},
   ...overrides,
 })
 
@@ -326,6 +325,8 @@ function panelProps(data: WorkflowRunChatData, sessions = listState(), openSessi
     useTrajectory: selector => selector(panelTrajectory),
     useInput: () => { throw new Error('unused') },
     inputActions: {
+      captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }),
+      insertText: () => false,
       setDraft: () => {},
       addAttachments: () => false,
       removeAttachment: () => {},
diff --git a/packages/client/ui-workspace/README.i18n.yaml b/packages/client/ui-workspace/README.i18n.yaml
index d6fe6aa37c..3a35e45163 100644
--- a/packages/client/ui-workspace/README.i18n.yaml
+++ b/packages/client/ui-workspace/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-workspace/README.md
-README.md: 4280a8888fc4db9bc2360d5c8ad9c4e7ff62c53a
-README.zh.md: 6b41555c1b4dbaf2c62776040ac9cd29c0562635
+README.md: 3fd9308f0f47a561a08f831f7d923aad2863a25b
+README.zh.md: 97bcac6456bb68606a4747984c24f5f618fa9bb4
diff --git a/packages/client/ui-workspace/README.md b/packages/client/ui-workspace/README.md
index 4280a8888f..3fd9308f0f 100644
--- a/packages/client/ui-workspace/README.md
+++ b/packages/client/ui-workspace/README.md
@@ -25,7 +25,7 @@ This package lets users browse grouped or flat Session lists, choose a Workspace
 <a id="use-this-package"></a>
 ## Use this package
 
-Use the sidebar to browse Workspaces and their Sessions, reorder them, and start new ones; use the picker in the Session Intent hero to choose a Workspace for a new session. An open Workspace shows five non-blank Sessions by default and keeps the selected blank **New Session** as one provisional extra row until its first prompt. **Show more** reveals the hidden remainder; closing and reopening the Workspace restores this folded projection.
+Use the sidebar to browse Workspaces and their Sessions, reorder them, and start new ones; use the picker in the Session Intent hero to choose a Workspace for a new session. An open Workspace shows five idle, non-blank Sessions by default. Running Sessions, including parents with running children, remain visible in their ordered positions without using that quota; the selected blank **New Session** is also an extra row until its first prompt. Each **Show more** click reveals up to five more idle Sessions; after the final batch, **Show less** restores the initial rows while keeping running Sessions visible. Closing and reopening the Workspace also restores this folded projection.
 
 ### Reordering and view options
 
@@ -67,7 +67,13 @@ The value is intentionally best effort for cold Sessions. An identity-matching u
 
 `ctx.uiWorkspace.openSession(target)` synchronously replaces the owned `mainView` reference and returns the main area to Conversation without waiting for `reference.ready`, so history loading renders inside the selected Session view. The target may be a known Session id or a durable direct-parent subagent address; an explicit address does not require a preloaded parent catalog. `openWorkspace(id, beforeOpen?)` opens its result only if no later navigation has superseded the request; New Session uses `openWorkspace`. `forkSession(id)` creates the child without navigating or superseding a pending navigation. The optional synchronous preparation callback runs after the target is retained and only for a current Workspace request, so superseded requests do not move composer drafts. Navigation or owner disposal suppresses the late UI commit, not the underlying Session creation. Startup restoration retains its main reference without changing the selected panel or cancelling a later navigation. Archiving the main Session releases its reference and clears the main selection. Selection failure leaves a global panel visible. Session rows read `usePanelInfo` to suppress their selected appearance while a global panel is active; search and directory-picker focus alone do not leave that panel.
 
-New Session tries to acquire the first eligible blank in catalog order; startup restoration tries the saved blank. If that writer is held, navigation creates a new Session without trying other blanks. Other acquisition failures abort the request and are currently reported only to the console. Released blanks retain their slash-command state when reused. Later navigation cancels a pending startup selection.
+Navigation and startup restoration obtain the selected Session's projections from its `follow`; neither issues a separate projection refresh for that Session or its parent.
+
+New Session tries to acquire the first eligible blank in catalog order; startup restoration tries the saved blank. If that writer is held, navigation creates a new Session without trying other blanks. Other acquisition failures abort the request: an explicit New Session or hero Workspace pick shows the failure as a transient notice quoting the Host's code and message (for example a preset that fails to mount) or, for a failure that is not a Host refusal, that failure's own message; a request a later navigation or owner disposal superseded raises no notice, and startup restoration reports only to the console. Released blanks retain their slash-command state when reused. Later navigation cancels a pending startup selection.
+
+Once both Workspace and Session startup baselines are ready, an empty installation calls `workspaces.initializeDefault` and creates or reuses its blank Session. The composer becomes editable when that Session is selected; no message is submitted automatically. Later navigation or owner disposal prevents startup from selecting its result. Ineligible first use leaves the folder picker available without an error. Default Workspace creation failure shows a transient notice directing the user to Choose workspace, and is not retried until the next startup. Session creation failures use the ordinary restoration error handling. The registered Workspace remains available if Session creation or later submission fails.
+
+The Client chooses the initial directory name and title from its language at startup: Chinese uses `默认工作区`, English uses `Default workspace`, and other languages use directory `default-workspace` with title `Default workspace`. The request retains those names during initialization. A successfully initialized Workspace keeps its directory and title across language changes.
 
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
diff --git a/packages/client/ui-workspace/README.zh.md b/packages/client/ui-workspace/README.zh.md
index 6b41555c1b..97bcac6456 100644
--- a/packages/client/ui-workspace/README.zh.md
+++ b/packages/client/ui-workspace/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-用侧边栏浏览 Workspace 及其 Session、重排它们并新建会话；在 Session Intent 主视觉区用选择器为新会话选择 Workspace。打开的 Workspace 默认显示五条非空白 Session，并在首条提示词落地前把当前选中的空白**新会话**作为一条临时额外行。**展开其余**会显示隐藏条目；关闭再打开 Workspace 会恢复该折叠投影。
+用侧边栏浏览 Workspace 及其 Session、重排它们并新建会话；在 Session Intent 主视觉区用选择器为新会话选择 Workspace。打开的 Workspace 默认显示五条空闲的非空白 Session。正在运行的 Session（包括有子会话正在运行的父会话）始终按原顺序显示，不占用这五条配额；当前选中的空白**新会话**在首条提示词落地前也作为额外行。每次点击**展开其余**最多再显示五条空闲 Session；全部显示后，**收起**恢复初始行数，但仍显示正在运行的 Session。关闭再打开 Workspace 也会恢复该折叠投影。
 
 ### 重排序与视图选项
 
@@ -67,7 +67,13 @@ Session 行渲染运行时的实时 `pendingInteraction` 分类：审批显示**
 
 `ctx.uiWorkspace.openSession(target)` 会同步替换其拥有的 `mainView` reference，并让主区域返回 Conversation，而不等待 `reference.ready`，因此历史加载会显示在已经选中的 Session 视图内。目标可以是已知 Session id，也可以是持久的直接父子 subagent 地址；显式地址不要求预先加载 parent catalog。`openWorkspace(id, beforeOpen?)` 仅在请求未被后续导航替代时打开结果；新会话使用 `openWorkspace`。`forkSession(id)` 创建子会话，不导航，也不替代尚未完成的导航。可选的同步准备回调在目标被 retain 后执行，并且仅对仍有效的 Workspace 请求执行，因此过期请求不会搬移 composer 草稿。后续导航或 owner 释放会阻止晚到的 UI 提交，但不取消底层 Session 创建。启动恢复会 retain 主 reference，不改变已选面板，也不取消后续导航。归档主 Session 会释放其 reference 并清除主选择。选择失败时保留当前全局面板。Session 行读取 `usePanelInfo`，在全局面板活跃时不显示 Session 选中样式；仅把焦点移到搜索框或目录选择器不会离开该面板。
 
-新建会话尝试获取列表中第一个符合条件的空白会话；启动恢复尝试已保存的空白会话。若该写锁被占用，导航直接新建 Session，不再尝试其他空白会话。其他获取错误会中止请求，目前只报告到控制台。已释放的空白会话被复用时保留 slash 命令状态。后续导航会取消尚未完成的启动选择。
+导航和启动恢复通过所选 Session 的 `follow` 获取投影，不会另行刷新该 Session 或其父会话的投影。
+
+新建会话尝试获取列表中第一个符合条件的空白会话；启动恢复尝试已保存的空白会话。若该写锁被占用，导航直接新建 Session，不再尝试其他空白会话。其他获取错误会中止请求：显式新建会话或在 hero 中选择工作区时，失败以短暂提示展示，引用 Host 的错误码和消息（例如 preset 挂载失败），非 Host 拒绝的失败则显示其自身消息；已被后续导航或 owner 销毁取代的请求不弹提示，启动恢复仍只报告到控制台。已释放的空白会话被复用时保留 slash 命令状态。后续导航会取消尚未完成的启动选择。
+
+Workspace 和 Session 的启动基线均就绪后，空安装环境调用 `workspaces.initializeDefault`，创建或复用其空白 Session。选中该 Session 后输入框才可编辑，不会自动提交消息。后续导航或所属上下文销毁会阻止启动流程选中其结果。不符合首次使用条件时仍可选择文件夹，不显示错误。默认工作区创建失败时显示短暂提示，引导用户通过“选择工作区”选择文件夹，直到下次启动才重试。Session 创建失败沿用普通的恢复错误处理。登记成功的工作区在 Session 创建或后续提交失败时仍然保留。
+
+Client 在启动时按其语言选择初始目录名和标题：中文使用 `默认工作区`，英文使用 `Default workspace`，其他语言使用目录 `default-workspace` 和标题 `Default workspace`。初始化过程中保留请求中的名称。成功初始化的工作区在切换语言后保留原目录和标题。
 
 <a id="understand-the-implementation"></a>
 ## 理解实现
diff --git a/packages/client/ui-workspace/src/client/contract/slots.ts b/packages/client/ui-workspace/src/client/contract/slots.ts
index 6a54d79146..c37fa75e73 100644
--- a/packages/client/ui-workspace/src/client/contract/slots.ts
+++ b/packages/client/ui-workspace/src/client/contract/slots.ts
@@ -238,12 +238,19 @@ export type SessionRowActionProps<Injected extends object = object> =
   & PropsLocale<'workspace'>
   & InjectFace<Injected>
 
-/** One transient notice a row action raises; the overlay toast entry renders it. */
+/** One transient Workspace notice rendered by the overlay toast entry. */
 export type RowToast =
   | { kind: 'archived'; sessionId: SessionId }
   | { kind: 'pinFailed' }
   | { kind: 'unpinFailed' }
   | { kind: 'archivedNotOpenable' }
+  | { kind: 'defaultWorkspaceFailed' }
+  /**
+   * An explicit New Session request that failed. `message` is untranslated:
+   * a Host refusal as `code: message` — the stable code stays in the copy so
+   * a report can be searched by it — and any other failure's own message.
+   */
+  | { kind: 'createFailed'; message: string }
 
 /** The notice on display; `seq` keys remounts so a repeated notice restarts its hold. */
 export type RowToastState = RowToast & { seq: number }
@@ -377,5 +384,5 @@ export type WorkspacePickerProps =
   PropsRuntime<'conversation.hero.workspace'>
   & PropsRenderSlots<'conversation.hero.workspace.directoryFlow'>
   & Omit<WorkspacePickerInjected, 'hooks'>
-  & DirectoryPickingHooks
+  & PropsHooks<WorkspacePickerInjected['hooks']>
   & PropsLocale<'workspace'>
diff --git a/packages/client/ui-workspace/src/client/index.ts b/packages/client/ui-workspace/src/client/index.ts
index 0614dea6a4..2339aa77f0 100644
--- a/packages/client/ui-workspace/src/client/index.ts
+++ b/packages/client/ui-workspace/src/client/index.ts
@@ -103,8 +103,12 @@ export function apply(ctx: Context): void {
   const viewHandle = createWorkspaceViewStore()
   const viewInstance = viewHandle.create()
   const viewStore: typeof viewHandle = { ...viewHandle, create: () => viewInstance }
+  const rowToast = createSnapshotStore<RowToastState | null>(null)
+  let toastSeq = 0
+  const notify = (toast: RowToast): void => { rowToast.set({ ...toast, seq: ++toastSeq }) }
   const uiWorkspace = new UiWorkspaceService(
-    ctx, ctx.remote.directoryPicker, workspaces, sessions, viewInstance.actions)
+    ctx, ctx.remote.directoryPicker, workspaces, sessions, viewInstance.actions, notify,
+  )
   ctx.slots.provideRoot({ hooks: { workspaces: workspaces.list } })
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-workspace: dictionaries')
 
@@ -137,9 +141,6 @@ export function apply(ctx: Context): void {
   // writes through its own injected callback and the surface reads through
   // its bound hook.
   const renameRequest = createSnapshotStore<SessionRenameTarget | null>(null)
-  const rowToast = createSnapshotStore<RowToastState | null>(null)
-  let toastSeq = 0
-  const notify = (toast: RowToast): void => { rowToast.set({ ...toast, seq: ++toastSeq }) }
   const requestSessionRename = (sessionId: SessionId, currentTitle: string): void => {
     renameRequest.set({ sessionId, currentTitle })
   }
diff --git a/packages/client/ui-workspace/src/client/locales.ts b/packages/client/ui-workspace/src/client/locales.ts
index e721af231f..203811d38c 100644
--- a/packages/client/ui-workspace/src/client/locales.ts
+++ b/packages/client/ui-workspace/src/client/locales.ts
@@ -6,6 +6,8 @@
 
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
+  'defaultWorkspace.failed': '无法创建默认工作区，请通过“选择工作区”选择文件夹',
+  'defaultWorkspace.title': '默认工作区',
   'group.ungrouped': '未分组',
   'session.new': '新会话',
   'section.workspaces': '工作区',
@@ -60,6 +62,7 @@ export const zh = {
   'toast.archivedFilter': '筛选已归档会话',
   'toast.pinFailed': '置顶失败，请稍后重试',
   'toast.unpinFailed': '取消置顶失败，请稍后重试',
+  'toast.createFailed': '新建会话失败：{message}',
   'sessions.count.one': '{n} 个会话',
   'sessions.count.other': '{n} 个会话',
   'actions.workspace.aria': '工作区“{name}”的操作',
@@ -99,6 +102,8 @@ export type WorkspaceKey = keyof typeof zh
 
 /** English dictionary, checked complete against the zh key set. */
 export const en = {
+  'defaultWorkspace.failed': 'Unable to create default workspace. Use Choose workspace to select a folder.',
+  'defaultWorkspace.title': 'Default workspace',
   'group.ungrouped': 'Ungrouped',
   'session.new': 'New Session',
   'section.workspaces': 'Workspaces',
@@ -153,6 +158,7 @@ export const en = {
   'toast.archivedFilter': 'filter archived sessions',
   'toast.pinFailed': 'Pin failed. Try again later.',
   'toast.unpinFailed': 'Unpin failed. Try again later.',
+  'toast.createFailed': 'New session failed: {message}',
   'sessions.count.one': '{n} session',
   'sessions.count.other': '{n} sessions',
   'actions.workspace.aria': 'Workspace actions for {name}',
diff --git a/packages/client/ui-workspace/src/client/navigation.ts b/packages/client/ui-workspace/src/client/navigation.ts
index d08bf2da00..eefaab86b5 100644
--- a/packages/client/ui-workspace/src/client/navigation.ts
+++ b/packages/client/ui-workspace/src/client/navigation.ts
@@ -16,6 +16,9 @@ import type {
 } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type { RowToast } from './contract/slots.ts'
+import { en, zh } from './locales.ts'
 import { pinOrderAccounts, pinOrderSource } from './pin-order.ts'
 import type { WorkspaceViewStoreActions } from './stores.ts'
 
@@ -36,6 +39,8 @@ export interface UiWorkspace {
    * @param workspaceId - target Workspace.
    * @param beforeOpen - optional synchronous preparation for the selected Session, skipped after supersession.
    * @returns completion; a superseded request may create a Session but does not open it.
+   * @throws on failure; a refused creation is also shown through the Workspace
+   * notice unless a later navigation or disposal superseded the request.
    */
   openWorkspace(workspaceId: WorkspaceId, beforeOpen?: (sessionId: SessionId) => void): Promise<void>
   /**
@@ -51,7 +56,8 @@ export interface UiWorkspace {
    */
   connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId>
   /**
-   * Start a New Session flow and navigate to its Session.
+   * Start a New Session flow and navigate to its Session; a creation the Host
+   * refuses is shown through the Workspace notice and leaves the selection as it was.
    * @param workspaceId - explicit target; absent inherits the current or most recent Workspace.
    */
   startSession(workspaceId?: WorkspaceId): void
@@ -131,6 +137,7 @@ class UiWorkspaceService extends Service implements UiWorkspace {
    * @param workspaces - pure Workspace Controller.
    * @param sessions - pure Session Controller.
    * @param view - the browser's viewing-store write set (one instance shared with its registration).
+   * @param notify - show one notice through the Workspace notice channel.
    */
   constructor(
     ctx: Context,
@@ -138,6 +145,7 @@ class UiWorkspaceService extends Service implements UiWorkspace {
     private readonly workspaces: IWorkspaces,
     private readonly sessions: ISessions,
     private readonly view: Pick<WorkspaceViewStoreActions, 'pinSessionOrder'>,
+    private readonly notify: (toast: RowToast) => void,
   ) {
     super(ctx, 'uiWorkspace')
     ctx.effect(() => {
@@ -183,9 +191,7 @@ class UiWorkspaceService extends Service implements UiWorkspace {
     try {
       return await this.sessions.create({ workspaceId, sessionId })
     } catch (error: unknown) {
-      // Client plugin bundles do not share error-class identity.
-      if (!(error instanceof Error) || error.name !== 'SessionCreateError'
-        || (error as SessionCreateError).rpcError.code !== 'session/writer-held') throw error
+      if (sessionCreateErrorOf(error)?.rpcError.code !== 'session/writer-held') throw error
       return this.sessions.create({ workspaceId })
     }
   }
@@ -196,7 +202,15 @@ class UiWorkspaceService extends Service implements UiWorkspace {
 
   async openWorkspace(workspaceId: WorkspaceId, beforeOpen?: (sessionId: SessionId) => void): Promise<void> {
     const navigation = AbortSignal.any([this.ctx.layout.beginNavigation(), this.lifetime.signal])
-    const sessionId = await this.connectWorkspace(workspaceId)
+    let sessionId: SessionId
+    try {
+      sessionId = await this.connectWorkspace(workspaceId)
+    } catch (error: unknown) {
+      // Reported here, not in connectWorkspace: startup restoration calls that
+      // directly and stays console-only.
+      if (!navigation.aborted) this.notify({ kind: 'createFailed', message: creationFailureMessage(error) })
+      throw error
+    }
     if (navigation.aborted) return
     this.replaceMain(sessionId, navigation, 'reveal', beforeOpen)
   }
@@ -303,7 +317,6 @@ class UiWorkspaceService extends Service implements UiWorkspace {
   private async restoreSelection(workspaces: WorkspaceSnapshot, sessions: SessionListState): Promise<void> {
     const saved = this.selection.getSnapshot()
     if (saved.subagentAddress !== undefined) {
-      void this.sessions.refreshProjections(saved.subagentAddress.parentSessionId)
       this.replaceMain(saved.subagentAddress, this.lifetime.signal, 'preserve')
       return
     }
@@ -320,13 +333,32 @@ class UiWorkspaceService extends Service implements UiWorkspace {
       && !workspaces.archivedSessionIds.includes(summary.id)) {
       sessionId = await this.reuseBlank(workspace.workspaceId, summary.id)
     }
-    const target = workspace?.workspaceId ?? recentWorkspace(workspaces.items, sessions.byId)
+    let target = workspace?.workspaceId ?? recentWorkspace(workspaces.items, sessions.byId)
+    if (target === undefined && workspaces.items.length === 0 && sessions.ids.length === 0) {
+      const prepared = await this.initializeDefaultWorkspace(navigation)
+      if (navigation.aborted) return
+      target = prepared?.workspaceId
+    }
     if (sessionId === undefined && target !== undefined) sessionId = await this.connectWorkspace(target)
     if (sessionId !== undefined && !navigation.aborted) {
       this.replaceMain(sessionId, navigation, 'preserve')
     }
   }
 
+  private async initializeDefaultWorkspace(signal: AbortSignal): Promise<WorkspaceView | undefined> {
+    const language = this.ctx.locale.getSnapshot().active.toLowerCase().split('-')[0]
+    const title = (language === 'zh' ? zh : en)['defaultWorkspace.title']
+    try {
+      return await this.workspaces.initializeDefault({
+        directoryName: language === 'zh' || language === 'en' ? title : 'default-workspace',
+        title,
+      }, signal)
+    } catch (_error: unknown) {
+      if (!signal.aborted) this.notify({ kind: 'defaultWorkspaceFailed' })
+      return undefined
+    }
+  }
+
   /** @returns true when an archived current selection was cleared. */
   private clearArchivedCurrent(): boolean {
     const current = this.mainReference?.sessionId
@@ -373,12 +405,30 @@ class UiWorkspaceService extends Service implements UiWorkspace {
     const previous = this.mainReference
     this.mainReference = reference
     previous?.release()
-    void this.sessions.refreshProjections(reference.sessionId)
     if (panel === 'reveal') this.ctx.layout.selectPanel(null)
   }
 
 }
 
+/**
+ * `error` as the Session Controller's creation failure, or undefined when it
+ * is not one. Client plugin bundles do not share error-class identity, so the
+ * name decides.
+ */
+function sessionCreateErrorOf(error: unknown): SessionCreateError | undefined {
+  return error instanceof Error && error.name === 'SessionCreateError' ? error as SessionCreateError : undefined
+}
+
+/**
+ * The words a failed Session creation is reported in: a Host refusal keeps its
+ * stable code and message; any other failure keeps its own message.
+ */
+function creationFailureMessage(error: unknown): string {
+  const refused = sessionCreateErrorOf(error)
+  if (refused !== undefined) return `${refused.rpcError.code}: ${refused.rpcError.message}`
+  return error instanceof Error ? error.message : String(error)
+}
+
 /** Stable tie-breaking follows Host Workspace order. */
 function recentWorkspace(
   workspaces: readonly WorkspaceView[],
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.module.css b/packages/client/ui-workspace/src/client/rows/Rows.module.css
index 5a643c235a..26a6af0825 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.module.css
+++ b/packages/client/ui-workspace/src/client/rows/Rows.module.css
@@ -182,13 +182,31 @@
   outline: none;
 }
 
-/* Hovering a session row reveals a title wider than its cell: Rows.tsx scrolls
-   it to its end while the pointer rests on the row — smoothly, through the
-   scroll-behavior here — and returns it to the start in one step when the
-   pointer leaves. */
+/* Hovering a session row marquees a title wider than its cell: Rows.tsx crawls
+   it at a constant speed to its far edge while the pointer rests on the row,
+   holds it there, and returns it to the start in one step when the pointer
+   leaves. The motion is scripted frame by frame (reduced motion jumps), so no
+   scroll-behavior applies here. */
 .sessionRow .title {
   flex: 1;
-  scroll-behavior: smooth;
+}
+
+/* While the marquee travels, both clipping edges fade in over 12px instead of
+   hard-cutting a character: the left once the title has moved off its start
+   (data-scrolled), the right while text still remains beyond the cell
+   (data-clipped) — at the far edge the right fade lifts so the final character
+   reads at full strength. The mask rides the title span itself, so the status
+   slot and every other leading cell keep their full color. */
+.sessionRow .title[data-scrolled] {
+  mask-image: linear-gradient(to right, transparent, #000 12px);
+}
+
+.sessionRow .title[data-clipped] {
+  mask-image: linear-gradient(to left, transparent, #000 12px);
+}
+
+.sessionRow .title[data-scrolled][data-clipped] {
+  mask-image: linear-gradient(to right, transparent, #000 12px, #000 calc(100% - 12px), transparent);
 }
 
 .meta {
@@ -287,7 +305,7 @@
 }
 
 /* The unclipped hover state drops the ellipsis, which would otherwise cover
-   the characters the scroll reveal reached. Guarded because a touch tap
+   the characters the marquee reached. Guarded because a touch tap
    latches `:hover` on the row after the title has already returned: an
    unguarded rule would strand that row without its ellipsis. */
 @media (hover: hover) {
@@ -418,9 +436,4 @@
     animation: none;
     transition: none;
   }
-
-  /* The title reveal jumps to the far edge instead of gliding there. */
-  .sessionRow .title {
-    scroll-behavior: auto;
-  }
 }
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx
index ee35919e1f..a3cfa707de 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.tsx
+++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx
@@ -2,7 +2,7 @@
  * Workspace browser tree row components (figma Cell set 14:3080): pure presentational —
  * all data and callbacks arrive via props. Hover swaps (folder->chevron,
  * time->ellipsis, action buttons) are CSS-only, and a session row's clipped
- * title is scrolled programmatically while the row is hovered. Workspace row
+ * title marquees programmatically while the row is hovered. Workspace row
  * menus are visual-only except Rename/Delete. A Session row's "..." menu and
  * its hover buttons are the `sidebar.workspaces.session.menu.item` and
  * `sidebar.workspaces.session.row.action` lists, rendered through the
@@ -11,6 +11,7 @@
  * session and workspace hover cards are suppressed while a menu is open.
  */
 import { useEffect, useMemo, useRef, useState } from 'react'
+import type { RefObject } from 'react'
 import clsx from 'clsx'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import {
@@ -37,31 +38,84 @@ function displayTitle(node: SessionNode, t: RowTranslate): string {
    accidental jitter, so the title stays put. */
 const MIN_TITLE_REVEAL_PX = 8
 
+/* Marquee travel speed: slow enough to read the text as it passes. */
+const TITLE_MARQUEE_PX_PER_MS = 0.03
+
 /**
- * Reveal a title wider than its one-line cell while its row is hovered: the
- * title clips its own text, so the far edge (a fork's incremented title, for
- * example) is reachable by scrolling the element to its end. Overflow of at
- * most {@link MIN_TITLE_REVEAL_PX} stays put — a barely-clipped title moving a
- * few pixels reads as jitter, not a reveal. Leaving returns the title to the
- * start in one step, because the resting ellipsis and the narrowed cell would
- * otherwise meet the text while it travelled back. The stylesheet decides
- * whether either move glides or jumps.
+ * Place the title's scroll position and publish the stylesheet's fade-mask
+ * hooks: `data-scrolled` while the title has left its start (left fade) and
+ * `data-clipped` while text remains beyond the right edge (right fade).
  * @param title - the row's clipping title element.
- * @param revealed - whether the pointer is on the row.
+ * @param left - scroll offset in CSS pixels.
+ * @param range - the title's maximum scroll offset in CSS pixels.
  */
-function revealClippedTitle(title: HTMLSpanElement | null, revealed: boolean): void {
-  /* v8 ignore next -- defensive: the title span renders unconditionally. */
-  if (title === null) return
-  if (revealed) {
-    const range = title.scrollWidth - title.clientWidth
-    if (range <= MIN_TITLE_REVEAL_PX) return
-    title.scrollLeft = range
-    return
-  }
+function placeTitle(title: HTMLSpanElement, left: number, range: number): void {
   // jsdom implements no scrollTo; the lane's direct assignment is instant there
-  // anyway, so both paths land on the same resting position.
+  // anyway, so both paths land on the same position.
+  if (typeof title.scrollTo === 'function') title.scrollTo({ left, behavior: 'instant' })
+  else title.scrollLeft = left
+  if (left > 0) title.dataset.scrolled = ''
+  else delete title.dataset.scrolled
+  if (left < range) title.dataset.clipped = ''
+  else delete title.dataset.clipped
+}
+
+/**
+ * Return the title to its resting state: scrolled to the start with both fade
+ * masks off, so the resting ellipsis renders at full strength.
+ * @param title - the row's clipping title element.
+ */
+function restTitle(title: HTMLSpanElement): void {
   if (typeof title.scrollTo === 'function') title.scrollTo({ left: 0, behavior: 'instant' })
   else title.scrollLeft = 0
+  delete title.dataset.scrolled
+  delete title.dataset.clipped
+}
+
+/**
+ * Marquee a title wider than its one-line cell while its row is hovered: the
+ * title clips its own text, so entering crawls it at a constant speed until the
+ * far edge (a fork's incremented title, for example) is in view, then rests
+ * there under the pointer. Overflow of at most {@link MIN_TITLE_REVEAL_PX}
+ * stays put — a barely-clipped title moving a few pixels reads as jitter, not a
+ * reveal. Leaving returns the title to the start in one step, because the
+ * resting ellipsis and the narrowed cell would otherwise meet the text while it
+ * travelled back. Reduced motion jumps to the far edge instead of crawling.
+ * @param title - ref to the row's clipping title element.
+ * @returns stable pointer enter/leave handlers for the row.
+ */
+function useTitleMarquee(title: RefObject<HTMLSpanElement | null>): { enter: () => void; leave: () => void } {
+  const frame = useRef(0)
+  useEffect(() => () => { cancelAnimationFrame(frame.current) }, [])
+  return useMemo(() => ({
+    enter: (): void => {
+      /* v8 ignore next -- defensive: the title span renders unconditionally. */
+      if (title.current === null) return
+      const element = title.current
+      const range = element.scrollWidth - element.clientWidth
+      if (range <= MIN_TITLE_REVEAL_PX) return
+      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+        placeTitle(element, range, range)
+        return
+      }
+      cancelAnimationFrame(frame.current)
+      let previous: number | undefined
+      let position = 0
+      const step = (now: DOMHighResTimeStamp): void => {
+        position += previous === undefined ? 0 : (now - previous) * TITLE_MARQUEE_PX_PER_MS
+        previous = now
+        placeTitle(element, Math.min(position, range), range)
+        if (position < range) frame.current = requestAnimationFrame(step)
+      }
+      frame.current = requestAnimationFrame(step)
+    },
+    leave: (): void => {
+      cancelAnimationFrame(frame.current)
+      /* v8 ignore next -- defensive: the title span renders unconditionally. */
+      if (title.current === null) return
+      restTitle(title.current)
+    },
+  }), [title])
 }
 
 /** Localized compact relative time ("刚刚"/"5分钟" in zh, "now"/"5min" in en). */
@@ -504,6 +558,7 @@ export function SessionNodeItem({
   const menuOpenState = useMemo((): MenuOpenState => [menuOpen, setMenuOpen], [menuOpen])
   const rowRef = useRef<HTMLDivElement>(null)
   const titleRef = useRef<HTMLSpanElement>(null)
+  const marquee = useTitleMarquee(titleRef)
   useEffect(() => {
     if (onReveal === undefined) return
     rowRef.current?.scrollIntoView({ block: 'nearest' })
@@ -524,8 +579,8 @@ export function SessionNodeItem({
       aria-selected={selected}
       aria-description={row.archived ? t('toast.archivedNotOpenable') : undefined}
       onClick={() => { onOpen(node.id) }}
-      onPointerEnter={() => { revealClippedTitle(titleRef.current, true) }}
-      onPointerLeave={() => { revealClippedTitle(titleRef.current, false) }}
+      onPointerEnter={marquee.enter}
+      onPointerLeave={marquee.leave}
       draggable={draggable}
       onDragStart={!draggable
         ? undefined
diff --git a/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.tsx b/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.tsx
index 7d5fc2e79e..a421d6bb95 100644
--- a/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.tsx
+++ b/packages/client/ui-workspace/src/client/rows/WorkspaceBrowser.tsx
@@ -50,19 +50,19 @@ const EXPAND_SLIDE_MS = 300
 const SEARCH_DEBOUNCE_MS = 250
 /** `session.search` wire bound, measured in JavaScript UTF-16 code units. */
 const SEARCH_QUERY_MAX_CODE_UNITS = 500
-/** Session rows visible per Workspace before the local overflow control. */
+/** Idle Session rows visible per Workspace before the local overflow control. */
 const COLLAPSED_SESSION_LIMIT = 5
 
-/** Fold one Workspace without charging its provisional New Session against the ordinary-row limit. */
-function collapsedSessionRows(sessions: readonly SessionNode[]): {
+/** Keep provisional and running rows outside the idle-session quota, including parents with running children. */
+function collapsedSessionRows(sessions: readonly SessionNode[], limit = COLLAPSED_SESSION_LIMIT): {
   rows: readonly SessionNode[]
   hiddenCount: number
 } {
-  let ordinaryCount = 0
+  let idleCount = 0
   const rows = sessions.filter((session) => {
-    if (session.blank) return true
-    if (ordinaryCount >= COLLAPSED_SESSION_LIMIT) return false
-    ordinaryCount += 1
+    if (session.blank || session.running || session.runningSubagentCount > 0) return true
+    if (idleCount >= limit) return false
+    idleCount += 1
     return true
   })
   return { rows, hiddenCount: sessions.length - rows.length }
@@ -79,11 +79,6 @@ function sanitizeSearchQuery(value: string): string {
   return withoutNul.slice(0, end)
 }
 
-/** Immutable membership toggle for the local expand-all array. */
-function toggled(list: readonly string[], key: string): string[] {
-  return list.includes(key) ? list.filter(k => k !== key) : [...list, key]
-}
-
 /**
  * Accept the native drag at document level while a row drag is active: row
  * hover still owns the insertion marker, and releasing outside the list must
@@ -258,7 +253,7 @@ type SessionTreeProps = Pick<
   onSessionRevealed: (sessionId: SessionId) => void
 }
 
-/** The scrolling session tree; unmounting drops the sessions subscription and expand-all state. */
+/** The scrolling session tree; unmounting drops the sessions subscription and local row limits. */
 function SessionTree({
   list, useSessionStatus, startSession, open, workspaces, ungroupedSessionIds,
   rowState,
@@ -278,7 +273,7 @@ function SessionTree({
   const revealGroup = revealSessionId === undefined || !workspaceReady
     ? undefined
     : owningGroupKey(workspaces, revealSessionId)
-  const [expandedSessionGroups, setExpandedSessionGroups] = useState<string[]>([])
+  const [sessionLimits, setSessionLimits] = useState<Readonly<Record<string, number>>>({})
   // Transient drag marker state; the selected mode owns the resulting order.
   const [drag, setDrag] = useState<DragState | null>(null)
   const sessionDropCommitted = useRef(false)
@@ -333,7 +328,7 @@ function SessionTree({
     const group = groups.find(candidate => candidate.key === revealGroup)
     if (group === undefined || !group.expanded || !group.sessions.some(row => row.id === revealSessionId)) return
     if (collapsedSessionRows(group.sessions).rows.some(row => row.id === revealSessionId)) return
-    setExpandedSessionGroups(keys => keys.includes(revealGroup) ? keys : [...keys, revealGroup])
+    setSessionLimits(limits => limits[revealGroup] === Infinity ? limits : { ...limits, [revealGroup]: Infinity })
   }, [groups, revealGroup, revealSessionId])
   const now = Date.now()
   const commitSessionDrag = (activeDrag: DragState, over: NonNullable<DragState['over']>): void => {
@@ -347,8 +342,7 @@ function SessionTree({
       ? ungroupedSessionIds
       : workspaces.find(workspace => workspace.workspaceId === activeDrag.accountKey)?.sessionIds
     if (accountSessionIds === undefined) return
-    const sessionsExpanded = expandedSessionGroups.includes(group.key)
-    const renderedSessions = sessionsExpanded ? group.sessions : collapsedSessionRows(group.sessions).rows
+    const renderedSessions = collapsedSessionRows(group.sessions, sessionLimits[group.key]).rows
     const nextOrder = sessionDragOrder(accountSessionIds, renderedSessions, activeDrag, over)
     if (nextOrder !== undefined) setSessionOrder(activeDrag.accountKey, nextOrder)
   }
@@ -395,10 +389,11 @@ function SessionTree({
     const children = childrenByParent.get(group.key) ?? []
     const compatibleDrag = workspaceDrag !== null && parents.get(workspaceDrag.workspaceId) === parents.get(group.key)
     const collapsed = collapsedSessionRows(group.sessions)
-    const sessionsExpanded = expandedSessionGroups.includes(group.key)
+    const visible = collapsedSessionRows(group.sessions, sessionLimits[group.key])
+    const sessionsExpanded = visible.hiddenCount === 0
     rowKeys.push(`workspace:${group.key}`)
     const childRows = group.expanded ? children.map(child => renderGroup(child, depth + 1)) : []
-    const sessions = sessionsExpanded ? group.sessions : collapsed.rows
+    const sessions = visible.rows
     for (const node of sessions) rowKeys.push(`session:${node.id}`)
     if (collapsed.hiddenCount > 0) rowKeys.push(`overflow:${group.key}`)
     const workspaceMarker = workspaceId !== undefined && workspaceDrag?.over?.id === workspaceId
@@ -477,7 +472,7 @@ function SessionTree({
           t={t}
           onToggle={() => {
             if (group.expanded) {
-              setExpandedSessionGroups(keys => keys.filter(key => key !== group.key))
+              setSessionLimits(limits => ({ ...limits, [group.key]: COLLAPSED_SESSION_LIMIT }))
             }
             setGroupExpanded(group.key, !group.expanded)
           }}
@@ -560,11 +555,20 @@ function SessionTree({
             className={css.sessionOverflowButton}
             data-row-key={`overflow:${group.key}`}
             aria-expanded={sessionsExpanded}
-            onClick={() => { setExpandedSessionGroups(keys => toggled(keys, group.key)) }}
+            onClick={() => {
+              setSessionLimits(limits => ({
+                ...limits,
+                [group.key]: sessionsExpanded
+                  ? COLLAPSED_SESSION_LIMIT
+                  : visible.hiddenCount <= COLLAPSED_SESSION_LIMIT
+                    ? Infinity
+                    : (limits[group.key] ?? COLLAPSED_SESSION_LIMIT) + COLLAPSED_SESSION_LIMIT,
+              }))
+            }}
           >
             {sessionsExpanded
               ? t('sessions.collapse')
-              : t('sessions.expand', { n: collapsed.hiddenCount })}
+              : t('sessions.expand', { n: visible.hiddenCount })}
           </button>
         )}
       </div>
@@ -580,7 +584,7 @@ function SessionTree({
         label={t('section.sessions')}
         rowKeys={rowKeys}
         ready={list.phase === 'ready' && workspaceReady && !nativeDragActive}
-        resetKey={JSON.stringify([animationResetKey, expandedSessionGroups])}
+        resetKey={JSON.stringify([animationResetKey, sessionLimits])}
       >
         {groups.length === 0 && (
           <div className={css.empty} data-row-key="empty">{t('empty.none')}</div>
diff --git a/packages/client/ui-workspace/src/client/session-actions/RowActionToast.tsx b/packages/client/ui-workspace/src/client/session-actions/RowActionToast.tsx
index f000fc4b4a..cbc7076dc7 100644
--- a/packages/client/ui-workspace/src/client/session-actions/RowActionToast.tsx
+++ b/packages/client/ui-workspace/src/client/session-actions/RowActionToast.tsx
@@ -1,19 +1,23 @@
 /**
- * The `shell.overlay` entry that shows the row actions' notices: the archived
- * notice with its undo and "show archived" actions, pin failures, and the
- * browser's "archived rows cannot be opened" notice. One notice at a time;
- * a parent rerender does not extend its hold.
+ * The `shell.overlay` entry for Workspace and Session notices.
+ * One notice is visible at a time; a parent rerender does not extend its hold.
  */
 import { IconWarningOutlineRegular, Toast } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { RowToastProps } from '../contract/slots.ts'
-
-/** Hold for the actionable archived notice: two buttons need a longer read-and-react window than a plain notice. */
-const ARCHIVED_TOAST_HOLD_MS = 6000
+import { assertNever } from '@deepseek-ai/dsh-util-values'
+import type { RowToastProps, RowToastState } from '../contract/slots.ts'
 
 /**
- * Render the row actions' current notice: the archived notice with its undo
- * and show-archived actions on a 6 s hold, or a plain warning for a failed
- * pin or an archived row that was clicked.
+ * Hold for the notices that take longer to read than a one-line warning: the
+ * actionable archived notice (two buttons to react to) and a refused Session
+ * creation, which quotes the Host's reason.
+ */
+const LONG_TOAST_HOLD_MS = 6000
+
+/**
+ * Render the current notice: the archived notice with its undo
+ * and show-archived actions on a 6 s hold, a refused Session creation with
+ * the Host's reason on the same hold, or a plain warning for a failed
+ * pin, an archived row that was clicked, or default Workspace creation.
  * @param props - the notice hook, its dismissal, the two archived-notice actions, and the locale seat.
  * @returns the notice on display, or null.
  */
@@ -27,7 +31,7 @@ export function RowActionToast({ useToast, dismissToast, undoArchive, showArchiv
         key={`toast-${String(toast.seq)}`}
         text={t('toast.archived')}
         tone="success"
-        holdMs={ARCHIVED_TOAST_HOLD_MS}
+        holdMs={LONG_TOAST_HOLD_MS}
         actions={[
           { label: t('toast.archivedUndo'), onClick: () => { dismissToast(); undoArchive(sessionId) } },
           { prefix: t('toast.archivedOr'), label: t('toast.archivedFilter'), onClick: () => { dismissToast(); showArchived() } },
@@ -36,15 +40,39 @@ export function RowActionToast({ useToast, dismissToast, undoArchive, showArchiv
       />
     )
   }
-  const text = toast.kind === 'pinFailed'
-    ? t('toast.pinFailed')
-    : toast.kind === 'unpinFailed' ? t('toast.unpinFailed') : t('toast.archivedNotOpenable')
+  if (toast.kind === 'createFailed') {
+    return (
+      <Toast
+        key={`toast-${String(toast.seq)}`}
+        text={t('toast.createFailed', { message: toast.message })}
+        icon={<IconWarningOutlineRegular />}
+        holdMs={LONG_TOAST_HOLD_MS}
+        onDone={dismissToast}
+      />
+    )
+  }
   return (
     <Toast
       key={`toast-${String(toast.seq)}`}
-      text={text}
+      text={plainNoticeText(toast, t)}
       icon={<IconWarningOutlineRegular />}
       onDone={dismissToast}
     />
   )
 }
+
+/** The copy of one plain warning, keyed by the notice kind the union closes over. */
+function plainNoticeText(
+  toast: Exclude<RowToastState, { kind: 'archived' | 'createFailed' }>,
+  t: RowToastProps['t'],
+): string {
+  switch (toast.kind) {
+    case 'pinFailed': return t('toast.pinFailed')
+    case 'unpinFailed': return t('toast.unpinFailed')
+    case 'defaultWorkspaceFailed': return t('defaultWorkspace.failed')
+    case 'archivedNotOpenable': return t('toast.archivedNotOpenable')
+    /* v8 ignore next 2 -- closed-union backstop; only reached if a notice kind is forged */
+    default:
+      return assertNever(toast)
+  }
+}
diff --git a/packages/client/ui-workspace/tests/apply.client.spec.ts b/packages/client/ui-workspace/tests/apply.client.spec.ts
index 704027f216..7899234773 100644
--- a/packages/client/ui-workspace/tests/apply.client.spec.ts
+++ b/packages/client/ui-workspace/tests/apply.client.spec.ts
@@ -1,5 +1,5 @@
 import { Context } from '@deepseek-ai/cordis'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import type {
   SessionListState, SessionReference, SessionSummary,
 } from '@deepseek-ai/dsh-api-session-controller/client'
@@ -34,7 +34,7 @@ const sessionState = (items: readonly SessionSummary[]): SessionListState => ({
   ids: items.map(item => item.id),
   byId: Object.fromEntries(items.map(item => [item.id, item])),
   phase: 'ready',
-  projectionsBySession: {}, jobsBySession: {},
+  projectionsBySession: {},
 })
 const workspace = (id: string, sessionIds: readonly string[]): WorkspaceView => ({
   workspaceId: id as WorkspaceId, path: `/projects/${id}`, title: id,
@@ -91,9 +91,11 @@ async function bench() {
   let sessionSnapshot = sessionState([])
   const subscribe = () => () => {}
   const workspacesSubscribe = vi.fn(subscribe)
+  const initializeDefault = vi.fn(async (): Promise<WorkspaceView | undefined> => undefined)
   ctx.provide('workspaces', {
     list: { getSnapshot: () => workspaceSnapshot, subscribe: workspacesSubscribe },
     create,
+    initializeDefault,
     rename,
     delete: vi.fn(async () => undefined),
     insertBefore: vi.fn(async () => undefined),
@@ -128,7 +130,7 @@ async function bench() {
   return {
     ctx, slots: ctx.get('slots') as SlotRegistry, locale, create, rename,
     retain, using, selectPanel, search, renameSession, binding, fork, pickDirectory, pinSession, unpinSession,
-    workspacesSubscribe,
+    workspacesSubscribe, initializeDefault,
     setWorkspaces: (snapshot: WorkspaceSnapshot): void => { workspaceSnapshot = snapshot },
     setSessions: (snapshot: SessionListState): void => { sessionSnapshot = snapshot },
   }
@@ -182,6 +184,20 @@ describe('ui-workspace apply', () => {
     ])
   })
 
+  it('reports a default Workspace creation failure through the shared notice overlay', async () => {
+    const b = await bench()
+    onTestFinished(() => b.ctx.fiber.dispose())
+    b.initializeDefault.mockRejectedValueOnce(new Error('denied'))
+    declare(b.slots, 'shell.overlay')
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const face = faceOf(entry(b.slots, 'shell.overlay', 'workspace.row-toast')) as RowToastInjected
+    await vi.waitFor(() => {
+      expect(face.hooks.toast.getSnapshot()).toMatchObject({ kind: 'defaultWorkspaceFailed' })
+    })
+    face.dismissToast()
+    expect(face.hooks.toast.getSnapshot()).toBeNull()
+  })
+
   it('registers browser and pickers for declarations arriving before or after apply', async () => {
     const before = await bench()
     declare(before.slots, 'sidebar.workspaces')
diff --git a/packages/client/ui-workspace/tests/browser-styles.client.spec.ts b/packages/client/ui-workspace/tests/browser-styles.client.spec.ts
index 38d4ee36a3..bf4191366b 100644
--- a/packages/client/ui-workspace/tests/browser-styles.client.spec.ts
+++ b/packages/client/ui-workspace/tests/browser-styles.client.spec.ts
@@ -108,13 +108,20 @@ describe('WorkspaceBrowser.module.css list', () => {
       .toBe('var(--dsw-alias-interactive-bg-hover)')
   })
 
-  it('reveals a clipped session title by scrolling it on row hover', () => {
-    // Smooth versus reduced motion is pinned as a computed style in
-    // apps/web/tests/sidebar-title-hover-scroll.e2e.ts: this helper merges
-    // same-selector rules across media queries, so the reduce override would
-    // mask the smooth declaration here.
+  it('marquees a clipped session title on row hover', () => {
+    // The crawl itself is scripted in Rows.tsx frame by frame, so the title
+    // declares no scroll-behavior; the stylesheet keeps the hovered cell
+    // unclipped and fades whichever edges cut text mid-travel, on the title
+    // span itself so the status slot beside it keeps its full color.
     expect(rowDeclarations('.sessionRow .title')?.get('flex')).toBe('1')
+    expect(rowDeclarations('.sessionRow .title')?.get('scroll-behavior')).toBeUndefined()
     expect(rowDeclarations('.sessionRow:hover .title')?.get('text-overflow')).toBe('clip')
+    expect(rowDeclarations('.sessionRow .title[data-scrolled]')?.get('mask-image'))
+      .toBe('linear-gradient(to right, transparent, #000 12px)')
+    expect(rowDeclarations('.sessionRow .title[data-clipped]')?.get('mask-image'))
+      .toBe('linear-gradient(to left, transparent, #000 12px)')
+    expect(rowDeclarations('.sessionRow .title[data-scrolled][data-clipped]')?.get('mask-image'))
+      .toBe('linear-gradient(to right, transparent, #000 12px, #000 calc(100% - 12px), transparent)')
   })
 
   it('pins both rail controls to the shared left anchor during the column slide', () => {
diff --git a/packages/client/ui-workspace/tests/rows.client.spec.tsx b/packages/client/ui-workspace/tests/rows.client.spec.tsx
index f41199824f..41e1b6e037 100644
--- a/packages/client/ui-workspace/tests/rows.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/rows.client.spec.tsx
@@ -208,66 +208,136 @@ describe('workspace browser rows', () => {
     expect(onOpen).toHaveBeenCalledWith(node.id)
   })
 
-  it('reveals a clipped session title by scrolling it while the row is hovered', () => {
-    const node: SessionNode = {
-      id: sid('clipped'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false,
-      running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0,
-      pinned: false, archived: false,
+  it('marquees a clipped session title at a constant speed while the row is hovered', () => {
+    vi.useFakeTimers()
+    // jsdom implements no matchMedia; the stub answers the reduced-motion probe.
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false })))
+    try {
+      const node: SessionNode = {
+        id: sid('clipped'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false,
+        running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0,
+        pinned: false, archived: false,
+      }
+      render(
+        <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()} t={t} />,
+      )
+      const row = screen.getByRole('treeitem')
+      const title = screen.getByText(node.title)
+      // jsdom lays out nothing: the title's clipped geometry is stated outright.
+      const geometry = (scrollWidth: number, clientWidth: number): void => {
+        Object.defineProperty(title, 'scrollWidth', { value: scrollWidth, configurable: true })
+        Object.defineProperty(title, 'clientWidth', { value: clientWidth, configurable: true })
+      }
+
+      geometry(320, 180)
+      fireEvent.pointerEnter(row)
+      // The first frame only records the clock; travel begins on the second.
+      vi.advanceTimersByTime(16)
+      expect(title.scrollLeft).toBe(0)
+      expect(title.hasAttribute('data-scrolled')).toBe(false)
+      expect(title.hasAttribute('data-clipped')).toBe(true)
+      // Constant 30px/s: 1600ms of frames crawl 48px, and the moved title
+      // publishes both fade-mask hooks — off its start, short of its far edge.
+      vi.advanceTimersByTime(1600)
+      expect(title.scrollLeft).toBeCloseTo(48, 5)
+      expect(title.hasAttribute('data-scrolled')).toBe(true)
+      expect(title.hasAttribute('data-clipped')).toBe(true)
+      // The crawl clamps at the far edge and rests there under the pointer;
+      // the right fade lifts so the final character reads at full strength.
+      vi.advanceTimersByTime(10_000)
+      expect(title.scrollLeft).toBe(140)
+      expect(title.hasAttribute('data-clipped')).toBe(false)
+      fireEvent.pointerLeave(row)
+      expect(title.scrollLeft).toBe(0)
+      expect(title.hasAttribute('data-scrolled')).toBe(false)
+      expect(title.hasAttribute('data-clipped')).toBe(false)
+
+      // A title that fits has no scroll range: hovering leaves it at its start.
+      geometry(180, 180)
+      fireEvent.pointerEnter(row)
+      vi.advanceTimersByTime(1000)
+      expect(title.scrollLeft).toBe(0)
+      fireEvent.pointerLeave(row)
+
+      // Overflow at the 8px jitter threshold also stays put.
+      geometry(188, 180)
+      fireEvent.pointerEnter(row)
+      vi.advanceTimersByTime(1000)
+      expect(title.scrollLeft).toBe(0)
+      fireEvent.pointerLeave(row)
+
+      // One pixel past the threshold crawls to its 9px extent.
+      geometry(189, 180)
+      fireEvent.pointerEnter(row)
+      vi.advanceTimersByTime(1000)
+      expect(title.scrollLeft).toBe(9)
+    } finally {
+      vi.useRealTimers()
+      vi.unstubAllGlobals()
     }
-    render(
-      <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()} t={t} />,
-    )
-    const row = screen.getByRole('treeitem')
-    const title = screen.getByText(node.title)
-    // jsdom lays out nothing: the title's clipped geometry is stated outright.
-    const geometry = (scrollWidth: number, clientWidth: number): void => {
-      Object.defineProperty(title, 'scrollWidth', { value: scrollWidth, configurable: true })
-      Object.defineProperty(title, 'clientWidth', { value: clientWidth, configurable: true })
-    }
-
-    geometry(320, 180)
-    fireEvent.pointerEnter(row)
-    expect(title.scrollLeft).toBe(140)
-    fireEvent.pointerLeave(row)
-    expect(title.scrollLeft).toBe(0)
-
-    // A title that fits has no scroll range: hovering leaves it at its start.
-    geometry(180, 180)
-    fireEvent.pointerEnter(row)
-    expect(title.scrollLeft).toBe(0)
-    fireEvent.pointerLeave(row)
-
-    // Overflow at the 8px jitter threshold also stays put.
-    geometry(188, 180)
-    fireEvent.pointerEnter(row)
-    expect(title.scrollLeft).toBe(0)
-    fireEvent.pointerLeave(row)
-
-    // One pixel past the threshold reveals.
-    geometry(189, 180)
-    fireEvent.pointerEnter(row)
-    expect(title.scrollLeft).toBe(9)
   })
 
-  it('returns a revealed title to its start in one step', () => {
-    const node: SessionNode = {
-      id: sid('instant-return'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false,
-      running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0,
-      pinned: false, archived: false,
-    }
-    render(
-      <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()} t={t} />,
-    )
-    const row = screen.getByRole('treeitem')
-    const title = screen.getByText(node.title)
-    const scrollTo = vi.fn()
-    Object.defineProperty(title, 'scrollTo', { value: scrollTo, configurable: true })
+  it('jumps a clipped title to its far edge under reduced motion', () => {
+    vi.stubGlobal('matchMedia', vi.fn((query: string) => ({ matches: query === '(prefers-reduced-motion: reduce)' })))
+    try {
+      const node: SessionNode = {
+        id: sid('reduced-motion'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false,
+        running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0,
+        pinned: false, archived: false,
+      }
+      render(
+        <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()} t={t} />,
+      )
+      const row = screen.getByRole('treeitem')
+      const title = screen.getByText(node.title)
+      Object.defineProperty(title, 'scrollWidth', { value: 320, configurable: true })
+      Object.defineProperty(title, 'clientWidth', { value: 180, configurable: true })
 
-    fireEvent.pointerEnter(row)
-    fireEvent.pointerLeave(row)
-    // Browsers receive the explicit instant behavior that the stylesheet's
-    // smooth scroll-behavior would otherwise override.
-    expect(scrollTo).toHaveBeenCalledWith({ left: 0, behavior: 'instant' })
+      fireEvent.pointerEnter(row)
+      expect(title.scrollLeft).toBe(140)
+      expect(title.hasAttribute('data-scrolled')).toBe(true)
+      expect(title.hasAttribute('data-clipped')).toBe(false)
+      fireEvent.pointerLeave(row)
+      expect(title.scrollLeft).toBe(0)
+      expect(title.hasAttribute('data-scrolled')).toBe(false)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('returns a marqueed title to its start in one step and cancels the crawl', () => {
+    vi.useFakeTimers()
+    vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false })))
+    try {
+      const node: SessionNode = {
+        id: sid('instant-return'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false,
+        running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0,
+        pinned: false, archived: false,
+      }
+      render(
+        <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()} t={t} />,
+      )
+      const row = screen.getByRole('treeitem')
+      const title = screen.getByText(node.title)
+      Object.defineProperty(title, 'scrollWidth', { value: 320, configurable: true })
+      Object.defineProperty(title, 'clientWidth', { value: 180, configurable: true })
+      const scrollTo = vi.fn()
+      Object.defineProperty(title, 'scrollTo', { value: scrollTo, configurable: true })
+
+      fireEvent.pointerEnter(row)
+      vi.advanceTimersByTime(160)
+      fireEvent.pointerLeave(row)
+      // Browsers receive the explicit instant behavior so mid-crawl positions
+      // never ease; the return is one step.
+      expect(scrollTo).toHaveBeenLastCalledWith({ left: 0, behavior: 'instant' })
+      // Leaving cancels the crawl rather than letting it finish under the mask.
+      const settled = scrollTo.mock.calls.length
+      vi.advanceTimersByTime(1000)
+      expect(scrollTo.mock.calls.length).toBe(settled)
+    } finally {
+      vi.useRealTimers()
+      vi.unstubAllGlobals()
+    }
   })
 
   it('keeps the active-Schedule marker between the title and time in grouped and flat rows', () => {
diff --git a/packages/client/ui-workspace/tests/session-actions.client.spec.tsx b/packages/client/ui-workspace/tests/session-actions.client.spec.tsx
index ce5cb47dda..55698968ad 100644
--- a/packages/client/ui-workspace/tests/session-actions.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/session-actions.client.spec.tsx
@@ -48,7 +48,7 @@ const one: SessionSummary = {
   id: ROW.sessionId, displayTitle: ROW.displayTitle, running: false, blank: false, updatedAt: 1, retainedBy: {},
 }
 const sessions: SessionListState = {
-  ids: [one.id], byId: { [one.id]: one }, phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+  ids: [one.id], byId: { [one.id]: one }, phase: 'ready', projectionsBySession: {},
 }
 // The Workspace snapshot lists no pins or archives: an action's membership
 // arrives through its injected Set hooks, never through this seat.
@@ -387,6 +387,7 @@ describe('RowActionToast', () => {
     ['pinFailed', '置顶失败，请稍后重试'],
     ['unpinFailed', '取消置顶失败，请稍后重试'],
     ['archivedNotOpenable', '已归档对话暂时无法查看，请取消归档后查看'],
+    ['defaultWorkspaceFailed', '无法创建默认工作区，请通过“选择工作区”选择文件夹'],
   ] as const)('shows the %s warning and takes it down when its hold ends', (kind, text) => {
     vi.useFakeTimers()
     try {
@@ -403,6 +404,24 @@ describe('RowActionToast', () => {
     }
   })
 
+  it('shows a refused creation with the Host reason and holds it as long as the archived notice', () => {
+    vi.useFakeTimers()
+    try {
+      const { dismissToast, notify } = toastSurface()
+      notify({ kind: 'createFailed', message: 'agent-preset/invalid: agent-presets: preset "broken" failed to mount' })
+      const alert = screen.getByRole('alert')
+      expect(alert.textContent).toBe('新建会话失败：agent-preset/invalid: agent-presets: preset "broken" failed to mount')
+      expect(alert.querySelector('button')).toBeNull()
+      act(() => { vi.advanceTimersByTime(4000) })
+      expect(dismissToast).not.toHaveBeenCalled()
+      act(() => { vi.advanceTimersByTime(3000) })
+      expect(dismissToast).toHaveBeenCalledOnce()
+      expect(screen.queryByRole('alert')).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('the archived notice holds longer than a plain notice, and a repeat restarts its hold', () => {
     vi.useFakeTimers()
     try {
diff --git a/packages/client/ui-workspace/tests/tree.client.spec.ts b/packages/client/ui-workspace/tests/tree.client.spec.ts
index 5072250b20..c8e117488a 100644
--- a/packages/client/ui-workspace/tests/tree.client.spec.ts
+++ b/packages/client/ui-workspace/tests/tree.client.spec.ts
@@ -23,7 +23,7 @@ const summary = (id: string, updatedAt: number, cwd?: string): SessionSummary =>
 const list = (...items: SessionSummary[]): SessionListState => ({
   ids: items.map(item => item.id),
   byId: Object.fromEntries(items.map(item => [item.id, item])),
-  phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+  phase: 'ready', projectionsBySession: {},
 })
 const catalog = (...ids: string[]): SessionProjectionSnapshot => ({
   values: { subagentCatalog: ids.map(id => ({
diff --git a/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx b/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx
index 21b6510a07..c4c55b612d 100644
--- a/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx
@@ -49,7 +49,7 @@ const sessionState = (
     ids: items.map(item => item.id),
     byId: Object.fromEntries(items.map(item => [item.id, item])),
     phase: 'ready',
-    projectionsBySession: {}, jobsBySession: {},
+    projectionsBySession: {},
     ...stateOverrides,
   }
   if (main === undefined) return state
@@ -700,6 +700,155 @@ describe('WorkspaceBrowser', () => {
     expect(screen.getByRole('button', { name: '展开其余 2 个会话' })).toBeTruthy()
   })
 
+  it('keeps running sessions outside every batch quota and preserves their order after collapse', () => {
+    const idle = Array.from({ length: 12 }, (_, index) => summary(`idle-${index + 1}`, 12 - index))
+    const first = summary('running-first', 14, { running: true })
+    const last = summary('running-last', 0, { running: true })
+    const blank = summary('blank', 15, { blank: true })
+    const items = [blank, first, ...idle, last]
+    mount({
+      useSessions: hook(sessionState(items, { main: blank.id })),
+      useWorkspaces: hook(workspaceState([workspace('alpha', items.map(item => item.id))])),
+    })
+    const expectRows = (count: number) => {
+      expect(screen.getAllByRole('treeitem').map(row =>
+        within(row).getByText(/^(alpha|新会话|running-(first|last)|idle-\d+)$/u).textContent)).toEqual([
+        'alpha', '新会话', 'running-first', ...idle.slice(0, count).map(item => item.displayTitle), 'running-last',
+      ])
+    }
+    expectRows(5)
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 7 个会话' }))
+    expectRows(10)
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 2 个会话' }))
+    expectRows(12)
+    fireEvent.click(screen.getByRole('button', { name: '收起' }))
+    expectRows(5)
+    fireEvent.click(screen.getByText('alpha'))
+    fireEvent.click(screen.getByText('alpha'))
+    expectRows(5)
+  })
+
+  it('reveals a hidden session when live running status starts and folds it when the run ends', () => {
+    const items = Array.from({ length: 12 }, (_, index) => summary(`session-${index + 1}`, 12 - index))
+    const b = mount({
+      useSessions: hook(sessionState(items)),
+      useWorkspaces: hook(workspaceState([workspace('alpha', items.map(item => item.id))])),
+    })
+    fireEvent.click(screen.getByText('alpha'))
+    expect(screen.queryByText('session-12')).toBeNull()
+    rerender(b, {
+      useSessionStatus: hook<SessionStatusSnapshot>(new Map([[sid('session-12'), {
+        running: true, pendingInteraction: undefined, completionUnread: false,
+      }]])),
+    })
+    expect(screen.getByText('session-12')).toBeTruthy()
+    expect(screen.queryByText('session-6')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 6 个会话' })).toBeTruthy()
+    rerender(b, {
+      useSessionStatus: hook<SessionStatusSnapshot>(new Map([[sid('session-12'), {
+        running: false, pendingInteraction: undefined, completionUnread: true,
+      }]])),
+    })
+    expect(screen.queryByText('session-12')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 7 个会话' })).toBeTruthy()
+  })
+
+  it('keeps a parent with a running child visible outside the idle-session quota', () => {
+    const items = Array.from({ length: 7 }, (_, index) => summary(`session-${index + 1}`, 7 - index))
+    const child = summary('child', 0, { origin: 'subagent', running: true })
+    mount({
+      useSessions: hook(sessionState([...items, child], {
+        projectionsBySession: {
+          [sid('session-7')]: {
+            state: 'ready', error: null,
+            values: { subagentCatalog: [{ id: child.id, mode: 'continuable', label: 'child', createdAt: 1 }] },
+          },
+        },
+      })),
+      useWorkspaces: hook(workspaceState([workspace('alpha', items.map(item => item.id))])),
+    })
+    fireEvent.click(screen.getByText('alpha'))
+    expect(screen.getByText('session-7')).toBeTruthy()
+    expect(screen.queryByText('session-6')).toBeNull()
+    expect(screen.queryByText('child')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 1 个会话' })).toBeTruthy()
+  })
+
+  it.each([false, true])('expands 17 ordinary sessions five at a time and resets after the final partial batch (blank: %s)', (withBlank) => {
+    const ordinary = Array.from({ length: 17 }, (_, index) => summary(`session-${index + 1}`, 17 - index))
+    const blank = summary('blank', 18, { blank: true })
+    const items = withBlank ? [blank, ...ordinary] : ordinary
+    mount({
+      useSessions: hook(sessionState(items, withBlank ? { main: blank.id } : {})),
+      useWorkspaces: hook(workspaceState([workspace('alpha', items.map(item => item.id))])),
+    })
+    if (!withBlank) fireEvent.click(screen.getByText('alpha'))
+    const expectVisible = (count: number) => {
+      for (const [index, item] of ordinary.entries()) {
+        expect(screen.queryByText(item.displayTitle) !== null).toBe(index < count)
+      }
+      expect(screen.getAllByRole('treeitem')).toHaveLength(count + 1 + Number(withBlank))
+      expect(screen.queryByText('新会话') !== null).toBe(withBlank)
+    }
+    expectVisible(5)
+    const labels: string[] = []
+    for (const [remaining, visible] of [[12, 10], [7, 15], [2, 17]] as const) {
+      const overflow = screen.getByRole('button', { name: `展开其余 ${remaining} 个会话` })
+      labels.push(overflow.textContent ?? '')
+      expect(screen.queryByRole('button', { name: '收起' })).toBeNull()
+      fireEvent.click(overflow)
+      expectVisible(visible)
+    }
+    expect(screen.queryByRole('button', { name: /展开其余/ })).toBeNull()
+    const collapse = screen.getByRole('button', { name: '收起' })
+    labels.push(collapse.textContent ?? '')
+    expect(labels).toMatchInlineSnapshot(`
+      [
+        "展开其余 12 个会话",
+        "展开其余 7 个会话",
+        "展开其余 2 个会话",
+        "收起",
+      ]
+    `)
+    fireEvent.click(collapse)
+    expectVisible(5)
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 12 个会话' }))
+    expectVisible(10)
+    expect(screen.getByRole('button', { name: '展开其余 7 个会话' })).toBeTruthy()
+  })
+
+  it('keeps each Workspace batch limit independent when another Workspace expands or collapses', () => {
+    const alpha = Array.from({ length: 17 }, (_, index) => summary(`alpha-${index + 1}`, 17 - index))
+    const beta = Array.from({ length: 11 }, (_, index) => summary(`beta-${index + 1}`, 11 - index))
+    mount({
+      useSessions: hook(sessionState([...alpha, ...beta])),
+      useWorkspaces: hook(workspaceState([
+        workspace('alpha', alpha.map(item => item.id)),
+        workspace('beta', beta.map(item => item.id)),
+      ])),
+    })
+    fireEvent.click(screen.getByText('alpha'))
+    fireEvent.click(screen.getByText('beta'))
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 12 个会话' }))
+    expect(screen.getByText('alpha-10')).toBeTruthy()
+    expect(screen.queryByText('alpha-11')).toBeNull()
+    expect(screen.queryByText('beta-6')).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 6 个会话' }))
+    expect(screen.getByText('beta-10')).toBeTruthy()
+    expect(screen.queryByText('beta-11')).toBeNull()
+    fireEvent.click(screen.getByText('alpha'))
+    fireEvent.click(screen.getByText('alpha'))
+    expect(screen.queryByText('alpha-6')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 12 个会话' })).toBeTruthy()
+    expect(screen.getByText('beta-10')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 1 个会话' }))
+    expect(screen.getByText('beta-11')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '收起' }))
+    expect(screen.queryByText('beta-6')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 6 个会话' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: '展开其余 12 个会话' })).toBeTruthy()
+  })
+
   it('keeps the blank New Session outside the five-row folding quota', () => {
     const ordinary = Array.from({ length: 6 }, (_, index) => summary(`session-${index + 1}`, 6 - index))
     const blank = summary('blank', 7, { blank: true })
@@ -756,6 +905,36 @@ describe('WorkspaceBrowser', () => {
     expect(screen.queryByText('session-6')).toBeNull()
   })
 
+  it('reorders a newly exposed batch row while preserving the blank and hidden tail', () => {
+    const ordinary = Array.from({ length: 12 }, (_, index) => summary(`session-${index + 1}`, 12 - index))
+    const blank = summary('blank', 13, { blank: true })
+    const b = mount({
+      useSessions: hook(sessionState([blank, ...ordinary], { main: blank.id })),
+      useWorkspaces: hook(workspaceState([workspace('alpha', [blank.id, ...ordinary.map(item => item.id)])])),
+    })
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 7 个会话' }))
+    const source = screen.getByText('session-10').closest('[role="treeitem"]') as HTMLElement
+    const target = screen.getByText('session-6').closest('[role="treeitem"]') as HTMLElement
+    target.getBoundingClientRect = () => ({
+      top: 100, bottom: 134, left: 0, right: 200, width: 200, height: 34,
+      x: 0, y: 100, toJSON: () => ({}),
+    })
+    fireEvent.dragStart(source, { dataTransfer: dragData() })
+    fireDrag(target, 'drop', 105)
+
+    expect(b.store.getSnapshot().sessionOrderByAccount.alpha).toEqual([
+      'blank', 'session-1', 'session-2', 'session-3', 'session-4', 'session-5',
+      'session-10', 'session-6', 'session-7', 'session-8', 'session-9', 'session-11', 'session-12',
+    ])
+    expect(screen.getAllByRole('treeitem').slice(1).map(row => row.querySelector('[class*="title"]')?.textContent)).toEqual([
+      '新会话', 'session-1', 'session-2', 'session-3', 'session-4', 'session-5',
+      'session-10', 'session-6', 'session-7', 'session-8', 'session-9',
+    ])
+    expect(screen.queryByText('session-11')).toBeNull()
+    expect(screen.queryByText('session-12')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 2 个会话' })).toBeTruthy()
+  })
+
   it('discards manual positions on recency selection and switches to Manual on drag', async () => {
     const initial = sessionState([summary('one', 3), summary('two', 2)])
     const b = mount({
@@ -1299,6 +1478,30 @@ describe('WorkspaceBrowser', () => {
     expect(b.store.getSnapshot().groupExpansion).not.toHaveProperty('stale')
   })
 
+  it('reveals every session when a search result is beyond the initial five-row quota', () => {
+    const items = Array.from({ length: 17 }, (_, index) => summary(`session-${index + 1}`, 17 - index))
+    const b = mount({
+      useSessions: hook(sessionState(items)),
+      useWorkspaces: hook(workspaceState([workspace('alpha', items.map(item => item.id))])),
+    })
+    const input = screen.getByPlaceholderText<HTMLInputElement>('搜索会话名称')
+    fireEvent.change(input, { target: { value: 'session-11' } })
+    fireEvent.click(screen.getByRole('treeitem'))
+
+    expect(b.props.open).toHaveBeenCalledWith(sid('session-11'))
+    expect(input.value).toBe('')
+    for (const item of items) expect(screen.getByText(item.displayTitle)).toBeTruthy()
+    expect(screen.queryByRole('button', { name: /展开其余/ })).toBeNull()
+    expect(scrollIntoView.mock.instances.at(-1)).toBe(screen.getByText('session-11').closest('[role="treeitem"]'))
+    fireEvent.click(screen.getByRole('button', { name: '收起' }))
+    expect(screen.queryByText('session-6')).toBeNull()
+    expect(screen.queryByText('session-11')).toBeNull()
+    fireEvent.click(screen.getByRole('button', { name: '展开其余 12 个会话' }))
+    expect(screen.getByText('session-10')).toBeTruthy()
+    expect(screen.queryByText('session-11')).toBeNull()
+    expect(screen.getByRole('button', { name: '展开其余 7 个会话' })).toBeTruthy()
+  })
+
   it('keeps the bounded group projection when the revealed result is already within it', () => {
     const sessions = sessionState([
       summary('target', 6, { displayTitle: 'Needle session' }),
diff --git a/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx b/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx
index 9ff0181207..4bb54db303 100644
--- a/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx
@@ -35,7 +35,7 @@ function hook<T>(snapshot: T) {
   return function select<S>(selector: (state: T) => S): S { return selector(snapshot) }
 }
 const sessions: SessionListState = {
-  ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+  ids: [], byId: {}, phase: 'ready', projectionsBySession: {},
 }
 const noPendingInteraction: SessionStatusSnapshot = new Map()
 const workspaceState = (items: readonly WorkspaceView[]): WorkspaceSnapshot => ({
diff --git a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
index a8e10756e4..b74a51b3ca 100644
--- a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
+++ b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts
@@ -1,4 +1,6 @@
+import { setImmediate } from 'node:timers/promises'
 import { Context } from '@deepseek-ai/cordis'
+import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type {
   ISessions, SessionListState, SessionReference, SessionSummary,
@@ -14,6 +16,7 @@ import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client'
 import { SessionId } from '@deepseek-ai/dsh-session/types'
 import { LayoutController } from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { MainPanelId } from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { RowToast } from '../src/client/contract/slots.ts'
 import { DirectoryBrowseError, UiWorkspaceService } from '../src/client/navigation.ts'
 import { createWorkspaceViewStore, FLAT_SESSION_ORDER_KEY } from '../src/client/stores.ts'
 import { UNGROUPED_KEY } from '../src/client/tree.ts'
@@ -78,7 +81,6 @@ function sessionState(
     byId: Object.fromEntries(summaries.map(item => [item.id, item])),
     phase,
     projectionsBySession: {},
-    jobsBySession: {},
   }
 }
 
@@ -169,6 +171,7 @@ class FakeSessions implements ISessions {
 }
 
 class FakeWorkspaces implements IWorkspaces {
+  readonly initializeDefault = vi.fn<IWorkspaces['initializeDefault']>(async () => undefined)
   readonly list: MutableSource<WorkspaceSnapshot>
   readonly archiveCalls: SessionId[] = []
   readonly unarchiveCalls: SessionId[] = []
@@ -263,6 +266,8 @@ class FakeDirectoryPicker {
 }
 
 interface BenchOptions {
+  readonly language?: string
+  readonly configureWorkspaces?: (workspaces: FakeWorkspaces) => void
   readonly workspaces?: WorkspaceSnapshot
   readonly sessions?: SessionListState
   readonly configureSessions?: (sessions: FakeSessions) => void
@@ -271,6 +276,10 @@ interface BenchOptions {
 function bench(options: BenchOptions = {}) {
   const ctx = new Context()
   contexts.push(ctx)
+  const locale = new LocaleRuntime(ctx)
+  if (options.language === 'fr') locale.addLanguage({ id: 'fr', label: 'Français', fallback: 'en' })
+  locale.setLocale(options.language ?? 'en')
+  ctx.provide('locale', locale)
   const layout = new LayoutController({
     selectPanel: vi.fn(), retainMainPanels: vi.fn(),
     setSidebar: vi.fn(), toggleSidebar: vi.fn(), setViewportWidth: vi.fn(),
@@ -282,25 +291,134 @@ function bench(options: BenchOptions = {}) {
   const directoryPicker = new FakeDirectoryPicker()
   const workspaces = new FakeWorkspaces(options.workspaces ?? workspaceState([], [], 'pending'))
   const sessions = new FakeSessions(options.sessions ?? sessionState([], 'pending'))
+  options.configureWorkspaces?.(workspaces)
   options.configureSessions?.(sessions)
   const view = createWorkspaceViewStore().create()
+  const notify = vi.fn<(toast: RowToast) => void>()
   const uiWorkspace = new UiWorkspaceService(
     ctx,
     directoryPicker.remote,
     workspaces,
     sessions,
     view.actions,
+    notify,
   )
-  return { ctx, directoryPicker, sessions, uiWorkspace, workspaces, layout, selectPanel, view }
+  return { ctx, directoryPicker, sessions, uiWorkspace, workspaces, layout, selectPanel, view, notify }
 }
 
 describe('UiWorkspaceService', () => {
+  it.each([
+    ['zh', '默认工作区', '默认工作区'],
+    ['en', 'Default workspace', 'Default workspace'],
+    ['fr', 'default-workspace', 'Default workspace'],
+  ])('prepares and selects the default Workspace after both startup baselines (%s)', async (language, directoryName, title) => {
+    const b = bench({ language, configureWorkspaces: (workspaces) => {
+      workspaces.initializeDefault.mockImplementation(async () => {
+        const item = workspace('default')
+        workspaces.list.set(workspaceState([item]))
+        return item
+      })
+    } })
+    expect(b.workspaces.initializeDefault).not.toHaveBeenCalled()
+    b.sessions.list.set(sessionState())
+    expect(b.workspaces.initializeDefault).not.toHaveBeenCalled()
+    b.workspaces.list.set(workspaceState())
+    await vi.waitFor(() => {
+      expect(b.sessions.retain).toHaveBeenCalledExactlyOnceWith(sid('created-default'), { source: 'mainView' })
+    })
+    expect(b.workspaces.initializeDefault).toHaveBeenCalledExactlyOnceWith({ directoryName, title }, expect.any(AbortSignal))
+    expect(b.sessions.create).toHaveBeenCalledWith({ workspaceId: wid('default') })
+    expect(b.notify).not.toHaveBeenCalled()
+  })
+
+  it('leaves an ineligible empty installation without a Session or failure notice', async () => {
+    const b = bench({ workspaces: workspaceState(), sessions: sessionState() })
+    await setImmediate()
+    b.workspaces.list.set(workspaceState())
+    b.sessions.list.set(sessionState())
+    await setImmediate()
+    expect(b.workspaces.initializeDefault).toHaveBeenCalledOnce()
+    expect(b.sessions.create).not.toHaveBeenCalled()
+    expect(b.notify).not.toHaveBeenCalled()
+  })
+
+  it('requires explicit selection when the startup Session list contains history', async () => {
+    const b = bench({ workspaces: workspaceState(), sessions: sessionState([summary('history')]) })
+    await setImmediate()
+    expect(b.workspaces.initializeDefault).not.toHaveBeenCalled()
+    expect(b.sessions.create).not.toHaveBeenCalled()
+  })
+
+  it('publishes a startup directory failure once without creating a Session', async () => {
+    const b = bench({ workspaces: workspaceState(), sessions: sessionState(), configureWorkspaces: (workspaces) => {
+      workspaces.initializeDefault.mockRejectedValueOnce(new Error('denied'))
+    } })
+    await vi.waitFor(() => { expect(b.notify).toHaveBeenCalledExactlyOnceWith({ kind: 'defaultWorkspaceFailed' }) })
+    b.workspaces.list.set(workspaceState())
+    await setImmediate()
+    expect(b.workspaces.initializeDefault).toHaveBeenCalledOnce()
+    expect(b.sessions.create).not.toHaveBeenCalled()
+    expect(b.notify).toHaveBeenCalledExactlyOnceWith({ kind: 'defaultWorkspaceFailed' })
+  })
+
+  it.each(['session', 'panel', 'disposal'] as const)('cancels startup directory preparation after %s navigation', async (kind) => {
+    const pending = Promise.withResolvers<WorkspaceView>()
+    const b = bench({ workspaces: workspaceState(), sessions: sessionState(), configureWorkspaces: (workspaces) => {
+      workspaces.initializeDefault.mockReturnValueOnce(pending.promise)
+    } })
+    if (kind === 'session') b.uiWorkspace.openSession(sid('manual'))
+    else if (kind === 'panel') b.layout.selectPanel('other-panel' as MainPanelId)
+    else await b.ctx.fiber.dispose()
+    expect(b.workspaces.initializeDefault.mock.calls[0]![1]?.aborted).toBe(true)
+    pending.resolve(workspace('default'))
+    await setImmediate()
+    expect(b.sessions.create).not.toHaveBeenCalled()
+    expect(b.sessions.retain.mock.calls.map(args => args[0])).toEqual(kind === 'session' ? [sid('manual')] : [])
+    expect(b.notify).not.toHaveBeenCalled()
+  })
+
+  it.each(['session', 'panel', 'disposal'] as const)('suppresses a startup directory failure after %s navigation', async (kind) => {
+    const pending = Promise.withResolvers<WorkspaceView>()
+    const b = bench({ workspaces: workspaceState(), sessions: sessionState(), configureWorkspaces: (workspaces) => {
+      workspaces.initializeDefault.mockReturnValueOnce(pending.promise)
+    } })
+    if (kind === 'session') b.uiWorkspace.openSession(sid('manual'))
+    else if (kind === 'panel') b.layout.selectPanel('other-panel' as MainPanelId)
+    else await b.ctx.fiber.dispose()
+    pending.reject(new Error('late failure'))
+    await setImmediate()
+    expect(b.sessions.create).not.toHaveBeenCalled()
+    expect(b.notify).not.toHaveBeenCalled()
+  })
+
+  it.each([false, true])('reports Session failure without a directory error and retains the Workspace (superseded: %s)', async (superseded) => {
+    const warning = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const created = Promise.withResolvers<SessionId>()
+    const b = bench({ workspaces: workspaceState(), sessions: sessionState(), configureWorkspaces: (workspaces) => {
+      workspaces.initializeDefault.mockImplementationOnce(async () => {
+        const item = workspace('default')
+        workspaces.list.set(workspaceState([item]))
+        return item
+      })
+    }, configureSessions: (sessions) => { sessions.create.mockReturnValueOnce(created.promise) } })
+    await vi.waitFor(() => { expect(b.sessions.create).toHaveBeenCalledOnce() })
+    if (superseded) b.layout.selectPanel('other-panel' as MainPanelId)
+    const failure = new Error('session failed')
+    created.reject(failure)
+    await vi.waitFor(() => {
+      expect(warning).toHaveBeenCalledExactlyOnceWith('initial Session restoration failed:', failure)
+    })
+    expect(b.workspaces.list.getSnapshot().items).toEqual([workspace('default')])
+    expect(b.notify).not.toHaveBeenCalled()
+    expect(b.sessions.retain).not.toHaveBeenCalled()
+  })
+
   it('retains an explicit main target before revealing its Conversation', () => {
     const b = bench()
     b.uiWorkspace.openSession(sid('target'))
     expect(b.selectPanel).toHaveBeenCalledWith(null)
     expect(b.sessions.retain).toHaveBeenCalledWith(sid('target'), { source: 'mainView' })
-    expect(b.sessions.refreshProjections).toHaveBeenCalledWith(sid('target'))
+    expect(b.sessions.refreshProjections).not.toHaveBeenCalled()
   })
 
   it('keeps the current panel when retaining the target fails', () => {
@@ -371,6 +489,18 @@ describe('UiWorkspaceService', () => {
     }
   })
 
+  it.each(['disposal', 'a later navigation'] as const)('keeps a creation refused after %s silent', async (kind) => {
+    const b = bench({ workspaces: workspaceState([workspace('a')]) })
+    const created = Promise.withResolvers<SessionId>()
+    b.sessions.create.mockReturnValueOnce(created.promise)
+    const pending = b.uiWorkspace.openWorkspace(wid('a'))
+    if (kind === 'disposal') await b.ctx.fiber.dispose()
+    else b.uiWorkspace.openSession(sid('elsewhere'))
+    created.reject(new Error('late refusal'))
+    await expect(pending).rejects.toThrow('late refusal')
+    expect(b.notify).not.toHaveBeenCalled()
+  })
+
   it('ignores a rejected startup selection and stale catalog callbacks after disposal', async () => {
     const created = Promise.withResolvers<SessionId>()
     const warning = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
@@ -523,6 +653,40 @@ describe('UiWorkspaceService', () => {
     expect(b.sessions.retain).not.toHaveBeenCalled()
   })
 
+  it('reports a refused explicit Session creation through the Workspace notice', async () => {
+    const b = bench({ workspaces: workspaceState([workspace('a')]), sessions: sessionState() })
+    // Startup restoration creates its own Session first and stays quiet on failure (pinned above).
+    await vi.waitFor(() => { expect(b.sessions.retain).toHaveBeenCalledOnce() })
+    b.sessions.retain.mockClear()
+    expect(b.notify).not.toHaveBeenCalled()
+    const warning = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const refused = new SessionCreateError(new RemoteError(
+      'agent-preset/invalid',
+      'agent-presets: preset "broken" failed to mount: row "workflow-ptc" names a plugin that cannot be resolved',
+      { agentPreset: 'broken', reason: 'row "workflow-ptc" names a plugin that cannot be resolved' },
+    ), undefined)
+    b.sessions.create.mockRejectedValueOnce(refused)
+    b.uiWorkspace.startSession(wid('a'))
+    await vi.waitFor(() => {
+      expect(b.notify).toHaveBeenCalledExactlyOnceWith({
+        kind: 'createFailed',
+        message: 'agent-preset/invalid: agent-presets: preset "broken" failed to mount: row "workflow-ptc" names a plugin that cannot be resolved',
+      })
+    })
+    expect(warning).toHaveBeenCalledExactlyOnceWith('new session failed:', refused)
+    expect(b.sessions.retain).not.toHaveBeenCalled()
+
+    // The hero picker reaches the same creation through openWorkspace; a
+    // failure that is not a Host refusal keeps its own message.
+    b.sessions.create.mockRejectedValueOnce(new Error('create failed'))
+    await expect(b.uiWorkspace.openWorkspace(wid('a'))).rejects.toThrow('create failed')
+    expect(b.notify).toHaveBeenLastCalledWith({ kind: 'createFailed', message: 'create failed' })
+    b.sessions.create.mockRejectedValueOnce('rejected without an Error')
+    await expect(b.uiWorkspace.openWorkspace(wid('a'))).rejects.toBe('rejected without an Error')
+    expect(b.notify).toHaveBeenLastCalledWith({ kind: 'createFailed', message: 'rejected without an Error' })
+    expect(b.notify).toHaveBeenCalledTimes(3)
+  })
+
   it('uses only an explicit Workspace or the recent-Workspace policy for new Sessions', async () => {
     const current = summary('current', { cwd: '/w/current-home', updatedAt: 1 })
     const recent = summary('recent', { cwd: '/w/recent-home', updatedAt: 2 })
@@ -827,10 +991,7 @@ describe('UiWorkspaceService', () => {
     })
 
     expect(b.sessions.retain).toHaveBeenCalledExactlyOnceWith(address, { source: 'mainView' })
-    expect(b.sessions.refreshProjections.mock.calls).toEqual([
-      [address.parentSessionId],
-      [address.childSessionId],
-    ])
+    expect(b.sessions.refreshProjections).not.toHaveBeenCalled()
   })
 
   it('persists a catalog-resolved address after string subagent navigation', () => {
diff --git a/packages/compaction/compaction-image-offload/tests/image-offload.spec.ts b/packages/compaction/compaction-image-offload/tests/image-offload.spec.ts
index 2123638197..001b307a65 100644
--- a/packages/compaction/compaction-image-offload/tests/image-offload.spec.ts
+++ b/packages/compaction/compaction-image-offload/tests/image-offload.spec.ts
@@ -10,9 +10,10 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import BasicCompactionEngine from '@deepseek-ai/dsh-compaction-basic'
 import TokenMeter from '@deepseek-ai/dsh-token-meter'
 import { ImageVariantId } from '@deepseek-ai/dsh-attachment'
-import { serializeRequestWithImages } from '@deepseek-ai/dsh-llm-deepseek/src/protocols/chat-completions/serialize.ts'
+import { resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+import { inlineImages } from '@deepseek-ai/dsh-llm-deepseek/src/images.ts'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import { createAssistantMessage, createToolResultMessage, createUserMessage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmAdapter, LlmError, ToolCallId } from '@deepseek-ai/dsh-llm'
+import { createAssistantMessage, createToolResultMessage, createUserMessage, projectOffloadedImages, offloadedImageText, IMAGE_OFFLOAD_REQUIRED_CODE, LlmAdapter, LlmError, ToolCallId } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { isReplacementSurfaceEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { Session } from '@deepseek-ai/dsh-session'
@@ -32,15 +33,15 @@ class ScriptedAdapter extends LlmAdapter {
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     this.requests.push(options)
     if (this.serializeSummary && options.purpose === 'compaction') {
-      await serializeRequestWithImages(options, {
-        representation: { kind: 'base64' },
-        requestImages: new Map([image('first').attachment].map(ref => [ref.attachmentId, {
+      inlineImages(
+        projectOffloadedImages(options.messages, ref => offloadedImageText(ref)),
+        new Map([image('first').attachment].map(ref => [ref.attachmentId, {
           variantId: ImageVariantId(`sha256:${'b'.repeat(64)}`), attachment: ref,
           data: new Uint8Array(ref.bytes), mediaType: ref.mediaType, bytes: ref.bytes,
           width: ref.width, height: ref.height, depth: 'uchar', space: 'srgb', hasAlpha: false,
         }])),
-        maxRequestImageBytes: 1,
-      })
+        resolveAdapterOptions({ maxInlineRequestImageBytes: 1, inlineImageOffloadByteQuantum: 1 }),
+      )
     }
     const entry = this.script.shift()
     if (entry === undefined) throw new Error('script exhausted')
@@ -132,7 +133,7 @@ describe('summary image offload', () => {
     expect(decisions(agent.session)).toEqual([])
   })
 
-  it('recovers the real summary serializer with a tighter image budget and fresh pricing', async () => {
+  it('recovers real summary image preparation with a tighter budget and fresh pricing', async () => {
     const { compact, agent, adapter } = await summaryHarness([textResponse('answer'), textResponse('checkpoint')])
     const span = await seedImages(agent, ['first', 'second'])
     adapter.serializeSummary = true
diff --git a/packages/context/file-reference-local/README.i18n.yaml b/packages/context/file-reference-local/README.i18n.yaml
index 1395353c93..8bd8e62df0 100644
--- a/packages/context/file-reference-local/README.i18n.yaml
+++ b/packages/context/file-reference-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/context/file-reference-local/README.md
-README.md: efeebdbd3e113597cc93dfe4d6c379e16b324d93
-README.zh.md: f286f92d6e6ec76afc9919db9f81c73e4ace8d04
+README.md: b80f5863e2cae166277d7672085bd1a9742e6cf3
+README.zh.md: 343d0950986df8e071c307314ce2e860168c4308
diff --git a/packages/context/file-reference-local/README.md b/packages/context/file-reference-local/README.md
index efeebdbd3e..b80f5863e2 100644
--- a/packages/context/file-reference-local/README.md
+++ b/packages/context/file-reference-local/README.md
@@ -105,7 +105,7 @@ When the addressed agent has an effective `read` tool, the provider contributes
 ##### File-reference instruction
 
 ```markdown
-Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
+Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 ```
 
 #### Token effect
diff --git a/packages/context/file-reference-local/README.zh.md b/packages/context/file-reference-local/README.zh.md
index f286f92d6e..343d095098 100644
--- a/packages/context/file-reference-local/README.zh.md
+++ b/packages/context/file-reference-local/README.zh.md
@@ -105,7 +105,7 @@ agent（智能体）及宿主 UI 可以用各 agent 本地工作区中经过排
 ##### 文件引用指令
 
 ```markdown
-Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
+Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 ```
 
 #### Token 影响
diff --git a/packages/context/file-reference/README.i18n.yaml b/packages/context/file-reference/README.i18n.yaml
index 404975fb63..6d1e7a991a 100644
--- a/packages/context/file-reference/README.i18n.yaml
+++ b/packages/context/file-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 packages/context/file-reference/README.md
-README.md: ce84a91e96988fb662ee665707d1ce2ad1651327
-README.zh.md: ffdce668dd1b4a5a39a076d6abc998ec6db2ce92
+README.md: 3b759a88bd9ebb59fbf3d039756e66ad6901a893
+README.zh.md: d7dedc46365d70740480167cdfa0432f494d4563
diff --git a/packages/context/file-reference/README.md b/packages/context/file-reference/README.md
index ce84a91e96..3b759a88bd 100644
--- a/packages/context/file-reference/README.md
+++ b/packages/context/file-reference/README.md
@@ -29,7 +29,7 @@ Choose this package when a host-backed UI (web or terminal) should offer `@file`
 
 ### Mention grammar
 
-An `@path` token at the start of input or after whitespace triggers completion; an `@` inside another token, such as an email address, does not. `@"path with spaces"` opens a quoted mention, and a directory candidate keeps that quote open after its trailing slash so completion can descend another level. The formatter rejects paths with control characters or embedded quotes that the grammar cannot represent safely.
+An `@path` token at the start of input or after whitespace triggers completion; an `@` inside another token, such as an email address, does not. `@"path with spaces"` opens a quoted mention, and a directory candidate keeps that quote open after its trailing slash so completion can descend another level. Completed directory chips close the quote after the trailing slash. Relative mentions resolve from the workspace root; absolute mentions retain the host path. The formatter rejects paths with control characters or embedded quotes that the grammar cannot represent safely.
 
 ### Getting candidates
 
diff --git a/packages/context/file-reference/README.zh.md b/packages/context/file-reference/README.zh.md
index ffdce668dd..d7dedc4636 100644
--- a/packages/context/file-reference/README.zh.md
+++ b/packages/context/file-reference/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### mention 语法
 
-输入开头或空白后的 `@path` token 会触发补全；其他 token 内部的 `@`（如电子邮件地址）不会。`@"path with spaces"` 打开带引号的 mention，目录候选在其尾斜杠后保持引号打开，使补全可以继续深入下一层。格式化器会拒绝含有语法无法安全表示的控制字符或内嵌引号的路径。
+输入开头或空白后的 `@path` token 会触发补全；其他 token 内部的 `@`（如电子邮件地址）不会。`@"path with spaces"` 打开带引号的 mention，目录候选在其尾斜杠后保持引号打开，使补全可以继续深入下一层。格式化器会拒绝含有语法无法安全表示的控制字符或内嵌引号的路径。 已完成的目录 chip 在末尾斜杠之后闭合引号。相对引用从工作区根目录解析，绝对引用保留主机路径。
 
 ### 获取候选
 
diff --git a/packages/context/file-reference/src/index.ts b/packages/context/file-reference/src/index.ts
index bf1025714f..d6b30e783e 100644
--- a/packages/context/file-reference/src/index.ts
+++ b/packages/context/file-reference/src/index.ts
@@ -14,7 +14,7 @@ export type { ActiveAtToken } from './grammar.ts'
 export type { FileReferenceCandidate } from './types.ts'
 
 /** Model guidance for path-only references selected by a user interface. */
-export const FILE_REFERENCE_PROMPT = 'Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.'
+export const FILE_REFERENCE_PROMPT = 'Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 8a503e803f..bfbfe913e9 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: 7c3073aefb90fa2ec74d521d6c9d97aff5f74ace
-README.zh.md: 44621a0b02eadfc574f6f6b924f64cfeb4141cd3
+README.md: f74182e468c8c844be71f762c6f0dd266cf799f3
+README.zh.md: e55d481dc61ae52b7d08ff09ffb0595ce085fd76
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 7c3073aefb..f74182e468 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -122,6 +122,8 @@ Prompt admission uses the actual `prepareCall()` result, not the preceding `requ
 
 ### Failure and cancellation
 
+`turn/end` declares `TurnEndCancelCause`; cancellation records a fresh `AgentCancelCause` there, retaining the caller's `kind` and the hook's `reason` text. The live `AbortSignal.reason` remains the caller's object, which a transport may extend — Node's fetch assigns a `stack` onto it — so the copy keeps that trace out of the log and keeps the ending appendable.
+
 Final adapter selection, dispatch, and iteration failures arrive as terminal finishes and enter `agent/request-error`; a handling listener returns `{ kind: 'retry' }` without calling `next()`, while an unhandled failure is terminal. Middleware, result-processing, tool, and other extension failures remain thrown and close the turn directly — plugin failure ends the turn, not the loop. Undispatched model tool calls after cancellation receive synthetic `tool/call` plus `ABORTED_BEFORE_DISPATCH` result pairs. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the signal lifecycle.
 
 </details>
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index 44621a0b02..e55d481dc6 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -122,6 +122,8 @@ const handle = await ctx.agents.create({
 
 ### 失败与取消
 
+`turn/end` 声明的类型是 `TurnEndCancelCause`；取消时，循环在其中记录一份新的 `AgentCancelCause`，保留调用方的 `kind` 和 hook 的 `reason` 文本。实时 `AbortSignal.reason` 仍是调用方的那个对象，传输层可能向其添加属性——Node 的 fetch 会给它赋一个 `stack`——因此这份拷贝既让该调用栈不进入日志，也让结束事件保持可追加。
+
 最终适配器选择、分发与迭代失败以终止结束的形式到达并进入 `agent/request-error`；处理该失败的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`，未被处理的失败则是终态。Middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次——插件失败结束的是轮次，不是循环。取消后未分发的模型工具调用会收到合成的 `tool/call` 加 `ABORTED_BEFORE_DISPATCH` 结果对。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md)拥有信号生命周期。
 
 </details>
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index 4ea7593551..98114f53cd 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -23,7 +23,7 @@ import {
   errorChain,
   markAgentLoopRequest,
 } from '@deepseek-ai/dsh-llm'
-import { deepFreeze } from '@deepseek-ai/dsh-util-values'
+import { assertNever, deepFreeze } from '@deepseek-ai/dsh-util-values'
 import type { Scope } from '@deepseek-ai/dsh-scope'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import type { EpochHeader, RequestContext, Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session'
@@ -68,6 +68,31 @@ function requestProposal(header: EpochHeader): LlmCallConfig {
   return proposal
 }
 
+/**
+ * Read the cause `cancel()` passed when aborting a loop-owned signal, copying
+ * only the fields `turn/end` records. The live reason stays the caller's
+ * object, and Node's fetch assigns a `stack` onto it that `Session.append`
+ * would either log or reject as data JSON cannot hold.
+ * @param signal - a turn or maintenance signal this loop owns.
+ * @returns the copied cause, or undefined while the signal is still live.
+ */
+function abortedCancelCause(signal: AbortSignal): AgentCancelCause | undefined {
+  if (!signal.aborted) return undefined
+  // `cancel()` is the only aborter of the signals this loop owns.
+  const cause = signal.reason as AgentCancelCause
+  switch (cause.kind) {
+    case 'user':
+    case 'parent':
+    case 'disposed':
+      return { kind: cause.kind }
+    case 'hook':
+      return { kind: 'hook', reason: cause.reason }
+    /* v8 ignore next -- cancel accepts the closed AgentCancelCause union */
+    default:
+      return assertNever(cause)
+  }
+}
+
 /** Drives one session through turn and step boundaries. */
 export class ReactLoopAgent implements Agent {
   readonly inbox: ReactLoopInbox
@@ -170,7 +195,7 @@ export class ReactLoopAgent implements Agent {
         return await job(maintenance.abort.signal)
       } finally {
         this.setPhase({ kind: 'idle', lastTurn: maintenance.lastTurn })
-        const cause = maintenance.abort.signal.reason as AgentCancelCause | undefined
+        const cause = abortedCancelCause(maintenance.abort.signal)
         if (cause?.kind !== 'disposed' && maintenance.wakeRequested && this.inbox.hasPending) this.wakeDriver()
         done.resolve()
       }
@@ -190,7 +215,7 @@ export class ReactLoopAgent implements Agent {
       // Maintenance and aborted drivers cannot deliver the wake: latch it for
       // replay at convergence. Live drivers claim queued work themselves;
       // disposal never latches, so teardown waits on no model turn.
-      const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
+      const reason = abortedCancelCause(this.phase.abort.signal)
       if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
         this.phase.wakeRequested = true
       }
@@ -321,8 +346,10 @@ export class ReactLoopAgent implements Agent {
         target = 'next-step'
       }
     } catch (error: unknown) {
-      if (signal.aborted) {
-        turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause }
+      // A cause is present exactly while the signal is aborted.
+      const cause = abortedCancelCause(signal)
+      if (cause !== undefined) {
+        turnEnds = { kind: 'aborted', reason: cause }
         throw error
       }
       // Every failure is structured: an `LlmError` keeps its facts, anything
diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts
index 872e983639..add362835b 100644
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -3,7 +3,8 @@ import { ToolCallId, createUserMessage, expandAssistantStream } from '@deepseek-
  * Tests for the queue-aware `Agent.cancel()` primitive. The default clears
  * queued and steering work, while `keepInbox` preserves pending input for a
  * later wake after the active turn reaches quiescence. The suite
- * covers every landing window plus signal reset and `whenIdle()` quiescence.
+ * covers every landing window plus signal reset, `whenIdle()` quiescence, and
+ * the cause each cancelled turn records.
  * @module dsh-agent-loop/tests/cancel
  */
 
@@ -13,7 +14,7 @@ import LlmRuntime from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId, SessionLogOffset, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime, { defineContentToolFixture, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent, type AgentCancelCause } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
@@ -57,6 +58,92 @@ function userTexts(agent: Agent): string[] {
 }
 
 describe('Agent.cancel()', () => {
+  /**
+   * Cancel one turn, let `mutate` alter the caller's cause the way a transport
+   * does once it observes the abort, then report every recorded turn ending.
+   */
+  async function endingsAfterMutatingCancel(
+    cause: AgentCancelCause,
+    mutate: (cause: AgentCancelCause) => void,
+  ): Promise<{ endings: TurnEndReason[]; errors: unknown[]; requests: number }> {
+    const adapter = new MockAdapter([textResponse('next turn')])
+    const ctx = await harness(adapter)
+    try {
+      const agent = await ctx.agentLoop.create(SessionId('cancel-mutated-cause'), { provider: 'mock', model: 'mock' })
+      const errors: unknown[] = []
+      ctx.on('agent/error', ({ error }) => { errors.push(error) })
+      ctx.on('agent/request', ({ signal, turn }, next) => {
+        if (turn === 1) {
+          signal.addEventListener('abort', () => { mutate(cause) }, { once: true })
+          agent.cancel(cause)
+        }
+        return next()
+      })
+
+      send(agent, 'cancel this turn')
+      await agent.whenIdle()
+      // A second turn proves the cancelled one closed: an unclosed turn would
+      // make the next `turn/start` fail the session's turn-bracket invariant.
+      send(agent, 'continue')
+      await agent.whenIdle()
+
+      return {
+        endings: agent.session.snapshotEvents()
+          .flatMap(event => event.type === 'turn/end' ? [event.data.reason] : []),
+        errors,
+        requests: adapter.requests.length,
+      }
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  }
+
+  /**
+   * Node's fetch assigns an enumerable `stack` string onto the abort reason it
+   * receives (`node:internal/deps/undici`), which a plain assignment reproduces.
+   */
+  function assignTransportStack(cause: AgentCancelCause): void {
+    Object.defineProperty(cause, 'stack', {
+      value: 'Error\n    at node:internal/deps/undici/undici',
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+  }
+
+  /** Add an own property JSON discards, the descriptor `Error.captureStackTrace` produces. */
+  function captureNonEnumerableStack(cause: AgentCancelCause): void {
+    Error.captureStackTrace(cause)
+  }
+
+  it.each<AgentCancelCause>([
+    { kind: 'user' },
+    { kind: 'parent' },
+    { kind: 'hook', reason: 'policy stopped this turn' },
+    { kind: 'disposed' },
+  ])('records $kind cancellation without the stack a transport assigned to the abort reason', async (cause) => {
+    const expectedCause = { ...cause }
+
+    const { endings, errors, requests } = await endingsAfterMutatingCancel(cause, assignTransportStack)
+
+    expect(Object.getOwnPropertyDescriptor(cause, 'stack')?.enumerable).toBe(true)
+    expect(errors).toEqual([])
+    expect(endings).toEqual([{ kind: 'aborted', reason: expectedCause }, { kind: 'completed' }])
+    expect(requests).toBe(1)
+  })
+
+  it('closes a cancelled turn whose abort reason acquired an own property JSON discards', async () => {
+    const cause: AgentCancelCause = { kind: 'user' }
+
+    // `Session.append` rejects a payload JSON cannot hold rather than logging a
+    // lossy ending, so the caller's object must not reach the log by reference.
+    const { endings, errors } = await endingsAfterMutatingCancel(cause, captureNonEnumerableStack)
+
+    expect(Object.getOwnPropertyDescriptor(cause, 'stack')?.enumerable).toBe(false)
+    expect(errors).toEqual([])
+    expect(endings).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }])
+  })
+
   it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
diff --git a/packages/core/system-prompt/src/index.ts b/packages/core/system-prompt/src/index.ts
index 0a5d7555f0..6935ed1d06 100644
--- a/packages/core/system-prompt/src/index.ts
+++ b/packages/core/system-prompt/src/index.ts
@@ -143,7 +143,6 @@ const SECTION_ORDERS = {
   TOOL_LSP: 2200,
   TOOL_SESSION_QUERY: 2300,
   TOOL_GOAL: 2400,
-  TOOL_CORDIS: 2500,
   TOOL_WORKFLOW: 2600,
   TOOL_RALPH: 2700,
   TOOL_SUBAGENT: 2800,
diff --git a/packages/core/system-prompt/tests/system-prompt.spec.ts b/packages/core/system-prompt/tests/system-prompt.spec.ts
index 1d73203062..16a79c807f 100644
--- a/packages/core/system-prompt/tests/system-prompt.spec.ts
+++ b/packages/core/system-prompt/tests/system-prompt.spec.ts
@@ -18,7 +18,7 @@ const SECTION_ORDER_NAMES = [
   'PLAN_POLICY', 'TEAM_POLICY', 'PTC_ONLY', 'FILE_REFERENCE', 'TOOL_BASH',
   'TOOL_PWSH', 'TOOL_READ', 'TOOL_WRITE', 'TOOL_EDIT', 'TOOL_GLOB',
   'TOOL_GREP', 'TOOL_JOBS', 'TOOL_PTY', 'TOOL_WEB_SEARCH', 'TOOL_WEB_FETCH',
-  'TOOL_LSP', 'TOOL_SESSION_QUERY', 'TOOL_GOAL', 'TOOL_CORDIS', 'TOOL_WORKFLOW',
+  'TOOL_LSP', 'TOOL_SESSION_QUERY', 'TOOL_GOAL', 'TOOL_WORKFLOW',
   'TOOL_RALPH', 'TOOL_SUBAGENT', 'TOOL_REPORT', 'TOOLS_SDK',
   'DELIVERABLE_FILE_REFERENCES', 'STRUCTURED_OUTPUT',
   'HARNESS_SOURCE', 'WEB_SURFACE', 'DEPLOYMENT_PERSONA_SUFFIX',
diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts
index ba76ed68e4..0519f3b9cb 100644
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -31,7 +31,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
       'create_goal', 'edit', 'exit_plan_mode', 'get_goal', 'glob', 'grep',
       'interrupt_agent', 'interrupt_agent', 'job_kill', 'job_list', 'job_output',
       'list_agents', 'list_agents', 'list_mcp_resource_templates', 'list_mcp_resources',
-      'list_subagent_models', 'lsp', 'plugin_manager', 'present', 'pwsh', 'pwsh', 'ralph',
+      'list_subagent_models', 'load_workspace_dependencies', 'lsp', 'plugin_manager', 'present', 'pwsh', 'pwsh', 'ralph',
       'read', 'read_image', 'read_mcp_resource', 'run_code', 'schedule_create', 'schedule_delete',
       'schedule_list', 'send_message', 'send_message', 'session_event_read', 'session_event_search',
       'session_event_trace', 'session_search', 'session_trace', 'skill', 'spawn_teammate',
diff --git a/packages/document/office-to-pdf/src/index.ts b/packages/document/office-to-pdf/src/index.ts
index fbcff20e1a..f8d3b993c9 100644
--- a/packages/document/office-to-pdf/src/index.ts
+++ b/packages/document/office-to-pdf/src/index.ts
@@ -187,7 +187,7 @@ export class OfficeToPdf extends TypertRemoteService {
       const files = this.ctx.get('workspaceFiles')
       const fs = this.ctx.get('fs')
       if (files === undefined || fs === undefined) throw new OfficeToPdfError('unavailable', 'Office file rendering requires workspaceFiles and fs.')
-      const authorized = await files.readBytes(scope, path, { offset: 0, length: 1 }, signal)
+      const authorized = await files.readBytes(scope, path, { range: { offset: 0, length: 1 } }, signal)
       const source = await files.stat(scope, path, signal)
       const assertUnchanged = (current: WorkspaceFileStat): void => {
         if (current.absolutePath !== source.absolutePath || current.version !== source.version) {
diff --git a/packages/document/office-to-pdf/src/types.ts b/packages/document/office-to-pdf/src/types.ts
index a1123a5ba1..5138dad52c 100644
--- a/packages/document/office-to-pdf/src/types.ts
+++ b/packages/document/office-to-pdf/src/types.ts
@@ -45,7 +45,9 @@ export type OfficeToPdfErrorCode =
   | 'invalid-output' | 'timeout' | 'unavailable' | 'failed' | 'busy' | 'source-changed'
 
 /** PDF content carries the original Office file's absolute path and version. */
-export interface RenderedDocumentBytes extends WorkspaceFileBytes {
+export interface RenderedDocumentBytes extends Omit<WorkspaceFileBytes, 'data'> {
+  /** Base64 PDF contents carried by the JSON Remote response. */
+  readonly data: string
   readonly missingFonts: string[]
   readonly generation: OfficeToPdfGeneration
 }
diff --git a/packages/document/office-to-pdf/tests/remote.spec.ts b/packages/document/office-to-pdf/tests/remote.spec.ts
index 542dc1a333..4029f3ea74 100644
--- a/packages/document/office-to-pdf/tests/remote.spec.ts
+++ b/packages/document/office-to-pdf/tests/remote.spec.ts
@@ -31,7 +31,7 @@ beforeEach(async () => {
   fileInfo = vi.fn<FileSystem['stat']>().mockResolvedValue(sourceInfo)
   processPath = vi.fn<FileSystem['processPath']>().mockReturnValue(source.absolutePath)
   ctx.provide('fs', { resolve: vi.fn().mockResolvedValue(target), stat: fileInfo, processPath, readBytes: read } as never)
-  authorize = vi.fn<WorkspaceFiles['readBytes']>().mockResolvedValue(wireSource)
+  authorize = vi.fn<WorkspaceFiles['readBytes']>().mockResolvedValue({ ...wireSource, eof: false, data: rawSource.data.subarray(0, 1) })
   metadata = vi.fn<WorkspaceFiles['stat']>().mockResolvedValue(source)
   await ctx.plugin(OfficeToPdf)
   generation = ctx.officeToPdf.generation
@@ -48,7 +48,7 @@ it.each(['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx'])('converts authorized %s b
   const path = `report.${extension.toUpperCase()}`
   const result = await ctx.officeToPdf.render(scope, path, 'foreground', new AbortController().signal)
   expect(read).toHaveBeenCalledExactlyOnceWith(target, expect.any(AbortSignal), 4)
-  expect(authorize).toHaveBeenCalledExactlyOnceWith(scope, path, { offset: 0, length: 1 }, expect.any(AbortSignal))
+  expect(authorize).toHaveBeenCalledExactlyOnceWith(scope, path, { range: { offset: 0, length: 1 } }, expect.any(AbortSignal))
   expect(render).toHaveBeenCalledOnce()
   expect(render.mock.calls[0]?.[0]).toMatchObject({ extension, priority: 'foreground', source: { version: source.version, bytes: 4 } })
   expect(result).toEqual({ ...wireSource, data: Buffer.from(pdf).toString('base64'), bytes: pdf.length, missingFonts: ['Missing Serif'], generation })
diff --git a/packages/experimental/agent-team-profile/README.i18n.yaml b/packages/experimental/agent-team-profile/README.i18n.yaml
index 12faf98360..9f2ca6ce41 100644
--- a/packages/experimental/agent-team-profile/README.i18n.yaml
+++ b/packages/experimental/agent-team-profile/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/experimental/agent-team-profile/README.md
-README.md: 2d94b4d1c0e7de9079ac28945f1e79594b17bb76
-README.zh.md: b1126a266c472d5548b0adbc4139d701ac5b4f6f
+README.md: 053f44b673552e7bb7d63ed944652ea6fb87145a
+README.zh.md: bd6837339298fc13908e077833f75aa9c3a6696e
diff --git a/packages/experimental/agent-team-profile/README.md b/packages/experimental/agent-team-profile/README.md
index 2d94b4d1c0..053f44b673 100644
--- a/packages/experimental/agent-team-profile/README.md
+++ b/packages/experimental/agent-team-profile/README.md
@@ -48,7 +48,7 @@ In an existing profile’s `package.json`, keep `@deepseek-ai/dsh-experimental-a
 
 The layer adds the Agent Teams domain and its scoped creation, roster, messaging, interruption, waiting, and task-board tools. Direct delegation uses `spawn_teammate`, which supports fresh and fork context. The `subagent` and `subagent_fork` tools and overlapping global child controls are disabled. Workflow retains the base profile’s `spawn` provider, while the underlying Subagent services and both providers remain available to teammates and workflow.
 
-In Web and Desktop conversations, the [Team UI](../client-ui-agent-team/README.md) displays the member roster and shared task board and opens teammate sessions. The same bundle switch controls the tools and browser UI.
+In Web and Desktop conversations, the [Team UI](../client-ui-agent-team/README.md) displays the member roster and shared task board and opens teammate sessions. The same bundle switch controls the tools and browser UI. The Plugins page reads the bundle's [icon](icon.svg) from its `package.json.icon` declaration, including while the bundle is disabled.
 
 -----
 
diff --git a/packages/experimental/agent-team-profile/README.zh.md b/packages/experimental/agent-team-profile/README.zh.md
index b1126a266c..bd68373392 100644
--- a/packages/experimental/agent-team-profile/README.zh.md
+++ b/packages/experimental/agent-team-profile/README.zh.md
@@ -48,7 +48,7 @@ dsh plugin --profile web add @deepseek-ai/dsh-experimental-agent-team-profile
 
 本层会添加 Agent Teams domain，以及 Team-scoped 创建、roster、消息、interrupt、等待与任务板工具。直接委派使用支持 fresh 和 fork 上下文的 `spawn_teammate`。`subagent`、`subagent_fork` 工具和名称重叠的全局 child control 均被禁用。Workflow 保留 base profile 的 `spawn` 提供方，底层 Subagent 服务和两个提供方仍供 teammate 与 workflow 使用。
 
-在 Web 和 Desktop 会话中，[Team UI](../client-ui-agent-team/README.zh.md) 显示成员列表与共享任务看板，并可打开成员会话。同一个组合包开关控制工具与浏览器 UI。
+在 Web 和 Desktop 会话中，[Team UI](../client-ui-agent-team/README.zh.md) 显示成员列表与共享任务看板，并可打开成员会话。同一个组合包开关控制工具与浏览器 UI。插件页通过组合包的 `package.json.icon` 声明读取其[图标](icon.svg)，组合包禁用时也会显示。
 
 -----
 
diff --git a/packages/experimental/agent-team-profile/icon.svg b/packages/experimental/agent-team-profile/icon.svg
new file mode 100644
index 0000000000..488848231e
--- /dev/null
+++ b/packages/experimental/agent-team-profile/icon.svg
@@ -0,0 +1,12 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M13.3027 17.1077H9.03125V12.8372H13.3027V17.1077ZM17.5742 12.8372C17.574 15.1958 15.6623 17.1075 13.3037 17.1077V8.56567H17.5742V12.8372Z" fill="url(#a)" />
+  <path d="M18.5229 12.8372V8.56567H22.7944V12.8372H27.0659V17.1077H22.7944C20.4357 17.1077 18.5232 15.1959 18.5229 12.8372Z" fill="#F2AF63" />
+  <path d="M17.5742 26.6072H13.3037V18.0642C15.6625 18.0644 17.5742 19.9769 17.5742 22.3357V26.6072ZM13.3027 22.3357H9.03125V18.0642H13.3027V22.3357Z" fill="#7CB7FF" />
+  <path d="M22.7944 26.6072H18.5229V22.3357C18.5229 19.9768 20.4355 18.0642 22.7944 18.0642H27.0659V22.3357H22.7944V26.6072Z" fill="#45D9E7" />
+  <defs>
+    <linearGradient id="a" x1="16.1247" y1="6.6613" x2="9.03125" y2="19.2206" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7CB7FF" />
+      <stop offset="1" stop-color="#145AF3" />
+    </linearGradient>
+  </defs>
+</svg>
diff --git a/packages/experimental/agent-team-profile/package.json b/packages/experimental/agent-team-profile/package.json
index 73999ee5d4..fcc06fcf37 100644
--- a/packages/experimental/agent-team-profile/package.json
+++ b/packages/experimental/agent-team-profile/package.json
@@ -2,6 +2,7 @@
   "name": "@deepseek-ai/dsh-experimental-agent-team-profile",
   "description": "Agent Teams collaboration, tools, and Web UI in one experimental bundle",
   "version": "0.1.6-alpha.2",
+  "icon": "./icon.svg",
   "publishConfig": {
     "access": "public"
   },
@@ -24,6 +25,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "icon.svg",
     "locale/*.json",
     "lib/index.js",
     "cordis.patch.yml",
diff --git a/packages/experimental/client-ui-agent-team/README.i18n.yaml b/packages/experimental/client-ui-agent-team/README.i18n.yaml
index 196e093462..914a388b83 100644
--- a/packages/experimental/client-ui-agent-team/README.i18n.yaml
+++ b/packages/experimental/client-ui-agent-team/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/experimental/client-ui-agent-team/README.md
-README.md: 34e89cfe92db9656cf2fc948e154627c0d5f9407
-README.zh.md: e01cbbb534282fb2c6731579fc753954bcde314b
+README.md: 6d45e618d937cfadcec238c6d0d7dcf3e8747501
+README.zh.md: 879b1784bbe3d2ef6f3f66ab66b9dda7c820a0ed
diff --git a/packages/experimental/client-ui-agent-team/README.md b/packages/experimental/client-ui-agent-team/README.md
index 34e89cfe92..6d45e618d9 100644
--- a/packages/experimental/client-ui-agent-team/README.md
+++ b/packages/experimental/client-ui-agent-team/README.md
@@ -29,7 +29,7 @@ Enable this package through [`@deepseek-ai/dsh-experimental-agent-team-profile`]
 
 ### Inspect and navigate the roster
 
-Opening the panel calls `agentTeams/view`. Roster rows show durable names, turn availability, model, and diagnostics. Provisioning and running members use the shared ongoing loader, inactive members use idle, and failed members use error. Selecting a healthy teammate refreshes the existing direct-child catalog and opens the ordinary `{ parentSessionId, childSessionId, mode: 'continuable' }` address. History and later human prompts continue through the stable addressed-subagent conversation path; this package adds no Team-specific address field.
+Opening the panel calls `agentTeams/view`. Roster rows show durable names, turn availability, model, and diagnostics. Provisioning and running members use the shared ongoing loader, inactive members use idle, and failed members use error. Selecting a healthy teammate opens the ordinary `{ parentSessionId, childSessionId, mode: 'continuable' }` address from its Lead and roster identity without refreshing or checking the parent catalog. The Host validates the parent, child, and mode when history opens. History and later human prompts continue through the stable addressed-subagent conversation path; this package adds no Team-specific address field.
 
 ### Manage the task board
 
diff --git a/packages/experimental/client-ui-agent-team/README.zh.md b/packages/experimental/client-ui-agent-team/README.zh.md
index e01cbbb534..879b1784bb 100644
--- a/packages/experimental/client-ui-agent-team/README.zh.md
+++ b/packages/experimental/client-ui-agent-team/README.zh.md
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 检查并导航 roster
 
-打开 panel 会调用 `agentTeams/view`。Roster row 展示持久 name、轮次可用状态、model 与 diagnostics。provisioning 和 running 成员使用共享 ongoing loading，inactive 成员使用 idle 灰点，failed 成员使用 error 红点。选择健康 teammate 时，系统刷新既有直接 child catalog，并打开普通的 `{ parentSessionId, childSessionId, mode: 'continuable' }` address。History 与后续人类提示词继续使用稳定 addressed-subagent 会话路径；本包不会添加 Team 专用 address 字段。
+打开 panel 会调用 `agentTeams/view`。Roster row 展示持久 name、轮次可用状态、model 与 diagnostics。provisioning 和 running 成员使用共享 ongoing loading，inactive 成员使用 idle 灰点，failed 成员使用 error 红点。选择健康 teammate 时，系统直接根据其 Lead 与 roster 身份打开普通的 `{ parentSessionId, childSessionId, mode: 'continuable' }` address，不刷新或检查 parent catalog。Host 在打开历史时校验 parent、child 与 mode。History 与后续人类提示词继续使用稳定 addressed-subagent 会话路径；本包不会添加 Team 专用 address 字段。
 
 ### 管理任务板
 
diff --git a/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx b/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx
index f0a25a790e..a32e2dc24e 100644
--- a/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx
+++ b/packages/experimental/client-ui-agent-team/src/client/TeamAction.tsx
@@ -44,7 +44,7 @@ export interface TeamActionInjected {
     writeScopes?: string[]
     owner?: string
   }) => Promise<TeamTaskActionResult>
-  openTeammate: (sessionId: SessionId, member: TeamRosterMember) => Promise<void>
+  openTeammate: (sessionId: SessionId, member: TeamRosterMember) => void
 }
 
 /** Full props of the Team conversation-header action. */
@@ -312,7 +312,11 @@ export function TeamAction({
                       disabled={member.role === 'lead' || member.status === 'failed' || member.status === 'provisioning'}
                       title={member.role === 'teammate' ? t('open') : undefined}
                       onClick={() => {
-                        void openTeammate(sessionId, member).catch((reason: unknown) => { setError(String(reason)) })
+                        try {
+                          openTeammate(sessionId, member)
+                        } catch (reason) {
+                          setError(String(reason))
+                        }
                       }}
                     >
                       <StateDot state={memberDotState(member.status)} />
diff --git a/packages/experimental/client-ui-agent-team/src/client/mount.ts b/packages/experimental/client-ui-agent-team/src/client/mount.ts
index 7108c67e8d..235aa9b7ac 100644
--- a/packages/experimental/client-ui-agent-team/src/client/mount.ts
+++ b/packages/experimental/client-ui-agent-team/src/client/mount.ts
@@ -51,14 +51,10 @@ function registerUi(ctx: ClientContext): void {
         ...owner === undefined ? {} : { owner },
       })
     },
-    async openTeammate(sessionId: SessionId, member: TeamRosterMember): Promise<void> {
+    openTeammate(sessionId: SessionId, member: TeamRosterMember): void {
       if (member.role !== 'teammate') return
       const parentSessionId = leadSessionId(sessionId)
-      await sessions.refreshProjections(parentSessionId)
       if ((sessions.retainInfo(sessionId).getSnapshot().retainedBy.mainView ?? 0) === 0) return
-      const catalog = sessions.list.getSnapshot().projectionsBySession[parentSessionId]
-      const child = catalog?.values.subagentCatalog?.find(entry => entry.id === member.id)
-      if (child === undefined) return
       ctx.uiWorkspace.openSession({
         parentSessionId,
         childSessionId: member.id,
diff --git a/packages/experimental/client-ui-agent-team/tests/browser-plugin.client.spec.ts b/packages/experimental/client-ui-agent-team/tests/browser-plugin.client.spec.ts
index 5619b5dbd7..74a7e9a729 100644
--- a/packages/experimental/client-ui-agent-team/tests/browser-plugin.client.spec.ts
+++ b/packages/experimental/client-ui-agent-team/tests/browser-plugin.client.spec.ts
@@ -24,7 +24,6 @@ async function bench(options: {
   conflict?: boolean
   registrationFailure?: boolean
   remoteFailure?: 'view' | 'update'
-  refreshGate?: Promise<void>
   catalog?: 'missing' | 'empty'
 } = {}) {
   const ctx = new Context()
@@ -110,7 +109,7 @@ async function bench(options: {
       : undefined,
     refreshProjections: (id: SessionId) => {
       navigation.push(['refresh', id])
-      return options.refreshGate ?? Promise.resolve()
+      return Promise.resolve()
     },
     retainInfo: (id: SessionId) => ({
       getSnapshot: () => ({
@@ -185,7 +184,7 @@ describe('ui-team browser plugin', () => {
     ])
     expect(b.calls.at(-1)?.args[1]).toMatchObject({ owner: 'worker' })
 
-    await actions.openTeammate(SESSION, {
+    actions.openTeammate(SESSION, {
       id: SESSION,
       name: 'lead',
       role: 'lead',
@@ -238,7 +237,7 @@ describe('ui-team browser plugin', () => {
     })
   })
 
-  it('refreshes the descriptor catalog before opening a continuable teammate address', async () => {
+  it('opens a continuable teammate address without refreshing the parent catalog', async () => {
     const b = await bench()
     const actions = (b.entry()!.inject as unknown as () => TeamActionInjected)()
     const member: TeamRosterMember = {
@@ -248,9 +247,8 @@ describe('ui-team browser plugin', () => {
       status: 'inactive',
       diagnostics: [],
     }
-    await actions.openTeammate(SESSION, member)
+    actions.openTeammate(SESSION, member)
     expect(b.navigation).toEqual([
-      ['refresh', SESSION],
       ['open', {
         parentSessionId: SESSION,
         childSessionId: CHILD,
@@ -263,7 +261,7 @@ describe('ui-team browser plugin', () => {
     const b = await bench({ addressed: true })
     const actions = (b.entry()!.inject as unknown as () => TeamActionInjected)()
     await actions.load(CHILD)
-    await actions.openTeammate(CHILD, {
+    actions.openTeammate(CHILD, {
       id: CHILD,
       name: 'worker',
       role: 'teammate',
@@ -272,7 +270,6 @@ describe('ui-team browser plugin', () => {
     })
     expect(b.calls[0]).toEqual({ method: 'agentTeams/view', args: [SESSION] })
     expect(b.navigation).toEqual([
-      ['refresh', SESSION],
       ['open', {
         parentSessionId: SESSION,
         childSessionId: CHILD,
@@ -281,36 +278,34 @@ describe('ui-team browser plugin', () => {
     ])
   })
 
-  it('does not open a teammate after navigation switches during catalog refresh', async () => {
-    const refresh = Promise.withResolvers<undefined>()
-    const b = await bench({ refreshGate: refresh.promise })
+  it('does not open a teammate from a conversation outside the main view', async () => {
+    const b = await bench()
     const actions = (b.entry()!.inject as unknown as () => TeamActionInjected)()
-    const opening = actions.openTeammate(SESSION, {
+    b.select('other-session' as SessionId)
+    actions.openTeammate(SESSION, {
       id: CHILD,
       name: 'worker',
       role: 'teammate',
       status: 'inactive',
       diagnostics: [],
     })
-    expect(b.navigation).toEqual([['refresh', SESSION]])
-    b.select('other-session' as SessionId)
-    refresh.resolve(undefined)
-    await opening
-    expect(b.navigation).toEqual([['refresh', SESSION]])
+    expect(b.navigation).toEqual([])
   })
 
-  it('does not open a teammate missing from the parent catalog', async () => {
+  it('opens a teammate when the parent catalog is missing or empty', async () => {
     for (const catalog of ['missing', 'empty'] as const) {
       const b = await bench({ catalog })
       const actions = (b.entry()!.inject as unknown as () => TeamActionInjected)()
-      await actions.openTeammate(SESSION, {
+      actions.openTeammate(SESSION, {
         id: CHILD,
         name: 'worker',
         role: 'teammate',
         status: 'inactive',
         diagnostics: [],
       })
-      expect(b.navigation).toEqual([['refresh', SESSION]])
+      expect(b.navigation).toEqual([
+        ['open', { parentSessionId: SESSION, childSessionId: CHILD, mode: 'continuable' }],
+      ])
       await b.fiber.dispose()
     }
   })
diff --git a/packages/experimental/client-ui-agent-team/tests/team-action.client.spec.tsx b/packages/experimental/client-ui-agent-team/tests/team-action.client.spec.tsx
index 52136ffc1e..f29533fd7c 100644
--- a/packages/experimental/client-ui-agent-team/tests/team-action.client.spec.tsx
+++ b/packages/experimental/client-ui-agent-team/tests/team-action.client.spec.tsx
@@ -84,7 +84,7 @@ function actions(overrides: Partial<TeamActionInjected> = {}): TeamActionInjecte
       ok: true,
       value: { ok: true, value: { ...task, revision: 2 } },
     }),
-    openTeammate: () => Promise.resolve(),
+    openTeammate: () => {},
     ...overrides,
   }
 }
@@ -119,7 +119,7 @@ describe('TeamAction', () => {
   })
 
   it('loads roster/task diagnostics on open and navigates a healthy teammate', async () => {
-    const openTeammate = vi.fn(() => Promise.resolve())
+    const openTeammate = vi.fn()
     render(<TeamAction {...props(actions({ openTeammate }))} />)
     fireEvent.click(screen.getByRole('button', { name: /Agent Team/u }))
     const worker = await screen.findByRole('button', { name: /worker/u })
@@ -495,7 +495,7 @@ describe('TeamAction', () => {
       ],
     }
     const load = vi.fn(() => Promise.resolve({ ok: true as const, value: richView }))
-    const openTeammate = vi.fn(() => Promise.reject(new Error('navigation failed')))
+    const openTeammate = vi.fn(() => { throw new Error('navigation failed') })
     render(<TeamAction {...props(actions({ load, openTeammate }))} />)
     fireEvent.click(screen.getByRole('button', { name: /Agent Team/u }))
     expect(await screen.findByText('provider failed')).toBeTruthy()
diff --git a/packages/experimental/tool-agent-team/tests/tool-team.spec.ts b/packages/experimental/tool-agent-team/tests/tool-team.spec.ts
index 2c1f188bc2..198e39f35f 100644
--- a/packages/experimental/tool-agent-team/tests/tool-team.spec.ts
+++ b/packages/experimental/tool-agent-team/tests/tool-team.spec.ts
@@ -17,11 +17,18 @@ import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
 import { renderPrompt, renderContextSnapshot } from '@deepseek-ai/dsh-system-prompt'
 import * as ToolSubagentControl from '@deepseek-ai/dsh-tool-subagent-control'
 import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
-import { serializeRequest } from '@deepseek-ai/dsh-llm-deepseek/src/protocols/chat-completions/serialize.ts'
+import { resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+import { serialize } from '@deepseek-ai/dsh-llm-deepseek/src/serialize.ts'
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import TeamService from '../../agent-team/src/index.ts'
 import * as toolTeam from '../src/index.ts'
 
+function serializeRequest(request: GenerateOptions) {
+  const connection = resolveAdapterOptions({ models: [{ id: request.model, systemPromptUpdate: 'in-history' }] })
+  return serialize(request, connection, request.messages, new Map(), () => undefined)
+}
+
 const SIGNAL = new AbortController().signal
 const TOOL_NAMES = [
   'spawn_teammate',
@@ -263,18 +270,18 @@ describe('dsh-tool-team', () => {
     await waitNoAgent(ctx, childId)
     const childRequest = serializeRequest(adapter.requests[1]!)
     expect(childRequest.tools).toEqual(parentRequest.tools)
-    expect(childRequest.messages[0]).toEqual(parentRequest.messages[0])
-    expect(JSON.stringify(childRequest.messages[0])).not.toContain('Your Team role')
+    expect(childRequest.system).toEqual(parentRequest.system)
+    expect(childRequest.system).not.toContain('Your Team role')
     if (mode === 'fork') {
       expect(childRequest.messages.slice(0, parentRequest.messages.length)).toEqual(parentRequest.messages)
       expect(adapter.requests[1]!.messages.slice(0, parentHistory.length)).toEqual(parentHistory)
     } else {
       expect(JSON.stringify(childRequest.messages)).not.toContain('Parent task')
     }
-    expect(childRequest.messages).toContainEqual({
-      role: 'user',
-      content: '<system-reminder>\nYou are teammate "reviewer".\n</system-reminder>\n\nReview the work',
-    })
+    expect(childRequest.messages.at(-1)?.content.slice(0, 2)).toEqual([
+      { type: 'text', text: '<system-reminder>\nYou are teammate "reviewer".\n</system-reminder>\n\n' },
+      { type: 'text', text: 'Review the work' },
+    ])
     await using persisted = await ctx.sessionPersistence.open(childId, 'read')
     const { events } = await persisted.read()
     const initial = events.findLast(event => event.type === 'user/message' && event.data.source.kind === 'user')
@@ -302,7 +309,7 @@ describe('dsh-tool-team', () => {
     const childRequest = serializeRequest(adapter.requests[1]!)
     expect(childRequest.tools).toEqual(parentRequest.tools)
     expect(childRequest.messages.slice(0, parentRequest.messages.length)).toEqual(parentRequest.messages)
-    expect(childRequest.messages.at(-1)?.content).toBe('Continue independently')
+    expect(childRequest.messages.at(-1)?.content).toContainEqual({ type: 'text', text: 'Continue independently' })
     expect(JSON.stringify(childRequest.messages)).not.toContain('system-reminder')
     expect(handle.agent.session.snapshotEvents().slice(0, seed.length)).toEqual(seed)
     expect(ctx.agentTeams.listMembers(handle.agent).map(member => member.name)).toEqual(['lead'])
@@ -336,7 +343,7 @@ describe('dsh-tool-team', () => {
       expect(fork.tools).toEqual(original.tools)
       expect(fork.messages.slice(0, original.messages.length)).toEqual(original.messages)
       expect(forkRequest.messages.slice(0, inheritedHistory.length)).toEqual(inheritedHistory)
-      expect(fork.messages).toContainEqual({ role: 'user', content: 'Continue independently' })
+      expect(fork.messages.at(-1)?.content).toContainEqual({ type: 'text', text: 'Continue independently' })
       expect(JSON.stringify(fork.messages)).not.toContain('You are the Team Lead')
       expect(handle.agent.session.snapshotEvents().slice(0, seed.length)).toEqual(seed)
     } finally {
@@ -372,7 +379,7 @@ describe('dsh-tool-team', () => {
     await waitNoAgent(ctx, childId)
     const reminder = '<system-reminder>\nYou are teammate "reviewer".\n</system-reminder>\n\n'
     const first = serializeRequest(adapter.requests[0]!).messages
-    expect(first).toContainEqual({ role: 'user', content: `${reminder}Review the work` })
+    expect(first.at(-1)?.content.slice(0, 2)).toEqual([{ type: 'text', text: reminder }, { type: 'text', text: 'Review the work' }])
     expect(adapter.requests[1]!.messages.filter(message => message.content.some(block =>
       block.type === 'text' && block.text === reminder))).toHaveLength(1)
     expect(JSON.stringify(serializeRequest(adapter.requests[2]!).messages)).not.toContain('You are teammate')
@@ -411,8 +418,10 @@ describe('dsh-tool-team', () => {
     })
     expect(spawned.isError, text(spawned)).toBe(false)
     await waitNoAgent(ctx, spawnedChildId(ctx, lead, spawned))
-    expect(serializeRequest(adapter.requests[0]!).messages.at(-1)?.content)
-      .toBe('<system-reminder>\nYou are teammate "reviewer".\n</system-reminder>\n\nReview the work')
+    expect(serializeRequest(adapter.requests[0]!).messages.at(-1)?.content).toEqual([
+      { type: 'text', text: '<system-reminder>\nYou are teammate "reviewer".\n</system-reminder>\n\n' },
+      { type: 'text', text: 'Review the work' },
+    ])
   })
 
   it('returns actionable no-progress output and renders structured wait cancellation', async () => {
diff --git a/packages/experimental/webworker-packer/README.i18n.yaml b/packages/experimental/webworker-packer/README.i18n.yaml
index 0d9d1a565a..ef7b29f03e 100644
--- a/packages/experimental/webworker-packer/README.i18n.yaml
+++ b/packages/experimental/webworker-packer/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/experimental/webworker-packer/README.md
-README.md: c927fd2f4b3bef3078a263f7b65bb0130898ef5b
-README.zh.md: 2a10a8c0f51f7596d27b8c2ad92a1eeea6715ca8
+README.md: dfb3eccf8343f29c1028dae3a2db22a543675de8
+README.zh.md: 3c528628a8d810db00d9bd8b2c0b64a179faa729
diff --git a/packages/experimental/webworker-packer/README.md b/packages/experimental/webworker-packer/README.md
index c927fd2f4b..dfb3eccf83 100644
--- a/packages/experimental/webworker-packer/README.md
+++ b/packages/experimental/webworker-packer/README.md
@@ -31,7 +31,7 @@ The pack is a three-layer standard stack:
 
 1. **Roster** — the composed profile's plugin rows (standard YAML parse under Include's dialect, `!!js` intact), plus the rows of every config tree the CLI declares in its `package.json` `dsh.configTrees` (agent presets), materialized as a Node-style dependency closure. External peer edges never bind the worker; workspace peers stay on the chain.
 2. **Publish view** — each workspace or vendored package contributes its built npm slice (`files` through picomatch) without source or workspace `dist/`. External packages retain published JavaScript under both `src/` and `dist/` because their `main` or `exports` may point there; only generic test, map, declaration, and archive exclusions apply.
-3. **Reachability sweep** — the runtime loader's own resolution walks from every workspace export face plus the worker assembly's seeds (`IMAGE_ENTRY_SEEDS`), lowering each reached module to the wrapper contract at pack time. The transform reports statically named imports, re-exports, and dynamic imports; calls through `require`; and module-scope direct calls of the form `createRequire(import.meta.url)('pkg')` through a named import from `node:module` or `module`, including an import alias. Page assets (`lib/client.js` behind `./client` exports) ship verbatim; an unresolvable request from our own code fails the pack, third-party ones are tolerated to fail loud at require time.
+3. **Reachability sweep** — the runtime loader's own resolution walks from every non-wildcard workspace runtime export plus the worker assembly's seeds (`IMAGE_ENTRY_SEEDS`), lowering each reached module to the wrapper contract at pack time. Declaration-only condition trees do not seed the sweep; runtime requests for those exports still fail. The transform reports statically named imports, re-exports, and dynamic imports; calls through `require`; and module-scope direct calls of the form `createRequire(import.meta.url)('pkg')` through a named import from `node:module` or `module`, including an import alias. Page assets (`lib/client.js` behind `./client` exports) ship verbatim; an unresolvable request from our own code fails the pack, third-party ones are tolerated to fail loud at require time.
 
 `repository.ts` owns the repo-shaped inputs (workspace scan of `vendor/`, `packages/`, `native/system/packages/`, and `apps/`; profile composition through the real CLI dump path); `pack.ts` owns none of them, so the same library packs a different tree by being called differently. The native scan makes the Landlock entry package an ordinary published-view dependency while its executable remains a Worker platform implementation. The CLI is `dsh-pack-vfs-image --out <file> [--profile web]`; `apps/web`'s `build:preview` runs it after the preview shell build.
 
diff --git a/packages/experimental/webworker-packer/README.zh.md b/packages/experimental/webworker-packer/README.zh.md
index 2a10a8c0f5..3c528628a8 100644
--- a/packages/experimental/webworker-packer/README.zh.md
+++ b/packages/experimental/webworker-packer/README.zh.md
@@ -31,7 +31,7 @@ VFS 镜像打包器：把一份合成 profile 变成浏览器 worker 挂载为
 
 1. **Roster**——合成 profile 的插件行（标准 YAML 解析、Include 方言、`!!js` 原样保留），加上 CLI（命令行界面）在 `package.json` `dsh.configTrees` 里声明的每棵配置树（agent（智能体） presets）的行，按 Node 式依赖闭包物化。外部 peer 边绝不会绑定到 worker，workspace peer 保留在链上。
 2. **发布视图**——每个 workspace 或 vendored 包贡献其构建后的 npm 切片（`files` 走 picomatch），不带源码和 workspace `dist/`。外部包的 `main` 或 `exports` 可能指向 `src/` 或 `dist/`，因此两处发布 JavaScript 都会保留，只应用通用的测试、map、声明与归档排除规则。
-3. **可达性 sweep**——用运行时加载器自己的解析，从全部 workspace 导出面加 worker 装配种子（`IMAGE_ENTRY_SEEDS`）出发，打包时把每个可达模块转换为符合包装层约定的形式。该转换会报告名称可静态确定的 import、re-export 与动态 import、经 `require` 发起的调用，以及通过 `node:module` 或 `module` 具名导入（含导入别名）在模块作用域直接发起的 `createRequire(import.meta.url)('pkg')` 调用。页面资产（`./client` 导出背后的 `lib/client.js`）原样直发；自家代码的不可解析请求会让打包失败，第三方不可解析请求则允许延后到 require 时明确失败。
+3. **可达性 sweep**——用运行时加载器自己的解析, 从全部不含通配符的 workspace 运行时导出加 worker 装配种子 (`IMAGE_ENTRY_SEEDS`) 出发, 打包时把每个可达模块转换为符合包装层约定的形式. 仅含类型声明的条件树不作为扫描入口; 运行时代码请求这些导出仍会失败. 该转换会报告名称可静态确定的 import、re-export 与动态 import、经 `require` 发起的调用, 以及通过 `node:module` 或 `module` 具名导入 (含导入别名) 在模块作用域直接发起的 `createRequire(import.meta.url)('pkg')` 调用. 页面资产 (`./client` 导出背后的 `lib/client.js`) 原样直发; 自家代码的不可解析请求会让打包失败, 第三方不可解析请求则允许延后到 require 时明确失败.
 
 `repository.ts` 拥有仓库形态输入（`vendor/`、`packages/`、`native/system/packages/` 与 `apps/` 的 workspace 扫描；经真 CLI dump 路径合成 profile）；`pack.ts` 一概不拥有，同一库换参即可打另一棵树。Native 扫描使 Landlock 入口包成为普通发布视图依赖，其可执行文件仍由 Worker 平台实现。CLI 为 `dsh-pack-vfs-image --out <file> [--profile web]`；`apps/web` 的 `build:preview` 在预览壳构建后运行它。
 
diff --git a/packages/experimental/webworker-packer/src/pack.ts b/packages/experimental/webworker-packer/src/pack.ts
index 63d37ef6e8..4a065b96e7 100644
--- a/packages/experimental/webworker-packer/src/pack.ts
+++ b/packages/experimental/webworker-packer/src/pack.ts
@@ -349,6 +349,15 @@ function debuggerNamer(workspaces: ReadonlyMap<string, string>, resolveFrom: str
   }
 }
 
+/** Declaration-only condition trees add no runtime roots; explicit imports still resolve normally. */
+function isDeclarationOnlyExport(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false
+  if (Array.isArray(value)) return value.length > 0 && value.every(isDeclarationOnlyExport)
+  const conditions = Object.entries(value)
+  return conditions.length > 0 && conditions.every(([condition, target]) =>
+    condition === 'types' || condition.startsWith('types@') || isDeclarationOnlyExport(target))
+}
+
 function sweepImage(
   files: ImageFiles,
   options: PackOptions,
@@ -383,11 +392,13 @@ function sweepImage(
     } catch {
       continue
     }
-    // Every non-wildcard face is a root; a face resolving onto a page asset is
-    // kept untransformed below rather than excluded here.
+    // Every non-wildcard runtime face is a root; a face resolving onto a page
+    // asset is kept untransformed below rather than excluded here.
     const subpaths = manifest.exports === undefined
       ? ['.']
-      : Object.keys(manifest.exports).filter(key => key.startsWith('.') && !key.includes('*'))
+      : Object.entries(manifest.exports)
+        .filter(([key, target]) => key.startsWith('.') && !key.includes('*') && !isDeclarationOnlyExport(target))
+        .map(([key]) => key)
     for (const subpath of subpaths) {
       queue.push({ specifier: subpath === '.' ? name : `${name}/${subpath.slice(2)}`, from: root, importer: `workspace face ${name}` })
     }
diff --git a/packages/experimental/webworker-packer/tests/built-lib.e2e.ts b/packages/experimental/webworker-packer/tests/built-lib.e2e.ts
index 87ed0e83f1..e945c60c8c 100644
--- a/packages/experimental/webworker-packer/tests/built-lib.e2e.ts
+++ b/packages/experimental/webworker-packer/tests/built-lib.e2e.ts
@@ -87,6 +87,23 @@ it('loads both tarballs through plain Node and mounts their base image and overl
     assert.equal(readFileSync(worker, 'utf8').match(/^import[ \\t]/m), null)
     const base = packer.packVfsImage({ config: '[]\\n', profile: 'packed-consumer', workspaces: new Map(), resolveFrom: process.cwd(), entries: [] })
     assert.deepEqual(base.missing, [])
+    mkdirSync('subject/lib', { recursive: true })
+    const subject = '@deepseek-ai/dsh-image-export-fixture'
+    writeFileSync('subject/package.json', JSON.stringify({ name: subject, files: ['lib'], exports: {
+      '.': { default: './lib/index.js' }, './types': { types: './lib/index.d.ts' },
+    } }))
+    writeFileSync('subject/lib/index.js', 'export const value = 1')
+    writeFileSync('subject/lib/index.d.ts', 'export declare const value: number')
+    const typedOptions = { config: '- id: subject\\n  name: "' + subject + '"\\n', profile: 'typed-consumer',
+      workspaces: new Map([[subject, fileURLToPath(new URL('./subject', import.meta.url))]]),
+      resolveFrom: process.cwd(), entries: [] }
+    const typed = packer.packVfsImage(typedOptions)
+    assert.deepEqual(typed.missing, [])
+    assert.ok(Object.hasOwn(typed.files, 'node_modules/' + subject + '/lib/index.js'))
+    assert.equal(Object.hasOwn(typed.files, 'node_modules/' + subject + '/lib/index.d.ts'), false)
+    writeFileSync('subject/lib/index.js', 'export { value } from "' + subject + '/types"')
+    assert.throws(() => packer.packVfsImage(typedOptions),
+      error => error instanceof Error && error.message.includes('does not export "./types"'))
     const vfs = runtime.loadVfsImage(await runtime.inflateImage(base.image, 'packed base'))
     assert.ok(vfs.existsSync('/dsh/' + packer.MANIFEST_PATH))
     mkdirSync('overlay')
diff --git a/packages/experimental/webworker-packer/tests/exports.spec.ts b/packages/experimental/webworker-packer/tests/exports.spec.ts
new file mode 100644
index 0000000000..b34b157d49
--- /dev/null
+++ b/packages/experimental/webworker-packer/tests/exports.spec.ts
@@ -0,0 +1,69 @@
+/** Runtime reachability ignores declaration-only export roots, not runtime requests. */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it, type TestContext } from 'vitest'
+import { packVfsImage, type PackOptions } from '../src/pack.ts'
+
+const SUBJECT = '@deepseek-ai/dsh-image-export-fixture'
+
+function fixture(test: TestContext, face: unknown, source = 'export const value = 1'): PackOptions {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-image-exports-'))
+  test.onTestFinished(() => { rmSync(root, { recursive: true, force: true }) })
+  mkdirSync(join(root, 'lib'))
+  writeFileSync(join(root, 'package.json'), JSON.stringify({
+    name: SUBJECT,
+    type: 'module',
+    files: ['lib'],
+    exports: {
+      '.': { types: './lib/index.d.ts', default: './lib/index.js' },
+      './contract': face,
+    },
+  }))
+  writeFileSync(join(root, 'lib/index.js'), source)
+  writeFileSync(join(root, 'lib/index.d.ts'), 'export declare const value: number')
+  writeFileSync(join(root, 'lib/contract.js'), 'export const value = 2')
+  return {
+    config: `- id: subject\n  name: '${SUBJECT}'\n`,
+    profile: 'export-check',
+    workspaces: new Map([[SUBJECT, root]]),
+    resolveFrom: root,
+    entries: [],
+  }
+}
+
+it.for([
+  { types: './lib/index.d.ts' },
+  { 'types@>=5.2': './lib/index.d.ts' },
+  { browser: { types: './lib/index.d.ts' } },
+  [{ types: './lib/index.d.ts' }],
+])('packs a declaration-only export without requesting a runtime entry: %j', (face, test) => {
+  const result = packVfsImage(fixture(test, face))
+  expect(result.missing).toEqual([])
+  expect(Object.keys(result.files)).toContain(`node_modules/${SUBJECT}/lib/index.js`)
+  expect(Object.keys(result.files)).not.toContain(`node_modules/${SUBJECT}/lib/index.d.ts`)
+  expect(Object.keys(result.files)).not.toContain(`node_modules/${SUBJECT}/lib/contract.js`)
+})
+
+it.for([
+  { types: './lib/index.d.ts', default: './lib/contract.js' },
+  [{ types: './lib/index.d.ts' }, './lib/contract.js'],
+])('retains the runtime target beside a types condition: %j', (face, test) => {
+  const result = packVfsImage(fixture(test, face))
+  expect(Object.keys(result.files)).toContain(`node_modules/${SUBJECT}/lib/contract.js`)
+})
+
+it('rejects a runtime import of a declaration-only export', (test) => {
+  const options = fixture(test, { types: './lib/index.d.ts' }, `export { value } from '${SUBJECT}/contract'`)
+  expect(() => packVfsImage(options)).toThrow('does not export "./contract"')
+})
+
+it('rejects an assembly entry that requests a declaration-only export', (test) => {
+  const options = fixture(test, { types: './lib/index.d.ts' })
+  expect(() => packVfsImage({ ...options, entries: [`${SUBJECT}/contract`] })).toThrow('worker assembly entry')
+})
+
+it('rejects a missing runtime target beside a types condition', (test) => {
+  const options = fixture(test, { types: './lib/index.d.ts', default: './lib/missing.js' })
+  expect(() => packVfsImage(options)).toThrow('cannot resolve')
+})
diff --git a/packages/experimental/webworker-packer/tests/preview.spec.ts b/packages/experimental/webworker-packer/tests/preview.spec.ts
index 2c5c381059..f3b5937ab9 100644
--- a/packages/experimental/webworker-packer/tests/preview.spec.ts
+++ b/packages/experimental/webworker-packer/tests/preview.spec.ts
@@ -65,7 +65,7 @@ describe('Node preparation of Preview Session data', () => {
     expect(packVfsOverlay(fixture.trees).files).toEqual(original.files)
   })
 
-  it.each(['missing-descriptor', 'other-root', 'other-origin', 'current-child'] as const)('adds catalog facts only for supported direct subagent children in the same root: %s', (mode) => {
+  it.each(['missing-descriptor', 'other-root', 'other-origin', 'current-child'] as const)('catalogs direct subagent children in the same root, retaining missing descriptors as unknown: %s', (mode) => {
     const fixture = source()
     const parent = fixture.put(3)
     const childDirectory = join(fixture.trees[0]!.directory, 'sessions', mode === 'other-root' ? 'other' : 'project', 'child')
@@ -84,8 +84,12 @@ describe('Node preparation of Preview Session data', () => {
     const packed = packPreviewFixture(fixture.trees)
     const restored = restore(packed.files[`home/sessions/project/example/${sessionFormatLogFilename(currentVersion)}`])
     expect(restored.inheritedEventCount).toBe(0)
-    expect(restored.events).toEqual(mode === 'current-child' ? [{ type: 'subagent/catalog', seq: 0, time: 1,
-      data: { version: 0, childId: 'child', childCreatedAt: 2, mode: 'one-shot' } }] : [])
+    const catalog = mode === 'current-child'
+      ? [{ version: 0, childId: 'child', childCreatedAt: 2, mode: 'one-shot' }]
+      : mode === 'missing-descriptor'
+        ? [{ version: 1, childId: 'child', childCreatedAt: 2, mode: 'unknown' }]
+        : []
+    expect(restored.events).toEqual(catalog.map(data => ({ type: 'subagent/catalog', seq: 0, time: 1, data })))
     for (const [path, bytes] of Object.entries(original.files)) expect(packed.files[path], path).toEqual(bytes)
     expect(readFileSync(parent)).toEqual(before)
     expect(readFileSync(childPath)).toEqual(childBefore)
diff --git a/packages/experimental/webworker-runtime/README.i18n.yaml b/packages/experimental/webworker-runtime/README.i18n.yaml
index d6fa266c66..96ccbc1151 100644
--- a/packages/experimental/webworker-runtime/README.i18n.yaml
+++ b/packages/experimental/webworker-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/experimental/webworker-runtime/README.md
-README.md: ce98accac7abb2241f79b16e596e68e1d1fbdd95
-README.zh.md: cc3cf583bb77ed0d3e9611f8d8543f39b9ea9d18
+README.md: f4e412e25e70fe74d66018bf3a0cb66a550603e4
+README.zh.md: 5ae13f0ae49961cfe67d5b567999f500fe7f6f7a
diff --git a/packages/experimental/webworker-runtime/README.md b/packages/experimental/webworker-runtime/README.md
index ce98accac7..f4e412e25e 100644
--- a/packages/experimental/webworker-runtime/README.md
+++ b/packages/experimental/webworker-runtime/README.md
@@ -30,7 +30,7 @@ Three build artifacts and one source-owned process layer:
 - **`lib/index.js` (assembly library)** — `createWorkerHost`/`startWorkerHost` mount the base image and any ordered data overlays (`storage/`), install the module loader (`module-system/`) and the `process` shim, boot the tree through the image's own `dsh-app-boot`, and hand the tunnel its serving seams. Overlays may replace files only under `home/` and `workspace/`; they cannot replace the base manifest, configuration, or modules. The image layout contract (`image-layout.ts`: virtual root, config/manifest paths, empty directories, the `lowered` wrapper-contract gate) is shared with the packer. Boot patches force the deployment-shaped rows: frontend serving off, JSONL session logs on the plaintext path, preset roots onto the image's `config/agent-presets`.
 - **`lib/worker.js` (worker bundle)** — the assembly plus this package's Node-compatibility layer as one self-contained ES module. The module proxy table (`module-proxies.ts`) is the only platform fork: `node:*` builtins over VFS/tunnel/browser primitives, structural stubs that fail loud on the console for what a browser cannot do, and native/binary package replacements. `node:module` supplies `createRequire().resolve` and `.resolve.paths()` over the image package root, so unchanged packages can discover manifests without evaluating their modules. The `node:util` JSON-data comparator compares own enumerable properties, preserving Node admission decisions for recorded fields such as `__proto__`. The global `process` shim carries Node detection fields including `title`, preventing Worker execution from entering DOM-only branches. The pack-time parser reports statically named module requests, including module-scope direct calls of the form `createRequire(import.meta.url)('pkg')` through a named `node:module` or `module` import, to the packer's reachability walk. Stored, CommonJS-obtained, and rebased `createRequire` calls require image entry seeds. VFS mutations drive `node:fs` callback, polling, and promise watchers; open descriptors retain file identity and access mode across rename, replacement, and unlink, `FileHandle.stat({ bigint: true })` reports the same device and inode identity as a path stat while the name still refers to that file, and `FileHandle.chmod()` updates the opened file identity; `readable-stream` supplies the stream state machine used by file streams and unchanged image packages such as Chokidar and readdirp. AsyncLocalStorage carries sync-stack causality across `await` through the snapshot/restore faces the pack-time lowering injects. The worker holds no compiler: an image the packer did not lower is refused at mount. The callback `fs.realpath.native` alias resolves within the mounted VFS and supports `util.promisify`.
 - **`src/shell/` (the worker's own process layer)** — a browser worker cannot fork, so `node:child_process` is not a stub but an implementation: `spawn` starts the command in its own Web Worker — this same bundle, told by its first frame to be a shell process — and reports it through the `ChildProcess` surface the subprocess service consumes. The command runs off the host's thread, `SIGKILL` terminates it whatever it is doing, and it reaches the VFS only by message (the host serves those frames). Worker platform executables preserve native-package protocols such as Landlock without replacing their JavaScript packages or coupling their implementations to `node:child_process`; ordinary commands use the package's evaluator and coreutils command table. The grammar is `@yarnpkg/parsers`' `parseShell`, while `execSync`/`fork` still refuse because they need a real process.
-- **`lib/client.js` (page half)** — startup has two independent stages. `chooseWorkerHostSource({ image?, fixtureManifest? })` optionally owns the boot barrier and fixture manifest: without `preview-fixture` it waits at the source chooser, while a valid query selects directly; either path returns ordered overlays. `connectWorkerHost(worker, { image?, overlays? })` remains the public base-runtime connector; callers that skip the chooser get an empty overlay list. `apps/web` invokes both and supplies its statically bundled Worker. The opening `init` frame carries the base and ordered overlay URLs, the boot payload delivers the structured index-injection table, and `applyIndexInjections` executes it before the shell entry runs. Script preload rows are advisory and skipped because `/plugins` resources resolve only through the tunnel; `loadBundle` fetches each combo on first demand, embeds its tunnel-only source map as a Base64 data URL, and executes the script as a Blob. The tunnel also exposes fetch-shaped transport, the independent file-upload carrier, and the API client. Request frames preserve Blob bodies through structured clone and transfer `ReadableStream<Uint8Array>` ownership. The Host Worker streams both forms into the route, so neither browser thread creates a complete byte array for a generic-file upload.
+- **`lib/client.js` (page half)** — startup has two independent stages. `chooseWorkerHostSource({ image?, fixtureManifest? })` optionally owns the boot barrier and fixture manifest: without `preview-fixture` it waits at the source chooser, while a valid query selects directly; either path returns ordered overlays. `connectWorkerHost(worker, { image?, overlays? })` remains the public base-runtime connector; callers that skip the chooser get an empty overlay list. `apps/web` invokes both and supplies its statically bundled Worker. The opening `init` frame carries the base and ordered overlay URLs, the boot payload delivers the structured index-injection table, and `applyIndexInjections` executes it before the shell entry runs. Script preload rows are advisory and skipped because `/plugins` resources resolve only through the tunnel; `loadBundle` fetches each combo on first demand, embeds its tunnel-only source map as a Base64 data URL, and executes the script as a Blob. The tunnel also exposes fetch-shaped transport, the independent file-upload carrier, and the API client. Request frames preserve Blob bodies through structured clone and transfer `ReadableStream<Uint8Array>` ownership. The Host Worker streams both forms into the route, so neither browser thread creates a complete byte array for a generic-file upload. A Remote stream's uplink crosses as `stream-uplink-item` / `stream-uplink-end` frames into an unbounded `TunnelUplink` that drops items arriving after `end`: the page and its worker are one trusted same-origin boundary, so the Host inbox cap does not apply.
 
 Acceptance lives in `apps/web/tests/preview-boot.e2e.ts`, which serves the real built pages and drives the pre-boot chooser plus Worker activation in headless Chromium. The empty selection exercises first-run startup. The `vfs-example` overlay supplies ordinary workspace files and plaintext persistence artifacts for cold Workspace/Session discovery, tool presentation, subagent navigation, and history paging without a model request. The [packer](../webworker-packer/README.md) prepares current-generation successors from committed historical logs in Node; those source logs remain byte-identical in the overlay. The fixture generator owns the acceptance test's current projection cache. The chooser reserves WebFS as a separate user-authorized source; that provider does not read the built-in fixture.
 
diff --git a/packages/experimental/webworker-runtime/README.zh.md b/packages/experimental/webworker-runtime/README.zh.md
index cc3cf583bb..5ae13f0ae4 100644
--- a/packages/experimental/webworker-runtime/README.zh.md
+++ b/packages/experimental/webworker-runtime/README.zh.md
@@ -30,7 +30,7 @@ kind: "package-library"
 - **`lib/index.js`（装配库）**——`createWorkerHost`/`startWorkerHost` 挂载基础镜像和按序排列的数据 overlays（`storage/`）、安装模块加载器（`module-system/`）与 `process` shim、经镜像自带的 `dsh-app-boot` 启动插件树，并把服务 seam 交给隧道。Overlay 只能替换 `home/` 与 `workspace/` 下的文件，不能替换基础 manifest、配置或模块。镜像布局契约（`image-layout.ts`：虚拟根、config/manifest 路径、空目录、`lowered` 包装契约门）与 packer 共享。boot patch 强制部署形态行：关前端静态服务、JSONL 会话日志走明文、preset 根指向镜像内 `config/agent-presets`。
 - **`lib/worker.js`（worker 束）**——装配库加本包的 Node 兼容层，合成一个自含 ES module。模块代理表（`module-proxies.ts`）是唯一平台叉口：`node:*` 内建走 VFS、隧道和浏览器原语，浏览器做不到的走结构化 stub（调用即在 console 报错并抛出），native/binary 包则替换执行后端。`node:module` 在镜像 package 根之上提供 `createRequire().resolve` 与 `.resolve.paths()`，使未修改的包无需执行目标模块即可发现 manifest。`node:util` 的 JSON 数据比较器检查可枚举的自有属性，使 `__proto__` 等记录字段的准入判定与 Node 一致。全局 `process` shim 带有包括 `title` 在内的 Node 环境识别字段，避免 Worker 执行误入仅适用于 DOM 的分支。pack 期解析器会把名称静态可知的模块请求报告给 packer 的可达性遍历，其中包括通过 `node:module` 或 `module` 具名导入在模块作用域直接发起的 `createRequire(import.meta.url)('pkg')` 调用。保存、经 CommonJS 获取或另设基准的 `createRequire` 调用需要镜像入口种子。VFS mutation 驱动 `node:fs` 的 callback、polling 和 promise watcher；打开的 descriptor 在 rename、replacement 和 unlink 后仍保留文件身份与访问模式，只要文件名仍指向该文件，`FileHandle.stat({ bigint: true })` 报告的 device 与 inode 身份就与路径 stat 相同，`FileHandle.chmod()` 则更新打开文件身份的权限；`readable-stream` 提供文件流以及 Chokidar、readdirp 等未修改镜像包所用的流状态机。AsyncLocalStorage 经 pack 时降低注入的 snapshot/restore 面在 `await` 间携带同步栈因果。worker 不带编译器：packer 未降低的镜像在挂载时被拒。回调式 `fs.realpath.native` 别名在已挂载的 VFS 内解析路径，并支持 `util.promisify`。
 - **`src/shell/`（worker 自己的进程层）**——浏览器 worker 无法 fork，所以 `node:child_process` 不是 stub 而是实现：`spawn` 把命令放进它自己的 Web Worker——就是这同一个束，由首帧告诉它「你是 shell 进程」——并以 subprocess 服务消费的 `ChildProcess` 面报告结果。命令不占宿主线程，`SIGKILL` 不管它在干什么都能终止它，而它只能靠消息触达 VFS（由宿主应答这些帧）。Worker 平台 executable 在不替换 JavaScript 包、也不把具体实现耦合进 `node:child_process` 的情况下保持 Landlock 等 native 包协议；普通命令使用本包的求值器与 coreutils 命令表。语法来自 `@yarnpkg/parsers` 的 `parseShell`，而 `execSync`/`fork` 依然拒绝，因为它们需要真进程。
-- **`lib/client.js`（页面半）**——启动分为相互独立的两段。`chooseWorkerHostSource({ image?, fixtureManifest? })` 可选地拥有 boot barrier 与 fixture manifest：没有 `preview-fixture` 时停在来源选择面板，合法 query 则直接选择；两条路径都返回按序排列的 overlays。`connectWorkerHost(worker, { image?, overlays? })` 仍是公开的基础运行态连接器；调用方跳过选择器时 overlay 列表为空。`apps/web` 调用这两段并提供静态打包的 Worker。开局 `init` 帧携带基础镜像与按序排列的 overlay URL，boot 载荷送达结构化 index 注入表，`applyIndexInjections` 在壳入口运行前逐行执行。脚本 preload 行只是提示，因此会被跳过：`/plugins` 资源只能经 tunnel 解析，`loadBundle` 会在首次需要时获取 combo、把仅 tunnel 可达的 sourcemap 内嵌为 Base64 data URL，再以 Blob 执行脚本。Tunnel 还暴露 fetch 形式的传输、独立文件上传载体和 API 客户端。请求帧通过结构化克隆保留 Blob 请求体，并转移 `ReadableStream<Uint8Array>` 的所有权。Host Worker 将两种请求体都逐块送入路由，因此通用文件上传不会在任何浏览器线程创建完整字节数组。
+- **`lib/client.js`（页面半）**——启动分为相互独立的两段。`chooseWorkerHostSource({ image?, fixtureManifest? })` 可选地拥有 boot barrier 与 fixture manifest：没有 `preview-fixture` 时停在来源选择面板，合法 query 则直接选择；两条路径都返回按序排列的 overlays。`connectWorkerHost(worker, { image?, overlays? })` 仍是公开的基础运行态连接器；调用方跳过选择器时 overlay 列表为空。`apps/web` 调用这两段并提供静态打包的 Worker。开局 `init` 帧携带基础镜像与按序排列的 overlay URL，boot 载荷送达结构化 index 注入表，`applyIndexInjections` 在壳入口运行前逐行执行。脚本 preload 行只是提示，因此会被跳过：`/plugins` 资源只能经 tunnel 解析，`loadBundle` 会在首次需要时获取 combo、把仅 tunnel 可达的 sourcemap 内嵌为 Base64 data URL，再以 Blob 执行脚本。Tunnel 还暴露 fetch 形式的传输、独立文件上传载体和 API 客户端。请求帧通过结构化克隆保留 Blob 请求体，并转移 `ReadableStream<Uint8Array>` 的所有权。Host Worker 将两种请求体都逐块送入路由，因此通用文件上传不会在任何浏览器线程创建完整字节数组。Remote 流的上行以 `stream-uplink-item` / `stream-uplink-end` 帧进入没有上限的 `TunnelUplink`，`end` 之后到达的项被丢弃：页面与其 worker 是同一个可信的同源边界，Host 的 inbox 上限在此不适用。
 
 验收在 `apps/web/tests/preview-boot.e2e.ts`：静态服务真实构建页面，在 headless Chromium 里驱动 pre-boot 选择面板与 Worker 激活。空白选择验证首次启动；`vfs-example` overlay 提供普通 workspace 文件与明文 persistence 产物，无需模型请求即可验证 Workspace/Session 冷发现、工具呈现、subagent 导航和历史分页。[打包器](../webworker-packer/README.zh.md)在 Node 中根据已提交的历史日志准备当前代后继文件；这些源日志在 overlay 中逐字节保持不变。fixture 生成器负责验收测试的当前投影缓存。选择面板为 WebFS 保留独立的用户授权来源；该 provider 不读取内置 fixture。
 
diff --git a/packages/experimental/webworker-runtime/src/client/client.ts b/packages/experimental/webworker-runtime/src/client/client.ts
index a569e48276..e6a2a18537 100644
--- a/packages/experimental/webworker-runtime/src/client/client.ts
+++ b/packages/experimental/webworker-runtime/src/client/client.ts
@@ -13,6 +13,8 @@ import type {
   TunnelRequestId,
   TunnelStreamEndFrame,
   TunnelStreamErrorFrame,
+  TunnelStreamUplinkEndFrame,
+  TunnelStreamUplinkItemFrame,
   TunnelStreamItemFrame,
   TunnelStreamOpenFrame,
 } from '../transport/frames.ts'
@@ -33,6 +35,19 @@ interface PendingUnary {
 
 type LogicalStreamFrame = TunnelStreamItemFrame | TunnelStreamEndFrame | TunnelStreamErrorFrame
 
+interface UplinkPump {
+  /** Settles once the pump has stopped posting frames. */
+  readonly done: Promise<void>
+  /** Interrupt the pump, including a read blocked on the caller's iterator, and return that iterator at once. */
+  stop(): void
+}
+
+/** One open logical stream: its downlink inbox and, once the open frame is posted, its uplink pump. */
+interface LogicalStream {
+  readonly inbox: LogicalStreamInbox
+  pump: UplinkPump | undefined
+}
+
 interface TunnelStreamFailureMarker {
   readonly kind: 'remote' | 'carrier'
   readonly code?: string
@@ -143,7 +158,7 @@ export class WorkerTunnel {
   private nextId = 1
   private readonly unary = new Map<TunnelRequestId, PendingUnary>()
   private readonly bodyStreams = new Map<TunnelRequestId, ReadableStreamDefaultController<Uint8Array>>()
-  private readonly logicalStreams = new Map<TunnelRequestId, LogicalStreamInbox>()
+  private readonly logicalStreams = new Map<TunnelRequestId, LogicalStream>()
   /**
    * In-flight request descriptions, so a refusal names what was refused.
    *
@@ -178,7 +193,7 @@ export class WorkerTunnel {
         kind: 'carrier',
         message: `web-preview tunnel: worker failed: ${event.message}`,
       }, { cause: reason })
-      for (const inbox of this.logicalStreams.values()) inbox.fail(failure)
+      for (const { inbox } of this.logicalStreams.values()) inbox.fail(failure)
       this.logicalStreams.clear()
       for (const release of this.releases.values()) release()
       this.releases.clear()
@@ -234,17 +249,19 @@ export class WorkerTunnel {
    * @param endpoint - canonical Gateway Remote endpoint.
    * @param payload - decoded endpoint payload.
    * @param signal - logical-stream cancellation.
+   * @param uplink - the stream's uplink, posted as `stream-uplink-item` frames and closed with `stream-uplink-end`.
    * @returns decoded stream values from the worker Host.
    */
-  async *open(endpoint: string, payload: unknown, signal: AbortSignal): AsyncGenerator {
+  async *open(endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>): AsyncGenerator {
     signal.throwIfAborted()
     const id = this.nextId++
     const inbox = new LogicalStreamInbox()
+    const stream: LogicalStream = { inbox, pump: undefined }
     let opened = false
     let terminal = false
     const onAbort = (): void => { inbox.fail(signal.reason) }
     signal.addEventListener('abort', onAbort, { once: true })
-    this.logicalStreams.set(id, inbox)
+    this.logicalStreams.set(id, stream)
     this.inFlight.set(id, `STREAM ${endpoint}`)
     try {
       const frame: TunnelStreamOpenFrame = { t: 'stream-open', id, endpoint, payload }
@@ -257,6 +274,7 @@ export class WorkerTunnel {
           message: `web-preview tunnel: failed to open Remote stream ${endpoint}`,
         }, { cause })
       }
+      if (uplink !== undefined) stream.pump = this.pumpUplink(id, uplink, signal, inbox)
       while (true) {
         const response = await inbox.next()
         signal.throwIfAborted()
@@ -272,10 +290,67 @@ export class WorkerTunnel {
       signal.removeEventListener('abort', onAbort)
       this.logicalStreams.delete(id)
       this.inFlight.delete(id)
+      stream.pump?.stop()
       if (opened && !terminal) this.abortWorkerOperation(id)
+      if (stream.pump !== undefined) await stream.pump.done
     }
   }
 
+  /**
+   * Post the caller's uplink items for one logical stream. A failing uplink
+   * fails the downlink, and the enclosing `open` then aborts the worker side.
+   * `stop()` interrupts a pump blocked on `uplink.next()` and returns the
+   * caller's iterator at once, so a handle's queue closes and `send()` throws
+   * from then on; a generator blocked in `next()` completes that return only
+   * once it yields, so it is not awaited.
+   */
+  private pumpUplink(
+    id: TunnelRequestId,
+    uplink: AsyncIterable<unknown>,
+    signal: AbortSignal,
+    inbox: LogicalStreamInbox,
+  ): UplinkPump {
+    const interrupt = Promise.withResolvers<IteratorReturnResult<undefined>>()
+    const iterator = uplink[Symbol.asyncIterator]()
+    const state = { active: true, released: false }
+    const release = (): void => {
+      if (state.released) return
+      state.released = true
+      void Promise.resolve(iterator.return?.()).catch(() => undefined)
+    }
+    const done = this.forwardUplink(id, iterator, interrupt.promise, () => state.active && !signal.aborted)
+      .then((exhausted) => { state.released ||= exhausted }, (error: unknown) => { inbox.fail(error) })
+      .then(release)
+    return {
+      done,
+      stop: () => {
+        state.active = false
+        interrupt.resolve({ value: undefined, done: true })
+        release()
+      },
+    }
+  }
+
+  /**
+   * Post items until the caller's iterator ends, the pump is stopped, or the page aborts the stream.
+   * @returns whether the caller's iterator was exhausted and the uplink end posted.
+   */
+  private async forwardUplink(
+    id: TunnelRequestId,
+    iterator: AsyncIterator<unknown>,
+    interrupt: Promise<IteratorReturnResult<undefined>>,
+    isActive: () => boolean,
+  ): Promise<boolean> {
+    for (;;) {
+      const next = await Promise.race([iterator.next(), interrupt])
+      if (!isActive()) return false
+      if (next.done === true) break
+      this.worker.postMessage({ t: 'stream-uplink-item', id, value: next.value } satisfies TunnelStreamUplinkItemFrame)
+    }
+    this.worker.postMessage({ t: 'stream-uplink-end', id } satisfies TunnelStreamUplinkEndFrame)
+    return true
+  }
+
   /**
    * Read the pre-cordis boot payload (the injection table).
    * @returns The payload the page applies before the client tree loads.
@@ -472,7 +547,11 @@ export class WorkerTunnel {
       case 'stream-item':
       case 'stream-end':
       case 'stream-error': {
-        this.logicalStreams.get(frame.id)?.push(frame)
+        const stream = this.logicalStreams.get(frame.id)
+        if (stream === undefined) return
+        stream.inbox.push(frame)
+        // A terminal frame ends the uplink now, not on the consumer's next read.
+        if (frame.t !== 'stream-item') stream.pump?.stop()
         return
       }
       default: {
diff --git a/packages/experimental/webworker-runtime/src/client/index.ts b/packages/experimental/webworker-runtime/src/client/index.ts
index 467f915902..1fff274cfd 100644
--- a/packages/experimental/webworker-runtime/src/client/index.ts
+++ b/packages/experimental/webworker-runtime/src/client/index.ts
@@ -27,7 +27,12 @@ export {
 interface ClientTransportGlobal {
   __DSH_TRANSPORT__?: {
     fetch: TunnelFetch
-    openStream: (endpoint: string, payload: unknown, signal: AbortSignal) => AsyncIterable<unknown>
+    openStream: (
+      endpoint: string,
+      payload: unknown,
+      signal: AbortSignal,
+      uplink?: AsyncIterable<unknown>,
+    ) => AsyncIterable<unknown>
     loadBundle: (url: string) => Promise<void>
     /** The page spawned the worker the Host runs in, so the page owns it. */
     ownsHost: boolean
@@ -151,7 +156,7 @@ export async function connectWorkerHost(worker: Worker, options?: WorkerHostConn
     const payload = await tunnel.bootPayload()
     ;(globalThis as ClientTransportGlobal).__DSH_TRANSPORT__ = {
       fetch: (input, init) => tunnel.fetch(input, init),
-      openStream: (endpoint, payload, signal) => tunnel.open(endpoint, payload, signal),
+      openStream: (endpoint, payload, signal, uplink) => tunnel.open(endpoint, payload, signal, uplink),
       loadBundle: (url: string) => tunnel.loadBundle(url),
       // The host lives in a worker this page spawned: the page owns it, so
       // the privileged surface stays reachable off loopback authorities.
diff --git a/packages/experimental/webworker-runtime/src/index.ts b/packages/experimental/webworker-runtime/src/index.ts
index fd3e3f563b..9bb306433c 100644
--- a/packages/experimental/webworker-runtime/src/index.ts
+++ b/packages/experimental/webworker-runtime/src/index.ts
@@ -11,8 +11,8 @@ export {
   type TunnelAbortFrame, type TunnelInboundFrame, type TunnelOutboundFrame, type TunnelRequestFrame,
   type TunnelRequestId, type TunnelResponseChunkFrame, type TunnelResponseEndFrame,
   type TunnelResponseErrorFrame, type TunnelResponseFrame, type TunnelResponseHeadFrame,
-  type TunnelStreamEndFrame, type TunnelStreamErrorFrame, type TunnelStreamItemFrame,
-  type TunnelStreamOpenFrame,
+  type TunnelStreamEndFrame, type TunnelStreamErrorFrame, type TunnelStreamUplinkEndFrame,
+  type TunnelStreamUplinkItemFrame, type TunnelStreamItemFrame, type TunnelStreamOpenFrame,
 } from './transport/frames.ts'
 export {
   DEFAULT_CONDITIONS, requireActiveModuleLoader, setActiveModuleLoader, WorkerModuleLoader,
diff --git a/packages/experimental/webworker-runtime/src/transport/frames.ts b/packages/experimental/webworker-runtime/src/transport/frames.ts
index 01d399d4e8..744338be1d 100644
--- a/packages/experimental/webworker-runtime/src/transport/frames.ts
+++ b/packages/experimental/webworker-runtime/src/transport/frames.ts
@@ -25,6 +25,19 @@ export interface TunnelStreamOpenFrame {
   readonly payload: unknown
 }
 
+/** One uplink item for an open Remote stream; `value` absent and `undefined` are equivalent. */
+export interface TunnelStreamUplinkItemFrame {
+  readonly t: 'stream-uplink-item'
+  readonly id: TunnelRequestId
+  readonly value?: unknown
+}
+
+/** Page-side half-close of a Remote stream's uplink. */
+export interface TunnelStreamUplinkEndFrame {
+  readonly t: 'stream-uplink-end'
+  readonly id: TunnelRequestId
+}
+
 /** Page-side cancellation of an in-flight request or stream. */
 export interface TunnelAbortFrame {
   readonly t: 'abort'
@@ -47,6 +60,8 @@ export type TunnelInboundFrame =
   | TunnelInitFrame
   | TunnelRequestFrame
   | TunnelStreamOpenFrame
+  | TunnelStreamUplinkItemFrame
+  | TunnelStreamUplinkEndFrame
   | TunnelAbortFrame
 
 /** Complete response for unary requests and static files. */
@@ -153,6 +168,8 @@ export function parseInboundFrame(data: unknown): TunnelInboundFrame {
     throw new Error(`webworker tunnel: frame has no usable id: ${JSON.stringify(frame.id)}`)
   }
   if (frame.t === 'abort') return { t: 'abort', id }
+  if (frame.t === 'stream-uplink-end') return { t: 'stream-uplink-end', id }
+  if (frame.t === 'stream-uplink-item') return { t: 'stream-uplink-item', id, value: frame.value }
   if (frame.t === 'stream-open') {
     if (typeof frame.endpoint !== 'string' || frame.endpoint.length === 0) {
       throw new Error(`webworker tunnel: stream ${String(id)} needs a non-empty endpoint`)
diff --git a/packages/experimental/webworker-runtime/src/transport/tunnel.ts b/packages/experimental/webworker-runtime/src/transport/tunnel.ts
index dc6608f975..b94f927a9d 100644
--- a/packages/experimental/webworker-runtime/src/transport/tunnel.ts
+++ b/packages/experimental/webworker-runtime/src/transport/tunnel.ts
@@ -91,10 +91,11 @@ export interface TunnelSeams {
   readonly directFetch: (request: Request) => Promise<Response>
   /** Boot payload for `GET /__boot__`: the structured index injection table. */
   readonly bootPayload: () => unknown
-  /** Open one decoded Gateway Remote stream without another network carrier. */
+  /** Open one decoded Gateway Remote stream without another network carrier; `uplink` carries the page's items. */
   readonly openStream: (
     endpoint: string,
     payload: unknown,
+    uplink: AsyncIterable<unknown>,
     signal: AbortSignal,
   ) => Promise<AsyncIterable<unknown>>
   /** Convert a Gateway stream failure to stable Client fields. */
@@ -173,6 +174,54 @@ class BufferedSink {
   }
 }
 
+/** Uplink items of one worker-local logical stream, read once by the Host method as its `uplink`. */
+class TunnelUplink implements AsyncIterable<unknown>, AsyncIterator<unknown> {
+  private readonly items: unknown[] = []
+  private ended = false
+  private closed = false
+  private wake: (() => void) | undefined
+
+  push(value: unknown): void {
+    if (this.ended || this.closed) return
+    this.items.push(value)
+    this.signal()
+  }
+
+  /** Page half-close or stream end; buffered items still drain. */
+  end(): void {
+    this.ended = true
+    this.signal()
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return this
+  }
+
+  async next(): Promise<IteratorResult<unknown>> {
+    while (true) {
+      if (this.closed) return { value: undefined, done: true }
+      if (this.items.length > 0) return { value: this.items.shift(), done: false }
+      if (this.ended) return { value: undefined, done: true }
+      if (this.wake !== undefined) throw new Error('webworker tunnel: stream uplink has one pending read')
+      await new Promise<void>((resolve) => { this.wake = resolve })
+    }
+  }
+
+  /** The Host stopped reading: buffered and later items are dropped. */
+  return(): Promise<IteratorResult<unknown>> {
+    this.closed = true
+    this.items.length = 0
+    this.signal()
+    return Promise.resolve({ value: undefined, done: true })
+  }
+
+  private signal(): void {
+    const wake = this.wake
+    this.wake = undefined
+    wake?.()
+  }
+}
+
 /** One tunnel per worker; wire {@link TunnelServer.handleMessage} to `onmessage` first. */
 export class TunnelServer {
   private readonly port: TunnelPort
@@ -181,6 +230,8 @@ export class TunnelServer {
   private readonly unaryApiLane: 'route' | 'direct'
   private readonly queue: QueuedFrame[] = []
   private readonly inFlight = new Map<TunnelRequestId, InFlight>()
+  /** Uplinks of accepted `stream-open` frames, buffering items that arrive before or while the stream serves. */
+  private readonly uplinks = new Map<TunnelRequestId, TunnelUplink>()
   private seams: TunnelSeams | undefined
   private failure: string | undefined
   private listener: RequestListener | undefined
@@ -203,9 +254,18 @@ export class TunnelServer {
       // one reaching a live server is a client double-connect.
       throw new Error('webworker tunnel: duplicate init frame; the tunnel is already open')
     }
+    if (frame.t === 'stream-uplink-item') {
+      this.uplinks.get(frame.id)?.push(frame.value)
+      return
+    }
+    if (frame.t === 'stream-uplink-end') {
+      this.uplinks.get(frame.id)?.end()
+      return
+    }
     if (frame.t === 'abort') {
       this.inFlight.get(frame.id)?.abort()
       this.inFlight.delete(frame.id)
+      this.dropUplink(frame.id)
       // A request still parked in the boot queue must not run after its
       // caller gave up; serve() would otherwise execute it post-boot.
       const queued = this.queue.findIndex(request => request.id === frame.id)
@@ -213,6 +273,7 @@ export class TunnelServer {
       return
     }
     if (this.failure !== undefined) {  this.refuse(frame, this.failure); return }
+    if (frame.t === 'stream-open') this.uplinks.set(frame.id, new TunnelUplink())
     if (this.seams === undefined) {
       this.queue.push(frame)
       return
@@ -247,6 +308,7 @@ export class TunnelServer {
 
   private refuse(frame: QueuedFrame, message: string): void {
     if (frame.t === 'stream-open') {
+      this.dropUplink(frame.id)
       this.send({
         t: 'stream-error',
         id: frame.id,
@@ -276,10 +338,11 @@ export class TunnelServer {
       return
     }
     const seams = this.seams
+    const uplink = this.uplinks.get(frame.id) ?? new TunnelUplink()
     const controller = new AbortController()
     this.inFlight.set(frame.id, { abort: () => { controller.abort() } })
     try {
-      const source = await seams.openStream(frame.endpoint, frame.payload, controller.signal)
+      const source = await seams.openStream(frame.endpoint, frame.payload, uplink, controller.signal)
       for await (const value of source) {
         if (controller.signal.aborted) return
         this.send({ t: 'stream-item', id: frame.id, value })
@@ -296,9 +359,17 @@ export class TunnelServer {
       }
     } finally {
       this.inFlight.delete(frame.id)
+      this.dropUplink(frame.id)
     }
   }
 
+  /** The stream is over: settle any Host read still waiting on its uplink and stop buffering. */
+  private dropUplink(id: TunnelRequestId): void {
+    const uplink = this.uplinks.get(id)
+    this.uplinks.delete(id)
+    uplink?.end()
+  }
+
   private sinkFor(id: TunnelRequestId): ResponseSink {
     const send = this.send.bind(this)
     const inFlight = this.inFlight
diff --git a/packages/experimental/webworker-runtime/src/worker-host.ts b/packages/experimental/webworker-runtime/src/worker-host.ts
index 70b70ac9ed..3c96174f8d 100644
--- a/packages/experimental/webworker-runtime/src/worker-host.ts
+++ b/packages/experimental/webworker-runtime/src/worker-host.ts
@@ -256,7 +256,9 @@ export function createWorkerHost(options: WorkerHostOptions): WorkerHost {
       tunnel.serve({
         directFetch: (request: Request) => handler.fetch(request),
         bootPayload: () => readBootPayload(ctx),
-        openStream: typertGateway.wireStream.open,
+        // The worker tree serves its own page: every stream speaks for the operator.
+        openStream: (endpoint, payload, uplink, signal) =>
+          typertGateway.wireStream.open(endpoint, payload, uplink, undefined, signal),
         streamFailure: typertGateway.wireStream.failure,
       })
     } catch (reason) {
diff --git a/packages/experimental/webworker-runtime/tests/transport/frames.spec.ts b/packages/experimental/webworker-runtime/tests/transport/frames.spec.ts
index 4113bfd25b..0ee1b9f94f 100644
--- a/packages/experimental/webworker-runtime/tests/transport/frames.spec.ts
+++ b/packages/experimental/webworker-runtime/tests/transport/frames.spec.ts
@@ -21,6 +21,17 @@ describe('tunnel init frame', () => {
   })
 })
 
+describe('tunnel uplink frames', () => {
+  it('parses uplink items with and without a value and the uplink end', () => {
+    expect(parseInboundFrame({ t: 'stream-uplink-item', id: 7, value: { line: 'ls' } }))
+      .toEqual({ t: 'stream-uplink-item', id: 7, value: { line: 'ls' } })
+    expect(parseInboundFrame({ t: 'stream-uplink-item', id: 'seven' }))
+      .toEqual({ t: 'stream-uplink-item', id: 'seven', value: undefined })
+    expect(parseInboundFrame({ t: 'stream-uplink-end', id: 7 })).toEqual({ t: 'stream-uplink-end', id: 7 })
+    expect(() => parseInboundFrame({ t: 'stream-uplink-end' })).toThrow('frame has no usable id')
+  })
+})
+
 describe('tunnel request bodies', () => {
   it('accepts ArrayBuffer, Blob, and ReadableStream bodies and rejects other values', () => {
     const bytes = Uint8Array.of(1, 2).buffer
diff --git a/packages/experimental/webworker-runtime/tests/transport/tunnel-client.spec.ts b/packages/experimental/webworker-runtime/tests/transport/tunnel-client.spec.ts
index c309e99e09..2c5ae1545d 100644
--- a/packages/experimental/webworker-runtime/tests/transport/tunnel-client.spec.ts
+++ b/packages/experimental/webworker-runtime/tests/transport/tunnel-client.spec.ts
@@ -276,3 +276,92 @@ function stubWorker(): {
     dshRemoteStreamFailure: { kind: 'carrier' },
   })
 }
+
+// A stream posts each uplink item, then the uplink end, under the stream's id.
+{
+  const { worker, sent, deliver } = stubWorker()
+  const tunnel = new WorkerTunnel(worker)
+  const uplink = (async function *(): AsyncGenerator<string> {
+    yield 'a'
+    yield 'b'
+  })()
+  const stream = tunnel.open('job/attach', { args: {} }, new AbortController().signal, uplink)[Symbol.asyncIterator]()
+  const first = stream.next()
+  await settled(() => sent.length === 4)
+  check('a stream posts uplink items and the uplink end', sent, [
+    { t: 'stream-open', id: 1, endpoint: 'job/attach', payload: { args: {} } },
+    { t: 'stream-uplink-item', id: 1, value: 'a' },
+    { t: 'stream-uplink-item', id: 1, value: 'b' },
+    { t: 'stream-uplink-end', id: 1 },
+  ])
+  deliver({ t: 'stream-item', id: 1, value: 'echo:a' })
+  check('the downlink still yields Host items', await first, { value: 'echo:a', done: false })
+  const ended = stream.next()
+  deliver({ t: 'stream-end', id: 1 })
+  check('a duplex stream ends without an abort frame', [await ended, sent.length], [{ done: true, value: undefined }, 4])
+}
+
+// A failing uplink fails the downlink and aborts the worker side of the stream.
+{
+  const { worker, sent } = stubWorker()
+  const tunnel = new WorkerTunnel(worker)
+  const uplink = (async function *(): AsyncGenerator<string> {
+    yield 'a'
+    throw new Error('uplink exploded')
+  })()
+  const failure = await tunnel.open('job/attach', {}, new AbortController().signal, uplink)[Symbol.asyncIterator]().next()
+    .then(() => 'resolved', (error: unknown) => (error as Error).message)
+  check('an uplink failure fails the downlink', failure, 'uplink exploded')
+  check('an uplink failure aborts the worker stream', sent.map(frame => frame.t), ['stream-open', 'stream-uplink-item', 'abort'])
+}
+
+// The downlink ending first stops the uplink pump and releases the caller's iterator.
+{
+  const { worker, sent, deliver } = stubWorker()
+  const tunnel = new WorkerTunnel(worker)
+  let released = false
+  const uplink: AsyncIterable<string> = {
+    [Symbol.asyncIterator]: () => ({
+      next: () => new Promise<IteratorResult<string>>(() => {}),
+      return: async (): Promise<IteratorResult<string>> => {
+        released = true
+        return { value: undefined, done: true }
+      },
+    }),
+  }
+  const stream = tunnel.open('job/attach', {}, new AbortController().signal, uplink)[Symbol.asyncIterator]()
+  const ended = stream.next()
+  deliver({ t: 'stream-end', id: 1 })
+  check('the downlink ends while the uplink is idle', await ended, { done: true, value: undefined })
+  await settled(() => released)
+  check('the caller iterator is released without an uplink end', [released, sent.map(frame => frame.t)], [true, ['stream-open']])
+}
+
+// A terminal frame releases the caller's uplink iterator in the receive path, before the consumer reads it.
+{
+  const { worker, deliver } = stubWorker()
+  const tunnel = new WorkerTunnel(worker)
+  let released = false
+  const uplink: AsyncIterable<string> = {
+    [Symbol.asyncIterator]: () => ({
+      next: () => new Promise<IteratorResult<string>>(() => {}),
+      return: async (): Promise<IteratorResult<string>> => {
+        released = true
+        return { value: undefined, done: true }
+      },
+    }),
+  }
+  const stream = tunnel.open('job/attach', {}, new AbortController().signal, uplink)[Symbol.asyncIterator]()
+  const ended = stream.next()
+  deliver({ t: 'stream-end', id: 1 })
+  check('a terminal frame releases the uplink before the consumer reads', released, true)
+  check('the downlink then ends', await ended, { done: true, value: undefined })
+}
+
+/** Wait, in small hops, for a condition that a concurrent pump settles. */
+async function settled(condition: () => boolean): Promise<void> {
+  for (let attempt = 0; attempt < 200 && !condition(); attempt += 1) {
+    await new Promise<void>((resolve) => { setTimeout(resolve, 1) })
+  }
+  if (!condition()) throw new Error('fixture condition did not settle')
+}
diff --git a/packages/experimental/webworker-runtime/tests/transport/tunnel-server.spec.ts b/packages/experimental/webworker-runtime/tests/transport/tunnel-server.spec.ts
index 7ca4ba6260..68c956e467 100644
--- a/packages/experimental/webworker-runtime/tests/transport/tunnel-server.spec.ts
+++ b/packages/experimental/webworker-runtime/tests/transport/tunnel-server.spec.ts
@@ -137,8 +137,8 @@ describe('worker tunnel logical streams', () => {
     })
     expect(frames).toEqual([])
 
-    server.serve(seams(async (endpoint, payload, signal) => {
-      seen.push(endpoint, payload, signal)
+    server.serve(seams(async (endpoint, payload, uplink, signal) => {
+      seen.push(endpoint, payload, uplink, signal)
       return (async function *(): AsyncGenerator {
         yield { type: 'baseline' }
         yield { type: 'event', seq: 1 }
@@ -155,15 +155,103 @@ describe('worker tunnel logical streams', () => {
     expect(seen).toEqual([
       'session/follow',
       { args: { sessionId: 'session-1' } },
+      expect.any(Object),
       expect.any(AbortSignal),
     ])
   })
 
+  it('buffers uplink items until the Host reads them and ends the uplink on half-close', async () => {
+    const { server, frames } = harness()
+    server.handleMessage({ t: 'stream-open', id: 6, endpoint: 'job/attach', payload: { args: {} } })
+    server.handleMessage({ t: 'stream-uplink-item', id: 6, value: 'a' })
+    server.serve(seams(async (_endpoint, _payload, uplink) => (async function *(): AsyncGenerator {
+      for await (const item of uplink) yield `echo:${String(item)}`
+    })()))
+    await vi.waitFor(() => { expect(frames).toEqual([{ t: 'stream-item', id: 6, value: 'echo:a' }]) })
+
+    server.handleMessage({ t: 'stream-uplink-item', id: 6, value: 'b' })
+    server.handleMessage({ t: 'stream-uplink-item', id: 99, value: 'no such stream' })
+    server.handleMessage({ t: 'stream-uplink-end', id: 99 })
+    server.handleMessage({ t: 'stream-uplink-end', id: 6 })
+    await vi.waitFor(() => {
+      expect(frames).toEqual([
+        { t: 'stream-item', id: 6, value: 'echo:a' },
+        { t: 'stream-item', id: 6, value: 'echo:b' },
+        { t: 'stream-end', id: 6 },
+      ])
+    })
+  })
+
+  it('drops uplink items once the Host stops reading them', async () => {
+    const { server, frames } = harness()
+    const outcome = Promise.withResolvers<unknown>()
+    server.serve(seams(async (_endpoint, _payload, uplink) => {
+      const iterator = uplink[Symbol.asyncIterator]()
+      return (async function *(): AsyncGenerator {
+        yield 'ready'
+        const first = await iterator.next()
+        await iterator.return?.()
+        outcome.resolve({ first, afterReturn: await iterator.next() })
+      })()
+    }))
+    server.handleMessage({ t: 'stream-open', id: 7, endpoint: 'job/attach', payload: {} })
+    await vi.waitFor(() => { expect(frames).toContainEqual({ t: 'stream-item', id: 7, value: 'ready' }) })
+    server.handleMessage({ t: 'stream-uplink-item', id: 7, value: 'one' })
+    server.handleMessage({ t: 'stream-uplink-item', id: 7, value: 'dropped' })
+    await expect(outcome.promise).resolves.toEqual({
+      first: { value: 'one', done: false },
+      afterReturn: { value: undefined, done: true },
+    })
+    await vi.waitFor(() => { expect(frames).toContainEqual({ t: 'stream-end', id: 7 }) })
+  })
+
+  it('ends a pending uplink read when the page aborts the stream', async () => {
+    const { server } = harness()
+    const read = Promise.withResolvers<unknown>()
+    const opened = Promise.withResolvers<undefined>()
+    server.serve(seams(async (_endpoint, _payload, uplink, signal) => {
+      uplink[Symbol.asyncIterator]().next().then(read.resolve, read.resolve)
+      opened.resolve(undefined)
+      return (async function *(): AsyncGenerator {
+        await new Promise<void>((resolve) => {
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+      })()
+    }))
+    server.handleMessage({ t: 'stream-open', id: 8, endpoint: 'job/attach', payload: {} })
+    await opened.promise
+    server.handleMessage({ t: 'abort', id: 8 })
+    await expect(read.promise).resolves.toEqual({ value: undefined, done: true })
+  })
+
+  it('fails a stream whose Host reads the uplink twice concurrently', async () => {
+    const { server, frames } = harness()
+    server.serve(seams(async (_endpoint, _payload, uplink) => {
+      const iterator = uplink[Symbol.asyncIterator]()
+      void iterator.next()
+      await iterator.next()
+      return (async function *(): AsyncGenerator {})()
+    }))
+    server.handleMessage({ t: 'stream-open', id: 9, endpoint: 'job/attach', payload: {} })
+    await vi.waitFor(() => {
+      expect(frames).toEqual([{
+        t: 'stream-error',
+        id: 9,
+        failure: {
+          kind: 'remote',
+          code: 'fixture-stream-failed',
+          message: 'webworker tunnel: stream uplink has one pending read',
+          details: { fixture: true },
+        },
+      }])
+    })
+  })
+
   it('cancels one logical stream without emitting a terminal frame', async () => {
     const { server, frames } = harness()
     const opened = Promise.withResolvers<AbortSignal>()
     const stopped = Promise.withResolvers<undefined>()
-    server.serve(seams(async (_endpoint, _payload, signal) => {
+    server.serve(seams(async (_endpoint, _payload, _uplink, signal) => {
       opened.resolve(signal)
       return (async function *(): AsyncGenerator {
         yield 'ready'
diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
index df7a9d8900..6fe1e49f41 100644
--- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts
@@ -345,6 +345,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         description: 'Connect a Workspace and open its Session unless a later navigation supersedes it.',
         parameters: [{ name: 'workspaceId', description: 'target Workspace.' }, { name: 'beforeOpen', description: 'optional synchronous preparation for the selected Session, skipped after supersession.' }],
         returns: 'completion; a superseded request may create a Session but does not open it.',
+        throws: ['on failure; a refused creation is also shown through the Workspace notice unless a later navigation or disposal superseded the request.'],
       },
       {
         signature: 'forkSession(sessionId: SessionId): Promise<void>',
@@ -360,7 +361,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'startSession(workspaceId?: WorkspaceId): void',
-        description: 'Start a New Session flow and navigate to its Session.',
+        description: 'Start a New Session flow and navigate to its Session; a creation the Host refuses is shown through the Workspace notice and leaves the selection as it was.',
         parameters: [{ name: 'workspaceId', description: 'explicit target; absent inherits the current or most recent Workspace.' }],
       },
       {
@@ -515,7 +516,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ClientConnectionRpc',
-    declaration: 'export interface ClientConnectionRpc {\n    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<ConnectionRpcResult<unknown>>;\n    readonly open?: (channel: string, endpoint: string, payload: unknown, signal: AbortSignal) => AsyncIterable<unknown>;\n}',
+    declaration: 'export interface ClientConnectionRpc {\n    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<ConnectionRpcResult<unknown>>;\n    readonly open?: (channel: string, endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>) => AsyncIterable<unknown>;\n}',
   },
   {
     name: 'ClientRemote',
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index 76a69a3cdf..af3043fd78 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -176,7 +176,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n      { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:227',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:243',
   },
   {
     key: 'conversation.chat.commandview',
@@ -224,7 +224,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n      { name: \'conversation.chat.commandview\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:215',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:231',
   },
   {
     key: 'conversation.chat.node',
@@ -293,7 +293,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n      { name: \'conversation.chat.node\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:196',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:212',
   },
   {
     key: 'conversation.chat.turnTail',
@@ -354,7 +354,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n      { name: \'conversation.chat.turnTail\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:221',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:237',
   },
   {
     key: 'conversation.composer',
@@ -406,7 +406,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer\', () => ctx.slots.register(\n      { name: \'conversation.composer\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:183',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:187',
   },
   {
     key: 'conversation.composer.bar',
@@ -445,7 +445,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer.bar\', () => ctx.slots.register(\n      { name: \'conversation.composer.bar\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:201',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:207',
   },
   {
     key: 'conversation.composer.dock',
@@ -501,7 +501,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer.dock\', () => ctx.slots.register(\n      { name: \'conversation.composer.dock\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:195',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:199',
   },
   {
     key: 'conversation.header',
@@ -536,7 +536,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.header\', () => ctx.slots.register(\n      { name: \'conversation.header\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:135',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:139',
   },
   {
     key: 'conversation.header.leading',
@@ -565,7 +565,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.header.leading\', () => ctx.slots.register(\n      { name: \'conversation.header.leading\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:164',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:168',
   },
   {
     key: 'conversation.hero.agentPreset',
@@ -602,7 +602,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.agentPreset\', () => ctx.slots.register(\n      { name: \'conversation.hero.agentPreset\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:189',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:193',
   },
   {
     key: 'conversation.hero.brand.mark',
@@ -631,7 +631,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.brand.mark\', () => ctx.slots.register(\n      { name: \'conversation.hero.brand.mark\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:187',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:191',
   },
   {
     key: 'conversation.hero.workspace',
@@ -664,7 +664,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.workspace\', () => ctx.slots.register(\n      { name: \'conversation.hero.workspace\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:185',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:189',
   },
   {
     key: 'conversation.hero.workspace.directoryFlow',
@@ -698,6 +698,45 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.workspace.directoryFlow\', () => ctx.slots.register(\n      { name: \'conversation.hero.workspace.directoryFlow\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
     source: 'packages/client/ui-workspace/src/client/contract/slots.ts:99',
   },
+  {
+    key: 'conversation.input.activity',
+    kind: 'single',
+    scope: 'session',
+    summary: 'Compact action after the model selector; it can expand across the toolbar while retaining the editor and submit action.',
+    doc: 'Compact action after the model selector; it can expand across the toolbar while retaining the editor and submit action.',
+    registerOptions: [],
+    ownerProps: [
+      '/** A toolbar activity hides ordinary accessory controls while expanded; its occupant must release expansion on unmount. */\nexport interface InputActivityOwnerProps extends InputControlOwnerProps {\n  /** @param active - whether the occupant needs the toolbar width before the submit action. */\n  onActiveChange: (active: boolean) => void\n}',
+    ],
+    ownerPropsReferences: [
+      'InputControlOwnerProps',
+    ],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'usePanelInfo: UsePanelInfo',
+      'useSessions: UseSessions',
+      'useSessionStatus: UseSessionStatus',
+      'useSessionRetainInfo: UseSessionRetainInfo',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: '',
+    hookContext: '',
+    slotInject: '',
+    declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted',
+    occupants: [],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.activity\', () => ctx.slots.register(\n      { name: \'conversation.input.activity\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:205',
+  },
   {
     key: 'conversation.input.attachments',
     kind: 'single',
@@ -706,7 +745,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     doc: 'Optional draft-attachment rail and drop target.',
     registerOptions: [],
     ownerProps: [
-      '/** Input state handed to the optional attachment presentation plugin. */\nexport interface ComposerAttachmentsOwnerProps {\n  /** Browser-owned draft attachments in input order. */\n  attachments: readonly ComposerAttachment[]\n  /** Whether a document-level file drop may add attachments now. */\n  canAcceptDrop: boolean\n  /** Add one dropped batch through the composer\'s validation path. */\n  onAddFiles: (files: readonly File[]) => void\n  /** Remove one draft attachment through the Conversation service. */\n  onRemoveAttachment: (id: DraftAttachmentId) => void\n  /** Current per-draft upload states for file-kind attachments. */\n  uploads: DraftFileUploads\n  /** Restart one failed file upload. */\n  onRetryFile: (id: DraftAttachmentId) => void\n  /** Display-ready limits for the drop invitation. */\n  dropLimits?: { readonly count: number; readonly size: string } | undefined\n}',
+      '/** Input state handed to the optional attachment presentation plugin. */\nexport interface ComposerAttachmentsOwnerProps {\n  /** Browser-owned draft attachments in input order. */\n  attachments: readonly ComposerAttachment[]\n  /** Whether a document-level file drop may add attachments now. */\n  canAcceptDrop: boolean\n  /**\n   * Add one dropped batch through the composer\'s validation path.\n   * @param files - dropped, pasted, or picked browser files in source order.\n   * @param directories - members of `files` the drop source identified as directories.\n   */\n  onAddFiles: (files: readonly File[], directories?: ReadonlySet<File>) => void\n  /** Remove one draft attachment through the Conversation service. */\n  onRemoveAttachment: (id: DraftAttachmentId) => void\n  /** Current per-draft upload states for file-kind attachments. */\n  uploads: DraftFileUploads\n  /** Restart one failed file upload. */\n  onRetryFile: (id: DraftAttachmentId) => void\n  /** Display-ready limits for the drop invitation. */\n  dropLimits?: { readonly count: number; readonly size: string } | undefined\n}',
     ],
     ownerPropsReferences: [
       'ComposerAttachment',
@@ -737,7 +776,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.attachments\', () => ctx.slots.register(\n      { name: \'conversation.input.attachments\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:203',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:209',
   },
   {
     key: 'conversation.input.dock',
@@ -800,7 +839,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.dock\', () => ctx.slots.register(\n      { name: \'conversation.input.dock\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:191',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:195',
   },
   {
     key: 'conversation.input.left',
@@ -854,7 +893,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.left\', () => ctx.slots.register(\n      { name: \'conversation.input.left\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:197',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:201',
   },
   {
     key: 'conversation.input.model',
@@ -893,7 +932,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.model\', () => ctx.slots.register(\n      { name: \'conversation.input.model\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:213',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:219',
   },
   {
     key: 'conversation.input.overlay',
@@ -951,7 +990,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.overlay\', () => ctx.slots.register(\n      { name: \'conversation.input.overlay\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:193',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:197',
   },
   {
     key: 'conversation.input.permission',
@@ -990,7 +1029,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.permission\', () => ctx.slots.register(\n      { name: \'conversation.input.permission\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:211',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:217',
   },
   {
     key: 'conversation.input.plan',
@@ -1029,7 +1068,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.plan\', () => ctx.slots.register(\n      { name: \'conversation.input.plan\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:209',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:215',
   },
   {
     key: 'conversation.input.right',
@@ -1083,7 +1122,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.right\', () => ctx.slots.register(\n      { name: \'conversation.input.right\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:199',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:203',
   },
   {
     key: 'conversation.message.images',
@@ -1126,7 +1165,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.message.images\', () => ctx.slots.register(\n      { name: \'conversation.message.images\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-chat/src/client/contract/slots.ts:209',
+    source: 'packages/client/ui-chat/src/client/contract/slots.ts:225',
   },
   {
     key: 'conversation.plan-review.actions',
@@ -1221,7 +1260,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session\', () => ctx.slots.register(\n      { name: \'conversation.session\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:129',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:133',
   },
   {
     key: 'conversation.session.header',
@@ -1258,7 +1297,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header\', () => ctx.slots.register(\n      { name: \'conversation.session.header\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:137',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:141',
   },
   {
     key: 'conversation.session.header.actions',
@@ -1315,11 +1354,12 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
       'client-ui-agent-preset AgentPresetLabel id \'agent-preset\'',
       'client-ui-jobs JobListAction id \'job-list\'',
       'client-ui-schedule ScheduleCatalogAction id \'schedule-catalog\'',
+      'client-ui-subagent SubagentCatalogAction id \'subagent-catalog\'',
       'experimental-client-ui-agent-team TeamAction id \'agent-team\'',
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.actions\', () => ctx.slots.register(\n      { name: \'conversation.session.header.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:152',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:156',
   },
   {
     key: 'conversation.session.header.corner',
@@ -1358,7 +1398,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.corner\', () => ctx.slots.register(\n      { name: \'conversation.session.header.corner\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:175',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:179',
   },
   {
     key: 'conversation.session.header.lineage',
@@ -1399,7 +1439,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.lineage\', () => ctx.slots.register(\n      { name: \'conversation.session.header.lineage\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:146',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:150',
   },
   {
     key: 'conversation.session.header.utilities',
@@ -1458,7 +1498,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.utilities\', () => ctx.slots.register(\n      { name: \'conversation.session.header.utilities\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:158',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:162',
   },
   {
     key: 'conversation.trajectory.images',
@@ -1562,7 +1602,126 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.view\', () => ctx.slots.register(\n      { name: \'conversation.view\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:181',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:185',
+  },
+  {
+    key: 'deliverables.file.actions',
+    kind: 'list',
+    scope: 'session',
+    summary: 'Open one file through its authorized Session event coordinates.',
+    doc: 'Open one file through its authorized Session event coordinates.',
+    registerOptions: [
+      {
+        name: 'id',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key. Use an id of your own: a fresh id is added beside the shipped entries, while reusing a shipped id puts you in THAT cell and replaces it. Owners that filter by id address you by it.',
+      },
+      {
+        name: 'order',
+        requirement: 'optional',
+        type: 'number',
+        doc: 'Position among the entries, ascending (default 0).',
+      },
+      {
+        name: 'label',
+        requirement: 'optional',
+        type: 'string | (() => string)',
+        doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
+      },
+    ],
+    ownerProps: [
+      '/** Native file action selected by an explicit user gesture. */\nexport type PresentedAction = \'open\' | \'reveal\'',
+      '/** Failure feedback for the shared native opening control. */\nexport type PresentedOpenFailure = \'openError\' | \'revealError\' | null',
+    ],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'usePanelInfo: UsePanelInfo',
+      'useSessions: UseSessions',
+      'useSessionStatus: UseSessionStatus',
+      'useSessionRetainInfo: UseSessionRetainInfo',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: '',
+    hookContext: '',
+    slotInject: '',
+    declaredBy: 'an entry in \'conversation.chat.turnTail\' (client-ui-deliverables), so it exists while that entry is mounted',
+    occupants: [
+      'client-ui-open-in-app FileRouteAction id \'open-in-app\'',
+    ],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'deliverables.file.actions\', () => ctx.slots.register(\n      { name: \'deliverables.file.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-deliverables/src/client/file-actions.ts:8',
+  },
+  {
+    key: 'deliverables.review.file.actions',
+    kind: 'list',
+    scope: 'session',
+    summary: 'The same file actions owned by a changed-file review tab.',
+    doc: 'The same file actions owned by a changed-file review tab.',
+    registerOptions: [
+      {
+        name: 'id',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key. Use an id of your own: a fresh id is added beside the shipped entries, while reusing a shipped id puts you in THAT cell and replaces it. Owners that filter by id address you by it.',
+      },
+      {
+        name: 'order',
+        requirement: 'optional',
+        type: 'number',
+        doc: 'Position among the entries, ascending (default 0).',
+      },
+      {
+        name: 'label',
+        requirement: 'optional',
+        type: 'string | (() => string)',
+        doc: 'Display text where the owner projects one (nav rows, tabs). A thunk is re-read on every projection, so localized text follows the active locale without re-registering.',
+      },
+    ],
+    ownerProps: [
+      '/** Slot contract table. Owners extend via declaration merging; entries are {@link SlotEntryDef}. */\nexport interface SlotMap {}',
+    ],
+    ownerPropsReferences: [
+      'SlotEntryDef',
+    ],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'usePanelInfo: UsePanelInfo',
+      'useSessions: UseSessions',
+      'useSessionStatus: UseSessionStatus',
+      'useSessionRetainInfo: UseSessionRetainInfo',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: '',
+    hookContext: '',
+    slotInject: '',
+    declaredBy: 'an entry in \'sidebar.right.pane.tab\' (client-ui-deliverables), so it exists while that entry is mounted',
+    occupants: [
+      'client-ui-open-in-app FileRouteAction id \'open-in-app\'',
+    ],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'deliverables.review.file.actions\', () => ctx.slots.register(\n      { name: \'deliverables.review.file.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-deliverables/src/client/file-actions.ts:21',
   },
   {
     key: 'main',
@@ -1634,7 +1793,43 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'main.conversation\', () => ctx.slots.register(\n      { name: \'main.conversation\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:127',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:131',
+  },
+  {
+    key: 'plugins.bundle.activation',
+    kind: 'keyed',
+    scope: 'root',
+    summary: 'Optional guidance after the user enables a bundle from the list, keyed by npm package name.',
+    doc: 'Optional guidance after the user enables a bundle from the list, keyed by npm package name.',
+    registerOptions: [
+      {
+        name: 'key',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key: the entry renders where the owner dispatches this exact key. Registering an already-occupied key replaces that occupant.',
+      },
+    ],
+    ownerProps: [
+      '/** One user-requested bundle activation and navigation to its configuration page. */\nexport interface PluginActivationOwnerProps {\n  readonly packageName: string\n  /** Dismiss guidance for this activation. */\n  readonly onDismiss: () => void\n  /** Dismiss guidance and open this bundle\'s detail page. */\n  readonly onOpenDetails: () => void\n}',
+    ],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'usePanelInfo: UsePanelInfo',
+      'useSessions: UseSessions',
+      'useSessionStatus: UseSessionStatus',
+      'useSessionRetainInfo: UseSessionRetainInfo',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+    ],
+    keyDomain: 'open: any string the owner dispatches (no compile-time key set), none are taken yet',
+    hookContext: '',
+    slotInject: '',
+    declaredBy: 'an entry in \'main\' (client-ui-plugin-manager), so it exists while that entry is mounted',
+    occupants: [],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'plugins.bundle.activation\', () => ctx.slots.register(\n      { name: \'plugins.bundle.activation\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:34',
   },
   {
     key: 'plugins.bundle.config',
@@ -1670,7 +1865,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'plugins.bundle.config\', () => ctx.slots.register(\n      { name: \'plugins.bundle.config\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:39',
+    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:50',
   },
   {
     key: 'plugins.item',
@@ -1723,7 +1918,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'plugins.item\', () => ctx.slots.register(\n      { name: \'plugins.item\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:33',
+    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:44',
   },
   {
     key: 'plugins.row.config',
@@ -1759,7 +1954,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'plugins.row.config\', () => ctx.slots.register(\n      { name: \'plugins.row.config\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:47',
+    source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:58',
   },
   {
     key: 'rightbar',
@@ -1801,8 +1996,11 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     registerOptions: [],
     ownerProps: [
       '/** Right column owner share: resolved normal geometry and opening eligibility. */\nexport interface RightbarOwnerProps {\n  /** Resolved normal panel width in px, not the saved preference; zero if it cannot fit. */\n  width: number\n  /** Current frame width in px. */\n  viewportWidth: number\n  /**\n   * Whether a normal right panel can retain 300px beside a 400px center.\n   * Before a narrow opening, includes the space from collapsing the left sidebar.\n   */\n  canShow: boolean\n}',
+      '/** Identity of one open tab; distinct copies of one content share `contentId`, never `TabId`. */\nexport type TabId = Branded<\'TabId\'>',
+    ],
+    ownerPropsReferences: [
+      'Branded',
     ],
-    ownerPropsReferences: [],
     standardProps: [
       'useResource: UseResource',
       'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
@@ -1988,11 +2186,13 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     declaredBy: 'an entry in \'settings.section\' (client-ui-settings-general), so it exists while that entry is mounted',
     occupants: [
       'client-locale LanguageRow id \'language\'',
+      'client-ui-chat LinkOpeningRow id \'link-opening\'',
       'client-ui-chat PerformanceUsageRow id \'performance-usage\'',
       'client-ui-chat TranscriptViewRow id \'transcript-view\'',
       'client-ui-conversation EnterBehaviorRow id \'composer-enter\'',
       'client-ui-permission-presets PermissionRow id \'permission\'',
       'client-ui-settings-general DeveloperToolsRow id \'developer-tools\'',
+      'client-ui-settings-general CurrentVersionRow id \'current-version\'',
       'client-ui-theme AppearanceRow id \'appearance\'',
       'client-ui-theme FontSizeRow id \'font-size\'',
     ],
@@ -2659,7 +2859,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.pane.tab\', () => ctx.slots.register(\n      { name: \'sidebar.right.pane.tab\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:50',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:58',
   },
   {
     key: 'sidebar.right.pane.tab.title',
@@ -2708,7 +2908,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.pane.tab.title\', () => ctx.slots.register(\n      { name: \'sidebar.right.pane.tab.title\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:64',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:72',
   },
   {
     key: 'sidebar.right.tab.document',
@@ -3012,7 +3212,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.guide\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.guide\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:75',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:83',
   },
   {
     key: 'sidebar.right.tab.guide.entry',
@@ -3058,7 +3258,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.guide.entry\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.guide.entry\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:82',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:90',
   },
   {
     key: 'sidebar.right.tab.menu.item',
@@ -3116,7 +3316,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.menu.item\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.menu.item\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:94',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:102',
   },
   {
     key: 'sidebar.settings',
diff --git a/packages/extensions/tool-cordis/README.i18n.yaml b/packages/extensions/tool-cordis/README.i18n.yaml
index d9eef3eede..3f3feb821d 100644
--- a/packages/extensions/tool-cordis/README.i18n.yaml
+++ b/packages/extensions/tool-cordis/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/extensions/tool-cordis/README.md
-README.md: a0152cf3dbdd08599ba431113123c6aaf097723d
-README.zh.md: cde328fce54b4c18f57b7a044e6afc24215417dd
+README.md: 4e7efefd21e3b7cf40e8ba5fe2291d220dfd796f
+README.zh.md: 76331c25f0996c053b39e5b227a50afae84e6bb4
diff --git a/packages/extensions/tool-cordis/README.md b/packages/extensions/tool-cordis/README.md
index a0152cf3db..4e7efefd21 100644
--- a/packages/extensions/tool-cordis/README.md
+++ b/packages/extensions/tool-cordis/README.md
@@ -25,7 +25,7 @@ Inspect Host and Client runtime APIs before writing plugin code. Creator mode pr
 <a id="use-this-package"></a>
 ## Use this package
 
-Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-tool-cordis` alongside the host runner that provides `cordisInspect`. Call `cordis_inspect_list` to discover providers, then `cordis_inspect_query` for a provider's exact methods and types. Use [Plugin Manager](../../boot/plugin-manager/README.md) to install bundles containing plugin code or MCP configuration.
+Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-tool-cordis/host` once in the host composition beside the host runner that provides `cordisInspect`, and `@deepseek-ai/dsh-tool-cordis` in each agent preset that exposes the tools; a preset row alone registers no Host providers. Call `cordis_inspect_list` to discover providers, then `cordis_inspect_query` for a provider's exact methods and types. Use [Plugin Manager](../../boot/plugin-manager/README.md) to install bundles containing plugin code or MCP configuration.
 
 -----
 
@@ -35,7 +35,7 @@ Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-t
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-Host providers combine generated Service/Event catalogs and the requesting agent's tool registry. Client providers synchronize their manifests through the existing inspection registry and answer queries from a connected page. The tool plugin owns its registrations through Cordis effects; disposal removes both tools and prompt contributions. No invariant companion is published because inspection reads its providers directly and maintains no independent runtime projection.
+Host providers combine generated Service/Event catalogs and the requesting agent's tool registry. Client providers synchronize their manifests through the existing inspection registry and answer queries from a connected page. The host entry owns the Host provider registrations and the preset row owns the two tools, each through Cordis effects; the registry rejects a duplicate provider id, which is why the providers register once per process rather than per preset. No invariant companion is published because inspection reads its providers directly and maintains no independent runtime projection.
 
 </details>
 
@@ -54,15 +54,15 @@ Host providers combine generated Service/Event catalogs and the requesting agent
 
 #### What the model sees
 
-The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) describes two read-only inspection tools. The [prompt](src/prompt.ts) directs persistent changes through Plugin Manager and describes MCP setup. Creator visual requests default to an installed UI plugin displayed in the current Web page; the development skill covers Client packaging and slot registration. Query results contain the requested API declarations or live tool schemas.
+The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) describes two read-only inspection tools. The plugin contributes no system prompt section: the tool descriptions state when to call each tool and that queries never invoke business methods. In the `cordis` preset, the first-turn skill catalog carries the descriptions of the two shipped skills, which route plugin, MCP, composition, and destination-less visual requests to the skill covering Plugin Manager, MCP setup, Client packaging, and slot registration. Query results contain the requested API declarations or live tool schemas.
 
 #### Token effect
 
-Both tool schemas and the guidance section enter model requests while this plugin is visible. Query results append to the transcript; exact queries avoid loading unrelated declarations.
+Only the two tool schemas enter model requests while this plugin is visible. Query results append to the transcript; exact queries avoid loading unrelated declarations.
 
 #### KV Cache effect
 
-Unchanged schemas and guidance remain prefix-stable. Query results append to history; enabling other plugins can change subsequent tool schemas.
+Unchanged tool schemas remain prefix-stable. Query results append to history; enabling other plugins can change subsequent tool schemas.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/extensions/tool-cordis/README.zh.md b/packages/extensions/tool-cordis/README.zh.md
index cde328fce5..76331c25f0 100644
--- a/packages/extensions/tool-cordis/README.zh.md
+++ b/packages/extensions/tool-cordis/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-创造模式包含这组工具。其他组合需要同时挂载 `@deepseek-ai/dsh-tool-cordis` 和提供 `cordisInspect` 的 host runner。调用 `cordis_inspect_list` 发现 provider，再用 `cordis_inspect_query` 查询其具体方法和类型。通过 [Plugin Manager](../../boot/plugin-manager/README.zh.md) 安装包含插件代码或 MCP 配置的组合包。
+创造模式包含这组工具。其他组合需要在宿主组合里、提供 `cordisInspect` 的 host runner 旁挂载一次 `@deepseek-ai/dsh-tool-cordis/host`，并在每个要暴露这些工具的 agent preset 里挂载 `@deepseek-ai/dsh-tool-cordis`；仅有 preset 行不会注册任何 Host provider。调用 `cordis_inspect_list` 发现 provider，再用 `cordis_inspect_query` 查询其具体方法和类型。通过 [Plugin Manager](../../boot/plugin-manager/README.zh.md) 安装包含插件代码或 MCP 配置的组合包。
 
 -----
 
@@ -35,7 +35,7 @@ kind: "package-reference"
 <details>
 <summary>实现细节 — 点击展开</summary>
 
-Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注册表。Client provider 通过现有检查注册表同步清单，并从已连接页面回答查询。工具插件通过 Cordis effect 持有注册；释放时移除工具和提示词贡献。检查直接读取 provider，不维护独立运行时投影，因此不发布不变式配套插件。
+Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注册表。Client provider 通过现有检查注册表同步清单，并从已连接页面回答查询。宿主入口持有 Host provider 的注册，preset 行持有两个工具，都通过 Cordis effect；注册表拒绝重复的 provider id，所以 provider 按进程注册一次而不是按 preset 注册。检查直接读取 provider，不维护独立运行时投影，因此不发布不变式配套插件。
 
 </details>
 
@@ -54,15 +54,15 @@ Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注
 
 #### 模型所见
 
-[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis) 描述两个只读检查工具。[提示词](src/prompt.ts) 指引模型通过 Plugin Manager 进行持久化变更并说明 MCP 设置方式。创造模式的视觉请求默认通过已安装的 UI 插件显示在当前 Web 页面；开发技能说明 Client 打包和 slot 注册方法。查询结果包含所请求的 API 声明或当前工具 schema。
+[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis) 描述两个只读检查工具。插件不贡献 system prompt 段落：工具描述已说明何时调用每个工具以及查询不会调用业务方法。在 `cordis` preset 中，首轮 skill catalog 携带两个随附技能的描述，把插件、MCP、组合编辑和未指定去向的视觉请求路由到覆盖 Plugin Manager、MCP 设置、Client 打包和 slot 注册的技能。查询结果包含所请求的 API 声明或当前工具 schema。
 
 #### Token 影响
 
-插件可见时，两个工具 schema 和指导段落进入模型请求。查询结果追加到转录中；精确查询避免加载无关声明。
+插件可见时，只有两个工具 schema 进入模型请求。查询结果追加到转录中；精确查询避免加载无关声明。
 
 #### KV Cache 影响
 
-未改变的 schema 和指导保持前缀稳定。查询结果追加到历史中；启用其他插件可能改变后续工具 schema。
+未改变的工具 schema 保持前缀稳定。查询结果追加到历史中；启用其他插件可能改变后续工具 schema。
 
 ## 已知限制与待办
 
diff --git a/packages/extensions/tool-cordis/package.json b/packages/extensions/tool-cordis/package.json
index 8e9d109d8b..b844de74e3 100644
--- a/packages/extensions/tool-cordis/package.json
+++ b/packages/extensions/tool-cordis/package.json
@@ -18,18 +18,22 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./host": {
+      "types": "./lib/types/host.d.ts",
+      "default": "./lib/types/host.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-cordis-host-runner": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^"
   },
diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts
index eed58061e6..ddf1e301c6 100644
--- a/packages/extensions/tool-cordis/src/api-catalog.ts
+++ b/packages/extensions/tool-cordis/src/api-catalog.ts
@@ -735,8 +735,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'connection',
-    summary: 'Host `ctx.connection` shape consumed by transport-independent adapters.',
-    description: 'Host `ctx.connection` shape consumed by transport-independent adapters.',
+    summary: 'Host `ctx.connection` members consumed by transport-independent adapters.',
+    description: 'Host `ctx.connection` members consumed by transport-independent adapters.',
     methods: [
       {
         signature: 'readonly rpc: HostConnectionRpc',
@@ -748,6 +748,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         description: 'Exact Fetch routes for streaming or browser-native responses.',
         parameters: [],
       },
+      {
+        signature: 'readonly operator: PeerScope',
+        description: 'The operator Peer every admitted request speaks for; its scope lives as long as Connection.',
+        parameters: [],
+      },
       {
         signature: 'createSharedFetchHandler(channel: \'/api\'): ConnectionFetchHandler',
         description: 'Compose exact Fetch routes and the shared-channel RPC interceptor.',
@@ -760,6 +765,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [{ name: 'request', description: 'request headers from the HTTP or upgrade request.' }],
         returns: 'rejection status, or undefined when the route may accept the request.',
       },
+      {
+        signature: 'admit(request: ConnectionTrustRequest): PeerAdmission',
+        description: 'Admit one request: it passes requestRejection and speaks for the operator, or it is refused with that status.',
+        parameters: [{ name: 'request', description: 'request headers from the HTTP or upgrade request.' }],
+        returns: 'the operator Peer, or the rejection status.',
+      },
       {
         signature: 'authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean',
         description: 'Authenticate one frontend index request, owning a token redirect or 401.',
@@ -976,7 +987,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     description: 'Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.',
     methods: [
       {
-        signature: 'abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>',
+        signature: 'watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>',
         description: 'Observe one file or a directory\'s direct entries in this provider\'s execution world.',
         parameters: [{ name: 'target', description: 'resolved file or directory, including an absent path to observe for creation.' }, { name: 'changed', description: 'invalidation callback; errors can be reported during or after initialization.' }, { name: 'signal', description: 'cancels watcher initialization; the caller closes an initialized watcher.' }],
         returns: 'a promise resolving once observation is active, with an asynchronous close function.',
@@ -1203,57 +1214,75 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     ],
   },
   {
-    key: 'jobs',
-    summary: 'Abstract background job registry.',
-    description: 'Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- 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. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.\n- Owned-job access is fenced by the owner\'s session id. Ids are predictable, so authorization — not secrecy — is the boundary.\n- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.\n- start refuses work while no attached job 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.',
+    key: 'jobController',
+    summary: 'Host service backing the generated `ctx.remote.job` namespace.',
+    description: 'Host service backing the generated `ctx.remote.job` namespace.',
     methods: [
       {
-        signature: 'abstract start(spec: JobStart): JobId',
-        description: 'Preflight access, validation, owner cleanup, and implementation-owned admission before starting and atomically registering work. Any preflight rejection leaves no job id or execution resource. A throwing starter leaves nothing registered; after it returns, registration cannot fail. Settlement records the outcome, notifies listeners, and releases waiters.',
-        parameters: [{ name: 'spec', description: 'job identity, owner, and synchronous starter.' }],
+        signature: '@Remote({ mode: \'stream\' }) list(request: JobListRequest, signal: AbortSignal): AsyncIterable<JobListFrame>',
+        description: 'Stream the jobs one session can see — its own plus every unowned job — as whole-set frames: one on open, then one after each coalesced burst of lifecycle commits. The stream has no natural end; the carrier closes it.',
+        parameters: [{ name: 'request', description: 'the session whose visible set to mirror.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }],
+        returns: 'the roster frames.',
+      },
+      {
+        signature: '@Remote({ mode: \'stream\' }) follow(request: JobFollowRequest, signal: AbortSignal): AsyncIterable<JobFollowFrame>',
+        description: 'Stream one job\'s retained output from an absolute byte offset, then its terminal projection once settled and drained. Non-consuming: the model-facing cursor and notice state never observe these reads. The request\'s session is the fenced read\'s caller; the registry rejects a job the session cannot see and an unknown job.',
+        parameters: [{ name: 'request', description: 'target job, owning session, and optional resume offset.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }],
+        returns: 'anchor, coalesced output frames, and the terminal status.',
+      },
+    ],
+  },
+  {
+    key: 'jobs',
+    summary: 'Abstract background job registry.',
+    description: 'Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- 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. Such settlements announce `cause: \'teardown\'`, because a job whose owner is being destroyed has no reader left.\n- Owned-job access is fenced by the owner\'s session id. Ids are predictable, so authorization — not secrecy — is the boundary.\n- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter, so a consumer that claims a settlement while waiting always claims before the event.\n- start refuses work while no attached job 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 event delivery under `{ owners: \'scope\' }` — 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.\n- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model\'s consuming cursor and observers\' absolute offsets read the same bytes and never disturb each other.\n- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle.',
+    methods: [
+      {
+        signature: 'abstract readonly events: JobEvents',
+        description: 'Lifecycle and output events, filtered per subscription.',
+        parameters: [],
+      },
+      {
+        signature: 'abstract start(spec: JobSpec): JobId',
+        description: 'Preflight access, validation, owner cleanup, and implementation-owned admission before starting and atomically registering work. Any preflight rejection leaves no job id or execution resource. A throwing starter leaves nothing registered; after it returns, registration cannot fail.',
+        parameters: [{ name: 'spec', description: 'job identity, owner, output sources, and synchronous starter.' }],
         returns: 'the registry-issued `<kind>-N` id.',
       },
       {
-        signature: 'abstract list(caller?: Agent): JobSnapshot[]',
-        description: 'List caller-owned and unowned jobs in registration order without exposing another session\'s labels.',
-        parameters: [{ name: 'caller', description: 'reading agent; a non-agent caller sees only unowned jobs.' }],
-        returns: 'fresh snapshots.',
+        signature: 'abstract list(caller?: SessionId): JobView[]',
+        description: 'List caller-owned and unowned jobs in registration order.',
+        parameters: [{ name: 'caller', description: 'reading session; omission sees only unowned jobs.' }],
+        returns: 'fresh projections.',
       },
       {
-        signature: 'abstract get(id: JobId, caller?: Agent): JobSnapshot',
-        description: 'Return a non-consuming snapshot without changing its read cursor or notice state. Throws for an unknown or foreign job.',
-        parameters: [{ name: 'id', description: 'job to look up.' }, { name: 'caller', description: 'reading agent checked against the owner.' }],
-        returns: 'a fresh snapshot.',
+        signature: 'abstract get(id: JobId, caller?: SessionId): JobView',
+        description: 'Project one job without changing its cursor. Throws for an unknown or foreign job.',
+        parameters: [{ name: 'id', description: 'job to look up.' }, { name: 'caller', description: 'reading session checked against the owner.' }],
+        returns: 'a fresh projection.',
       },
       {
-        signature: 'abstract read(id: JobId, caller?: Agent): JobRead',
-        description: 'Read the next stream delta, or the idempotent final output after settlement. A terminal read marks the job reported. Throws for an unknown or foreign job.',
-        parameters: [{ name: 'id', description: 'job to read.' }, { name: 'caller', description: 'reading agent checked against the owner.' }],
-        returns: 'output text and the post-read snapshot.',
+        signature: 'abstract read(id: JobId, caller?: SessionId): JobRead',
+        description: 'Consume the ring from the model cursor and advance it to the current total. After settlement the first read also carries the producer\'s result. Throws for an unknown or foreign job.',
+        parameters: [{ name: 'id', description: 'job to read.' }, { name: 'caller', description: 'reading session checked against the owner.' }],
+        returns: 'the chunks since the cursor, the lossy flag, the result once, and the post-read projection.',
       },
       {
-        signature: 'abstract kill(id: JobId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
-        description: 'Request cancellation, then mark the job stopping and reported. A producer throw propagates without changing job state. Throws for an unknown or foreign job.',
-        parameters: [{ name: 'id', description: 'job to cancel.' }, { name: 'caller', description: 'killing agent checked against the owner.' }, { name: 'reason', description: 'logged reason forwarded to the producer.' }],
+        signature: 'abstract readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead',
+        description: 'Read retained ring output without moving the model cursor. Resume with a previous read\'s `next`; an offset inside a retained chunk returns the whole chunk (its `at` may precede `from`). Throws for a negative or non-integer offset, or an unknown or foreign job.',
+        parameters: [{ name: 'id', description: 'job to read.' }, { name: 'from', description: 'absolute byte offset to read from (0 for the retained head).' }, { name: 'caller', description: 'reading session checked against the owner.' }],
+        returns: 'retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.',
+      },
+      {
+        signature: 'abstract kill(id: JobId, caller?: SessionId, reason?: string): \'requested\' | \'already-finished\'',
+        description: 'Request cancellation, then mark the job stopping. A producer throw propagates without changing job state. A supplied reason is merged into terminal `detail` when the job settles `killed`. Throws for an unknown or foreign job.',
+        parameters: [{ name: 'id', description: 'job to cancel.' }, { name: 'caller', description: 'killing session checked against the owner.' }, { name: 'reason', description: 'cancellation reason forwarded verbatim to the producer.' }],
         returns: '`requested` for live work, otherwise `already-finished`.',
       },
       {
-        signature: 'abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>',
-        description: 'Wait for settlement or timeout without cancelling the job. Caller abort rejects only while the job is live; after settlement the terminal snapshot wins so a notice suppressed for this waiter is still delivered. Throws for invalid, unknown, or foreign input.',
-        parameters: [{ name: 'id', description: 'job to wait for.' }, { name: 'timeoutMs', description: 'positive finite wait bound in milliseconds.' }, { name: 'caller', description: 'waiting agent checked against the owner.' }, { name: 'signal', description: 'optional cancellation of the wait itself.' }],
-        returns: 'snapshot at settlement or timeout.',
-      },
-      {
-        signature: 'abstract onJobDone(listener: JobDoneListener): () => void',
-        description: 'Register an effect-scoped completion listener. It receives the settlements of the owners its registering context\'s scope covers; each listener is contained; returned promises are observed but not awaited. No listener runs after service disposal.',
-        parameters: [{ name: 'listener', description: 'receives each terminal snapshot and its exact owner.' }],
-        returns: 'disposer that unregisters the listener.',
-      },
-      {
-        signature: 'abstract onJobsChanged(listener: JobsChangedListener): () => void',
-        description: '/** Register an effect-scoped observer of visible-set changes. It fires after every commit that changes what list returns for that owner — registration, every stopping transition (including the one teardown performs before it awaits a slow producer), settlement, owner-disposal removal, and the emptying that service disposal commits — so an observer re-reads rather than accumulating deltas.\n\nDelivery is owner-relative on the same terms as onJobDone: an observer registered from an unscoped context — a host composition\'s own carrier — sees every owner, while one registered under an agent composition\'s scope sees exactly the agents composed under it.\n\nThis is not a superset of onJobDone: that one delivers the terminal record under first-wins semantics a job controller couples to notice delivery, while this one carries no delivery meaning and marks nothing reported. Listeners are contained and never awaited.',
-        parameters: [{ name: 'listener', description: 'receives the owner whose visible set changed, or `undefined` when an unowned job changed and every caller\'s set did.' }],
-        returns: 'disposer that unregisters the listener.',
+        signature: 'abstract wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView>',
+        description: 'Wait for settlement or timeout without cancelling the job. Caller abort rejects only while the job is live; after settlement the terminal projection wins. Rejects for an invalid timeout or an unknown or foreign job.',
+        parameters: [{ name: 'id', description: 'job to wait for.' }, { name: 'timeoutMs', description: 'positive finite wait bound in milliseconds.' }, { name: 'caller', description: 'waiting session checked against the owner.' }, { name: 'signal', description: 'optional cancellation of the wait itself.' }],
+        returns: 'projection at settlement or timeout.',
       },
       {
         signature: 'abstract attachController(name: string): () => void',
@@ -1744,6 +1773,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'confirmation after the native opener accepts the path.',
         throws: ['RemoteError when the request is invalid, has no verified Host mapping, is cancelled, or the opener fails.'],
       },
+      {
+        signature: '@Remote(\'workspacePathApplications\') async workspacePathApplications( request: { readonly path: string }, signal: AbortSignal, ): Promise<readonly SessionWorkspacePathApplication[]>',
+        description: 'Query current file handlers on the serving desktop without activating an Agent.',
+        parameters: [{ name: 'request', description: 'file path in Host filesystem syntax.' }, { name: 'signal', description: 'caller lifetime, propagated to filesystem and desktop queries.' }],
+        returns: 'OS application names, icons, and default selection; empty when desktop opening is unavailable.',
+        throws: ['RemoteError when the path is invalid, the query is cancelled, or native discovery fails.'],
+      },
       {
         signature: '@Remote(\'rename\') rename(request: SessionRenameRequest): Promise<SessionRenameValue>',
         description: 'Rename one Session after explicitly resuming it.',
@@ -1837,6 +1873,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     summary: 'Durable append-only session storage addressed through per-session handles.',
     description: 'Durable append-only session storage addressed through per-session handles.\n\nStorage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` — per handle or service-wide — is the durability barrier.\n\nVisibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.\n\nFreshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.',
     methods: [
+      {
+        signature: 'readonly identity: symbol = Symbol(\'sessionPersistence\')',
+        description: 'Process-local instance identity, stable through Context proxies and distinct after service replacement.',
+        parameters: [],
+      },
       {
         signature: 'abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>',
         description: 'Create a new stored session and take its write ownership.',
@@ -3068,7 +3109,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     description: 'Resolve strict generated definitions or conservative SRC markers against current Cordis Services and Typert providers.',
     methods: [
       {
-        signature: 'readonly wireStream: TypertGatewayWireStream = { open: (endpoint, payload, signal) => this.openWireStream(endpoint, payload, signal), failure: error => rpcError(error), }',
+        signature: 'readonly wireStream: TypertGatewayWireStream = { open: (endpoint, payload, uplink, peer, signal) => this.openWireStream(endpoint, payload, uplink, peer, signal, new AbortController()), failure: error => rpcError(error), }',
         description: 'Carrier adapter shared by the WebSocket mux and local Host transports.',
         parameters: [],
       },
@@ -3088,7 +3129,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       {
         signature: 'async stream(request: InvokeRemoteRequest): Promise<AsyncIterable<unknown>>',
         description: 'Open one live stream Remote method without assuming a physical carrier.',
-        parameters: [{ name: 'request', description: 'decoded endpoint and named wire arguments.' }],
+        parameters: [{ name: 'request', description: 'decoded endpoint, named wire arguments, and the Client uplink when the carrier has one.' }],
         returns: 'a cancellation-aware iterable over the business results.',
       },
     ],
@@ -3250,6 +3291,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [{ name: 'request', description: 'directory path to register.' }],
         returns: 'the Workspace and whether this call created it.',
       },
+      {
+        signature: '@Remote(\'initializeDefault\') async initializeDefault(request: WorkspaceInitializeDefaultRequest, signal: AbortSignal): Promise<WorkspaceValue | undefined>',
+        description: 'Initialize or reuse the default Workspace during first-use startup.',
+        parameters: [{ name: 'request', description: 'initial directory name and title; never rename an existing default.' }, { name: 'signal', description: 'caller lifetime; cancels native directory lookup.' }],
+        returns: 'the durable Workspace, or undefined when first-use initialization is ineligible; creates no Session or message.',
+      },
       {
         signature: '@Remote(\'rename\') rename(request: WorkspaceRenameRequest): Promise<WorkspaceValue>',
         description: 'Rename one Workspace to a unique non-blank title.',
@@ -3318,22 +3365,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         returns: 'the page, the file\'s version at the stat before it, and whether it reaches the last line.',
       },
       {
-        signature: '@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal, ): Promise<WorkspaceFileBytes>',
-        description: 'Read one byte window of a regular file readable by the filesystem backend: raw bytes, no text decoding and no binary rejection.',
-        parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'absolute path or path relative to the workspace root; files outside it are allowed.' }, { name: 'range', description: 'the byte window; omitted fields take the window defaults.' }, { name: 'signal', description: 'caller cancellation.' }],
-        returns: 'the window in base64, the file\'s version and size at the stat before it, and whether it reaches the last byte.',
-      },
-      {
-        signature: '@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileBytes>',
-        description: 'Read a complete regular file as bytes, subject to the configured full-file cap.',
-        parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'absolute or workspace-relative file path.' }, { name: 'signal', description: 'caller cancellation.' }],
-        returns: 'one complete base64 window with offset zero and eof true; oversized files fail with too-large.',
-      },
-      {
-        signature: '@Remote async readRelated( workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal, ): Promise<WorkspaceFileBytes>',
-        description: 'Read a complete file relative to another file\'s directory, including outside the workspace.',
-        parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'base file, absolute or workspace-relative.' }, { name: 'relativePath', description: 'relative filesystem path, not a URL or absolute path.' }, { name: 'signal', description: 'caller cancellation.' }],
-        returns: 'the complete related file using the ordinary file-size and access checks.',
+        signature: '@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise<WorkspaceFileBytes>',
+        description: 'Read a complete regular file or one byte range without text decoding.',
+        parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'target path, absolute or workspace-relative; relative to the base file\'s directory when provided.' }, { name: 'options', description: 'optional base file and range; without a range the complete-file cap applies.' }, { name: 'signal', description: 'caller cancellation.' }],
+        returns: 'native bytes with the file\'s version and size at the preceding stat, byte offset, and EOF marker.',
       },
       {
         signature: '@Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>',
@@ -3367,6 +3402,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         parameters: [{ name: 'path', description: 'Existing directory to own, in a fully qualified path spelling.' }, { name: 'title', description: 'Display title used only when a new record is created.' }],
         returns: 'the existing or newly durable workspace.',
       },
+      {
+        signature: 'initializeDefault(resolveDirectory: () => Promise<{ path: string; title: string }>): Promise<Workspace | undefined>',
+        description: 'Initialize the default Workspace only while both the registry and Session history are empty. Repeated requests reuse its durable identity; deleting that registration permanently disables automatic creation.',
+        parameters: [{ name: 'resolveDirectory', description: 'resolve the absolute directory and initial title; called only for eligible creation, inside the registry mutation queue. Missing directories are created recursively before registration. After resolution, caller cancellation does not roll back creation or registration.' }],
+        returns: 'the initialized Workspace, or undefined when automatic creation is ineligible.',
+      },
       {
         signature: 'get(id: WorkspaceId): Workspace | undefined',
         description: 'Look up a workspace by id.',
@@ -4399,6 +4440,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ConnectionRequestRejection',
     declaration: 'export type ConnectionRequestRejection = 401 | 403 | undefined;',
   },
+  {
+    name: 'ConnectionRpcAttachment',
+    declaration: 'export interface ConnectionRpcAttachment {\n    readonly path: readonly (string | number)[];\n    readonly bytes: Uint8Array;\n}',
+  },
   {
     name: 'ConnectionRpcEndpointMatcher',
     declaration: 'export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean;',
@@ -4409,7 +4454,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ConnectionRpcHandler',
-    declaration: 'export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcResult<unknown>>;',
+    declaration: 'export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal, peer: PeerScope) => Promise<ConnectionRpcHandlerResult>;',
+  },
+  {
+    name: 'ConnectionRpcHandlerResult',
+    declaration: 'export type ConnectionRpcHandlerResult = {\n    readonly ok: true;\n    readonly value: unknown;\n    readonly attachments?: readonly ConnectionRpcAttachment[];\n} | {\n    readonly ok: false;\n    readonly error: ConnectionRpcFailure;\n};',
   },
   {
     name: 'ConnectionRpcResult',
@@ -4925,7 +4974,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InvocationDescriptor',
-    declaration: 'export interface InvocationDescriptor {\n    readonly id: string;\n    readonly service: string;\n    readonly namespace: string;\n    readonly method: string;\n    readonly implementation?: string;\n    readonly mode?: \'stream\';\n    readonly invocation: {\n        readonly kind: \'direct\';\n    } | {\n        readonly kind: \'context\';\n        readonly context: string;\n        readonly wire: string;\n        readonly codec: TypertCodec;\n    };\n    readonly scope?: {\n        readonly context: string;\n        readonly wire: string;\n    };\n    readonly parameters: readonly InvocationParameterDescriptor[];\n    readonly cancellation?: {\n        readonly parameter: \'signal\';\n    };\n    readonly result: TypertCodec;\n    readonly sourceLocation?: InvocationSourceLocation;\n}',
+    declaration: 'export interface InvocationDescriptor {\n    readonly id: string;\n    readonly service: string;\n    readonly namespace: string;\n    readonly method: string;\n    readonly implementation?: string;\n    readonly mode?: \'stream\';\n    readonly invocation: {\n        readonly kind: \'direct\';\n    } | {\n        readonly kind: \'context\';\n        readonly context: string;\n        readonly wire: string;\n        readonly codec: TypertCodec;\n    };\n    readonly scope?: {\n        readonly context: string;\n        readonly wire: string;\n    };\n    readonly parameters: readonly InvocationParameterDescriptor[];\n    readonly uplink?: {\n        readonly codec: TypertCodec;\n    };\n    readonly cancellation?: {\n        readonly parameter: \'signal\';\n    };\n    readonly result: TypertCodec;\n    readonly sourceLocation?: InvocationSourceLocation;\n}',
   },
   {
     name: 'InvocationParameterDescriptor',
@@ -4937,15 +4986,51 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'InvokeRemoteRequest',
-    declaration: 'export interface InvokeRemoteRequest {\n    readonly namespace: string;\n    readonly method: string;\n    readonly args: Readonly<Record<string, unknown>>;\n    readonly signal?: AbortSignal;\n}',
+    declaration: 'export interface InvokeRemoteRequest {\n    readonly namespace: string;\n    readonly method: string;\n    readonly args: Readonly<Record<string, unknown>>;\n    readonly uplink?: AsyncIterable<unknown>;\n    readonly peer?: PeerScope;\n    readonly signal?: AbortSignal;\n}',
   },
   {
-    name: 'JobDoneListener',
-    declaration: 'export type JobDoneListener = (snapshot: JobSnapshot, owner: Agent | undefined) => void | PromiseLike<void>;',
+    name: 'JobAppendOptions',
+    declaration: 'export interface JobAppendOptions {\n    channel?: JobChannel;\n    gapBefore?: true;\n}',
+  },
+  {
+    name: 'JobChannel',
+    declaration: 'export type JobChannel = \'stdout\' | \'stderr\' | \'log\';',
+  },
+  {
+    name: 'JobChunk',
+    declaration: 'export interface JobChunk {\n    readonly at: number;\n    readonly text: string;\n    readonly channel?: JobChannel;\n    readonly gapBefore?: true;\n}',
+  },
+  {
+    name: 'JobEvent',
+    declaration: 'export type JobEvent = {\n    readonly type: \'registered\' | \'progress\' | \'stopping\' | \'removed\';\n    readonly job: JobView;\n} | {\n    readonly type: \'settled\';\n    readonly job: JobView;\n    readonly cause: JobSettleCause;\n} | {\n    readonly type: \'output\';\n    readonly id: JobId;\n    readonly owner?: SessionId;\n    readonly total: number;\n};',
+  },
+  {
+    name: 'JobEventFilter',
+    declaration: 'export type JobEventFilter = {\n    readonly owner: SessionId;\n} | {\n    readonly owners: \'all\' | \'scope\';\n};',
+  },
+  {
+    name: 'JobEventListener',
+    declaration: 'export type JobEventListener = (event: JobEvent) => void;',
+  },
+  {
+    name: 'JobEvents',
+    declaration: 'export interface JobEvents {\n    subscribe(filter: JobEventFilter, listener: JobEventListener): () => void;\n}',
+  },
+  {
+    name: 'JobFollowFrame',
+    declaration: 'export type JobFollowFrame = {\n    readonly type: \'opened\';\n    readonly job: JobView;\n    readonly from: number;\n} | {\n    readonly type: \'output\';\n    readonly chunks: readonly JobChunk[];\n    readonly next: number;\n    readonly lossy?: true;\n} | {\n    readonly type: \'status\';\n    readonly job: JobView;\n};',
+  },
+  {
+    name: 'JobFollowRequest',
+    declaration: 'export interface JobFollowRequest {\n    readonly sessionId?: SessionId;\n    readonly jobId: JobId;\n    readonly from?: number;\n}',
+  },
+  {
+    name: 'JobHandle',
+    declaration: 'export interface JobHandle {\n    readonly id: JobId;\n    append(text: string, options?: JobAppendOptions): void;\n    updateProgress(line: string): void;\n}',
   },
   {
     name: 'JobHooks',
-    declaration: 'export interface JobHooks {\n    cancel(reason?: string): void;\n    done: Promise<JobOutcome>;\n    readOutput?(): string;\n}',
+    declaration: 'export interface JobHooks {\n    cancel(reason?: string): void;\n    done: Promise<JobOutcome>;\n}',
   },
   {
     name: 'JobId',
@@ -4959,30 +5044,50 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'JobKindMap',
     declaration: 'export interface JobKindMap {\n    bash: \'bash\';\n    subagent: \'subagent\';\n}',
   },
+  {
+    name: 'JobListFrame',
+    declaration: 'export interface JobListFrame {\n    readonly type: \'rows\';\n    readonly jobs: readonly JobView[];\n}',
+  },
+  {
+    name: 'JobListRequest',
+    declaration: 'export interface JobListRequest {\n    readonly sessionId: SessionId;\n}',
+  },
   {
     name: 'JobOutcome',
-    declaration: 'export interface JobOutcome {\n    status: \'completed\' | \'killed\' | \'failed\';\n    detail?: string;\n    output?: string;\n}',
+    declaration: 'export interface JobOutcome {\n    status: \'completed\' | \'killed\' | \'failed\';\n    detail?: string;\n    result?: string;\n}',
+  },
+  {
+    name: 'JobOutputRead',
+    declaration: 'export interface JobOutputRead {\n    chunks: readonly JobChunk[];\n    next: number;\n    lossy: boolean;\n}',
+  },
+  {
+    name: 'JobOutputSource',
+    declaration: 'export interface JobOutputSource {\n    channel?: JobChannel;\n    read(fromByte: number): JobSourceRead;\n}',
   },
   {
     name: 'JobRead',
-    declaration: 'export interface JobRead {\n    text: string;\n    snapshot: JobSnapshot;\n}',
+    declaration: 'export interface JobRead {\n    chunks: readonly JobChunk[];\n    lossy: boolean;\n    result?: string;\n    job: JobView;\n}',
   },
   {
-    name: 'JobsChangedListener',
-    declaration: 'export type JobsChangedListener = (owner: Agent | undefined) => void;',
+    name: 'JobSettleCause',
+    declaration: 'export type JobSettleCause = \'producer\' | \'kill\' | \'teardown\';',
   },
   {
-    name: 'JobSnapshot',
-    declaration: 'export interface JobSnapshot {\n    id: JobId;\n    kind: JobKind;\n    label: string;\n    outputLimitBytes?: number;\n    ownerSession?: SessionId;\n    status: JobStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
+    name: 'JobSourceRead',
+    declaration: 'export interface JobSourceRead {\n    text: string;\n    nextOffset: number;\n    lossy: boolean;\n    spillPath?: string;\n}',
   },
   {
-    name: 'JobStart',
-    declaration: 'export interface JobStart {\n    kind: JobKind;\n    label: string;\n    outputLimitBytes?: number;\n    owner?: Agent;\n    run(): JobHooks;\n}',
+    name: 'JobSpec',
+    declaration: 'export interface JobSpec {\n    kind: JobKind;\n    label: string;\n    owner?: SessionId;\n    outputLimitBytes?: number;\n    output?: readonly JobOutputSource[];\n    run(job: JobHandle): JobHooks;\n}',
   },
   {
     name: 'JobStatus',
     declaration: 'export type JobStatus = \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';',
   },
+  {
+    name: 'JobView',
+    declaration: 'export interface JobView {\n    readonly id: JobId;\n    readonly kind: string;\n    readonly label: string;\n    readonly owner?: SessionId;\n    readonly outputLimitBytes?: number;\n    readonly status: JobStatus;\n    readonly progress?: string;\n    readonly detail?: string;\n    readonly startedAt: number;\n    readonly finishedAt?: number;\n    readonly output: {\n        readonly total: number;\n        readonly earliest: number;\n        readonly spillPaths?: readonly string[];\n    };\n}',
+  },
   {
     name: 'JsonSchemaNode',
     declaration: 'export interface JsonSchemaNode {\n    type?: JsonSchemaType;\n    oneOf?: JsonSchemaNode[];\n    properties?: Record<string, JsonSchemaNode>;\n    required?: string[];\n    additionalProperties?: boolean;\n    items?: JsonSchemaNode;\n    enum?: JsonSchemaScalar[];\n    const?: JsonSchemaScalar;\n    description?: string;\n    title?: string;\n    default?: JsonValue;\n    examples?: JsonValue;\n}',
@@ -5271,6 +5376,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ModelReasoningEffort',
     declaration: 'export interface ModelReasoningEffort {\n    readonly id: string;\n    readonly name: string;\n    readonly description?: string;\n}',
   },
+  {
+    name: 'NativeFileApplication',
+    declaration: 'export interface NativeFileApplication {\n    readonly id: string;\n    readonly name: string;\n    readonly default: boolean;\n    readonly icon: string | null;\n}',
+  },
   {
     name: 'ObjectJsonSchema',
     declaration: 'export type ObjectJsonSchema = JsonSchemaNode & {\n    type: \'object\';\n};',
@@ -5315,6 +5424,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'PackageResult',
     declaration: 'export interface PackageResult {\n    exitCode: number;\n    output: string;\n    truncated: boolean;\n    logPath: string;\n    kind?: PluginInstallFailureKind;\n}',
   },
+  {
+    name: 'PeerAdmission',
+    declaration: 'export type PeerAdmission = {\n    readonly peer: PeerScope;\n} | {\n    readonly rejection: 401 | 403;\n};',
+  },
+  {
+    name: 'PeerId',
+    declaration: 'export type PeerId = Branded<\'PeerId\'>;',
+  },
+  {
+    name: 'PeerScope',
+    declaration: 'export interface PeerScope {\n    readonly id: PeerId;\n    readonly ctx: Context;\n    dispose(): Promise<void>;\n}',
+  },
   {
     name: 'PermissionCatalog',
     declaration: 'export interface PermissionCatalog {\n    options: PresetOption[];\n}',
@@ -5365,7 +5486,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'PluginLocalizedMeta',
-    declaration: 'export interface PluginLocalizedMeta {\n    readonly title?: LocalizedText;\n    readonly description?: LocalizedText;\n    readonly error?: string;\n}',
+    declaration: 'export interface PluginLocalizedMeta {\n    readonly title?: LocalizedText;\n    readonly description?: LocalizedText;\n    readonly icon?: string;\n    readonly error?: string;\n}',
   },
   {
     name: 'PluginRegistries',
@@ -5577,7 +5698,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'RenderedDocumentBytes',
-    declaration: 'export interface RenderedDocumentBytes extends WorkspaceFileBytes {\n    readonly missingFonts: string[];\n    readonly generation: OfficeToPdfGeneration;\n}',
+    declaration: 'export interface RenderedDocumentBytes extends Omit<WorkspaceFileBytes, \'data\'> {\n    readonly data: string;\n    readonly missingFonts: string[];\n    readonly generation: OfficeToPdfGeneration;\n}',
   },
   {
     name: 'ReplayEnvelope',
@@ -5745,7 +5866,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionAddress',
-    declaration: 'export type SessionAddress = {\n    readonly kind: \'session\';\n    readonly sessionId: SessionId;\n} | {\n    readonly kind: \'subagent\';\n    readonly parentSessionId: SessionId;\n    readonly childSessionId: SessionId;\n    readonly mode: \'one-shot\' | \'continuable\';\n};',
+    declaration: 'export type SessionAddress = {\n    readonly kind: \'session\';\n    readonly sessionId: SessionId;\n} | {\n    readonly kind: \'subagent\';\n    readonly parentSessionId: SessionId;\n    readonly childSessionId: SessionId;\n    readonly mode: \'one-shot\' | \'continuable\' | \'unknown\';\n};',
   },
   {
     name: 'SessionAssistantStreamAttempt',
@@ -5781,11 +5902,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionControlBaseline',
-    declaration: 'export interface SessionControlBaseline {\n    readonly jobs: Readonly<Record<SessionId, readonly SessionJob[]>>;\n    readonly projections: Readonly<Record<SessionId, SessionProjectionBaseline>>;\n}',
+    declaration: 'export interface SessionControlBaseline {\n    readonly projections: Readonly<Record<SessionId, SessionProjectionBaseline>>;\n}',
   },
   {
     name: 'SessionControlFrame',
-    declaration: 'export type SessionControlFrame = {\n    readonly type: \'baseline\';\n    readonly value: SessionControlBaseline;\n} | {\n    readonly type: \'jobs\';\n    readonly sessionId: SessionId;\n    readonly jobs: readonly SessionJob[];\n} | ({\n    readonly type: \'projection\';\n} & SessionProjectionUpdate);',
+    declaration: 'export type SessionControlFrame = {\n    readonly type: \'baseline\';\n    readonly value: SessionControlBaseline;\n} | ({\n    readonly type: \'projection\';\n} & SessionProjectionUpdate);',
   },
   {
     name: 'SessionCreateRequest',
@@ -5935,10 +6056,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionInspection',
     declaration: 'export interface SessionInspection extends SessionStorageMetadata {\n    readonly events: readonly SessionEvent[];\n}',
   },
-  {
-    name: 'SessionJob',
-    declaration: 'export interface SessionJob {\n    readonly id: JobId;\n    readonly kind: string;\n    readonly label: string;\n    readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n    readonly detail?: string;\n    readonly startedAt: number;\n    readonly finishedAt?: number;\n}',
-  },
   {
     name: 'SessionLineageNode',
     declaration: 'export interface SessionLineageNode {\n    session: SessionRecord;\n    descendants: SessionLineageNode[];\n}',
@@ -5981,7 +6098,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionOpenWorkspacePathRequest',
-    declaration: 'export interface SessionOpenWorkspacePathRequest {\n    readonly action?: \'reveal\';\n    readonly path: string;\n}',
+    declaration: 'export interface SessionOpenWorkspacePathRequest {\n    readonly action?: \'reveal\';\n    readonly application?: string;\n    readonly path: string;\n}',
   },
   {
     name: 'SessionOpenWorkspacePathValue',
@@ -6235,6 +6352,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionWireHeader',
     declaration: 'export interface SessionWireHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly isSeeded: boolean;\n    readonly origin?: \'subagent\';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}',
   },
+  {
+    name: 'SessionWorkspacePathApplication',
+    declaration: 'export type SessionWorkspacePathApplication = NativeFileApplication;',
+  },
   {
     name: 'SettingsApplies',
     declaration: 'export type SettingsApplies = \'live\' | \'restart\';',
@@ -6295,9 +6416,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ShellExecSpec',
     declaration: 'export interface ShellExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    stdoutMaxBytes: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    dshEnv?: DshEnvironment | undefined;\n    sandboxPolicy: SandboxExecutionPolicy | undefined;\n}',
   },
+  {
+    name: 'ShellObservedStreams',
+    declaration: 'export interface ShellObservedStreams {\n    stdout: SubprocessOutputReader;\n    stderr: SubprocessOutputReader;\n}',
+  },
   {
     name: 'ShellProcess',
-    declaration: 'export interface ShellProcess {\n    status: ShellProcessStatus;\n    exitCode: number | null;\n    signal: NodeJS.Signals | null;\n    readonly done: Promise<void>;\n    sandbox?: ShellSandboxInfo;\n    readOutput(): ShellProcessRead;\n    kill(): boolean;\n}',
+    declaration: 'export interface ShellProcess {\n    status: ShellProcessStatus;\n    exitCode: number | null;\n    signal: NodeJS.Signals | null;\n    readonly done: Promise<void>;\n    sandbox?: ShellSandboxInfo;\n    readOutput(): ShellProcessRead;\n    observed: ShellObservedStreams;\n    kill(): boolean;\n}',
   },
   {
     name: 'ShellProcessRead',
@@ -6429,7 +6554,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubagentCatalogEntry',
-    declaration: 'export type SubagentCatalogEntry = {\n    readonly id: SessionId;\n    readonly createdAt: number;\n} & ({\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n} | {\n    readonly mode: \'continuable\';\n    readonly label: string;\n});',
+    declaration: 'export type SubagentCatalogEntry = {\n    readonly id: SessionId;\n    readonly createdAt: number;\n} & ({\n    readonly mode: \'one-shot\';\n    readonly label?: string;\n} | {\n    readonly mode: \'continuable\';\n    readonly label: string;\n} | {\n    readonly mode: \'unknown\';\n    readonly label?: string;\n});',
   },
   {
     name: 'SubagentCatalogRow',
@@ -6905,7 +7030,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TypertCodec',
-    declaration: 'export type TypertCodec = {\n    readonly mode: \'strict\';\n    readonly typeSymbol: string;\n    readonly create: () => TypertSchema;\n} | {\n    readonly mode: \'src-json\';\n};',
+    declaration: 'export type TypertCodec = {\n    readonly mode: \'strict\';\n    readonly typeSymbol: string;\n    readonly create: () => TypertSchema;\n    readonly decode?: (value: unknown) => unknown;\n    readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown;\n} | {\n    readonly mode: \'src-json\';\n};',
   },
   {
     name: 'TypertContribution',
@@ -6933,7 +7058,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TypertGatewayWireStream',
-    declaration: 'export interface TypertGatewayWireStream {\n    readonly open: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<AsyncIterable<unknown>>;\n    readonly failure: (error: unknown) => {\n        readonly code: string;\n        readonly message: string;\n        readonly details: object;\n    };\n}',
+    declaration: 'export interface TypertGatewayWireStream {\n    readonly open: (endpoint: string, payload: unknown, uplink: AsyncIterable<unknown>, peer: PeerScope | undefined, signal: AbortSignal) => Promise<AsyncIterable<unknown>>;\n    readonly failure: (error: unknown) => {\n        readonly code: string;\n        readonly message: string;\n        readonly details: object;\n    };\n}',
   },
   {
     name: 'TypertMemberModel',
@@ -7203,6 +7328,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WorkspaceByteRange',
     declaration: 'export interface WorkspaceByteRange {\n    readonly offset?: number;\n    readonly length?: number;\n}',
   },
+  {
+    name: 'WorkspaceByteReadOptions',
+    declaration: 'export interface WorkspaceByteReadOptions {\n    readonly range?: WorkspaceByteRange;\n    readonly baseFile?: string;\n}',
+  },
   {
     name: 'WorkspaceChangedFile',
     declaration: 'export interface WorkspaceChangedFile {\n    path: string;\n    display: string;\n    added: number;\n    deleted: number;\n    binary?: true;\n    oversized?: true;\n}',
@@ -7241,7 +7370,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'WorkspaceFileBytes',
-    declaration: 'export interface WorkspaceFileBytes extends WorkspaceFileStat {\n    readonly offset: number;\n    readonly data: string;\n    readonly eof: boolean;\n}',
+    declaration: 'export interface WorkspaceFileBytes<Data extends Uint8Array = Uint8Array> extends WorkspaceFileStat {\n    readonly offset: number;\n    readonly data: Data;\n    readonly eof: boolean;\n}',
   },
   {
     name: 'WorkspaceFileChange',
@@ -7279,6 +7408,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WorkspaceFollowIncrement',
     declaration: 'export type WorkspaceFollowIncrement = {\n    readonly type: \'upsert\';\n    readonly workspace: WorkspaceView;\n} | {\n    readonly type: \'remove\';\n    readonly workspaceId: WorkspaceId;\n} | {\n    readonly type: \'order\';\n    readonly workspaceIds: readonly WorkspaceId[];\n} | {\n    readonly type: \'archived\';\n    readonly archivedSessionIds: readonly SessionId[];\n} | {\n    readonly type: \'pinned\';\n    readonly pinnedSessionIds: readonly SessionId[];\n};',
   },
+  {
+    name: 'WorkspaceInitializeDefaultRequest',
+    declaration: 'export interface WorkspaceInitializeDefaultRequest {\n    readonly directoryName: string;\n    readonly title: string;\n}',
+  },
   {
     name: 'WorkspaceInsertBeforeRequest',
     declaration: 'export interface WorkspaceInsertBeforeRequest {\n    readonly workspaceId: WorkspaceId;\n    readonly beforeWorkspaceId?: WorkspaceId;\n}',
diff --git a/packages/extensions/tool-cordis/src/host.ts b/packages/extensions/tool-cordis/src/host.ts
new file mode 100644
index 0000000000..d3c024f77e
--- /dev/null
+++ b/packages/extensions/tool-cordis/src/host.ts
@@ -0,0 +1,20 @@
+/** Host-plane registration of the first-party Cordis inspect providers. */
+import type { Context } from '@deepseek-ai/cordis'
+import { hostInspectProviders } from './providers.ts'
+
+export const name = 'cordis-inspect-providers'
+/** Required services: the Host inspect registry and the Tool registry the `Tool` provider reads. */
+export const inject = ['cordisInspect', 'tools']
+
+/**
+ * Register the Host inspect providers once per process. The registry keys
+ * providers by id and rejects a duplicate, so this row belongs to the host
+ * composition beside `cordis-host-runner`; every per-session `tool-cordis`
+ * row reads the shared set through its tools.
+ * @param ctx Host composition context.
+ */
+export function apply(ctx: Context): void {
+  for (const provider of hostInspectProviders(ctx)) {
+    ctx.effect(() => ctx.cordisInspect.register(provider), `cordis-inspect-providers: ${provider.manifest.id}`)
+  }
+}
diff --git a/packages/extensions/tool-cordis/src/index.ts b/packages/extensions/tool-cordis/src/index.ts
index 90f3401d75..d52ed7a076 100644
--- a/packages/extensions/tool-cordis/src/index.ts
+++ b/packages/extensions/tool-cordis/src/index.ts
@@ -5,25 +5,20 @@ import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 import { presentInspectListCall, presentInspectQueryCall } from './present.ts'
-import { CORDIS_SYSTEM_PROMPT } from './prompt.ts'
-import { hostInspectProviders } from './providers.ts'
 
 export const name = 'tool-cordis'
-export const inject = ['tools', 'systemPrompt', 'cordisInspect']
+export const inject = ['tools', 'cordisInspect']
 
 function requireAgent(exec: ToolExecution): Agent {
   if (exec.agent === undefined) throw new Error('Cordis inspection requires an Agent-backed session')
   return exec.agent
 }
 
-/** Register read-only runtime inspection tools.
+/** Register read-only runtime inspection tools over the Host providers that
+ * `@deepseek-ai/dsh-tool-cordis/host` registers once per process.
  * @param ctx Agent-scoped registration context.
  */
 export function apply(ctx: Context): void {
-  ctx.systemPrompt.section({ name: 'tool:cordis', order: ctx.systemPrompt.getSectionOrder('TOOL_CORDIS'), text: CORDIS_SYSTEM_PROMPT })
-  for (const provider of hostInspectProviders(ctx)) {
-    ctx.effect(() => ctx.cordisInspect.register(provider), `tool-cordis: inspect ${provider.manifest.id}`)
-  }
   ctx.tools.register(defineTool({
     name: 'cordis_inspect_list',
     description:
@@ -46,16 +41,12 @@ export function apply(ctx: Context): void {
   ctx.tools.register(defineTool({
     name: 'cordis_inspect_query',
     description:
-      'Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come '
-      + 'from cordis_inspect_list, and input must satisfy that method\'s schema. Use this Tool before writing plugin code '
+      'Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from '
+      + 'cordis_inspect_list, and input must satisfy that method\'s schema. Use this Tool before writing plugin code '
       + 'to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot '
       + 'trees and props. Host queries run locally. A Client query waits for the first valid page response and '
       + 'remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service '
-      + 'methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate '
-      + 'the compact signature directory, then query the exact service or event for its structured contract and '
-      + 'referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an '
-      + 'exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, '
-      + 'scope, and registrant.',
+      + 'methods or modify the runtime.',
     parameters: {
       platform: { type: 'string', required: true, enum: ['host', 'client'], description: 'Runtime platform that owns the Provider.' },
       provider: { type: 'string', required: true, description: 'Exact Provider ID returned by cordis_inspect_list.' },
diff --git a/packages/extensions/tool-cordis/src/prompt.ts b/packages/extensions/tool-cordis/src/prompt.ts
deleted file mode 100644
index 6f0dd7eafb..0000000000
--- a/packages/extensions/tool-cordis/src/prompt.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-/** Model guidance for read-only runtime API discovery. */
-export const CORDIS_SYSTEM_PROMPT = `# Harness runtime inspection
-
-Use cordis_inspect_list to discover Host and Client providers, then cordis_inspect_query to read exact Service, Event, Tool, Theme or Slot APIs. These tools are read-only; queries do not invoke business methods.`
diff --git a/packages/extensions/tool-cordis/tests/host.spec.ts b/packages/extensions/tool-cordis/tests/host.spec.ts
new file mode 100644
index 0000000000..8763e44c44
--- /dev/null
+++ b/packages/extensions/tool-cordis/tests/host.spec.ts
@@ -0,0 +1,35 @@
+import { Context } from '@deepseek-ai/cordis'
+import { CordisInspectRegistryService } from '@deepseek-ai/dsh-cordis-host-runner'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { describe, expect, it } from 'vitest'
+import * as CordisInspectProviders from '../src/host.ts'
+
+/**
+ * The Host inspect providers are one process-global set: the host entry
+ * registers them beside the registry, and the per-session tool rows only read
+ * them. Mounting several presets that carry `tool-cordis` over the shared
+ * registry is covered by `apps/cli/tests/web-agent-presets.e2e.ts`.
+ */
+
+async function host(): Promise<Context> {
+  const ctx = new Context()
+  // The tool registry injects `systemPrompt`; nothing under test registers a prompt section.
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(CordisInspectRegistryService)
+  return ctx
+}
+
+describe('the cordis-inspect-providers host entry', () => {
+  it('registers the first-party Host providers and withdraws them on disposal', async () => {
+    const ctx = await host()
+    const fiber = ctx.plugin(CordisInspectProviders)
+    await fiber
+
+    expect(ctx.cordisInspect.list().map(provider => provider.id)).toEqual(['Service', 'Event', 'Builtin', 'Tool'])
+
+    await fiber.dispose()
+    expect(ctx.cordisInspect.list()).toEqual([])
+  })
+})
diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts
index 6f4ebe4e50..1158a6dede 100644
--- a/packages/fs/fs/src/index.ts
+++ b/packages/fs/fs/src/index.ts
@@ -10,6 +10,7 @@
 
 import { Context, Service } from '@deepseek-ai/cordis'
 import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { FsError } from './types.ts'
 import type {
   FsDirEntry,
   FsEditOutcome,
@@ -96,7 +97,12 @@ export abstract class FileSystem extends Service {
    * @returns a promise resolving once observation is active, with an asynchronous close function.
    * @throws when the provider does not support watching or cannot initialize the watcher.
    */
-  abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>
+  watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>> {
+    void target
+    void changed
+    signal.throwIfAborted()
+    return Promise.reject(new FsError('Filesystem watching is not supported by this provider.', 'FS_IO_ERROR'))
+  }
 
   /**
    * The sandbox mode this backend enforces on mutations BY DEFAULT, or
diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts
index 41e698a70e..e3105925a5 100644
--- a/packages/fs/fs/tests/service.spec.ts
+++ b/packages/fs/fs/tests/service.spec.ts
@@ -21,7 +21,6 @@ import type {
 
 /** A minimal in-memory fake implementing the provider primitives. */
 class FakeFileSystem extends FileSystem {
-  override watch(): never { throw new Error('Fixture does not support watching') }
   files = new Map<string, string>()
 
   override async resolve(path: string): Promise<FsTarget> {
@@ -145,6 +144,14 @@ describe('FileSystem provider seam', () => {
     await expect(fs.readBytes(target, undefined, 1)).rejects.toMatchObject({ code: 'FS_TOO_LARGE' })
   })
 
+  it('rejects watching when a provider does not implement observation', async () => {
+    const ctx = new Context()
+    await ctx.plugin(FakeFileSystem)
+    const fs = ctx.fs as FakeFileSystem
+    await expect(fs.watch(await fs.resolve('a.txt'), () => {}, new AbortController().signal))
+      .rejects.toMatchObject({ code: 'FS_IO_ERROR' })
+  })
+
   it('listDir returns child entry targets without reading file content', async () => {
     const ctx = new Context()
     await ctx.plugin(FakeFileSystem)
diff --git a/packages/host/open-in-app/README.i18n.yaml b/packages/host/open-in-app/README.i18n.yaml
index a0f9b65499..6d300a6296 100644
--- a/packages/host/open-in-app/README.i18n.yaml
+++ b/packages/host/open-in-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/host/open-in-app/README.md
-README.md: 0f0c05f48469a03bc115d84e93a174fbfeba0c42
-README.zh.md: 8a46759a9cc84fdda8ce62c3f448344c86179bb8
+README.md: 39cc7b854725aab363c4c42ad1ab27f99718e75e
+README.zh.md: c47a47c43f3dcf7b842af2bf57469c7b09dc49c9
diff --git a/packages/host/open-in-app/README.md b/packages/host/open-in-app/README.md
index 0f0c05f484..39cc7b8547 100644
--- a/packages/host/open-in-app/README.md
+++ b/packages/host/open-in-app/README.md
@@ -72,6 +72,8 @@ The route paths and wire payload types are published as the browser-safe `./shar
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
 
+Linux desktop-entry fields and icons use the shared [native-command](../../util/native-command/README.md) helpers. Directory launchers come from this package’s installed application catalog; file handlers come from the operating system’s associations.
+
 <details>
 <summary>Implementation internals — click to expand</summary>
 
diff --git a/packages/host/open-in-app/README.zh.md b/packages/host/open-in-app/README.zh.md
index 8a46759a9c..c47a47c43f 100644
--- a/packages/host/open-in-app/README.zh.md
+++ b/packages/host/open-in-app/README.zh.md
@@ -72,6 +72,8 @@ kind: "package-reference"
 <a id="understand-the-implementation"></a>
 ## 理解实现
 
+Linux 桌面文件字段和图标使用共享的 [native-command](../../util/native-command/README.zh.md) 工具。目录打开器来自本包的已安装应用列表，文件打开器来自操作系统的文件关联。
+
 <details>
 <summary>实现内幕——点击展开</summary>
 
diff --git a/packages/host/open-in-app/src/icons.ts b/packages/host/open-in-app/src/icons.ts
index 6908ce795b..4b07441c8c 100644
--- a/packages/host/open-in-app/src/icons.ts
+++ b/packages/host/open-in-app/src/icons.ts
@@ -11,10 +11,11 @@
 
 import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { isAbsolute, join } from 'node:path'
+import { join } from 'node:path'
+import { desktopApplicationIcon } from '@deepseek-ai/dsh-native-command'
 import type { OpenInAppApp } from './catalog.ts'
 import {
-  findDesktopEntry, isFile, output, resolveInternals, specFor, xdgDataDirectories,
+  findDesktopEntry, output, resolveInternals, specFor, xdgDataDirectories,
   type OpenInAppInternals, type OpenInAppResolvedLaunch, type ResolvedInternals,
 } from './resolver.ts'
 
@@ -121,50 +122,6 @@ async function extractExecutableIconPng(
   }
 }
 
-/** Theme sizes searched largest-first; the button renders at 15-18 CSS px. */
-const HICOLOR_SIZES = ['512x512', '256x256', '128x128', '64x64', '48x48', '32x32'] as const
-
-/** The media type an icon file's extension names. */
-function iconContentType(path: string): OpenInAppIcon['contentType'] | null {
-  if (path.endsWith('.png')) return 'image/png'
-  if (path.endsWith('.svg')) return 'image/svg+xml'
-  return null
-}
-
-/** Read one icon file when it exists and carries a servable media type. */
-async function readIconFile(path: string): Promise<OpenInAppIcon | null> {
-  const contentType = iconContentType(path)
-  if (contentType === null || !await isFile(path)) return null
-  return { bytes: await readFile(path), contentType }
-}
-
-/**
- * Resolve a Linux icon name through the hicolor theme and pixmaps
- * directories, largest size first. The user's active icon theme is not
- * consulted (README Known Limitations): hicolor is the freedesktop fallback
- * every theme inherits from, so the stock icon is found wherever the
- * application installed one.
- */
-async function findLinuxThemeIcon(
-  name: string, dataDirs: readonly string[],
-): Promise<OpenInAppIcon | null> {
-  for (const dataDir of dataDirs) {
-    for (const size of HICOLOR_SIZES) {
-      for (const extension of ['png', 'svg'] as const) {
-        const icon = await readIconFile(join(dataDir, 'icons', 'hicolor', size, 'apps', `${name}.${extension}`))
-        if (icon !== null) return icon
-      }
-    }
-    const scalable = await readIconFile(join(dataDir, 'icons', 'hicolor', 'scalable', 'apps', `${name}.svg`))
-    if (scalable !== null) return scalable
-    for (const extension of ['png', 'svg'] as const) {
-      const pixmap = await readIconFile(join(dataDir, 'pixmaps', `${name}.${extension}`))
-      if (pixmap !== null) return pixmap
-    }
-  }
-  return null
-}
-
 /** One Linux application's icon from its desktop entry's `Icon=` key. */
 async function extractLinuxIcon(
   desktopId: string, internals: ResolvedInternals,
@@ -172,8 +129,7 @@ async function extractLinuxIcon(
   const entry = await findDesktopEntry(desktopId, internals)
   const icon = entry?.icon
   if (icon === undefined || icon === '') return null
-  if (isAbsolute(icon)) return readIconFile(icon)
-  return findLinuxThemeIcon(icon, xdgDataDirectories(internals))
+  return desktopApplicationIcon(icon, xdgDataDirectories(internals))
 }
 
 /**
diff --git a/packages/host/open-in-app/src/resolver.ts b/packages/host/open-in-app/src/resolver.ts
index 7ab964b4fd..62c6f8e4bc 100644
--- a/packages/host/open-in-app/src/resolver.ts
+++ b/packages/host/open-in-app/src/resolver.ts
@@ -17,7 +17,7 @@ import { readdir, readFile, stat } from 'node:fs/promises'
 import { homedir, platform as osPlatform } from 'node:os'
 import { dirname, isAbsolute, join } from 'node:path'
 import {
-  canOpenNativePath, openNativePath, runNativeCommand, type NativeCommandRunner,
+  canOpenNativePath, openNativePath, runNativeCommand, desktopEntryFields, desktopDataDirectories, type NativeCommandRunner,
 } from '@deepseek-ai/dsh-native-command'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import {
@@ -379,24 +379,12 @@ export interface DesktopEntry {
  * @returns the recognized fields; keys outside the entry section are ignored.
  */
 export function parseDesktopEntry(text: string): DesktopEntry {
-  let inEntry = false
-  const fields: { exec?: string; tryExec?: string; icon?: string } = {}
-  for (const line of text.split(/\r?\n/)) {
-    const trimmed = line.trim()
-    if (trimmed.startsWith('[')) {
-      inEntry = trimmed === '[Desktop Entry]'
-      continue
-    }
-    if (!inEntry) continue
-    const separator = trimmed.indexOf('=')
-    if (separator < 0) continue
-    const key = trimmed.slice(0, separator).trim()
-    const value = trimmed.slice(separator + 1).trim()
-    if (key === 'Exec') fields.exec = value
-    else if (key === 'TryExec') fields.tryExec = value
-    else if (key === 'Icon') fields.icon = value
+  const fields = desktopEntryFields(text)
+  return {
+    ...(fields.Exec === undefined ? {} : { exec: fields.Exec }),
+    ...(fields.TryExec === undefined ? {} : { tryExec: fields.TryExec }),
+    ...(fields.Icon === undefined ? {} : { icon: fields.Icon }),
   }
-  return fields
 }
 
 /**
@@ -405,9 +393,7 @@ export function parseDesktopEntry(text: string): DesktopEntry {
  * @returns the data directories, freedesktop defaults applied.
  */
 export function xdgDataDirectories(internals: ResolvedInternals): readonly string[] {
-  const dataHome = internals.env['XDG_DATA_HOME'] ?? join(internals.home, '.local', 'share')
-  const dataDirs = internals.env['XDG_DATA_DIRS'] ?? '/usr/local/share:/usr/share'
-  return [dataHome, ...dataDirs.split(':').filter(dir => dir !== '')]
+  return desktopDataDirectories(internals.home, internals.env)
 }
 
 /**
diff --git a/packages/host/plugin-inventory/tests/inventory.spec.ts b/packages/host/plugin-inventory/tests/inventory.spec.ts
index c403d6fe76..f55ca87a38 100644
--- a/packages/host/plugin-inventory/tests/inventory.spec.ts
+++ b/packages/host/plugin-inventory/tests/inventory.spec.ts
@@ -51,7 +51,7 @@ function metadataFixture(mode: 'native' | 'runtime') {
     ? join(root, 'installation', 'node_modules', 'local-plugin')
     : join(root, 'node_modules', 'local-plugin')
   const resolution: RuntimeResolution = {
-    profilesDir, profileDir, localPackageNames: [],
+    profilesDir, profileDir, localPackageNames: [], linkedRoots: [],
     entries: [{ name: 'local-plugin', packageDir: dir, version: undefined,
       declarer: join(dir, 'package.json'), scope: 'installation' }],
   }
diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml
index 96a6f4432f..3f353ad6d9 100644
--- a/packages/host/webserver/README.i18n.yaml
+++ b/packages/host/webserver/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/webserver/README.md
-README.md: df1881a3a16b69f61127956127c7806c70793f91
-README.zh.md: 1d07d43ac97c616c9b7450da71ad09cb55fa4267
+README.md: 9dd698404719eecdf9fb4c40720ccc74ab37be9d
+README.zh.md: d4701b79e432dfa3e8ba8485f8644758ec3b34d7
diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md
index df1881a3a1..9dd6984047 100644
--- a/packages/host/webserver/README.md
+++ b/packages/host/webserver/README.md
@@ -38,7 +38,7 @@ Compose the webserver as the HTTP transport of a browser-facing host, then let t
 
 `host` accepts exactly two values: `127.0.0.1` (default posture, loopback only) and `0.0.0.0` (deliberate network exposure — the server carries no TLS, authentication, or origin policy of its own). `port` 0 requests an OS-assigned port; `ctx.webServer.port` reads the listening port afterwards.
 
-Set `compression: 'gzip'` to wrap eligible socket-backed responses without changing route APIs. The client must accept gzip and the media type must be compressible; known response lengths below `compressionThresholdBytes` remain uncompressed, while unknown-length streams are eligible immediately. Existing encodings, `Cache-Control: no-transform`, range responses, SSE, ZIP, and the packaged `.gz` Worker image remain unchanged. The shipped Web bundle uses compression level 1 with a 1024-byte threshold; other compositions default to no compression.
+Set `compression: 'gzip'` to wrap eligible socket-backed responses without changing route APIs. The client must accept gzip and the media type must be compressible or `multipart/form-data`; known response lengths below `compressionThresholdBytes` remain uncompressed, while unknown-length streams are eligible immediately. Existing encodings, `Cache-Control: no-transform`, range responses, SSE, ZIP, and the packaged `.gz` Worker image remain unchanged. The shipped Web bundle uses compression level 1 with a 1024-byte threshold; other compositions default to no compression.
 
 ### Registering routes
 
diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md
index 1d07d43ac9..d4701b79e4 100644
--- a/packages/host/webserver/README.zh.md
+++ b/packages/host/webserver/README.zh.md
@@ -38,7 +38,7 @@ kind: "package-reference"
 
 `host` 只接受两个值：`127.0.0.1`（默认姿态，仅回环）与 `0.0.0.0`（有意向网络开放——服务器自身不携带 TLS、认证或来源策略）。`port` 为 0 时请求 OS 分配端口；之后用 `ctx.webServer.port` 读取正在监听的端口。
 
-设置 `compression: 'gzip'` 可以包装符合条件的 socket-backed 响应，而不改变 route API。客户端必须接受 gzip，且媒体类型必须可压缩；已知长度小于 `compressionThresholdBytes` 的响应保持未压缩，未知长度的流则立即符合条件。已有编码、`Cache-Control: no-transform`、range 响应、SSE（Server-Sent Events）、ZIP 与已打包的 `.gz` Worker image 均保持不变。随附 Web bundle 使用 level 1 与 1024 字节阈值；其他组合默认不压缩。
+设置 `compression: 'gzip'` 可以包装符合条件的 socket-backed 响应，而不改变 route API。客户端必须接受 gzip，且媒体类型必须可压缩或为 `multipart/form-data`；已知长度小于 `compressionThresholdBytes` 的响应保持未压缩，未知长度的流则立即符合条件。已有编码、`Cache-Control: no-transform`、range 响应、SSE（Server-Sent Events）、ZIP 与已打包的 `.gz` Worker image 均保持不变。随附 Web bundle 使用 level 1 与 1024 字节阈值；其他组合默认不压缩。
 
 ### 注册路由
 
diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts
index 7443d04211..5b490fc770 100644
--- a/packages/host/webserver/src/index.ts
+++ b/packages/host/webserver/src/index.ts
@@ -95,6 +95,7 @@ function createGzipMiddleware(config: ResolvedConfig): NodeMiddleware {
       if (response.getHeader('content-range') !== undefined) return false
       const contentType = response.getHeader('content-type')
       if (typeof contentType === 'string' && contentType.toLowerCase().startsWith('text/event-stream')) return false
+      if (typeof contentType === 'string' && /^multipart\/form-data(?:;|$)/i.test(contentType)) return true
       return compressionMiddleware.filter(request, response)
     },
   }) as NodeMiddleware
diff --git a/packages/jobs/jobs-local/README.i18n.yaml b/packages/jobs/jobs-local/README.i18n.yaml
index 963541f876..fa9e9e94bb 100644
--- a/packages/jobs/jobs-local/README.i18n.yaml
+++ b/packages/jobs/jobs-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/jobs/jobs-local/README.md
-README.md: 51fbffc4892f6a4781343e13863770fb4e8e8e6a
-README.zh.md: 710c02c923994df596e544345cac4cd4d0bd2809
+README.md: d141d19b06f0d329ee6a544b10f535d87086a48d
+README.zh.md: 38f8989f230fc9317fbc56d73ffcc9a8dc42db00
diff --git a/packages/jobs/jobs-local/README.md b/packages/jobs/jobs-local/README.md
index 51fbffc489..d141d19b06 100644
--- a/packages/jobs/jobs-local/README.md
+++ b/packages/jobs/jobs-local/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-jobs-local` runs background jobs inside the harness process: work keeps running while the agent moves on, and the owning agent can read, wait on, list, and cancel it, with completion delivered as an in-session notice when `dsh-tool-jobs` is also mounted. It implements the `dsh-jobs` contract with in-memory records handed out as fresh snapshots, never live state. A per-owner concurrency limit (default 10) bounds how many jobs one agent can have running or stopping at once; jobs die with the harness process and are not durable across restarts.
+`dsh-jobs-local` runs background jobs inside the harness process while the agent continues. The owning agent can read, wait on, list, and cancel its jobs; mounting `dsh-tool-jobs` also delivers completion notices in-session. Configurable concurrency and output-retention limits bound resource use. Producers can supply output for periodic reading or append it directly; users can observe retained output without consuming the agent's unread output. Jobs end when their owner or the harness shuts down.
 
 ## Table of Contents
 
@@ -33,7 +33,7 @@ Choose it when jobs should live in the harness process and die with it. Avoid it
 
 ### Minimal configuration
 
-Loading the plugin registers `ctx.jobs`; `maxConcurrentJobsPerOwner` is optional and defaults to `10`.
+Loading the plugin registers `ctx.jobs`; every field is optional.
 
 ```yaml
 - name: '@deepseek-ai/dsh-jobs-local'
@@ -42,8 +42,11 @@ Loading the plugin registers `ctx.jobs`; `maxConcurrentJobsPerOwner` is optional
 | Field | Default | Meaning |
 |---|---|---|
 | `maxConcurrentJobsPerOwner` | `10` | Maximum `running` plus `stopping` jobs per exact owner, or in the shared unowned bucket |
+| `retainBytes` | `262144` | Live ring retention per job, in UTF-8 bytes |
+| `settledRetainBytes` | `16384` | Ring retention kept after a job settles, in UTF-8 bytes; bytes the model has not read stay until its first terminal read |
+| `pumpPollMs` | `150` | Poll interval for a job's pull sources, in milliseconds |
 
-The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-jobs-local) is the exhaustive source for the accepted field.
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-jobs-local) is the exhaustive source for the accepted fields.
 
 ### What each owner gets
 
@@ -69,10 +72,11 @@ This section explains the design decisions behind the registry and points at the
 
 ### Design philosophy
 
-- **In-memory records, fresh snapshots.** `LocalJobRegistry` keeps one `TrackedJob` per job and projects a new read-only snapshot per call; callers never receive live state.
-- **Owner-relative layers, one process-wide registry.** Controllers, completion listeners, and change observers are filed into the scope that registered them (`ScopedLayers`), and reads union the global layer with the owner's scope chain — so one preset's job controls never hold `start()` open for an agent whose own composition loads none, and a settlement reaches only the listeners its owner's composition registered.
+- **In-memory records, fresh projections.** `LocalJobRegistry` keeps one `TrackedJob` per job — lifecycle state, the output ring, and the model cursor — and projects a new read-only view or chunk copy per call; callers never receive live state.
+- **Retention is bounded per ring.** Appends past the live cap drop the oldest retained chunks (a single oversized chunk keeps its UTF-8-safe tail); a reader below the retained window gets a lossy read, never an error. Settlement trims to the settled cap but never below the bytes the model cursor has not consumed, so a job that finishes before its first `job_output` hands over everything the live cap retained; that terminal read then trims to the settled cap.
+- **Owner-relative layers, one process-wide registry.** Controllers and `{ owners: 'scope' }` subscriptions are filed into the scope that registered them (`ScopedLayers`), and reads union the global layer with the owner's scope chain — so one preset's job controls never hold `start()` open for an agent whose own composition loads none, and a scoped settlement reaches only the listeners its owner's composition registered.
 - **Preflight before start.** `start()` checks controller service, spec validity, live ownership, and capacity before invoking the producer, so a rejection leaves no job id or execution resource; registration commits without a later failable step.
-- **First-wins settlement, completion last.** The earliest terminal outcome records once, releases waiters, and notifies listeners once with per-listener containment; completion is announced after the record is committed and the visible-set change published, because a reporter may open a model turn synchronously.
+- **First-wins settlement, event last.** The earliest terminal outcome records once, waits for the pump's final drain, trims the ring, releases waiters, and then delivers one `settled` event with per-listener containment, followed by the ring's final `output` signal.
 - **Teardown never deadlocks.** A throwing cancel force-fails the record and reports a possible orphan instead of stalling disposal.
 
 ### Source map
@@ -80,19 +84,22 @@ This section explains the design decisions behind the registry and points at the
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, `LocalJobRegistry`, admission, lifecycle, teardown |
-| — | No runtime invariant companion is published; `@deepseek-ai/dsh-jobs/invariant` owns per-snapshot identity, status, timestamp, and owner checks. This provider's admission decision uses private configuration and must fail before a backend starter runs; `LocalJobRegistry.start()` enforces it synchronously for current producers. Repeating an aggregate after publication would expose private configuration solely to this companion and would not verify the fail-closed pre-start guarantee. |
+| [`src/events.ts`](src/events.ts) | Scope-layered event routing: `{ owner }`, `{ owners: 'all' }`, and `{ owners: 'scope' }` subscriptions |
+| [`src/ring.ts`](src/ring.ts) | The bounded per-job output ring: append, retention trim, offset reads |
+| [`src/pump.ts`](src/pump.ts) | The registry-owned pull pump: one timer per job, final drain before settlement |
+| — | No runtime invariant companion is published; `@deepseek-ai/dsh-jobs/invariant` owns the event-protocol and event-versus-read checks. This provider's admission decision uses private configuration and must fail before a backend starter runs; `LocalJobRegistry.start()` enforces it synchronously for current producers. Repeating an aggregate after publication would expose private configuration solely to this companion and would not verify the fail-closed pre-start guarantee. |
 
 ### Scope layers
 
-`attachController`, `onJobDone`, and `onJobsChanged` register into the calling context's scope layer. The controller question (`servesOwner`) and listener delivery (`listenersFor`, `changedFor`) walk the same chain: global layer first, then each scoped layer along the owner's chain. Registrations are anonymous tokens so duplicate labels stay independently disposable.
+`attachController` and `{ owners: 'scope' }` subscriptions register into the calling context's scope layer; `{ owner }` and `{ owners: 'all' }` subscriptions are unscoped. The controller question (`servesOwner`) and scoped delivery walk the same chain: global layer first, then each scoped layer along the owner's chain. Registrations are anonymous tokens so duplicate labels stay independently disposable.
 
 ### Admission and settlement
 
-`activeJobCount` counts authoritative records per exact owner or in the shared unowned bucket. `settle` marks a job reported when waiters are pending, resolves every waiter, records the terminal snapshot, announces the visible-set change, then notifies completion listeners. Pending waits mark the job reported before listeners run so completion reporters do not duplicate notices; a teardown cancel marks it for the same reason — nothing will read a notice addressed to an owner being destroyed.
+`activeJobCount` counts authoritative records per exact owner or in the shared unowned bucket. `settle` records the terminal outcome once (merging a recorded kill reason into a `killed` detail), clears the progress line, trims the ring to the settled cap (keeping every byte the model cursor has not consumed), resolves every waiter, then emits `settled` with its cause and the ring's final `output` signal. The cause is `kill` after `JobRegistry.kill`, `teardown` after an owner or service cancel, and `producer` otherwise; `dsh-tool-jobs` uses it to skip notices nobody can read.
 
 ### Teardown
 
-Owner disposal (`disposeOwned`) cancels the owner's jobs, awaits their settlement, removes their records, and announces the removal — the one visible-set change no per-job record carries. Service disposal (`disposeAll`) closes listeners, cancels all live jobs, awaits settlement, clears the store, announces the emptying to the distinct owners, then detaches the cross-fiber owner-cleanup effects.
+Owner disposal (`disposeOwned`) cancels the owner's jobs, awaits their settlement, removes their records, and announces each removal — the one visible-set change no per-job record carries. Service disposal (`disposeAll`) cancels all live jobs, awaits settlement, removes every record (announcing each removal, so a subscriber mounted outside the service drops its rows), then detaches the cross-fiber owner-cleanup effects.
 
 </details>
 
@@ -103,7 +110,7 @@ Owner disposal (`disposeOwned`) cancels the owner's jobs, awaits their settlemen
 
 Read these pages when the package-level contract is not enough. They move from the registry contract to the model-facing controls and the design records.
 
-- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, snapshot fields, and `ctx.jobs` Cordis surface.
+- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, projection fields, and `ctx.jobs` Cordis surface.
 - [jobs group map](../README.md) — the sibling group page and its package table.
 - [Registry contract](../jobs/README.md) — the abstract `ctx.jobs` service this package implements.
 - [Model-facing job controls](../tool-jobs/README.md) — the `job_output`, `job_list`, and `job_kill` tools and completion notices.
diff --git a/packages/jobs/jobs-local/README.zh.md b/packages/jobs/jobs-local/README.zh.md
index 710c02c923..38f8989f23 100644
--- a/packages/jobs/jobs-local/README.zh.md
+++ b/packages/jobs/jobs-local/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-jobs-local` 在 harness 进程内运行后台任务：工作会在 agent（智能体）继续推进的同时保持运行，拥有它的 agent 可以读取、等待、列出和取消它；同时挂载 `dsh-tool-jobs` 时，完成以会话内通知送达。它用内存记录实现 `dsh-jobs` 约定，并且只交出全新快照，从不交出实时状态。按所有者的并发上限（默认 10）约束一个 agent 同时处于运行或停止中的任务数量；任务会随 harness 进程终止而消失，无法跨重启持久。
+`dsh-jobs-local` 在 agent（智能体）继续推进时，于 harness 进程内运行后台任务。拥有任务的 agent 可以读取、等待、列出和取消任务；同时挂载 `dsh-tool-jobs` 时，还会收到会话内完成通知。可配置的并发与输出保留上限约束资源使用。生产方可以提供供定期读取的输出，也可以直接追加；用户可以观察保留的输出，而不消耗 agent 尚未读取的内容。任务在拥有者或 harness 关闭时结束。
 
 ## 目录
 
@@ -33,7 +33,7 @@ kind: "package-reference"
 
 ### 最小配置
 
-加载插件即注册 `ctx.jobs`；`maxConcurrentJobsPerOwner` 可选，默认为 `10`。
+加载插件即注册 `ctx.jobs`；每个字段都是可选的。
 
 ```yaml
 - name: '@deepseek-ai/dsh-jobs-local'
@@ -42,6 +42,9 @@ kind: "package-reference"
 | 字段 | 默认值 | 含义 |
 |---|---|---|
 | `maxConcurrentJobsPerOwner` | `10` | 每个精确所有者，或共享的无主桶中，`running` 加 `stopping` 任务的最大数量 |
+| `retainBytes` | `262144` | 每个任务输出环的运行期保留量，UTF-8 字节 |
+| `settledRetainBytes` | `16384` | 任务结算后保留的环容量，UTF-8 字节；模型尚未读取的字节保留到它的首次终态读取 |
+| `pumpPollMs` | `150` | 任务拉取源的轮询间隔，毫秒 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-jobs-local)是每个受支持字段的穷尽式真源。
 
@@ -69,10 +72,11 @@ kind: "package-reference"
 
 ### 设计理念
 
-- **内存记录，全新快照。** `LocalJobRegistry` 为每个任务保存一条 `TrackedJob`，每次调用都投影出新的只读快照；调用方永远不会拿到实时状态。
-- **按所有者分层，一个进程级注册表。** 控制器、完成监听器与变更观察者归档到注册方所在的 scope（`ScopedLayers`），读取把全局层与所有者的 scope 链求并集——因此某个 preset 的任务控制绝不会为自身组合未加载任何控制器的 agent 保持 `start()` 可用，一次结算也只会抵达其所有者所属组合注册的监听器。
+- **内存记录、全新投影。** `LocalJobRegistry` 为每个任务保存一份 `TrackedJob`——生命周期状态、输出环与模型游标——每次调用都投影新的只读视图或块副本；调用方永远拿不到实时状态。
+- **环的保留量有界。** 追加超出运行期上限时丢弃最老的保留块（单个超限块保留其 UTF-8 安全尾部）；低于保留窗口的读取得到 lossy 结果而非错误。结算时裁剪到结算上限，但绝不低于模型游标尚未消费的字节数，因此在首次 `job_output` 之前结束的任务会交出运行期上限保留的全部输出；那次终态读取之后才裁剪到结算上限。
+- **按所有者分层，一个进程级注册表。** 控制器与 `{ owners: 'scope' }` 订阅归档到注册方所在的 scope（`ScopedLayers`），读取把全局层与所有者的 scope 链求并集——因此某个 preset 的任务控制绝不会为自身组合未加载任何控制器的 agent 保持 `start()` 可用，一次带 scope 的结算也只会抵达其所有者所属组合注册的监听器。
 - **启动前先预检。** `start()` 在调用生产方之前检查控制器服务、spec 有效性、仍存活的所有权与容量，因此拒绝不会留下 job id 或执行资源；注册一旦提交，后续不再有可失败步骤。
-- **结算首次优先，完成最后。** 最早的终止结果只记录一次，释放等待方，并只通知监听器一次，各监听器故障单独隔离；完成在记录提交且可见集变更发布之后才宣布，因为报告方可能同步开启一个模型轮次。
+- **结算首次优先，事件最后。** 最早的终止结果只记录一次，等待泵的最后一次排干，裁剪环，释放等待方，然后投递一次带逐监听器隔离的 `settled` 事件，再跟上环的最终 `output` 信号。
 - **销毁永不死锁。** 抛出的取消会强制失败记录并报告可能的孤立工作，而不是让释放停滞。
 
 ### 源码地图
@@ -80,19 +84,22 @@ kind: "package-reference"
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：`Config` schema、`LocalJobRegistry`、准入、生命周期、销毁 |
-| — | 不发布运行时不变式伴生入口；快照的标识、状态、时间戳与所有者检查位于 `@deepseek-ai/dsh-jobs/invariant`。此提供方的准入决策使用私有配置，并且必须在后端启动器运行前失败；当前生产方由 `LocalJobRegistry.start()` 同步执行该决策。发布后再重复聚合只会向 companion 暴露私有配置，也无法验证失败发生在启动前。 |
+| [`src/events.ts`](src/events.ts) | 按 scope 分层的事件路由：`{ owner }`、`{ owners: 'all' }` 与 `{ owners: 'scope' }` 订阅 |
+| [`src/ring.ts`](src/ring.ts) | 每个任务的有界输出环：追加、保留裁剪、按偏移读取 |
+| [`src/pump.ts`](src/pump.ts) | 注册表拥有的拉取泵：每个任务一个定时器，结算前最后一次排干 |
+| — | 不发布运行时不变式伴生入口；事件协议与事件对读取的检查位于 `@deepseek-ai/dsh-jobs/invariant`。此提供方的准入决策使用私有配置，并且必须在后端启动器运行前失败；当前生产方由 `LocalJobRegistry.start()` 同步执行该决策。发布后再重复聚合只会向 companion 暴露私有配置，也无法验证失败发生在启动前。 |
 
 ### scope 分层
 
-`attachController`、`onJobDone` 与 `onJobsChanged` 注册到调用上下文所在的 scope 层。控制器问题（`servesOwner`）与监听器投递（`listenersFor`、`changedFor`）走同一条链：先是全局层，再沿所有者的链逐层。注册是无名 token，因此重复标签仍可独立释放。
+`attachController` 与 `{ owners: 'scope' }` 订阅注册到调用上下文所在的 scope 层；`{ owner }` 与 `{ owners: 'all' }` 订阅不带 scope。控制器问题（`servesOwner`）与带 scope 的投递走同一条链：先是全局层，再沿所有者的链逐层。注册是无名 token，因此重复标签仍可独立释放。
 
 ### 准入与结算
 
-`activeJobCount` 按精确所有者或共享无主桶统计权威记录。`settle` 在存在挂起等待方时把任务标为已报告，解析每个等待方，记录终止快照，宣布可见集变更，然后通知完成监听器。挂起的等待会在监听器运行前把任务标为已报告，因此完成报告方不会重复通知；销毁时的取消出于同样理由标记——面向正在被销毁的所有者的通知不会有人读到。
+`activeJobCount` 按精确所有者或共享无主桶统计权威记录。`settle` 只记录一次终止结果（把记录下来的 kill 原因合并进 `killed` 的 detail），清除进度行，把环裁剪到结算保留量（保留模型游标尚未消费的全部字节），解析每个等待方，然后发出带原因的 `settled` 与环的最终 `output` 信号。原因在 `JobRegistry.kill` 之后为 `kill`，在所有者或服务取消之后为 `teardown`，否则为 `producer`；`dsh-tool-jobs` 据此跳过没人能读的通知。
 
 ### 销毁
 
-所有者释放（`disposeOwned`）会取消该所有者的任务、等待其结算、移除其记录，并宣布移除——这是任何逐任务记录都无法表达的可见集变更。服务释放（`disposeAll`）会关闭监听器、取消所有存活任务、等待结算、清空存储、向不同的所有者宣布清空，然后分离跨 fiber 的所有者清理 effect。
+所有者释放（`disposeOwned`）会取消该所有者的任务、等待其结算、移除其记录，并逐条宣布移除——这是任何逐任务记录都无法表达的可见集变更。服务释放（`disposeAll`）会取消所有存活任务、等待结算、移除每条记录（逐条宣布移除，让挂载在服务之外的订阅者丢掉它的行），然后分离跨 fiber 的所有者清理 effect。
 
 </details>
 
@@ -103,7 +110,7 @@ kind: "package-reference"
 
 当包级约定不够用时阅读以下页面。它们从注册表约定逐步进入模型侧控制与设计记录。
 
-- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、快照字段与 `ctx.jobs` 的 Cordis 接口面。
+- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、投影字段与 `ctx.jobs` 的 Cordis 接口面。
 - [jobs 组映射](../README.zh.md)——同级组页面及其包表格。
 - [注册表约定](../jobs/README.zh.md)——本包实现的抽象 `ctx.jobs` 服务。
 - [模型侧任务控制](../tool-jobs/README.zh.md)——`job_output`、`job_list` 与 `job_kill` 工具及完成通知。
diff --git a/packages/jobs/jobs-local/src/events.ts b/packages/jobs/jobs-local/src/events.ts
new file mode 100644
index 0000000000..8c13e4dd9c
--- /dev/null
+++ b/packages/jobs/jobs-local/src/events.ts
@@ -0,0 +1,102 @@
+/**
+ * Event routing for the local registry: subscriptions file by filter, and
+ * every commit dispatches once to each matching listener with containment.
+ * @module @deepseek-ai/dsh-jobs-local/events
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope'
+import type { ScopeLayer } from '@deepseek-ai/dsh-scope'
+import type { JobEvent, JobEventFilter, JobEventListener } from '@deepseek-ai/dsh-jobs'
+
+/** One registered listener and the filter it declared. */
+interface Subscription {
+  filter: JobEventFilter
+  listener: JobEventListener
+}
+
+/**
+ * One scope's contributions: the job controllers attached from it and the
+ * `{ owners: 'scope' }` subscriptions registered there. Both tables are
+ * anonymous because a contribution is identified by its own disposer, never
+ * by a name a second registrant could shadow.
+ */
+export class JobLayer implements ScopeLayer {
+  /** Tokens of the job controllers attached from this scope. */
+  readonly controllers = new AnonymousEntries<symbol>()
+  /** The `{ owners: 'scope' }` subscriptions registered from this scope. */
+  readonly scoped = new AnonymousEntries<Subscription>()
+
+  isEmpty(): boolean {
+    return this.controllers.isEmpty() && this.scoped.isEmpty()
+  }
+}
+
+/**
+ * Routes events to subscriptions. `{ owner }` and `{ owners: 'all' }`
+ * subscriptions are evaluated against every event regardless of where they
+ * were registered; `{ owners: 'scope' }` subscriptions file into the
+ * registering context's scope layer and receive the owners composed under it
+ * — the global layer, reached from an unscoped context, receives every owner.
+ */
+export class JobEventHub {
+  private readonly unscoped = new Set<Subscription>()
+
+  /**
+   * @param layers - the scope-layer table shared with the controller handshake.
+   * @param warn - sink for a listener's contained failure.
+   */
+  constructor(
+    private readonly layers: ScopedLayers<JobLayer>,
+    private readonly warn: (message: string) => void,
+  ) {}
+
+  /**
+   * Register one listener as an effect of `ctx`.
+   * @param ctx - the subscribing context; owns the effect and, for `'scope'`, names the scope.
+   * @param filter - which owners' events to deliver.
+   * @param listener - receives each matching event.
+   * @returns disposer that unregisters the listener.
+   */
+  subscribe(ctx: Context, filter: JobEventFilter, listener: JobEventListener): () => void {
+    const subscription: Subscription = { filter, listener }
+    if ('owners' in filter && filter.owners === 'scope') {
+      return this.layers.effect(ctx, layer => layer.scoped.append(subscription), { label: 'jobs.events.subscribe()' })
+    }
+    const dispose = ctx.effect(() => {
+      this.unscoped.add(subscription)
+      return () => { this.unscoped.delete(subscription) }
+    }, 'jobs.events.subscribe()')
+    // oxlint-disable-next-line typescript/no-misused-promises -- exact synchronous disposer preserves Cordis effect identity
+    return dispose
+  }
+
+  /**
+   * Deliver one event to every matching subscription, containing each
+   * listener so an observer cannot break the commit already made.
+   * @param event - the event to deliver.
+   * @param owner - the job's exact owner, or undefined for unowned work.
+   */
+  emit(event: JobEvent, owner: Agent | undefined): void {
+    const ownerId = owner?.id
+    for (const subscription of this.unscoped) {
+      const { filter } = subscription
+      if ('owner' in filter && ownerId !== undefined && ownerId !== filter.owner) continue
+      this.deliver(subscription, event)
+    }
+    for (const subscription of this.layers.global.scoped.values()) this.deliver(subscription, event)
+    const scope = owner === undefined ? undefined : scopeOf(owner.ctx)
+    for (const layer of this.layers.chainLayers(scope)) {
+      for (const subscription of layer.scoped.values()) this.deliver(subscription, event)
+    }
+  }
+
+  private deliver(subscription: Subscription, event: JobEvent): void {
+    try {
+      subscription.listener(event)
+    } catch (error: unknown) {
+      this.warn(`jobs: event listener threw on ${event.type}: ${String(error)}`)
+    }
+  }
+}
diff --git a/packages/jobs/jobs-local/src/index.ts b/packages/jobs/jobs-local/src/index.ts
index 0e0f161eaf..54ba6905d2 100644
--- a/packages/jobs/jobs-local/src/index.ts
+++ b/packages/jobs/jobs-local/src/index.ts
@@ -1,7 +1,8 @@
 /**
  * Process-local provider for the background-job capability seam
- * (`ctx.jobs`). It keeps every record in memory and hands out fresh
- * snapshots, never live state.
+ * (`ctx.jobs`). It keeps every job — lifecycle state, the bounded output
+ * ring, and the model cursor — in memory and hands out fresh projections and
+ * chunk copies, never live state.
  *
  * Registrations outlive producer and controller fibers. Agent or service
  * disposal cancels live work and awaits compliant producers; a throwing
@@ -12,14 +13,18 @@
 import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope'
-import type { ScopeLayer } from '@deepseek-ai/dsh-scope'
+import { ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope'
+import type { SessionId } from '@deepseek-ai/dsh-session'
 import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { JobRegistry, JobId } from '@deepseek-ai/dsh-jobs'
 import type {
-  JobDoneListener, JobKind, JobOutcome, JobRead, JobSnapshot, JobStart, JobStatus,
-  JobsChangedListener,
+  JobAppendOptions, JobEvent, JobEvents, JobHandle, JobKind, JobOutcome, JobOutputRead, JobOutputSource,
+  JobRead, JobSettleCause, JobSpec, JobStatus, JobView,
 } from '@deepseek-ai/dsh-jobs'
+import { JobEventHub, JobLayer } from './events.ts'
+import { startPump } from './pump.ts'
+import type { PumpHandle } from './pump.ts'
+import { OutputRing } from './ring.ts'
 
 /** Timeout code that distinguishes a bounded wait from caller cancellation. */
 export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
@@ -27,6 +32,15 @@ export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
 /** Default maximum number of active jobs in one exact-owner bucket. */
 const DEFAULT_MAX_CONCURRENT_JOBS_PER_OWNER = 10
 
+/** Default live ring retention per job, in UTF-8 bytes. */
+const DEFAULT_RETAIN_BYTES = 256 * 1024
+
+/** Default ring retention kept after settlement, in UTF-8 bytes. */
+const DEFAULT_SETTLED_RETAIN_BYTES = 16 * 1024
+
+/** Default poll interval for pull sources, in milliseconds. */
+const DEFAULT_PUMP_POLL_MS = 150
+
 /** Configuration for the process-local job registry. */
 export interface Config {
   /**
@@ -34,9 +48,31 @@ export interface Config {
    * omission defaults to 10.
    */
   maxConcurrentJobsPerOwner?: number
+  /** Live ring retention per job in UTF-8 bytes; omission defaults to 262144. */
+  retainBytes?: number
+  /**
+   * Ring retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384.
+   * Settlement keeps every byte the model cursor has not consumed on top of
+   * this cap; the first terminal model read then trims to it.
+   */
+  settledRetainBytes?: number
+  /** Poll interval for a job's pull sources, in milliseconds; omission defaults to 150. */
+  pumpPollMs?: number
 }
 
-/** The registry's mutable per-job record (never handed out — see {@link LocalJobRegistry.snapshot}). */
+/**
+ * Producer-written state shared between the {@link JobHandle} and the
+ * registered record: the starter call writes through it before the commit,
+ * the same object serves the job for its whole life afterwards.
+ */
+interface ProducerState {
+  /** Live progress line until settlement clears it. */
+  progress: string | undefined
+  /** The committed registry record; undefined exactly during the starter call. */
+  job: TrackedJob | undefined
+}
+
+/** The registry's mutable per-job record (never handed out — see {@link LocalJobRegistry.view}). */
 interface TrackedJob {
   id: JobId
   kind: JobKind
@@ -45,21 +81,38 @@ interface TrackedJob {
   /** Exact lifecycle owner; session-id authorization is derived from it. */
   owner: Agent | undefined
   cancel: (reason?: string) => void
-  readOutput: (() => string) | undefined
   status: JobStatus
+  ring: OutputRing
+  /** The model's consuming cursor; {@link JobRegistry.readAt} never moves it. */
+  modelCursor: number
+  /** Whether the first post-settlement read already handed out `result`. */
+  resultDelivered: boolean
+  /** Producer-shared progress line and commit binding. */
+  state: ProducerState
+  /** Terminal reason; a recorded kill reason is merged in at settlement. */
   detail: string | undefined
-  output: string | undefined
+  result: string | undefined
   startedAt: number
   finishedAt: number | undefined
-  reported: boolean
-  /** Resolves once the terminal snapshot is recorded and listeners notified. */
+  /** Reason recorded by {@link JobRegistry.kill}, merged into a `killed` settlement's detail. */
+  killReason: string | undefined
+  /** Set once a kill or teardown cancel ran; settlement reports it as the cause. */
+  settleCause: JobSettleCause | undefined
+  /** Resolves once the terminal record is committed and announced. */
   settled: Promise<void>
   /** Resolver for {@link settled}, called by the first effective settlement. */
   markSettled: () => void
-  /** Live waits; settlement with a waiter marks the job reported. */
-  waiters: number
   /** Removable resolvers for live waits; timeout/abort unregister before the job settles. */
   waitResolvers: Set<() => void>
+  /** The registry-owned pump over the spec's pull sources, when it named any. */
+  pump: PumpHandle | undefined
+  /**
+   * The spill file each pull source reported on its latest read, by source
+   * index; an entry is undefined while that source keeps none. Source
+   * metadata rather than per-chunk metadata, so it survives ring eviction and
+   * follows a source that withdraws its file.
+   */
+  spillPaths: (string | undefined)[]
 }
 
 /** True for the three terminal {@link JobStatus} values. */
@@ -67,22 +120,6 @@ function isTerminal(status: JobStatus): boolean {
   return status === 'completed' || status === 'killed' || status === 'failed'
 }
 
-/**
- * One scope's contributions: the job 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 JobLayer implements ScopeLayer {
-  readonly controllers = new AnonymousEntries<symbol>()
-  readonly listeners = new AnonymousEntries<JobDoneListener>()
-  readonly changed = new AnonymousEntries<JobsChangedListener>()
-
-  isEmpty(): boolean {
-    return this.controllers.isEmpty() && this.listeners.isEmpty() && this.changed.isEmpty()
-  }
-}
-
 /**
  * The in-memory `jobs` registry. See the Service Definition contract in
  * `@deepseek-ai/dsh-jobs` for the ownership, isolation, and lifecycle
@@ -95,16 +132,38 @@ export class LocalJobRegistry extends JobRegistry {
       .min(1)
       .max(Number.MAX_SAFE_INTEGER)
       .default(DEFAULT_MAX_CONCURRENT_JOBS_PER_OWNER),
+    retainBytes: z.number()
+      .step(1)
+      .min(1)
+      .max(Number.MAX_SAFE_INTEGER)
+      .default(DEFAULT_RETAIN_BYTES),
+    settledRetainBytes: z.number()
+      .step(1)
+      .min(1)
+      .max(Number.MAX_SAFE_INTEGER)
+      .default(DEFAULT_SETTLED_RETAIN_BYTES),
+    pumpPollMs: z.number()
+      .step(1)
+      .min(1)
+      .max(Number.MAX_SAFE_INTEGER)
+      .default(DEFAULT_PUMP_POLL_MS),
   })
 
   /** Schemastery-defaulted active-job limit. */
   private readonly maxConcurrentJobsPerOwner: number
+  /** Schemastery-defaulted live ring retention cap. */
+  private readonly retainBytes: number
+  /** Schemastery-defaulted settled ring retention cap. */
+  private readonly settledRetainBytes: number
+  /** Schemastery-defaulted pull-source poll interval. */
+  private readonly pumpPollMs: number
   private store = new Map<JobId, TrackedJob>()
   private counters = new Map<string, number>()
   /**
-   * Surfaces and listeners layered by the scope that registered them, in the
-   * tools-registry shape: a contribution files into its registering context's
-   * scope, and a read unions the global layer with the reader's scope chain.
+   * Controllers and scoped subscriptions layered by the scope that registered
+   * them, in the tools-registry shape: a contribution files into its
+   * registering context's scope, and a read unions the global layer with the
+   * owner's scope chain.
    *
    * The registry is one process-wide instance serving every composition, so a
    * flat table would answer a per-owner question process-wide: one preset's
@@ -114,7 +173,7 @@ export class LocalJobRegistry extends JobRegistry {
    * layer, so change notification is a no-op.
    */
   private readonly layers = new ScopedLayers<JobLayer>(() => new JobLayer(), () => {})
-  private listenersClosed = false
+  private readonly hub: JobEventHub
   /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
   private ownerCleanups = new Map<Agent, () => Promise<void> | void>()
   /** Service context used by detached settlement continuations and teardown. */
@@ -122,14 +181,31 @@ export class LocalJobRegistry extends JobRegistry {
 
   constructor(ctx: Context, config: Config) {
     super(ctx)
-    // Schemastery validates and fills the default before constructing the service.
-    this.maxConcurrentJobsPerOwner = (config as Required<Config>).maxConcurrentJobsPerOwner
+    // Schemastery validates and fills the defaults before constructing the service.
+    const resolved = config as Required<Config>
+    this.maxConcurrentJobsPerOwner = resolved.maxConcurrentJobsPerOwner
+    this.retainBytes = resolved.retainBytes
+    this.settledRetainBytes = resolved.settledRetainBytes
+    this.pumpPollMs = resolved.pumpPollMs
     this.selfCtx = ctx
+    this.hub = new JobEventHub(this.layers, (message) => { ctx.logger.warn(message) })
     ctx.effect(() => () => this.disposeAll(), 'jobs teardown')
   }
 
-  start(spec: JobStart): JobId {
-    if (!this.servesOwner(spec.owner)) {
+  /**
+   * The event stream bound to the accessing context: a subscription is an
+   * effect of that context, and `{ owners: 'scope' }` names its scope.
+   */
+  get events(): JobEvents {
+    const registrar = this.ctx
+    return {
+      subscribe: (filter, listener) => this.hub.subscribe(registrar, filter, listener),
+    }
+  }
+
+  start(spec: JobSpec): JobId {
+    const owner = this.resolveOwner(spec.owner)
+    if (!this.servesOwner(owner)) {
       throw new Error('background jobs unavailable: no job controller serves this agent (load @deepseek-ai/dsh-tool-jobs in its composition)')
     }
     if (spec.kind.length === 0) throw new Error('invalid job kind: expected a non-empty string')
@@ -138,19 +214,29 @@ export class LocalJobRegistry extends JobRegistry {
       && (!Number.isSafeInteger(spec.outputLimitBytes) || spec.outputLimitBytes <= 0)) {
       throw new Error(`invalid outputLimitBytes: expected a positive safe integer, got ${JSON.stringify(spec.outputLimitBytes)}`)
     }
-    if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
+    if (owner !== undefined) this.ensureOwnerCleanup(owner)
 
-    const active = this.activeJobCount(spec.owner)
+    const active = this.activeJobCount(owner)
     if (active >= this.maxConcurrentJobsPerOwner) {
       throw new Error(
         `background job limit reached for this owner (limit: ${this.maxConcurrentJobsPerOwner}); use job_kill to stop an unneeded job, wait for it to finish, then retry`,
       )
     }
 
-    const hooks = spec.run()
+    // The id is issued before the starter runs so the producer face can carry
+    // it; a throwing starter still leaves nothing registered — its ordinal is
+    // simply skipped.
     const count = (this.counters.get(spec.kind) ?? 0) + 1
     this.counters.set(spec.kind, count)
     const id = JobId(`${spec.kind}-${count}`)
+    const ring = new OutputRing()
+    const state: ProducerState = { progress: undefined, job: undefined }
+    const handle: JobHandle = {
+      id,
+      append: (text, options) => { this.appendRing(state, ring, text, options, 'producer') },
+      updateProgress: (line) => { this.updateProgress(state, line) },
+    }
+    const hooks = spec.run(handle)
 
     let markSettled!: () => void
     const settled = new Promise<void>((resolve) => { markSettled = resolve })
@@ -159,139 +245,92 @@ export class LocalJobRegistry extends JobRegistry {
       kind: spec.kind,
       label: spec.label,
       outputLimitBytes: spec.outputLimitBytes,
-      owner: spec.owner,
+      owner,
       cancel: hooks.cancel.bind(hooks),
-      readOutput: hooks.readOutput?.bind(hooks),
       status: 'running',
+      ring,
+      modelCursor: 0,
+      resultDelivered: false,
+      state,
       detail: undefined,
-      output: undefined,
+      result: undefined,
       startedAt: Date.now(),
       finishedAt: undefined,
-      reported: false,
+      killReason: undefined,
+      settleCause: undefined,
       settled,
       markSettled,
-      waiters: 0,
       waitResolvers: new Set(),
+      pump: undefined,
+      spillPaths: [],
     }
+    // Binding the shared producer state is the commit: writes staged inside
+    // the starter are already in the ring and `state`, and every later handle
+    // call reaches the registered record for its terminal checks and signals.
+    state.job = job
     this.store.set(id, job)
+    // Registration is complete and cannot fail from here, so the visible set
+    // has genuinely changed. The announcement precedes the pump because the
+    // pump drains its sources once synchronously, and that drain may append
+    // and announce output: a job's first event is always `registered`.
+    this.emit({ type: 'registered', job: this.view(job) }, owner)
 
-    void hooks.done.then(
-      (outcome) => { this.settle(job, outcome) },
-      (error: unknown) => {
+    // The producer's settlement or a registry-forced one ends the pump; the
+    // pump's final drain then lands before this registry trims the ring.
+    const producerDone = hooks.done.then(
+      outcome => outcome,
+      (error: unknown): JobOutcome => {
         // Contain a producer contract violation (`done` rejected) so cleanup and waiters cannot hang.
         this.selfCtx.logger.warn(`jobs: job ${job.id} producer done promise rejected (producer contract violation): ${String(error)}`)
-        this.settle(job, { status: 'failed', detail: String(error) })
+        return { status: 'failed', detail: String(error) }
       },
     )
-    // Registration is complete and cannot fail from here, so the visible set
-    // has genuinely changed.
-    this.notifyChanged(job.owner)
+    if (spec.output !== undefined && spec.output.length > 0) {
+      job.pump = startPump(
+        spec.output.map(source => this.guardSource(job, source)),
+        {
+          append: (text, options) => { this.appendRing(state, ring, text, options, 'pump') },
+          spill: (index, path) => { job.spillPaths[index] = path },
+        },
+        this.pumpPollMs,
+        Promise.race([producerDone, settled]),
+      )
+    }
+    void producerDone.then(async (outcome) => {
+      if (job.pump !== undefined) await job.pump.done
+      this.settle(job, outcome, job.settleCause ?? 'producer')
+    })
     return id
   }
 
-  list(caller?: Agent): JobSnapshot[] {
-    const session = caller?.id
+  list(caller?: SessionId): JobView[] {
     return [...this.store.values()]
-      .filter(job => job.owner === undefined || job.owner.id === session)
-      .map(job => this.snapshot(job))
+      .filter(job => job.owner === undefined || job.owner.id === caller)
+      .map(job => this.view(job))
   }
 
-  get(id: JobId, caller?: Agent): JobSnapshot {
-    const job = this.expect(id)
-    this.assertAccess(job, caller)
-    return this.snapshot(job)
+  get(id: JobId, caller?: SessionId): JobView {
+    return this.view(this.expect(id, caller))
   }
 
-  read(id: JobId, caller?: Agent): JobRead {
-    const job = this.expect(id)
-    this.assertAccess(job, caller)
-    const text = job.readOutput !== undefined
-      ? job.readOutput()
-      : isTerminal(job.status) ? job.output ?? '' : ''
-    if (isTerminal(job.status)) job.reported = true
-    return { text, snapshot: this.snapshot(job) }
+  read(id: JobId, caller?: SessionId): JobRead {
+    return this.readJob(this.expect(id, caller))
   }
 
-  kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished' {
-    const job = this.expect(id)
-    this.assertAccess(job, caller)
-    if (isTerminal(job.status)) {
-      job.reported = true
-      return 'already-finished'
+  readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead {
+    const job = this.expect(id, caller)
+    if (!Number.isSafeInteger(from) || from < 0) {
+      throw new Error(`invalid output read offset: expected a non-negative safe integer, got ${JSON.stringify(from)}`)
     }
-    // Cancel first so a throw leaves both lifecycle and notice state unchanged.
-    job.cancel(reason)
-    job.status = 'stopping'
-    job.reported = true
-    this.notifyChanged(job.owner)
-    return 'requested'
+    return job.ring.readFrom(from)
   }
 
-  async wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot> {
-    const job = this.expect(id)
-    this.assertAccess(job, caller)
-    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-      throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`)
-    }
-    if (!isTerminal(job.status)) {
-      if (signal?.aborted) throw new Error('wait aborted')
-      // Abort removes the waiter synchronously so same-tick settlement cannot
-      // suppress a notice for a wait that will reject.
-      job.waiters += 1
-      let counted = true
-      const uncount = (): void => {
-        if (!counted) return
-        counted = false
-        job.waiters -= 1
-      }
-      try {
-        // The scoped deadline distinguishes a successful wait timeout from
-        // caller cancellation and clears its timer on every exit.
-        using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
-        await new Promise<void>((resolve, reject) => {
-          const onSettled = (): void => {
-            job.waitResolvers.delete(onSettled)
-            d.signal.removeEventListener('abort', onAbort)
-            resolve()
-          }
-          const onAbort = (): void => {
-            job.waitResolvers.delete(onSettled)
-            // A settled job cannot reach here: settlement releases every waiter
-            // before it announces completion, and each released waiter detaches
-            // this listener in the same synchronous span, so nothing that reacts
-            // to a settlement can abort a wait the settlement already owed.
-            if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
-              resolve()
-            } else {
-              uncount()
-              reject(new Error('wait aborted'))
-            }
-          }
-          job.waitResolvers.add(onSettled)
-          d.signal.addEventListener('abort', onAbort, { once: true })
-        })
-      } finally {
-        uncount()
-      }
-    }
-    if (isTerminal(job.status)) job.reported = true
-    return this.snapshot(job)
+  kill(id: JobId, caller?: SessionId, reason?: string): 'requested' | 'already-finished' {
+    return this.killJob(this.expect(id, caller), reason)
   }
 
-  onJobDone(listener: JobDoneListener): () => void {
-    return this.layers.effect(
-      this.ctx,
-      layer => layer.listeners.append(listener),
-      { label: 'jobs.onJobDone()' },
-    )
-  }
-
-  onJobsChanged(listener: JobsChangedListener): () => void {
-    return this.layers.effect(
-      this.ctx,
-      layer => layer.changed.append(listener),
-      { label: 'jobs.onJobsChanged()' },
-    )
+  async wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView> {
+    return this.waitJob(this.expect(id, caller), timeoutMs, signal)
   }
 
   attachController(name: string): () => void {
@@ -304,6 +343,24 @@ export class LocalJobRegistry extends JobRegistry {
     )
   }
 
+  /**
+   * Resolve a spec's owner session to its live Agent. An owned registration
+   * needs the agent registry, and the session must currently have a live
+   * instance: that instance's disposal is what cancels and drops the job.
+   */
+  private resolveOwner(session: SessionId | undefined): Agent | undefined {
+    if (session === undefined) return undefined
+    const agents = this.selfCtx.get('agents')
+    if (agents === undefined) {
+      throw new Error('background job ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
+    }
+    const owner = agents.get(session)
+    if (owner === undefined) {
+      throw new Error(`session "${session}" has no live agent (background job owner must be live)`)
+    }
+    return owner
+  }
+
   /**
    * Whether an attached job controller can collect and stop work owned by
    * `owner`. The global layer holds every controller attached from an unscoped
@@ -327,133 +384,227 @@ export class LocalJobRegistry extends JobRegistry {
     return count
   }
 
-  /**
-   * The completion listeners that own `owner`'s notices: the global layer's
-   * first, then each scoped layer along the owner's chain. A listener outside
-   * that chain belongs to another composition and must not deliver, or the
-   * owner reads one notice per mounted preset.
-   * @param owner - the settled job's owner, or undefined for unowned work.
-   * @returns the listeners to notify, in registration order per layer.
-   */
-  private *listenersFor(owner?: Agent): IterableIterator<JobDoneListener> {
-    yield* this.layers.global.listeners.values()
-    const scope = owner === undefined ? undefined : scopeOf(owner.ctx)
-    for (const layer of this.layers.chainLayers(scope)) yield* layer.listeners.values()
-  }
-
-  /** Look up a job or fail loud. */
-  private expect(id: JobId): TrackedJob {
+  /** Look up a job and enforce caller access. */
+  private expect(id: JobId, caller?: SessionId): TrackedJob {
     const job = this.store.get(id)
     if (job === undefined) throw new Error(`unknown job ${id}`)
+    this.assertAccess(job, caller)
     return job
   }
 
   /**
    * The isolation fence: a job with an owner is reachable only by callers
    * whose session id matches (`!== undefined` semantics — an unowned job is
-   * open, and a no-agent caller can never match an owned one).
+   * open, and a caller-less view can never match an owned one).
    */
-  private assertAccess(job: TrackedJob, caller?: Agent): void {
-    if (job.owner !== undefined && job.owner.id !== caller?.id) {
+  private assertAccess(job: TrackedJob, caller: SessionId | undefined): void {
+    if (job.owner !== undefined && job.owner.id !== caller) {
       throw new Error(`job ${job.id} belongs to another session`)
     }
   }
 
-  /** Project a fresh read-only snapshot from the mutable record. */
-  private snapshot(job: TrackedJob): JobSnapshot {
-    const ownerSession = job.owner?.id
+  /** Project a fresh read-only view from the mutable record. */
+  private view(job: TrackedJob): JobView {
+    const owner = job.owner?.id
+    const spillPaths = [...new Set(job.spillPaths.filter((path): path is string => path !== undefined))]
     return {
       id: job.id,
       kind: job.kind,
       label: job.label,
+      ...owner !== undefined ? { owner } : {},
       ...job.outputLimitBytes !== undefined ? { outputLimitBytes: job.outputLimitBytes } : {},
-      ...ownerSession !== undefined ? { ownerSession } : {},
       status: job.status,
+      ...job.state.progress !== undefined ? { progress: job.state.progress } : {},
       ...job.detail !== undefined ? { detail: job.detail } : {},
       startedAt: job.startedAt,
       ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {},
-      reported: job.reported,
+      output: {
+        total: job.ring.total,
+        earliest: job.ring.earliest,
+        ...spillPaths.length > 0 ? { spillPaths } : {},
+      },
     }
   }
 
-  /**
-   * The change observers that own `owner`'s updates, resolved exactly like
-   * {@link listenersFor}: the global layer — a host composition's own carrier,
-   * which serves every owner — then each scoped layer along the owner's chain.
-   * An observer outside that chain belongs to another composition and would
-   * otherwise be told about agents it does not compose.
-   * @param owner - the owner whose visible set moved, or undefined for unowned work.
-   * @returns the observers to notify, in registration order per layer.
-   */
-  private *changedFor(owner?: Agent): IterableIterator<JobsChangedListener> {
-    yield* this.layers.global.changed.values()
-    const scope = owner === undefined ? undefined : scopeOf(owner.ctx)
-    for (const layer of this.layers.chainLayers(scope)) yield* layer.changed.values()
+  private emit(event: JobEvent, owner: Agent | undefined): void {
+    this.hub.emit(event, owner)
   }
 
   /**
-   * Announce that one owner's visible set changed. Each listener is contained
-   * so an observer cannot break a lifecycle commit that already happened.
+   * Consume the ring from the model cursor; the result rides the first read
+   * after settlement. A terminal read is the point the settled stream drops
+   * to the settled cap: settlement kept every unconsumed byte for it.
    */
-  private notifyChanged(owner: Agent | undefined): void {
-    for (const listener of this.changedFor(owner)) {
-      try {
-        listener(owner)
-      } catch (error: unknown) {
-        this.selfCtx.logger.warn(`jobs: onJobsChanged listener threw: ${String(error)}`)
-      }
+  private readJob(job: TrackedJob): JobRead {
+    const read = job.ring.readFrom(job.modelCursor)
+    job.modelCursor = job.ring.total
+    const result = isTerminal(job.status) && !job.resultDelivered ? job.result : undefined
+    if (result !== undefined) job.resultDelivered = true
+    if (isTerminal(job.status)) job.ring.trim(this.settledRetainBytes)
+    return {
+      chunks: read.chunks,
+      lossy: read.lossy,
+      ...result !== undefined ? { result } : {},
+      job: this.view(job),
     }
   }
 
+  private killJob(job: TrackedJob, reason?: string): 'requested' | 'already-finished' {
+    if (isTerminal(job.status)) return 'already-finished'
+    // Cancel first so a throw leaves lifecycle state unchanged.
+    job.cancel(reason)
+    job.status = 'stopping'
+    // Last writer wins on purpose: the detail reports the latest kill intent.
+    if (reason !== undefined) job.killReason = reason
+    job.settleCause = 'kill'
+    this.emit({ type: 'stopping', job: this.view(job) }, job.owner)
+    return 'requested'
+  }
+
+  private async waitJob(job: TrackedJob, timeoutMs: number, signal?: AbortSignal): Promise<JobView> {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`)
+    }
+    if (!isTerminal(job.status)) {
+      if (signal?.aborted) throw new Error('wait aborted')
+      // The scoped deadline distinguishes a successful wait timeout from
+      // caller cancellation and clears its timer on every exit.
+      using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
+      await new Promise<void>((resolve, reject) => {
+        const onSettled = (): void => {
+          job.waitResolvers.delete(onSettled)
+          d.signal.removeEventListener('abort', onAbort)
+          resolve()
+        }
+        const onAbort = (): void => {
+          job.waitResolvers.delete(onSettled)
+          // A settled job cannot reach here: settlement releases every waiter
+          // before it announces, and each released waiter detaches this
+          // listener in the same synchronous span, so nothing that reacts to a
+          // settlement can abort a wait the settlement already owed.
+          if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
+            resolve()
+          } else {
+            reject(new Error('wait aborted'))
+          }
+        }
+        job.waitResolvers.add(onSettled)
+        d.signal.addEventListener('abort', onAbort, { once: true })
+      })
+    }
+    return this.view(job)
+  }
+
   /**
-   * Record the first terminal outcome, release waiters, then announce
-   * completion. First-wins preserves a teardown force-failure against late
-   * producer settlement. Pending waits mark the job reported before listeners
-   * run. Completion is announced last because a reporter may open a model turn
-   * synchronously: every other observer of this settlement must already have
-   * seen the committed record.
+   * Append one chunk to the ring. A producer chunk against a settled job is
+   * logged and dropped; the registry's own pump drains silently after
+   * settlement (a forced settlement may precede the producer's). A chunk
+   * staged inside the starter call is retained and signals no observer — the
+   * registration commit publishes it.
    */
-  private settle(job: TrackedJob, outcome: JobOutcome): void {
+  private appendRing(
+    state: ProducerState,
+    ring: OutputRing,
+    text: string,
+    options: JobAppendOptions | undefined,
+    writer: 'producer' | 'pump',
+  ): void {
+    const job = state.job
+    if (job !== undefined && isTerminal(job.status)) {
+      if (writer === 'producer') this.selfCtx.logger.warn(`jobs: append to settled job ${job.id} dropped`)
+      return
+    }
+    if (!ring.append(text, options, this.retainBytes)) return
+    if (job !== undefined) this.emitOutput(job)
+  }
+
+  /**
+   * Contain a failing pull source: the first throw is logged, and the source
+   * reads as exhausted from then on, so the job runs to its own settlement
+   * with whatever the ring holds instead of freezing on a pump failure.
+   */
+  private guardSource(job: TrackedJob, source: JobOutputSource): JobOutputSource {
+    let failed = false
+    return {
+      ...source.channel !== undefined ? { channel: source.channel } : {},
+      read: (fromByte) => {
+        if (failed) return { text: '', nextOffset: fromByte, lossy: false }
+        try {
+          return source.read(fromByte)
+        } catch (error: unknown) {
+          failed = true
+          this.selfCtx.logger.warn(`jobs: output source for ${job.id} failed; its stream stops here: ${String(error)}`)
+          return { text: '', nextOffset: fromByte, lossy: false }
+        }
+      },
+    }
+  }
+
+  /** Announce that one job's ring advanced (append or settlement). */
+  private emitOutput(job: TrackedJob): void {
+    const owner = job.owner?.id
+    this.emit({ type: 'output', id: job.id, ...owner !== undefined ? { owner } : {}, total: job.ring.total }, job.owner)
+  }
+
+  /**
+   * Replace the live progress line through a producer face; a write against a
+   * settled job is logged and dropped. A write staged inside the starter call
+   * seeds the registered projection and signals no observer.
+   */
+  private updateProgress(state: ProducerState, line: string): void {
+    const job = state.job
+    if (job !== undefined && isTerminal(job.status)) {
+      this.selfCtx.logger.warn(`jobs: progress update on settled job ${job.id} dropped`)
+      return
+    }
+    state.progress = line
+    if (job !== undefined) this.emit({ type: 'progress', job: this.view(job) }, job.owner)
+  }
+
+  /**
+   * Record the first terminal outcome, release waiters, then announce the
+   * settlement. First-wins preserves a teardown force-failure against late
+   * producer settlement. The settled event follows every released waiter, so
+   * a consumer that claims while waiting always claims before the event.
+   */
+  private settle(job: TrackedJob, outcome: JobOutcome, cause: JobSettleCause): void {
     if (isTerminal(job.status)) return
     job.status = outcome.status
-    job.detail = outcome.detail
-    job.output = outcome.output
+    // A killed settlement carries the recorded kill reason in its detail:
+    // producer facts first (`signal: SIGTERM; cancelled by the user`). A job
+    // that outran its kill request (settled `completed`/`failed`) keeps the
+    // producer detail alone — the reason describes a kill that never landed.
+    if (outcome.status === 'killed' && job.killReason !== undefined) {
+      job.detail = outcome.detail !== undefined
+        ? `${outcome.detail}; ${job.killReason}`
+        : job.killReason
+    } else if (outcome.detail !== undefined) {
+      job.detail = outcome.detail
+    }
+    job.state.progress = undefined
+    job.result = outcome.result
     job.finishedAt = Date.now()
-    if (job.waiters > 0) job.reported = true
-    const snapshot = this.snapshot(job)
+    // Settlement ends the stream: trim to the settled cap before any observer
+    // reads the terminal projection, but never below the bytes the model
+    // cursor has not consumed. A job that finishes before its first model
+    // read keeps everything the live cap retained until that read.
+    job.ring.trim(Math.max(this.settledRetainBytes, job.ring.total - job.modelCursor))
     const waitResolvers = [...job.waitResolvers]
     job.waitResolvers.clear()
     for (const resolveWait of waitResolvers) resolveWait()
     job.markSettled()
-    this.notifyChanged(job.owner)
-    if (this.listenersClosed) return
-    for (const listener of this.listenersFor(job.owner)) {
-      try {
-        const returned = listener(snapshot, job.owner)
-        void Promise.resolve(returned).catch((error: unknown) => {
-          this.selfCtx.logger.warn(`jobs: onJobDone listener rejected for ${job.id}: ${String(error)}`)
-        })
-      } catch (error: unknown) {
-        this.selfCtx.logger.warn(`jobs: onJobDone listener threw for ${job.id}: ${String(error)}`)
-      }
-    }
+    this.emit({ type: 'settled', job: this.view(job), cause }, job.owner)
+    // The ring's stream ends with settlement; the signal follows the committed
+    // settlement so an observer that wakes on it reads the terminal state.
+    this.emitOutput(job)
   }
 
   /**
    * Attach one awaited cleanup through the exact owner's scope. This survives
    * producer reloads and joins agent quiescence; the retained disposer lets
-   * service teardown detach the cross-fiber effect. Fails when the registry is
-   * absent or the owner is not its currently registered instance.
+   * service teardown detach the cross-fiber effect.
    */
   private ensureOwnerCleanup(owner: Agent): void {
-    const ownerId = owner.id
-    const agents = this.selfCtx.get('agents')
-    if (agents === undefined) {
-      throw new Error('background job ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
-    }
-    if (agents.get(ownerId) !== owner) {
-      throw new Error(`agent "${ownerId}" is not the registered agent instance (background job owner must be live)`)
-    }
     if (this.ownerCleanups.has(owner)) return
     // Record only after attach succeeds; a disposing scope rejects new effects.
     const detach = owner.ctx.effect(() => async () => {
@@ -468,31 +619,30 @@ export class LocalJobRegistry extends JobRegistry {
     const owned = [...this.store.values()].filter(job => job.owner === owner)
     this.cancelForTeardown(owned, 'owner disposed')
     await Promise.all(owned.map(job => job.settled))
-    for (const job of owned) this.store.delete(job.id)
-    // Removal is the one visible-set change no per-job record carries, so it
-    // must be announced here or an observer keeps the dropped rows forever.
-    if (owned.length > 0) this.notifyChanged(owner)
+    this.remove(owned)
+  }
+
+  /** Drop settled records and announce each removal, the one visible-set change no per-job record carries. */
+  private remove(jobs: readonly TrackedJob[]): void {
+    for (const job of jobs) {
+      this.store.delete(job.id)
+      this.emit({ type: 'removed', job: this.view(job) }, job.owner)
+    }
   }
 
   /**
-   * Close listeners, cancel live jobs, await settlement, and detach owner
+   * Cancel live jobs, await settlement, drop every record, and detach owner
    * effects. Throwing cancels are force-failed to avoid teardown deadlock.
    */
   private async disposeAll(): Promise<void> {
-    // The flag is the whole guard: each layer entry's undo belongs to the fiber
-    // that registered it, so this service may not drop them on its own way out.
-    this.listenersClosed = true
     const all = [...this.store.values()]
     this.cancelForTeardown(all, 'jobs service disposed')
     await Promise.all(all.map(job => job.settled))
-    // Distinct owners whose records just disappeared. A change observer files
-    // into the layer of the context that registered it, so a consumer mounted
-    // outside this service — the api-proxy carrier registers from the mux
-    // stream — is still reachable here. Without this it keeps the rows it last
-    // received after a registry reload.
-    const emptied = new Set(all.map(job => job.owner))
-    this.store.clear()
-    for (const owner of emptied) this.notifyChanged(owner)
+    // A subscriber mounted outside this service — the job controller's rows
+    // stream registers from its own context — is still reachable here.
+    // Without the removals it keeps the rows it last received after a
+    // registry reload.
+    this.remove(all)
     // Detach cross-fiber owner effects after the shared store is quiescent.
     const ownerCleanups = [...this.ownerCleanups.values()]
     this.ownerCleanups.clear()
@@ -507,25 +657,21 @@ export class LocalJobRegistry extends JobRegistry {
   private cancelForTeardown(jobs: TrackedJob[], reason: string): void {
     for (const job of jobs) {
       if (isTerminal(job.status)) continue
-      // Teardown cancellation is a kill without a caller, so it claims the
-      // terminal report the same way `kill()` does. Nothing will read a notice
-      // for a job whose owner or service is being destroyed, and a waking
-      // reporter would spend a model request per teardown layer. This is
-      // decided before the producer runs: the force-failure below settles the
-      // record too, so a throwing cancel must not be the one path that
-      // announces an unreported completion into a disposing owner.
-      job.reported = true
+      // Whatever settles this job from here on, its owner or the service is
+      // being destroyed: the settlement announces `teardown` so a completion
+      // reporter does not address a reader that no longer exists.
+      job.settleCause = 'teardown'
       try {
         job.cancel(reason)
         job.status = 'stopping'
         // Teardown reaches settlement only after the producer releases, which a
         // slow stop can defer; announcing the transition here is what keeps an
         // observer from showing `running` for that whole window.
-        this.notifyChanged(job.owner)
+        this.emit({ type: 'stopping', job: this.view(job) }, job.owner)
       } catch (error: unknown) {
         const detail = `cancel threw during teardown; work may be orphaned: ${String(error)}`
         this.selfCtx.logger.warn(`jobs: cancel of ${job.id} threw during teardown; job record forced failed and work may be orphaned: ${String(error)}`)
-        this.settle(job, { status: 'failed', detail })
+        this.settle(job, { status: 'failed', detail }, 'teardown')
       }
     }
   }
diff --git a/packages/jobs/jobs-local/src/pump.ts b/packages/jobs/jobs-local/src/pump.ts
new file mode 100644
index 0000000000..4cd98e0dea
--- /dev/null
+++ b/packages/jobs/jobs-local/src/pump.ts
@@ -0,0 +1,106 @@
+/**
+ * The registry-owned pull pump: copies a job's {@link JobOutputSource}s into
+ * its ring at a bounded cadence and drains them once more after the
+ * producer settles, so the ring holds every byte before settlement trims and
+ * closes it. A lossy source read lands as a gap chunk; the spill file a source
+ * keeps is reported to the sink on every read, because that reference
+ * outlives any chunk. Pure utility — no cordis, no timers retained past
+ * settlement.
+ * @module @deepseek-ai/dsh-jobs-local/pump
+ */
+
+import type { JobAppendOptions, JobOutputSource } from '@deepseek-ai/dsh-jobs'
+
+/** One pump run; `done` resolves after the final post-settlement drain. */
+export interface PumpHandle {
+  done: Promise<void>
+}
+
+/** Where a pump delivers what it reads. */
+export interface PumpSink {
+  /**
+   * Append copied text to the ring.
+   * @param text - the chunk text, exactly as read.
+   * @param options - stream label and gap marker.
+   */
+  append(text: string, options?: JobAppendOptions): void
+  /**
+   * Record the spill file source `index` advertised on its latest read; called
+   * on every read, with `undefined` when the source keeps none or withdrew it.
+   * @param index - the source's position in the pump's source array.
+   * @param path - the host path the source reported, if any.
+   */
+  spill(index: number, path: string | undefined): void
+}
+
+/**
+ * Drain every source in array order, sleep `pollMs` or until `until`
+ * settles, repeat, then drain one final time. A lossy source read appends
+ * its surviving tail with `gapBefore`, so the discontinuity stays visible to
+ * observers. Sources drain in array order each round, so bytes two sources
+ * produced inside one poll window land in that order, not in the order they
+ * were written: the ring is a best-effort live view whose cross-source
+ * reordering is bounded by `pollMs`.
+ *
+ * The wait holds constant resources however long the job runs: one
+ * subscription on `until` for the whole run and one pending timer at a time.
+ * @param sources - producer streams, each pumped at its own offset.
+ * @param sink - receives each copied chunk and each source's current spill file.
+ * @param pollMs - poll interval in milliseconds; a positive finite number.
+ * @param until - settles (or rejects, which counts as settlement) when the producer finished; only its `then` is used.
+ * @returns the handle whose `done` resolves after the final drain.
+ */
+export function startPump(
+  sources: readonly JobOutputSource[],
+  sink: PumpSink,
+  pollMs: number,
+  until: PromiseLike<unknown>,
+): PumpHandle {
+  if (!Number.isFinite(pollMs) || pollMs <= 0) {
+    throw new Error(`invalid pump pollMs: expected a positive finite number of milliseconds, got ${JSON.stringify(pollMs)}`)
+  }
+  const states = sources.map(source => ({ source, cursor: 0 }))
+  const drain = (): void => {
+    for (const [index, state] of states.entries()) {
+      const { source } = state
+      const read = source.read(state.cursor)
+      state.cursor = read.nextOffset
+      sink.spill(index, read.spillPath)
+      if (read.text.length === 0) continue
+      if (source.channel === undefined && !read.lossy) {
+        sink.append(read.text)
+      } else {
+        sink.append(read.text, {
+          ...source.channel !== undefined ? { channel: source.channel } : {},
+          ...read.lossy ? { gapBefore: true as const } : {},
+        })
+      }
+    }
+  }
+  const done = (async (): Promise<void> => {
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let wake: (() => void) | undefined
+    const finish = (): void => {
+      settled = true
+      // Clear the pending poll so a finished pump holds no timer for up to one
+      // interval, and release the current wait so the final drain runs at once.
+      // `finish` always runs from a microtask, after the loop parked on its
+      // first timer, so the timer is never absent here.
+      clearTimeout(timer)
+      wake?.()
+    }
+    void until.then(finish, finish)
+    while (!settled) {
+      drain()
+      await new Promise<void>((resolve) => {
+        wake = resolve
+        timer = setTimeout(resolve, pollMs)
+      })
+      wake = undefined
+      timer = undefined
+    }
+    drain()
+  })()
+  return { done }
+}
diff --git a/packages/jobs/jobs-local/src/ring.ts b/packages/jobs/jobs-local/src/ring.ts
new file mode 100644
index 0000000000..fb4bcb3c5b
--- /dev/null
+++ b/packages/jobs/jobs-local/src/ring.ts
@@ -0,0 +1,113 @@
+/**
+ * The bounded output ring behind one job: chunks at absolute byte offsets,
+ * head eviction that never moves an assigned offset, and non-consuming reads
+ * from any offset.
+ * @module @deepseek-ai/dsh-jobs-local/ring
+ */
+
+import type { JobAppendOptions, JobChannel, JobOutputRead } from '@deepseek-ai/dsh-jobs'
+
+/** One retained ring entry; `bytes` caches the chunk's UTF-8 length. */
+interface RingChunk {
+  at: number
+  text: string
+  bytes: number
+  channel?: JobChannel
+  gapBefore?: true
+}
+
+/**
+ * The UTF-8-safe tail of `text` no longer than `maxBytes`: the byte cut
+ * advances past continuation bytes so the surviving text never starts inside
+ * a code point.
+ * @param text - the oversized chunk text.
+ * @param maxBytes - positive byte budget for the surviving tail.
+ * @returns the surviving tail and its exact byte length.
+ */
+function utf8Tail(text: string, maxBytes: number): { text: string; bytes: number } {
+  const raw = Buffer.from(text, 'utf8')
+  let start = raw.length - maxBytes
+  // The loop bound proves the index is in range; the assertion only
+  // discharges noUncheckedIndexedAccess.
+  while (start < raw.length && ((raw[start] as number) & 0xC0) === 0x80) start += 1
+  const tail = raw.subarray(start)
+  return { text: tail.toString('utf8'), bytes: tail.length }
+}
+
+/** Offsets stay absolute across eviction: `earliest` only ever advances. */
+export class OutputRing {
+  /** Retained chunks in offset order. */
+  private readonly chunks: RingChunk[] = []
+  /** Sum of the retained chunks' byte lengths. */
+  retainedBytes = 0
+  /** Total UTF-8 bytes ever appended — the offset the next chunk starts at. */
+  total = 0
+  /** Offset of the oldest retained byte (equals {@link total} when nothing is retained). */
+  earliest = 0
+
+  /**
+   * Append one chunk and trim the head to `cap`.
+   * @param text - the chunk text, exactly as produced.
+   * @param options - stream label and gap marker.
+   * @param cap - retention cap in UTF-8 bytes after this append.
+   * @returns false when the chunk was empty and nothing changed.
+   */
+  append(text: string, options: JobAppendOptions | undefined, cap: number): boolean {
+    if (text.length === 0) return false
+    const bytes = Buffer.byteLength(text, 'utf8')
+    this.chunks.push({
+      at: this.total,
+      text,
+      bytes,
+      ...options?.channel !== undefined ? { channel: options.channel } : {},
+      ...options?.gapBefore !== undefined ? { gapBefore: options.gapBefore } : {},
+    })
+    this.total += bytes
+    this.retainedBytes += bytes
+    this.trim(cap)
+    return true
+  }
+
+  /**
+   * Drop retained head chunks until the ring fits `cap`; a single oversized
+   * chunk keeps only its UTF-8-safe tail with a `gapBefore` marker.
+   * @param cap - retention cap in UTF-8 bytes.
+   */
+  trim(cap: number): void {
+    while (this.retainedBytes > cap && this.chunks.length > 1) {
+      const dropped = this.chunks.shift()
+      /* v8 ignore next -- the length guard proves shift() returns a chunk; the check only satisfies noUncheckedIndexedAccess. */
+      if (dropped === undefined) break
+      this.retainedBytes -= dropped.bytes
+    }
+    const single = this.chunks.length === 1 ? this.chunks[0] : undefined
+    if (single !== undefined && single.bytes > cap) {
+      const tail = utf8Tail(single.text, cap)
+      single.at += single.bytes - tail.bytes
+      single.text = tail.text
+      single.bytes = tail.bytes
+      single.gapBefore = true
+      this.retainedBytes = tail.bytes
+    }
+    this.earliest = this.chunks[0]?.at ?? this.total
+  }
+
+  /**
+   * Retained chunks overlapping `[from, total)` as fresh wire chunks.
+   * @param from - absolute byte offset to read from.
+   * @returns the chunks, the resume offset, and whether bytes before them were evicted.
+   */
+  readFrom(from: number): JobOutputRead {
+    const chunks = []
+    for (const chunk of this.chunks) {
+      if (chunk.at + chunk.bytes <= from) continue
+      chunks.push({
+        at: chunk.at,
+        text: chunk.text,
+        ...chunk.channel !== undefined ? { channel: chunk.channel } : {},
+        ...chunk.gapBefore !== undefined ? { gapBefore: chunk.gapBefore } : {},
+      })
+    }
+    return { chunks, next: this.total, lossy: from < this.earliest }
+  }
+}
diff --git a/packages/jobs/jobs-local/tests/events.spec.ts b/packages/jobs/jobs-local/tests/events.spec.ts
new file mode 100644
index 0000000000..5a653569b9
--- /dev/null
+++ b/packages/jobs/jobs-local/tests/events.spec.ts
@@ -0,0 +1,146 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { ScopedLayers, bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope'
+import type { ScopeKey } from '@deepseek-ai/dsh-scope'
+import { JobId } from '@deepseek-ai/dsh-jobs'
+import type { JobEvent, JobView } from '@deepseek-ai/dsh-jobs'
+import { JobEventHub, JobLayer } from '../src/events.ts'
+
+function agentIn(ctx: Context, rawId: string, presetScope?: ScopeKey): Agent {
+  const id = SessionId(rawId)
+  let agentCtx = ctx.plugin(() => {}).ctx
+  if (presetScope !== undefined) {
+    const key = {}
+    bindScopeParent(key, presetScope)
+    agentCtx = createScope(agentCtx, key).ctx
+  }
+  const session = Session.create(id)
+  return {
+    id,
+    options: {},
+    session,
+    inbox: unsupportedInbox(),
+    status: 'idle',
+    ctx: agentCtx,
+    send: () => {},
+    followup: () => {},
+    steer: () => {},
+    inject: () => {},
+    cancel: () => {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
+  }
+}
+
+function view(owner: Agent | undefined): JobView {
+  return {
+    id: JobId('bash-1'),
+    kind: 'bash',
+    label: 'x',
+    ...owner !== undefined ? { owner: owner.id } : {},
+    status: 'running',
+    startedAt: 0,
+    output: { total: 0, earliest: 0 },
+  }
+}
+
+function bench() {
+  const ctx = new Context()
+  const warnings: string[] = []
+  const layers = new ScopedLayers<JobLayer>(() => new JobLayer(), () => {})
+  const hub = new JobEventHub(layers, message => warnings.push(message))
+  return { ctx, hub, warnings }
+}
+
+describe('JobEventHub', () => {
+  it('delivers by owner: that session plus every unowned job, never another session', () => {
+    const { ctx, hub } = bench()
+    const alice = agentIn(ctx, 'alice')
+    const bob = agentIn(ctx, 'bob')
+    const seen: (string | undefined)[] = []
+    hub.subscribe(ctx, { owner: alice.id }, (event) => { seen.push(event.type === 'output' ? event.owner : event.job.owner) })
+
+    hub.emit({ type: 'registered', job: view(alice) }, alice)
+    hub.emit({ type: 'registered', job: view(bob) }, bob)
+    hub.emit({ type: 'registered', job: view(undefined) }, undefined)
+    hub.emit({ type: 'output', id: JobId('bash-1'), owner: bob.id, total: 1 }, bob)
+    hub.emit({ type: 'output', id: JobId('bash-1'), total: 1 }, undefined)
+    expect(seen).toEqual(['alice', undefined, undefined])
+  })
+
+  it("delivers 'all' everything and 'scope' only the owners composed under the subscriber", async () => {
+    const { ctx, hub } = bench()
+    const mount = createScope(ctx, {})
+    const otherMount = createScope(ctx, {})
+    const alice = agentIn(ctx, 'alice', scopeOf(mount.ctx))
+    const bob = agentIn(ctx, 'bob', scopeOf(otherMount.ctx))
+
+    const all: string[] = []
+    hub.subscribe(ctx, { owners: 'all' }, (event) => { all.push(event.type === 'output' ? String(event.owner) : String(event.job.owner)) })
+    const scoped: string[] = []
+    await mount.ctx.plugin((pluginCtx: Context) => {
+      hub.subscribe(pluginCtx, { owners: 'scope' }, (event) => { scoped.push(event.type === 'output' ? String(event.owner) : String(event.job.owner)) })
+    })
+    const unscoped: string[] = []
+    hub.subscribe(ctx, { owners: 'scope' }, (event) => { unscoped.push(event.type === 'output' ? String(event.owner) : String(event.job.owner)) })
+
+    hub.emit({ type: 'registered', job: view(alice) }, alice)
+    hub.emit({ type: 'registered', job: view(bob) }, bob)
+    hub.emit({ type: 'registered', job: view(undefined) }, undefined)
+    expect(all).toEqual(['alice', 'bob', 'undefined'])
+    // A preset-scoped subscription hears its own agents only; an unowned job
+    // has no chain to walk, so only unscoped subscriptions hear it.
+    expect(scoped).toEqual(['alice'])
+    expect(unscoped).toEqual(['alice', 'bob', 'undefined'])
+  })
+
+  it('contains a throwing listener and keeps delivering to later ones', () => {
+    const { ctx, hub, warnings } = bench()
+    const seen: JobEvent[] = []
+    hub.subscribe(ctx, { owners: 'all' }, () => { throw new Error('listener boom') })
+    hub.subscribe(ctx, { owners: 'all' }, (event) => { seen.push(event) })
+    hub.emit({ type: 'registered', job: view(undefined) }, undefined)
+    expect(seen).toHaveLength(1)
+    expect(warnings).toEqual([expect.stringContaining('event listener threw on registered: Error: listener boom')])
+  })
+
+  it('unregisters through the disposer and with the subscribing fiber', async () => {
+    const { ctx, hub } = bench()
+    const seen: number[] = []
+    const detach = hub.subscribe(ctx, { owners: 'all' }, () => { seen.push(1) })
+    const fiber = await ctx.plugin((pluginCtx: Context) => {
+      hub.subscribe(pluginCtx, { owners: 'scope' }, () => { seen.push(2) })
+      hub.subscribe(pluginCtx, { owner: SessionId('nobody') }, () => { seen.push(3) })
+    })
+
+    // Filter-kind order is not a contract; the assertion only fixes it for determinism.
+    hub.emit({ type: 'registered', job: view(undefined) }, undefined)
+    expect(seen).toEqual([1, 3, 2])
+    detach()
+    detach()
+    hub.emit({ type: 'registered', job: view(undefined) }, undefined)
+    expect(seen).toEqual([1, 3, 2, 3, 2])
+    await fiber.dispose()
+    hub.emit({ type: 'registered', job: view(undefined) }, undefined)
+    expect(seen).toEqual([1, 3, 2, 3, 2])
+  })
+
+  it('keeps a scoped layer alive only while a subscription or controller remains in it', async () => {
+    const { ctx, hub } = bench()
+    const mount = createScope(ctx, {})
+    const spy = vi.fn()
+    const fiber = await mount.ctx.plugin((pluginCtx: Context) => {
+      hub.subscribe(pluginCtx, { owners: 'scope' }, spy)
+    })
+    const alice = agentIn(ctx, 'alice', scopeOf(mount.ctx))
+    hub.emit({ type: 'registered', job: view(alice) }, alice)
+    expect(spy).toHaveBeenCalledTimes(1)
+    await fiber.dispose()
+    hub.emit({ type: 'registered', job: view(alice) }, alice)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(new JobLayer().isEmpty()).toBe(true)
+  })
+})
diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts
index dafd91844f..2b1fc0c08f 100644
--- a/packages/jobs/jobs-local/tests/jobs.spec.ts
+++ b/packages/jobs/jobs-local/tests/jobs.spec.ts
@@ -6,7 +6,9 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope'
 import type { ScopeKey } from '@deepseek-ai/dsh-scope'
 import { JobId } from '@deepseek-ai/dsh-jobs'
-import type { JobHooks, JobKind, JobOutcome, JobSnapshot, JobStart } from '@deepseek-ai/dsh-jobs'
+import type {
+  JobEvent, JobEventFilter, JobHandle, JobHooks, JobKind, JobOutcome, JobOutputSource, JobSpec, JobView,
+} from '@deepseek-ai/dsh-jobs'
 import LocalJobRegistry, { type Config as JobsConfig } from '@deepseek-ai/dsh-jobs-local'
 import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
 
@@ -56,25 +58,50 @@ async function disposeAgentScope(agent: Agent): Promise<void> {
   await dispose()
 }
 
-/** A controllable producer start-spec: settle its `done` on demand, record cancels. */
-function producer(overrides: Partial<Omit<JobStart, 'run'> & JobHooks> = {}) {
+/** Register a stub agent so the registry can resolve it as a live owner. */
+async function liveAgent(ctx: Context, rawId: string, presetScope?: ScopeKey): Promise<Agent> {
+  const agent = stubAgent(ctx, rawId, presetScope)
+  await ctx.agents.register(agent)
+  return agent
+}
+
+type ProducerOverrides = Partial<Pick<JobSpec, 'kind' | 'label' | 'outputLimitBytes' | 'output'> & JobHooks> & {
+  owner?: Agent
+}
+
+/** A controllable producer spec: settle its `done` on demand, record cancels, expose the handle. */
+function producer(overrides: ProducerOverrides = {}) {
   let settle!: (outcome: JobOutcome) => void
   let reject!: (error: unknown) => void
   const cancels: (string | undefined)[] = []
-  const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, ...hookOverrides } = overrides
+  const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, output, ...hookOverrides } = overrides
   const hooks: JobHooks = {
     cancel(reason) { cancels.push(reason) },
     done: new Promise<JobOutcome>((res, rej) => { settle = res; reject = rej }),
     ...hookOverrides,
   }
-  const spec: JobStart = {
+  let started: JobHandle | undefined
+  const spec: JobSpec = {
     kind,
     label,
-    ...owner !== undefined ? { owner } : {},
+    ...owner !== undefined ? { owner: owner.id } : {},
     ...outputLimitBytes !== undefined ? { outputLimitBytes } : {},
-    run: () => hooks,
+    ...output !== undefined ? { output } : {},
+    run: (job) => {
+      started = job
+      return hooks
+    },
+  }
+  return {
+    spec,
+    settle,
+    reject,
+    cancels,
+    job(): JobHandle {
+      if (started === undefined) throw new Error('producer not started')
+      return started
+    },
   }
-  return { spec, settle, reject, cancels }
 }
 
 async function harness(config: JobsConfig = {}) {
@@ -85,12 +112,19 @@ async function harness(config: JobsConfig = {}) {
   return ctx
 }
 
+/** Collect events matching `filter`; `types` narrows what is recorded. */
+function collect(ctx: Context, filter: JobEventFilter = { owners: 'all' }, types?: JobEvent['type'][]): JobEvent[] {
+  const seen: JobEvent[] = []
+  ctx.jobs.events.subscribe(filter, (event) => {
+    if (types === undefined || types.includes(event.type)) seen.push(event)
+  })
+  return seen
+}
+
 /**
  * Attach a job controller the way `tool-jobs` does: from a plugin whose own
  * `inject` resolves `ctx.jobs`, so the service method binds to the REGISTERING
- * context and the controller files into that context's scope layer. Reading the
- * service off a bare scoped context instead throws `cannot get property "jobs"
- * without inject`, which is the same rule the shipped plugin obeys.
+ * context and the controller files into that context's scope layer.
  * @param ctx - the context whose scope should own the controller.
  */
 async function attachControllerIn(ctx: Context): Promise<void> {
@@ -111,9 +145,22 @@ function waitResolverCount(ctx: Context, id: JobId): number {
   return job.waitResolvers.size
 }
 
+/** A scripted pull source: each read shifts the next scripted result. */
+function scriptedSource(reads: { text: string; lossy?: boolean }[], channel?: 'stdout' | 'stderr'): JobOutputSource {
+  let offset = 0
+  return {
+    ...channel !== undefined ? { channel } : {},
+    read() {
+      const next = reads.shift() ?? { text: '' }
+      offset += Buffer.byteLength(next.text, 'utf8')
+      return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false }
+    },
+  }
+}
+
 describe('LocalJobRegistry.start', () => {
-  it('preserves the SessionId brand on public owner snapshots', () => {
-    expectTypeOf<JobSnapshot['ownerSession']>().toEqualTypeOf<SessionId | undefined>()
+  it('preserves the SessionId brand on public owner projections', () => {
+    expectTypeOf<JobView['owner']>().toEqualTypeOf<SessionId | undefined>()
   })
 
   it('refuses to register while no job controller serves the owner', async () => {
@@ -133,10 +180,8 @@ describe('LocalJobRegistry.start', () => {
     const withoutControls = createScope(ctx, {})
     await attachControllerIn(withControls.ctx)
 
-    const served = stubAgent(ctx, 'served', scopeOf(withControls.ctx))
-    const unserved = stubAgent(ctx, 'unserved', scopeOf(withoutControls.ctx))
-    await ctx.agents.register(served)
-    await ctx.agents.register(unserved)
+    const served = await liveAgent(ctx, 'served', scopeOf(withControls.ctx))
+    const unserved = await liveAgent(ctx, 'unserved', scopeOf(withoutControls.ctx))
 
     expect(() => ctx.jobs.start(producer({ owner: served }).spec)).not.toThrow()
     expect(() => ctx.jobs.start(producer({ owner: unserved }).spec))
@@ -153,8 +198,7 @@ describe('LocalJobRegistry.start', () => {
     // The host-plane composition's own controls: no scope, so the global layer
     // holds them and every owner's read includes it.
     await attachControllerIn(ctx)
-    const scoped = stubAgent(ctx, 'scoped', scopeOf(createScope(ctx, {}).ctx))
-    await ctx.agents.register(scoped)
+    const scoped = await liveAgent(ctx, 'scoped', scopeOf(createScope(ctx, {}).ctx))
 
     expect(() => ctx.jobs.start(producer({ owner: scoped }).spec)).not.toThrow()
     expect(() => ctx.jobs.start(producer().spec)).not.toThrow()
@@ -176,6 +220,11 @@ describe('LocalJobRegistry.start', () => {
     },
   )
 
+  it('rejects a non-positive pump interval', async () => {
+    const ctx = new Context()
+    await expect(ctx.plugin(LocalJobRegistry, { pumpPollMs: 0 })).rejects.toThrow()
+  })
+
   it('accepts the largest safe integer limit', async () => {
     const ctx = await harness({ maxConcurrentJobsPerOwner: Number.MAX_SAFE_INTEGER })
     expect(ctx.jobs).toBeInstanceOf(LocalJobRegistry)
@@ -187,7 +236,7 @@ describe('LocalJobRegistry.start', () => {
     for (const job of live) ctx.jobs.start(job.spec)
 
     const blocked = producer()
-    const run = vi.fn(() => blocked.spec.run())
+    const run = vi.fn((job: JobHandle) => blocked.spec.run(job))
     expect(() => ctx.jobs.start({ ...blocked.spec, run }))
       .toThrow('background job limit reached for this owner (limit: 10)')
     expect(run).not.toHaveBeenCalled()
@@ -200,7 +249,7 @@ describe('LocalJobRegistry.start', () => {
     expect(ctx.jobs.start(first.spec)).toBe('bash-1')
 
     const blocked = producer()
-    const run = vi.fn(() => blocked.spec.run())
+    const run = vi.fn((job: JobHandle) => blocked.spec.run(job))
     expect(() => ctx.jobs.start({ ...blocked.spec, run }))
       .toThrow('use job_kill to stop an unneeded job, wait for it to finish, then retry')
     expect(run).not.toHaveBeenCalled()
@@ -236,17 +285,18 @@ describe('LocalJobRegistry.start', () => {
     },
   )
 
-  it('isolates exact owners, replacement objects with the same session id, and the unowned bucket', async () => {
+  it('buckets by exact owner: a same-session replacement and the unowned bucket count separately', async () => {
     const ctx = await harness({ maxConcurrentJobsPerOwner: 1 })
     const oldOwner = stubAgent(ctx, 'shared-session')
     const detachOld = await ctx.agents.register(oldOwner)
     const oldTask = producer({ owner: oldOwner })
     ctx.jobs.start(oldTask.spec)
 
-    const otherOwner = stubAgent(ctx, 'other-session')
-    await ctx.agents.register(otherOwner)
-    expect(() => ctx.jobs.start(producer({ owner: otherOwner }).spec)).not.toThrow()
+    await liveAgent(ctx, 'other-session')
+    expect(() => ctx.jobs.start({ ...producer().spec, owner: SessionId('other-session') })).not.toThrow()
 
+    // The session id resolves to whichever agent is live now; a replacement
+    // instance starts with its own bucket even while the old job runs on.
     await detachOld()
     const replacement = stubAgent(ctx, 'shared-session')
     await ctx.agents.register(replacement)
@@ -254,8 +304,6 @@ describe('LocalJobRegistry.start', () => {
 
     ctx.jobs.start(producer().spec)
     expect(() => ctx.jobs.start(producer().spec)).toThrow('(limit: 1)')
-    expect(() => ctx.jobs.start(producer({ owner: oldOwner }).spec))
-      .toThrow('is not the registered agent instance')
 
     oldTask.settle({ status: 'completed' })
     await tick()
@@ -272,94 +320,81 @@ describe('LocalJobRegistry.start', () => {
 })
 
 describe('LocalJobRegistry reads and settlement', () => {
-  it('stream kinds read a consuming delta; terminal reads mark reported', async () => {
+  it('read consumes the ring from the model cursor and advances it; readAt never moves it', async () => {
     const ctx = await harness()
-    const chunks = ['first', '', 'rest']
-    const p = producer({ readOutput: () => chunks.shift() ?? '' })
+    const p = producer()
     const id = ctx.jobs.start(p.spec)
+    const jobs = ctx.jobs
+    p.job().append('first', { channel: 'stdout' })
+    p.job().append('err', { channel: 'stderr' })
 
-    expect(ctx.jobs.read(id)).toMatchObject({ text: 'first', snapshot: { status: 'running', reported: false } })
-    expect(ctx.jobs.read(id).text).toBe('')
+    const first = jobs.read(id)
+    expect(first.chunks).toEqual([{ at: 0, text: 'first', channel: 'stdout' }, { at: 5, text: 'err', channel: 'stderr' }])
+    expect(first.lossy).toBe(false)
+    expect(first.result).toBeUndefined()
+    expect(first.job).toMatchObject({ status: 'running', output: { total: 8, earliest: 0 } })
+    expect(jobs.read(id).chunks).toEqual([])
 
-    p.settle({ status: 'completed', detail: 'exit code: 0' })
-    await tick()
-    const read = ctx.jobs.read(id)
-    expect(read.text).toBe('rest')
-    expect(read.snapshot).toMatchObject({ status: 'completed', detail: 'exit code: 0', reported: true })
-    expect(read.snapshot.finishedAt).toBeTypeOf('number')
+    // A non-consuming read from the head sees everything again, and leaves the cursor alone.
+    expect(jobs.readAt(id, 0).chunks).toHaveLength(2)
+    p.job().append('rest')
+    expect(jobs.read(id).chunks).toEqual([{ at: 8, text: 'rest' }])
   })
 
-  it('projects a producer-owned model output limit into reads and snapshots', async () => {
-    const ctx = await harness()
-    const p = producer({ outputLimitBytes: 64, readOutput: () => 'delta' })
-    const id = ctx.jobs.start(p.spec)
-    expect(ctx.jobs.read(id)).toMatchObject({
-      text: 'delta', snapshot: { outputLimitBytes: 64 },
-    })
-    expect(ctx.jobs.get(id)).toMatchObject({ outputLimitBytes: 64 })
-  })
-
-  it('final-output kinds read empty while live, the outcome output idempotently once settled', async () => {
+  it('hands the producer result out once, on the first read after settlement', async () => {
     const ctx = await harness()
     const p = producer({ kind: 'subagent', label: 'research job' })
     const id = ctx.jobs.start(p.spec)
+    const jobs = ctx.jobs
+    expect(jobs.read(id)).toMatchObject({ chunks: [], job: { status: 'running' } })
 
-    expect(ctx.jobs.read(id)).toMatchObject({ text: '', snapshot: { status: 'running' } })
-
-    p.settle({ status: 'completed', output: 'final answer' })
+    p.settle({ status: 'completed', result: 'final answer' })
     await tick()
-    expect(ctx.jobs.read(id).text).toBe('final answer')
-    expect(ctx.jobs.read(id).text).toBe('final answer') // idempotent, not consumed
+    const read = jobs.read(id)
+    expect(read.result).toBe('final answer')
+    expect(read.job).toMatchObject({ status: 'completed' })
+    expect(read.job.finishedAt).toBeTypeOf('number')
+    expect(jobs.read(id).result).toBeUndefined()
   })
 
-  it('a settled job without output reads as empty text', async () => {
+  it('a settled job without a result reads as empty', async () => {
     const ctx = await harness()
     const p = producer({ kind: 'subagent' })
     const id = ctx.jobs.start(p.spec)
     p.settle({ status: 'failed', detail: 'max-tokens' })
     await tick()
-    expect(ctx.jobs.read(id)).toMatchObject({ text: '', snapshot: { status: 'failed', detail: 'max-tokens' } })
+    expect(ctx.jobs.read(id)).toMatchObject({ chunks: [], job: { status: 'failed', detail: 'max-tokens' } })
+  })
+
+  it('projects a producer-owned model output limit into views', async () => {
+    const ctx = await harness()
+    const p = producer({ outputLimitBytes: 64 })
+    const id = ctx.jobs.start(p.spec)
+    expect(ctx.jobs.get(id)).toMatchObject({ outputLimitBytes: 64 })
+    expect(ctx.jobs.read(id).job).toMatchObject({ outputLimitBytes: 64 })
   })
 
   it('throws for unknown job ids', async () => {
     const ctx = await harness()
     expect(() => ctx.jobs.read(JobId('bash-99'))).toThrow('unknown job bash-99')
+    expect(() => ctx.jobs.get(JobId('bash-99'))).toThrow('unknown job bash-99')
   })
 
-  it('notifies onJobDone once per job with containment across listeners', async () => {
+  it('announces settlement once with containment across listeners', async () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(() => { throw new Error('listener boom') })
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    ctx.jobs.events.subscribe({ owners: 'all' }, () => { throw new Error('listener boom') })
+    const seen = collect(ctx, { owners: 'all' }, ['settled'])
 
     const p = producer()
     const id = ctx.jobs.start(p.spec)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
-    expect(seen).toHaveLength(1)
-    expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false })
+    expect(seen).toMatchObject([{ type: 'settled', cause: 'producer', job: { id, status: 'completed', detail: 'exit code: 0' } }])
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('listener boom'))
   })
 
-  it('contains a rejecting onJobDone listener without starving later listeners', async () => {
-    const ctx = await harness()
-    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const seen: JobId[] = []
-    ctx.jobs.onJobDone(async () => { throw new Error('async listener boom') })
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot.id))
-
-    const p = producer()
-    const id = ctx.jobs.start(p.spec)
-    p.settle({ status: 'completed' })
-    await tick()
-
-    expect(seen).toEqual([id])
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('onJobDone listener rejected'))
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('async listener boom'))
-  })
-
   it("contains rejection from the producer's done promise as a failed outcome (producer contract violation)", async () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
@@ -368,19 +403,19 @@ describe('LocalJobRegistry reads and settlement', () => {
     p.reject(new Error('transport exploded'))
     await tick()
 
-    expect(ctx.jobs.read(id).snapshot).toMatchObject({ status: 'failed', detail: 'Error: transport exploded' })
+    expect(ctx.jobs.get(id)).toMatchObject({ status: 'failed', detail: 'Error: transport exploded' })
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('producer contract violation'))
   })
 
-  it('unregisters onJobDone listeners with the contributing fiber (HMR safety)', async () => {
+  it('unregisters event listeners with the contributing fiber (HMR safety)', async () => {
     const ctx = await harness()
     const seen: string[] = []
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      inner.jobs.onJobDone(snapshot => void seen.push(snapshot.id))
+      inner.jobs.events.subscribe({ owners: 'all' }, event => void seen.push(event.type))
     }, { inject: ['jobs'] }))
     await fiber.dispose()
     // The returned disposer detaches too (the non-fiber path).
-    const detach = ctx.jobs.onJobDone(snapshot => void seen.push(snapshot.id))
+    const detach = ctx.jobs.events.subscribe({ owners: 'all' }, event => void seen.push(event.type))
     detach()
 
     const p = producer()
@@ -392,22 +427,39 @@ describe('LocalJobRegistry reads and settlement', () => {
 })
 
 describe('LocalJobRegistry.kill', () => {
-  it('cancels a live job with the forwarded reason and suppresses the notice', async () => {
+  it('cancels a live job with the forwarded reason and settles with cause kill', async () => {
     const ctx = await harness()
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const seen = collect(ctx, { owners: 'all' }, ['stopping', 'settled'])
     const p = producer()
     const id = ctx.jobs.start(p.spec)
 
     expect(ctx.jobs.kill(id, undefined, 'no longer needed')).toBe('requested')
     expect(p.cancels).toEqual(['no longer needed'])
-    expect(ctx.jobs.list()[0]).toMatchObject({ status: 'stopping', reported: true })
+    expect(ctx.jobs.list()[0]).toMatchObject({ status: 'stopping' })
+    expect(seen).toMatchObject([{ type: 'stopping', job: { id, status: 'stopping' } }])
 
-    p.settle({ status: 'killed' })
+    p.settle({ status: 'killed', detail: 'signal: SIGTERM' })
     await tick()
-    // The listener still fires (telemetry may care), but carries reported: true
-    // so the notice path suppresses its redundant "finished".
-    expect(seen[0]).toMatchObject({ id, status: 'killed', reported: true })
+    expect(seen[1]).toMatchObject({
+      type: 'settled',
+      cause: 'kill',
+      job: { id, status: 'killed', detail: 'signal: SIGTERM; no longer needed' },
+    })
+  })
+
+  it('merges a reason without producer detail and keeps producer detail alone when the job outran the kill', async () => {
+    const ctx = await harness()
+    const killed = producer()
+    const killedId = ctx.jobs.start(killed.spec)
+    ctx.jobs.kill(killedId, undefined, 'cancelled by the user')
+    killed.settle({ status: 'killed' })
+    const outran = producer()
+    const outranId = ctx.jobs.start(outran.spec)
+    ctx.jobs.kill(outranId, undefined, 'too late')
+    outran.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+    expect(ctx.jobs.get(killedId).detail).toBe('cancelled by the user')
+    expect(ctx.jobs.get(outranId).detail).toBe('exit code: 0')
   })
 
   it('reports an already-finished job instead of failing', async () => {
@@ -421,8 +473,7 @@ describe('LocalJobRegistry.kill', () => {
 
   it('propagates a throwing producer cancel and leaves the job untouched', async () => {
     const ctx = await harness()
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const seen = collect(ctx, { owners: 'all' }, ['stopping', 'settled'])
     let broken = true
     let settle!: (outcome: JobOutcome) => void
     const id = ctx.jobs.start({
@@ -434,12 +485,13 @@ describe('LocalJobRegistry.kill', () => {
       }),
     })
     expect(() => ctx.jobs.kill(id)).toThrow('cancel boom')
-    // The failed kill mutated NOTHING: still running, notice not suppressed,
-    // and a later (successful) kill still works.
-    expect(ctx.jobs.get(id)).toMatchObject({ status: 'running', reported: false })
+    // The failed kill mutated NOTHING: still running, and the settlement
+    // still reports the producer as its cause.
+    expect(ctx.jobs.get(id)).toMatchObject({ status: 'running' })
+    expect(seen).toEqual([])
     settle({ status: 'completed' })
     await tick()
-    expect(seen[0]).toMatchObject({ id, reported: false }) // notice would still fire
+    expect(seen).toMatchObject([{ type: 'settled', cause: 'producer', job: { id } }])
 
     broken = false
     expect(ctx.jobs.kill(id)).toBe('already-finished')
@@ -447,24 +499,26 @@ describe('LocalJobRegistry.kill', () => {
 })
 
 describe('LocalJobRegistry.wait', () => {
-  it('resolves with the terminal snapshot when the job settles, marked reported', async () => {
+  it('resolves with the terminal projection when the job settles, before the settled event', async () => {
     const ctx = await harness()
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const order: string[] = []
+    ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { if (event.type === 'settled') order.push('event') })
     const p = producer()
     const id = ctx.jobs.start(p.spec)
 
-    const wait = ctx.jobs.wait(id, 5_000)
+    const wait = ctx.jobs.wait(id, 5_000).then((view) => { order.push('wait'); return view })
     p.settle({ status: 'completed', detail: 'exit code: 0' })
-    expect(await wait).toMatchObject({ status: 'completed', reported: true })
-    // A waiting reader claims delivery before completion listeners inspect the snapshot.
-    expect(seen[0]).toMatchObject({ id, reported: true })
+    expect(await wait).toMatchObject({ status: 'completed' })
+    // Waiters are released synchronously inside the settlement, ahead of the
+    // event; their continuations run afterwards, which is why a claim made
+    // when the wait starts (not when it returns) is what stays ordered.
+    expect(order).toEqual(['event', 'wait'])
   })
 
-  it('returns the live snapshot on timeout without marking reported', async () => {
+  it('returns the live projection on timeout', async () => {
     const ctx = await harness()
     const id = ctx.jobs.start(producer().spec)
-    expect(await ctx.jobs.wait(id, 5)).toMatchObject({ status: 'running', reported: false })
+    expect(await ctx.jobs.wait(id, 5)).toMatchObject({ status: 'running' })
   })
 
   it('unregisters timed-out and aborted wait resolvers while the job remains live', async () => {
@@ -493,7 +547,7 @@ describe('LocalJobRegistry.wait', () => {
     const id = ctx.jobs.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
-    expect(await ctx.jobs.wait(id, 5_000)).toMatchObject({ status: 'completed', reported: true })
+    expect(await ctx.jobs.wait(id, 5_000)).toMatchObject({ status: 'completed' })
   })
 
   it('rejects a non-positive or non-finite timeout', async () => {
@@ -518,79 +572,70 @@ describe('LocalJobRegistry.wait', () => {
     await expect(ctx.jobs.wait(id, 5_000, undefined, preAborted.signal)).rejects.toThrow('wait aborted')
   })
 
-  it('an abort racing settlement in the same tick does not swallow the notice', async () => {
+  it('an abort racing settlement in the same tick rejects the wait and leaves the settlement intact', async () => {
     const ctx = await harness()
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const seen = collect(ctx, { owners: 'all' }, ['settled'])
     const p = producer()
     const id = ctx.jobs.start(p.spec)
 
     const controller = new AbortController()
     const wait = ctx.jobs.wait(id, 5_000, undefined, controller.signal)
-    // Settlement is queued first, so abort must remove the waiter synchronously;
-    // otherwise settlement suppresses the notice for a reader that receives nothing.
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     controller.abort()
     await expect(wait).rejects.toThrow('wait aborted')
-    expect(seen).toHaveLength(1)
-    expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false })
+    expect(seen).toMatchObject([{ type: 'settled', cause: 'producer', job: { id, status: 'completed' } }])
   })
 
-  it('an abort landing after settlement still delivers the terminal snapshot it owes', async () => {
+  it('an abort landing after settlement still delivers the terminal projection it owes', async () => {
     const ctx = await harness()
     const controller = new AbortController()
-    const seen: JobSnapshot[] = []
     // The listener aborts after settlement released this waiter but before its
     // resolve microtask runs. Releasing waiters ahead of the announcement is
     // what makes that abort harmless; this is the guard on that ordering.
-    ctx.jobs.onJobDone((snapshot) => {
-      seen.push(snapshot)
-      controller.abort()
-    })
+    ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { if (event.type === 'settled') controller.abort() })
     const p = producer()
     const id = ctx.jobs.start(p.spec)
 
     const wait = ctx.jobs.wait(id, 5_000, undefined, controller.signal)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
-    await expect(wait).resolves.toMatchObject({ status: 'completed', reported: true })
-    expect(seen[0]).toMatchObject({ id, reported: true }) // suppression stays honest: the wait delivered
+    await expect(wait).resolves.toMatchObject({ status: 'completed' })
   })
 })
 
 describe('LocalJobRegistry owner isolation', () => {
-  it('fences read/kill/wait to the owning session and keeps unowned jobs open', async () => {
+  it('fences every view operation to the owning session and keeps unowned jobs open', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'owner')
     const other = stubAgent(ctx, 'other')
 
     const owned = ctx.jobs.start(producer({ owner }).spec)
     const open = ctx.jobs.start(producer().spec)
 
     // The owner and the unowned job are reachable.
-    expect(ctx.jobs.read(owned, owner).snapshot.id).toBe(owned)
-    expect(ctx.jobs.read(open, other).snapshot.id).toBe(open)
+    expect(ctx.jobs.read(owned, owner.id).job.id).toBe(owned)
+    expect(ctx.jobs.read(open, other.id).job.id).toBe(open)
 
-    // A different session and a no-agent caller are rejected.
-    expect(() => ctx.jobs.read(owned, other)).toThrow(`job ${owned} belongs to another session`)
-    expect(() => ctx.jobs.kill(owned, other)).toThrow('belongs to another session')
-    await expect(ctx.jobs.wait(owned, 10, other)).rejects.toThrow('belongs to another session')
+    // A different session and an anonymous caller are rejected.
+    const foreign = ctx.jobs
+    expect(() => foreign.read(owned, other.id)).toThrow(`job ${owned} belongs to another session`)
+    expect(() => foreign.get(owned, other.id)).toThrow('belongs to another session')
+    expect(() => foreign.readAt(owned, 0, other.id)).toThrow('belongs to another session')
+    expect(() => foreign.kill(owned, other.id)).toThrow('belongs to another session')
+    await expect(foreign.wait(owned, 10, other.id)).rejects.toThrow('belongs to another session')
     expect(() => ctx.jobs.read(owned)).toThrow('belongs to another session')
   })
 
   it('list() shows only caller-owned plus unowned jobs', async () => {
     const ctx = await harness()
-    const alice = stubAgent(ctx, 'alice')
-    const bob = stubAgent(ctx, 'bob')
-    await ctx.agents.register(alice)
-    await ctx.agents.register(bob)
+    const alice = await liveAgent(ctx, 'alice')
+    const bob = await liveAgent(ctx, 'bob')
 
     const aliceTask = ctx.jobs.start(producer({ owner: alice }).spec)
     const bobTask = ctx.jobs.start(producer({ owner: bob }).spec)
     const openTask = ctx.jobs.start(producer({ kind: 'subagent' }).spec)
 
-    expect(ctx.jobs.list(alice).map(t => t.id)).toEqual([aliceTask, openTask])
-    expect(ctx.jobs.list(bob).map(t => t.id)).toEqual([bobTask, openTask])
+    expect(ctx.jobs.list(alice.id).map(t => t.id)).toEqual([aliceTask, openTask])
+    expect(ctx.jobs.list(bob.id).map(t => t.id)).toEqual([bobTask, openTask])
     expect(ctx.jobs.list().map(t => t.id)).toEqual([openTask])
   })
 
@@ -598,30 +643,30 @@ describe('LocalJobRegistry owner isolation', () => {
     const ctx = new Context()
     await ctx.plugin(LocalJobRegistry)
     ctx.jobs.attachController('test-controller')
-    expect(() => ctx.jobs.start(producer({ owner: stubAgent(ctx, 'a') }).spec))
+    expect(() => ctx.jobs.start({ ...producer().spec, owner: SessionId('a') }))
       .toThrow('background job ownership requires the agent registry')
     // The failed registration mutated nothing: no stored job, counter untouched.
     expect(ctx.jobs.list()).toEqual([])
     expect(ctx.jobs.start(producer().spec)).toBe('bash-1')
   })
 
-  it('a failed owner-cleanup attach leaves the registry unchanged and does not poison the owner', async () => {
+  it('rejects a session without a live agent and attaches cleanup once it has one', async () => {
     const ctx = await harness()
     const ghost = stubAgent(ctx, 'ghost') // never registered in ctx.agents
 
-    // Exact-instance validation precedes registry mutation and cleanup attachment.
+    // Owner resolution precedes registry mutation and cleanup attachment.
     expect(() => ctx.jobs.start(producer({ owner: ghost }).spec))
-      .toThrow('is not the registered agent instance')
-    expect(ctx.jobs.list(ghost)).toEqual([])
+      .toThrow('has no live agent')
+    expect(ctx.jobs.list(ghost.id)).toEqual([])
 
-    // A later valid registration must still attach cleanup for the same object.
+    // A later valid registration must still attach cleanup for the live instance.
     await ctx.agents.register(ghost)
     const cancels: (string | undefined)[] = []
     let settle!: (outcome: JobOutcome) => void
     const id = ctx.jobs.start({
       kind: 'bash',
       label: 'after retry',
-      owner: ghost,
+      owner: ghost.id,
       run: () => ({
         cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
         done: new Promise<JobOutcome>((res) => { settle = res }),
@@ -630,42 +675,37 @@ describe('LocalJobRegistry owner isolation', () => {
     expect(id).toBe('bash-1') // the failed attempt burned no counter
     await disposeAgentScope(ghost)
     expect(cancels).toEqual(['owner disposed'])
-    expect(ctx.jobs.list(ghost)).toEqual([])
+    expect(ctx.jobs.list(ghost.id)).toEqual([])
   })
 
-  it('rejects a stale owner instance after another agent reuses its id', async () => {
+  it('binds a session id to the agent that is live now, and reads stay keyed by that id', async () => {
     const ctx = await harness()
     const staleOwner = stubAgent(ctx, 'owner')
     const unregisterStale = await ctx.agents.register(staleOwner)
     await unregisterStale()
-
     const currentOwner = stubAgent(ctx, 'owner')
     await ctx.agents.register(currentOwner)
-    const current = producer({ owner: currentOwner })
-    ctx.jobs.start(current.spec) // Attach the current owner's cleanup first.
 
-    const stale = producer({ owner: staleOwner })
-    const staleRun = vi.fn(() => stale.spec.run())
-    expect(() => ctx.jobs.start({ ...stale.spec, run: staleRun }))
-      .toThrow('is not the registered agent instance')
-    expect(staleRun).not.toHaveBeenCalled()
-    // Access is keyed by the unified session id, so a reconnect carrying the
-    // same identity can observe the current job even though stale ownership
-    // registration is rejected by exact-instance validation.
-    expect(ctx.jobs.list(staleOwner)).toHaveLength(1)
-    expect(ctx.jobs.list(currentOwner)).toHaveLength(1)
+    const current = producer({ owner: currentOwner })
+    const id = ctx.jobs.start(current.spec)
+    // The stale instance shares the id, so the fence lets it read; ownership
+    // (and therefore teardown) belongs to the live instance.
+    expect(ctx.jobs.get(id, staleOwner.id).owner).toBe(currentOwner.id)
+    await disposeAgentScope(staleOwner)
+    expect(ctx.jobs.list(currentOwner.id)).toHaveLength(1)
 
     current.settle({ status: 'completed' })
     await tick()
     await disposeAgentScope(currentOwner)
+    expect(ctx.jobs.list(currentOwner.id)).toEqual([])
   })
 })
 
 describe('LocalJobRegistry owner cleanup', () => {
-  it('drains the owner: cancels live jobs, awaits settlement, drops snapshots', async () => {
+  it('drains the owner: cancels live jobs, awaits settlement, removes the rows', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'owner')
+    const seen = collect(ctx, { owner: owner.id }, ['removed'])
 
     // The producer settles only when cancelled — models a child that stops on request.
     let settle!: (outcome: JobOutcome) => void
@@ -673,7 +713,7 @@ describe('LocalJobRegistry owner cleanup', () => {
     ctx.jobs.start({
       kind: 'subagent',
       label: 'long research',
-      owner,
+      owner: owner.id,
       run: () => ({
         cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
         done: new Promise<JobOutcome>((res) => { settle = res }),
@@ -686,59 +726,33 @@ describe('LocalJobRegistry owner cleanup', () => {
 
     await disposeAgentScope(owner)
     expect(cancels).toEqual(['owner disposed'])
-    // Snapshots dropped: nothing of the owner's remains, listing is empty.
-    expect(ctx.jobs.list(owner)).toEqual([])
+    expect(ctx.jobs.list(owner.id)).toEqual([])
+    expect(seen.map(event => event.type === 'removed' ? event.job.id : undefined)).toEqual(['subagent-1', 'bash-1'])
   })
 
-  it('publishes the settled visible set before announcing completion', async () => {
+  it('announces teardown settlements with cause teardown', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
-    const p = producer({ owner })
-    ctx.jobs.start(p.spec)
-    // Registered after start so only the settlement's notifications are ordered.
-    const order: string[] = []
-    ctx.jobs.onJobsChanged(() => void order.push('changed'))
-    ctx.jobs.onJobDone(() => void order.push('done'))
-
-    p.settle({ status: 'completed' })
-    await tick()
-
-    // A completion reporter may open a turn synchronously. Announcing before
-    // the visible set is published would let a client render that turn while
-    // its job row still reads `running`.
-    expect(order).toEqual(['changed', 'done'])
-  })
-
-  it('reports a teardown-cancelled record so completion reporters stay quiet', async () => {
-    const ctx = await harness()
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const owner = await liveAgent(ctx, 'owner')
+    const seen = collect(ctx, { owners: 'all' }, ['settled'])
 
     let settle!: (outcome: JobOutcome) => void
     ctx.jobs.start({
       kind: 'subagent',
       label: 'long research',
-      owner,
+      owner: owner.id,
       run: () => ({
         cancel() { settle({ status: 'killed' }) },
         done: new Promise<JobOutcome>((res) => { settle = res }),
       }),
     })
 
-    // Observers still receive the terminal record; the report bit is what
-    // keeps a notice reporter from addressing an owner being destroyed.
     await disposeAgentScope(owner)
-    expect(seen).toHaveLength(1)
-    expect(seen[0]?.reported).toBe(true)
+    expect(seen).toMatchObject([{ type: 'settled', cause: 'teardown', job: { status: 'killed' } }])
   })
 
   it('attaches one cleanup per owner and drains all owned jobs with the scope', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'owner')
 
     const first = producer({ owner })
     const second = producer({ owner })
@@ -749,21 +763,21 @@ describe('LocalJobRegistry owner cleanup', () => {
     await tick()
     expect(owner.ctx.fiber.getEffects().filter(effect => effect.label === 'jobs.ownerCleanup()')).toHaveLength(1)
     await disposeAgentScope(owner)
-    expect(ctx.jobs.list(owner)).toEqual([])
+    expect(ctx.jobs.list(owner.id)).toEqual([])
   })
 
-  it('does not let an old scope cleanup cancel a same-id/session replacement job', async () => {
+  it('does not let an old scope cleanup cancel a same-session replacement job', async () => {
     const ctx = await harness()
     const oldOwner = stubAgent(ctx, 'owner')
     const detachOld = await ctx.agents.register(oldOwner)
     const cancels: string[] = []
 
-    function start(owner: Agent, label: string): JobId {
+    function start(label: string): JobId {
       let settle!: (outcome: JobOutcome) => void
       return ctx.jobs.start({
         kind: 'bash',
         label,
-        owner,
+        owner: SessionId('owner'),
         run: () => ({
           cancel() { cancels.push(label); settle({ status: 'killed' }) },
           done: new Promise<JobOutcome>((resolve) => { settle = resolve }),
@@ -771,15 +785,15 @@ describe('LocalJobRegistry owner cleanup', () => {
       })
     }
 
-    start(oldOwner, 'old job')
+    start('old job')
     await detachOld()
     const replacement = stubAgent(ctx, 'owner')
     await ctx.agents.register(replacement)
-    const replacementId = start(replacement, 'replacement job')
+    const replacementId = start('replacement job')
 
     await disposeAgentScope(oldOwner)
     expect(cancels).toEqual(['old job'])
-    expect(ctx.jobs.list(replacement).map(job => job.id)).toEqual([replacementId])
+    expect(ctx.jobs.list(replacement.id).map(job => job.id)).toEqual([replacementId])
 
     await disposeAgentScope(replacement)
     expect(cancels).toEqual(['old job', 'replacement job'])
@@ -790,8 +804,7 @@ describe('LocalJobRegistry owner cleanup', () => {
     await ctx.plugin(AgentRegistry)
     const tasksFiber = await ctx.plugin(LocalJobRegistry)
     ctx.jobs.attachController('test-controller')
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'owner')
     const ownerCleanupEffects = () => owner.ctx.fiber.getEffects()
       .filter(effect => effect.label === 'jobs.ownerCleanup()')
 
@@ -808,22 +821,19 @@ describe('LocalJobRegistry owner cleanup', () => {
     expect(ownerCleanupEffects()).toHaveLength(0)
     expect(ctx.get('jobs')).toBeDefined()
     expect(tasksFiber.getEffects().some(effect => effect.label === 'jobs teardown')).toBe(true)
-
   })
 
   it('force-fails a throwing teardown cancel without awaiting producer done, first outcome wins', async () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const owner = await liveAgent(ctx, 'owner')
+    const seen = collect(ctx, { owners: 'all' }, ['settled'])
 
     let settle!: (outcome: JobOutcome) => void
     ctx.jobs.start({
       kind: 'bash',
       label: 'broken producer',
-      owner,
+      owner: owner.id,
       run: () => ({
         cancel() { throw new Error('cancel boom') },
         done: new Promise<JobOutcome>((res) => { settle = res }),
@@ -848,24 +858,27 @@ describe('LocalJobRegistry owner cleanup', () => {
     expect(drainedWithoutProducerDone).toBe(true)
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned'))
     expect(seen).toHaveLength(1)
-    expect(seen[0]?.status).toBe('failed')
-    expect(seen[0]?.detail).toContain('cancel threw during teardown')
-    expect(ctx.jobs.list(owner)).toEqual([])
+    expect(seen[0]).toMatchObject({ cause: 'teardown', job: { status: 'failed' } })
+    expect((seen[0] as { job: JobView }).job.detail).toContain('cancel threw during teardown')
+    expect(ctx.jobs.list(owner.id)).toEqual([])
   })
 })
 
 describe('LocalJobRegistry disposal', () => {
-  it('cancels live jobs, awaits settlement, and silences listeners', async () => {
+  it('cancels live jobs, awaits settlement, and announces the teardown to outside subscribers', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     const fiber = await ctx.plugin(LocalJobRegistry)
-    const controller = await ctx.plugin(Object.assign((inner: Context) => {
+    await ctx.plugin(Object.assign((inner: Context) => {
       inner.jobs.attachController('test-controller')
     }, { inject: ['jobs'] }))
-    void controller
 
+    // A subscriber outside the registry's fiber is still listening when the
+    // registry unloads: it must see the rows leave, not keep them forever.
     const seen: string[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot.id))
+    ctx.jobs.events.subscribe({ owners: 'all' }, (event) => {
+      seen.push(event.type === 'settled' ? `settled:${event.cause}` : event.type)
+    })
     let settle!: (outcome: JobOutcome) => void
     const cancels: (string | undefined)[] = []
     ctx.jobs.start({
@@ -879,8 +892,7 @@ describe('LocalJobRegistry disposal', () => {
 
     await fiber.dispose()
     expect(cancels).toEqual(['jobs service disposed'])
-    // The teardown kill settles AFTER the listener registry closed: silent.
-    expect(seen).toEqual([])
+    expect(seen).toEqual(['registered', 'stopping', 'settled:teardown', 'output', 'removed'])
   })
 
   it('force-fails a throwing cancel so service disposal does not await producer done', async () => {
@@ -889,8 +901,7 @@ describe('LocalJobRegistry disposal', () => {
     const fiber = await ctx.plugin(LocalJobRegistry)
     ctx.jobs.attachController('test-controller')
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const seen: JobSnapshot[] = []
-    ctx.jobs.onJobDone(snapshot => void seen.push(snapshot))
+    const seen = collect(ctx, { owners: 'all' }, ['settled'])
 
     let settle!: (outcome: JobOutcome) => void
     ctx.jobs.start({
@@ -918,7 +929,7 @@ describe('LocalJobRegistry disposal', () => {
 
     expect(disposedWithoutProducerDone).toBe(true)
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned'))
-    expect(seen).toEqual([])
+    expect(seen).toMatchObject([{ type: 'settled', cause: 'teardown', job: { status: 'failed' } }])
   })
 
   it('detaches owner effects from still-live agent scopes when the service unloads', async () => {
@@ -926,13 +937,12 @@ describe('LocalJobRegistry disposal', () => {
     await ctx.plugin(AgentRegistry)
     const tasksFiber = await ctx.plugin(LocalJobRegistry)
     ctx.jobs.attachController('test-controller')
-    const owner = stubAgent(ctx, 'owner')
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'owner')
     let settle!: (outcome: JobOutcome) => void
     ctx.jobs.start({
       kind: 'bash',
       label: 'owned work',
-      owner,
+      owner: owner.id,
       run: () => ({
         cancel() { settle({ status: 'killed' }) },
         done: new Promise<JobOutcome>((resolve) => { settle = resolve }),
@@ -958,11 +968,10 @@ describe('LocalJobRegistry disposal', () => {
       inject: ['jobs'],
       apply(pluginCtx: Context) {
         pluginCtx.jobs.attachController('tool-jobs')
-        pluginCtx.jobs.onJobDone(() => {})
+        pluginCtx.jobs.events.subscribe({ owners: 'scope' }, () => {})
       },
     })
-    const owner = stubAgent(ctx, 'joined', scopeOf(standing.ctx))
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'joined', scopeOf(standing.ctx))
     expect(() => ctx.jobs.start(producer({ owner }).spec)).not.toThrow()
 
     await mount.dispose()
@@ -990,149 +999,415 @@ describe('LocalJobRegistry disposal', () => {
   })
 })
 
-describe('LocalJobRegistry.onJobsChanged', () => {
-  it('fires after registration, the stopping transition, and settlement', async () => {
+describe('LocalJobRegistry events', () => {
+  it('announces registration, progress, stopping, and settlement with the committed projection', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'alice')
-    await ctx.agents.register(owner)
-    const seen: (string | undefined)[] = []
-    ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id))
+    const owner = await liveAgent(ctx, 'alice')
+    const seen = collect(ctx, { owner: owner.id }, ['registered', 'progress', 'stopping', 'settled'])
 
     const p = producer({ owner })
     const id = ctx.jobs.start(p.spec)
     // Registration is announced only once the record is readable.
-    expect(seen).toEqual(['alice'])
-    expect(ctx.jobs.list(owner)).toHaveLength(1)
+    expect(seen).toMatchObject([{ type: 'registered', job: { id, owner: 'alice', status: 'running' } }])
+    expect(ctx.jobs.list(owner.id)).toHaveLength(1)
 
-    expect(ctx.jobs.kill(id, owner)).toBe('requested')
-    expect(seen).toEqual(['alice', 'alice'])
-    expect(ctx.jobs.get(id, owner).status).toBe('stopping')
+    p.job().updateProgress('3/10')
+    expect(seen[1]).toMatchObject({ type: 'progress', job: { id, progress: '3/10' } })
+
+    expect(ctx.jobs.kill(id, owner.id)).toBe('requested')
+    expect(seen[2]).toMatchObject({ type: 'stopping', job: { id, status: 'stopping', progress: '3/10' } })
 
     p.settle({ status: 'killed' })
     await tick()
-    expect(seen).toEqual(['alice', 'alice', 'alice'])
-    expect(ctx.jobs.get(id, owner).status).toBe('killed')
+    const settled = seen[3] as { job: JobView }
+    expect(seen[3]).toMatchObject({ type: 'settled', cause: 'kill', job: { id, status: 'killed' } })
+    expect(settled.job.progress).toBeUndefined()
     await disposeAgentScope(owner)
   })
 
-  it('reports an unowned change as undefined, since every caller can see it', async () => {
+  it('announces an unowned job to every session filter, since every caller can see it', async () => {
     const ctx = await harness()
-    const seen: (string | undefined)[] = []
-    ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id))
-
+    const seen = collect(ctx, { owner: SessionId('anyone') }, ['registered'])
     ctx.jobs.start(producer().spec)
-    expect(seen).toEqual([undefined])
+    expect(seen).toMatchObject([{ type: 'registered', job: { id: 'bash-1' } }])
+    expect((seen[0] as { job: JobView }).job.owner).toBeUndefined()
   })
 
   it('announces the owner-disposal removal, and stays silent when that owner had none', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'alice')
-    const bystander = stubAgent(ctx, 'bob')
-    await ctx.agents.register(owner)
-    await ctx.agents.register(bystander)
+    const owner = await liveAgent(ctx, 'alice')
+    const bystander = await liveAgent(ctx, 'bob')
     const p = producer({ owner })
     ctx.jobs.start(p.spec)
 
-    const seen: (string | undefined)[] = []
-    ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id))
+    const seen = collect(ctx, { owners: 'all' }, ['settled', 'removed'])
     p.settle({ status: 'completed' })
     await tick()
-    expect(seen).toEqual(['alice'])
+    expect(seen.map(event => event.type)).toEqual(['settled'])
 
     // Disposing an owner with no records changes no visible set.
     await disposeAgentScope(bystander)
-    expect(seen).toEqual(['alice'])
+    expect(seen.map(event => event.type)).toEqual(['settled'])
 
     await disposeAgentScope(owner)
-    expect(seen).toEqual(['alice', 'alice'])
-    expect(ctx.jobs.list(owner)).toEqual([])
+    expect(seen.map(event => event.type)).toEqual(['settled', 'removed'])
+    expect(ctx.jobs.list(owner.id)).toEqual([])
   })
 
   it('contains a throwing listener so the lifecycle commit still stands', async () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
-    const seen: (string | undefined)[] = []
-    ctx.jobs.onJobsChanged(() => { throw new Error('observer boom') })
-    ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id))
+    ctx.jobs.events.subscribe({ owners: 'all' }, () => { throw new Error('observer boom') })
+    const seen = collect(ctx, { owners: 'all' }, ['registered'])
 
     const id = ctx.jobs.start(producer().spec)
     expect(id).toBe('bash-1')
-    expect(seen).toEqual([undefined])
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('onJobsChanged listener threw'))
+    expect(seen).toHaveLength(1)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('event listener threw on registered'))
   })
 
-  it('unregisters through its disposer and with its fiber (HMR safety)', async () => {
-    const ctx = await harness()
-    const seen: number[] = []
-    const detach = ctx.jobs.onJobsChanged(() => void seen.push(1))
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      inner.jobs.onJobsChanged(() => void seen.push(2))
-    }, { inject: ['jobs'] }))
-
-    ctx.jobs.start(producer().spec)
-    expect(seen).toEqual([1, 2])
-
-    detach()
-    detach() // second call of the same disposer is a no-op
-    ctx.jobs.start(producer().spec)
-    expect(seen).toEqual([1, 2, 2])
-
-    await fiber.dispose()
-    ctx.jobs.start(producer().spec)
-    expect(seen).toEqual([1, 2, 2])
-  })
-})
-
-describe('LocalJobRegistry teardown change notifications', () => {
   it('announces the stopping transition during owner teardown, before settlement', async () => {
     const ctx = await harness()
-    const owner = stubAgent(ctx, 'alice')
-    await ctx.agents.register(owner)
+    const owner = await liveAgent(ctx, 'alice')
     const p = producer({ owner })
-    const id = ctx.jobs.start(p.spec)
+    ctx.jobs.start(p.spec)
 
-    const statuses: (string | undefined)[] = []
-    ctx.jobs.onJobsChanged((changed) => {
-      statuses.push(changed === undefined ? undefined : ctx.jobs.list(changed)[0]?.status)
+    const statuses: string[] = []
+    ctx.jobs.events.subscribe({ owner: owner.id }, (event) => {
+      if (event.type !== 'output') statuses.push(`${event.type}:${event.job.status}`)
     })
 
     // A slow producer keeps teardown parked between cancel and settlement;
     // an observer must not be left showing `running` for that whole window.
     const disposal = disposeAgentScope(owner)
     await tick()
-    expect(statuses).toEqual(['stopping'])
+    expect(statuses).toEqual(['stopping:stopping'])
 
     p.settle({ status: 'killed' })
     await disposal
     // Settlement, then the removal that empties the visible set.
-    expect(statuses).toEqual(['stopping', 'killed', undefined])
-    expect(ctx.jobs.list(owner)).toEqual([])
-    void id
+    expect(statuses).toEqual(['stopping:stopping', 'settled:killed', 'removed:killed'])
+    expect(ctx.jobs.list(owner.id)).toEqual([])
   })
 
-  it('announces the emptied set to a listener registered outside this service (reload safety)', async () => {
-    const ctx = new Context()
-    await ctx.plugin(AgentRegistry)
-    const fiber = await ctx.plugin(LocalJobRegistry)
-    ctx.jobs.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.
-    const seen: (string | undefined)[] = []
-    ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id))
-    let settle!: (outcome: JobOutcome) => void
-    ctx.jobs.start({
-      kind: 'bash',
-      label: 'sleep 600',
-      run: () => ({
-        cancel() { settle({ status: 'killed' }) },
-        done: new Promise<JobOutcome>((resolve) => { settle = resolve }),
-      }),
+  it('delivers scoped subscriptions to the owning composition only', async () => {
+    const ctx = await harness()
+    const mount = createScope(ctx, {})
+    const otherMount = createScope(ctx, {})
+    const alice = await liveAgent(ctx, 'alice', scopeOf(mount.ctx))
+    const bob = await liveAgent(ctx, 'bob', scopeOf(otherMount.ctx))
+    const everyone = collect(ctx, { owners: 'all' }, ['output'])
+    const scoped: string[] = []
+    await mount.ctx.plugin({
+      inject: ['jobs'],
+      apply(scopedCtx: Context) {
+        scopedCtx.jobs.events.subscribe({ owners: 'scope' }, (event) => {
+          if (event.type === 'output') scoped.push(String(event.id))
+        })
+      },
     })
-    seen.length = 0
+    const pa = producer({ owner: alice })
+    const aliceId = ctx.jobs.start(pa.spec)
+    const pb = producer({ owner: bob })
+    ctx.jobs.start(pb.spec)
+    pa.job().append('for alice observers')
+    pb.job().append('for bob observers')
+    expect(everyone).toHaveLength(2)
+    expect(scoped).toEqual([String(aliceId)])
+  })
+})
 
-    await fiber.dispose()
-    // stopping (teardown cancel), settlement, then the final empty set.
-    expect(seen).toEqual([undefined, undefined, undefined])
+describe('LocalJobRegistry output ring', () => {
+  it('appends advance absolute offsets and reach observers as output events', async () => {
+    const ctx = await harness()
+    const outputs = collect(ctx, { owners: 'all' }, ['output'])
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    p.job().append('hello ')
+    p.job().append('world', { channel: 'stderr' })
+    const first = ctx.jobs.readAt(id, 0)
+    expect(first).toEqual({
+      chunks: [{ at: 0, text: 'hello ' }, { at: 6, text: 'world', channel: 'stderr' }],
+      next: 11,
+      lossy: false,
+    })
+    // A second identical read proves nothing was consumed.
+    expect(ctx.jobs.readAt(id, 0)).toEqual(first)
+    // Resuming from `next` yields nothing until more output arrives.
+    expect(ctx.jobs.readAt(id, first.next).chunks).toEqual([])
+    p.job().append('!')
+    expect(ctx.jobs.readAt(id, first.next).chunks).toEqual([{ at: 11, text: '!' }])
+    expect(ctx.jobs.get(id).output).toEqual({ total: 12, earliest: 0 })
+    expect(outputs).toEqual([
+      { type: 'output', id, total: 6 },
+      { type: 'output', id, total: 11 },
+      { type: 'output', id, total: 12 },
+    ])
+  })
+
+  it('staged starter writes surface at the registration commit without observer signals', async () => {
+    const ctx = await harness()
+    const seen = collect(ctx)
+    let settle!: (outcome: JobOutcome) => void
+    const id = ctx.jobs.start({
+      kind: 'bash',
+      label: 'staged writes',
+      run: (job) => {
+        job.append('early ', { channel: 'stdout' })
+        job.updateProgress('booting')
+        return {
+          cancel() {},
+          done: new Promise<JobOutcome>((resolve) => { settle = resolve }),
+        }
+      },
+    })
+    // Only the registration commit announced anything.
+    expect(seen.map(event => event.type)).toEqual(['registered'])
+    const view = ctx.jobs.get(id)
+    expect(view.progress).toBe('booting')
+    expect(view.output.total).toBe(6)
+    expect(ctx.jobs.readAt(id, 0).chunks).toEqual([{ at: 0, text: 'early ', channel: 'stdout' }])
+    settle({ status: 'completed' })
+    await tick()
+  })
+
+  it('drops an empty append without waking observers', async () => {
+    const ctx = await harness()
+    const outputs = collect(ctx, { owners: 'all' }, ['output'])
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    p.job().append('')
+    expect(outputs).toEqual([])
+    expect(ctx.jobs.get(id).output.total).toBe(0)
+  })
+
+  it('rejects a negative or fractional read offset', async () => {
+    const ctx = await harness()
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    expect(() => ctx.jobs.readAt(id, -1)).toThrow(/invalid output read offset/)
+    expect(() => ctx.jobs.readAt(id, 0.5)).toThrow(/invalid output read offset/)
+    expect(() => ctx.jobs.readAt(JobId('bash-99'), 0)).toThrow(/unknown job/)
+  })
+
+  it('keeps the spill file each source currently reports as job metadata, beyond any chunk', async () => {
+    const ctx = await harness({ retainBytes: 4, pumpPollMs: 5 })
+    let withdrawn = false
+    const out: JobOutputSource = {
+      channel: 'stdout',
+      read: from => from === 0
+        ? { text: 'abcdefgh', nextOffset: 8, lossy: false, spillPath: '/spill/out.log' }
+        : { text: '', nextOffset: from, lossy: false, ...withdrawn ? {} : { spillPath: '/spill/out.log' } },
+    }
+    const err: JobOutputSource = {
+      channel: 'stderr',
+      read: from => ({ text: '', nextOffset: from, lossy: false, spillPath: '/spill/err.log' }),
+    }
+    const p = producer({ output: [out, err] })
+    const id = ctx.jobs.start(p.spec)
+    // The first drain ran inside start(): the live cap already evicted the head, yet the
+    // projection still names the files — no chunk carried them.
+    const view = ctx.jobs.get(id)
+    expect(view.output).toEqual({ total: 8, earliest: 4, spillPaths: ['/spill/out.log', '/spill/err.log'] })
+    expect(ctx.jobs.readAt(id, 0).chunks).toEqual([{ at: 4, text: 'efgh', channel: 'stdout', gapBefore: true }])
+
+    // A source that stops naming its file (a failed seal) withdraws it on the next drain.
+    withdrawn = true
+    await new Promise<void>(resolve => setTimeout(resolve, 20))
+    expect(ctx.jobs.get(id).output.spillPaths).toEqual(['/spill/err.log'])
+    p.settle({ status: 'completed' })
+    await tick()
+  })
+
+  it('announces registration before the pump drains a source that is readable at once', async () => {
+    const ctx = await harness({ pumpPollMs: 5 })
+    const events = collect(ctx)
+    const source: JobOutputSource = {
+      read: from => from === 0 ? { text: 'boot', nextOffset: 4, lossy: false } : { text: '', nextOffset: from, lossy: false },
+    }
+    const p = producer({ output: [source] })
+    const id = ctx.jobs.start(p.spec)
+    // The pump's first drain runs synchronously inside start(); the job's
+    // first event is still its registration.
+    expect(events.slice(0, 2).map(event => event.type)).toEqual(['registered', 'output'])
+    expect(ctx.jobs.readAt(id, 0).chunks.map(chunk => chunk.text)).toEqual(['boot'])
+    p.settle({ status: 'completed' })
+    await tick()
+  })
+
+  it('evicts whole head chunks past the live cap and flags stale readers lossy', async () => {
+    const ctx = await harness({ retainBytes: 8 })
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    p.job().append('aaaa')
+    p.job().append('bbbb')
+    p.job().append('cccc')
+    const read = ctx.jobs.readAt(id, 0)
+    expect(read.lossy).toBe(true)
+    expect(read.chunks).toEqual([{ at: 4, text: 'bbbb' }, { at: 8, text: 'cccc' }])
+    expect(read.next).toBe(12)
+    expect(ctx.jobs.get(id).output).toEqual({ total: 12, earliest: 4 })
+    // A reader at the retained boundary is not lossy.
+    expect(ctx.jobs.readAt(id, 4).lossy).toBe(false)
+    // The model cursor is subject to the same eviction.
+    expect(ctx.jobs.read(id).lossy).toBe(true)
+  })
+
+  it('settlement keeps the unconsumed stream for the model; the terminal read trims to the settled cap, ends the stream, and later writes drop', async () => {
+    const ctx = await harness({ retainBytes: 1024, settledRetainBytes: 4 })
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const outputs = collect(ctx, { owners: 'all' }, ['output'])
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    p.job().append('abcdefgh')
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+    expect(outputs.map(event => event.type === 'output' ? event.total : -1)).toEqual([8, 8])
+    // Nothing the model has not read is trimmed at settlement: a job that
+    // finishes before its first read still hands over everything the live
+    // cap retained, and observers see the same bytes.
+    expect(ctx.jobs.get(id)).toMatchObject({ status: 'completed', detail: 'exit code: 0', output: { total: 8, earliest: 0 } })
+    expect(ctx.jobs.readAt(id, 0)).toMatchObject({ lossy: false, chunks: [{ at: 0, text: 'abcdefgh' }] })
+    expect(ctx.jobs.read(id)).toMatchObject({ lossy: false, chunks: [{ at: 0, text: 'abcdefgh' }] })
+    // The terminal read consumed the stream: retention drops to the settled cap.
+    expect(ctx.jobs.get(id).output).toEqual({ total: 8, earliest: 4 })
+    const read = ctx.jobs.readAt(id, 0)
+    expect(read.lossy).toBe(true)
+    expect(read.chunks).toEqual([{ at: 4, text: 'efgh', gapBefore: true }])
+    // The stream ended with the settlement: a trailing flush cannot break teardown.
+    p.job().append('late')
+    p.job().updateProgress('late progress')
+    expect(warn.mock.calls.map(call => String(call[0]))).toEqual([
+      expect.stringContaining('append to settled job'),
+      expect.stringContaining('progress update on settled job'),
+    ])
+    expect(outputs).toHaveLength(2)
+    expect(ctx.jobs.get(id).progress).toBeUndefined()
+  })
+
+  it('a settlement after the model consumed the stream trims to the settled cap at once', async () => {
+    const ctx = await harness({ retainBytes: 1024, settledRetainBytes: 4 })
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    p.job().append('abcdefgh')
+    expect(ctx.jobs.read(id).chunks).toEqual([{ at: 0, text: 'abcdefgh' }])
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(ctx.jobs.get(id).output).toEqual({ total: 8, earliest: 4 })
+    // The cursor sits at the end: nothing new, and nothing lost behind it.
+    expect(ctx.jobs.read(id)).toMatchObject({ chunks: [], lossy: false })
+  })
+
+  it('settlement clears the progress line; the terminal detail is the outcome alone', async () => {
+    const ctx = await harness()
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    p.job().updateProgress('3/10 agents done')
+    expect(ctx.jobs.get(id)).toMatchObject({ progress: '3/10 agents done' })
+    p.settle({ status: 'completed' })
+    await tick()
+    const view = ctx.jobs.get(id)
+    expect(view.status).toBe('completed')
+    expect(view.progress).toBeUndefined()
+    expect(view.detail).toBeUndefined()
+  })
+
+  it('a teardown-forced settlement also ends the ring', async () => {
+    const ctx = await harness()
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const owner = await liveAgent(ctx, 'owner')
+    const p = producer({ owner })
+    const id = ctx.jobs.start(p.spec)
+    p.job().append('partial')
+    const disposal = disposeAgentScope(owner)
+    p.settle({ status: 'killed' })
+    await disposal
+    expect(() => ctx.jobs.readAt(id, 0, owner.id)).toThrow(/unknown job/)
+    // The producer face outlives the row; its trailing flush is dropped, not thrown.
+    p.job().append('late')
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('append to settled job'))
+  })
+
+  it('hands out fresh projections, never live registry state', async () => {
+    const ctx = await harness()
+    const p = producer()
+    const id = ctx.jobs.start(p.spec)
+    const before = ctx.jobs.get(id)
+    p.job().append('grow')
+    expect(before.output.total).toBe(0)
+    expect(ctx.jobs.get(id).output.total).toBe(4)
+  })
+})
+
+describe('LocalJobRegistry pull sources', () => {
+  it('pumps the spec sources into the ring and drains them once more before settlement', async () => {
+    const ctx = await harness({ pumpPollMs: 1 })
+    const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout')
+    // stderr only becomes readable once the producer has settled: the pump's
+    // final drain is the only read that can collect it.
+    let finishing = false
+    let errOffset = 0
+    const err: JobOutputSource = {
+      channel: 'stderr',
+      read() {
+        const text = finishing && errOffset === 0 ? 'E' : ''
+        errOffset += text.length
+        return { text, nextOffset: errOffset, lossy: false }
+      },
+    }
+    const p = producer({ output: [out, err] })
+    const id = ctx.jobs.start(p.spec)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(ctx.jobs.readAt(id, 0).chunks.map(chunk => chunk.text)).toEqual(['a', 'bc'])
+
+    const settled = collect(ctx, { owners: 'all' }, ['settled'])
+    finishing = true
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    // The final drain landed before the settlement announced itself.
+    expect(settled).toHaveLength(1)
+    expect(ctx.jobs.readAt(id, 0).chunks.map(chunk => chunk.text)).toEqual(['a', 'bc', 'E'])
+    expect(ctx.jobs.get(id)).toMatchObject({ status: 'completed', output: { total: 4 } })
+  })
+
+  it('contains a throwing source: warns once, keeps the job live, and settles on the producer', async () => {
+    const ctx = await harness({ pumpPollMs: 1 })
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const broken: JobOutputSource = { channel: 'stdout', read() { throw new Error('reader boom') } }
+    const healthy = scriptedSource([{ text: 'ok' }], 'stderr')
+    const p = producer({ output: [broken, healthy] })
+    const id = ctx.jobs.start(p.spec)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(ctx.jobs.get(id).status).toBe('running')
+    expect(ctx.jobs.readAt(id, 0).chunks).toEqual([{ at: 0, text: 'ok', channel: 'stderr' }])
+    expect(warn.mock.calls.map(call => String(call[0]))).toEqual([expect.stringContaining(`output source for ${id} failed`)])
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(ctx.jobs.get(id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' })
+  })
+
+  it('stops pumping silently after a forced settlement', async () => {
+    const ctx = await harness({ pumpPollMs: 1 })
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    const owner = await liveAgent(ctx, 'owner')
+    const source: JobOutputSource = {
+      read: fromByte => ({ text: 'x', nextOffset: fromByte + 1, lossy: false }),
+    }
+    ctx.jobs.start({
+      kind: 'bash',
+      label: 'endless',
+      owner: owner.id,
+      output: [source],
+      run: () => ({ cancel() { throw new Error('cancel boom') }, done: new Promise(() => {}) }),
+    })
+    await new Promise(resolve => setTimeout(resolve, 5))
+    await disposeAgentScope(owner)
+    await new Promise(resolve => setTimeout(resolve, 5))
+    // The forced failure is the only warning: the pump's later drains are silent.
+    expect(warn.mock.calls.map(call => String(call[0]))).toEqual([expect.stringContaining('work may be orphaned')])
   })
 })
diff --git a/packages/jobs/jobs-local/tests/pump.spec.ts b/packages/jobs/jobs-local/tests/pump.spec.ts
new file mode 100644
index 0000000000..f9d6087bb4
--- /dev/null
+++ b/packages/jobs/jobs-local/tests/pump.spec.ts
@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { JobAppendOptions, JobOutputSource } from '@deepseek-ai/dsh-jobs'
+import { startPump } from '../src/pump.ts'
+import type { PumpSink } from '../src/pump.ts'
+
+/** Record every append and spill report so pump behavior is observable without a registry. */
+function recorder() {
+  const appends: { text: string; options?: JobAppendOptions }[] = []
+  const spills: [number, string | undefined][] = []
+  const sink: PumpSink = {
+    append: (text, options) => { appends.push({ text, ...options !== undefined ? { options } : {} }) },
+    spill: (index, path) => { spills.push([index, path]) },
+  }
+  return { appends, spills, sink }
+}
+
+/** A scripted source: each read() shifts the next scripted result. */
+function scriptedSource(
+  reads: { text: string; lossy?: boolean; spillPath?: string }[],
+  channel?: 'stdout' | 'stderr',
+): { source: JobOutputSource; offsets: number[] } {
+  const offsets: number[] = []
+  let offset = 0
+  const source: JobOutputSource = {
+    ...channel !== undefined ? { channel } : {},
+    read(fromByte) {
+      offsets.push(fromByte)
+      const next = reads.shift() ?? { text: '' }
+      offset += Buffer.byteLength(next.text, 'utf8')
+      return {
+        text: next.text,
+        nextOffset: offset,
+        lossy: next.lossy ?? false,
+        ...next.spillPath !== undefined ? { spillPath: next.spillPath } : {},
+      }
+    },
+  }
+  return { source, offsets }
+}
+
+describe('startPump', () => {
+  it('copies labeled deltas at the poll cadence and resumes each source at its own offset', async () => {
+    vi.useFakeTimers()
+    try {
+      const { appends, sink } = recorder()
+      let settle!: () => void
+      const until = new Promise<void>((resolve) => { settle = resolve })
+      const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout')
+      const err = scriptedSource([{ text: '' }, { text: 'E' }], 'stderr')
+      const pump = startPump([out.source, err.source], sink, 50, until)
+
+      await vi.advanceTimersByTimeAsync(50)
+      settle()
+      await pump.done
+      expect(appends).toEqual([
+        { text: 'a', options: { channel: 'stdout' } },
+        { text: 'bc', options: { channel: 'stdout' } },
+        { text: 'E', options: { channel: 'stderr' } },
+      ])
+      // Every read resumed from the previous nextOffset, never from a shared cursor.
+      expect(out.offsets).toEqual([0, 1, 3])
+      expect(err.offsets).toEqual([0, 0, 1])
+      // Settlement cleared the pending poll timer instead of leaving it pending.
+      expect(vi.getTimerCount()).toBe(0)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('marks a lossy source read as a gap so observers see the discontinuity', async () => {
+    const { appends, sink } = recorder()
+    const { source } = scriptedSource([{ text: 'tail', lossy: true }])
+    await startPump([source], sink, 1, Promise.resolve()).done
+    expect(appends).toEqual([{ text: 'tail', options: { gapBefore: true } }])
+  })
+
+  it("reports each source's spill file on every read and withdraws it once a read stops naming it", async () => {
+    vi.useFakeTimers()
+    try {
+      const { appends, spills, sink } = recorder()
+      let settle!: () => void
+      const until = new Promise<void>((resolve) => { settle = resolve })
+      const out = scriptedSource([
+        { text: 'tail', lossy: true, spillPath: '/spill/out.log' },
+        { text: 'more', spillPath: '/spill/out.log' },
+        { text: '' },
+      ], 'stdout')
+      const err = scriptedSource([{ text: '' }, { text: 'E', spillPath: '/spill/err.log' }], 'stderr')
+      const pump = startPump([out.source, err.source], sink, 50, until)
+
+      await vi.advanceTimersByTimeAsync(50)
+      settle()
+      await pump.done
+      // Chunks carry the gap marker only; the file reference is source metadata.
+      expect(appends).toEqual([
+        { text: 'tail', options: { channel: 'stdout', gapBefore: true } },
+        { text: 'more', options: { channel: 'stdout' } },
+        { text: 'E', options: { channel: 'stderr' } },
+      ])
+      // Every read reports, lossy or clean, empty or not: the third stdout read withdraws the file.
+      expect(spills).toEqual([
+        [0, '/spill/out.log'], [1, undefined],
+        [0, '/spill/out.log'], [1, '/spill/err.log'],
+        [0, undefined], [1, undefined],
+      ])
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('treats a rejected settlement as settlement and still drains the final bytes', async () => {
+    const { appends, sink } = recorder()
+    const { source } = scriptedSource([{ text: 'last' }])
+    await startPump([source], sink, 1, Promise.reject(new Error('producer broke'))).done
+    expect(appends).toEqual([{ text: 'last' }])
+  })
+
+  it('subscribes to the settlement once and holds one poll timer however long the job runs', async () => {
+    vi.useFakeTimers()
+    try {
+      const { sink } = recorder()
+      let subscriptions = 0
+      let settle!: () => void
+      const settled = new Promise<void>((resolve) => { settle = resolve })
+      const counting = (promise: PromiseLike<unknown>): PromiseLike<unknown> => ({
+        then<Fulfilled = unknown, Rejected = never>(
+          onFulfilled?: ((value: unknown) => Fulfilled | PromiseLike<Fulfilled>) | null,
+          onRejected?: ((reason: unknown) => Rejected | PromiseLike<Rejected>) | null,
+        ): PromiseLike<Fulfilled | Rejected> {
+          subscriptions += 1
+          return counting(promise.then(onFulfilled, onRejected)) as PromiseLike<Fulfilled | Rejected>
+        },
+      })
+      const { source, offsets } = scriptedSource([])
+      const pump = startPump([source], sink, 50, counting(settled))
+
+      const rounds = 10_000
+      await vi.advanceTimersByTimeAsync(50 * rounds)
+      expect(offsets).toHaveLength(rounds + 1)
+      expect(subscriptions).toBeLessThanOrEqual(2)
+      expect(vi.getTimerCount()).toBe(1)
+
+      settle()
+      await pump.done
+      expect(offsets).toHaveLength(rounds + 2)
+      expect(vi.getTimerCount()).toBe(0)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('rejects a non-positive poll interval before touching any source', () => {
+    const { sink } = recorder()
+    expect(() => startPump([], sink, 0, Promise.resolve())).toThrow(/invalid pump pollMs/)
+  })
+})
diff --git a/packages/jobs/jobs-local/tests/ring.spec.ts b/packages/jobs/jobs-local/tests/ring.spec.ts
new file mode 100644
index 0000000000..670e121d0b
--- /dev/null
+++ b/packages/jobs/jobs-local/tests/ring.spec.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import { OutputRing } from '../src/ring.ts'
+
+describe('OutputRing', () => {
+  it('assigns absolute offsets by UTF-8 byte length and drops empty chunks silently', () => {
+    const ring = new OutputRing()
+    expect(ring.append('', undefined, 1024)).toBe(false)
+    expect(ring.append('héllo', { channel: 'stdout' }, 1024)).toBe(true)
+    expect(ring.append('wörld', { channel: 'stderr', gapBefore: true }, 1024)).toBe(true)
+    expect(ring.total).toBe(12)
+    expect(ring.earliest).toBe(0)
+    expect(ring.retainedBytes).toBe(12)
+    expect(ring.readFrom(0)).toEqual({
+      chunks: [
+        { at: 0, text: 'héllo', channel: 'stdout' },
+        { at: 6, text: 'wörld', channel: 'stderr', gapBefore: true },
+      ],
+      next: 12,
+      lossy: false,
+    })
+  })
+
+  it('reads from a foreign offset by returning the whole overlapping chunk', () => {
+    const ring = new OutputRing()
+    ring.append('abc', undefined, 1024)
+    ring.append('def', undefined, 1024)
+    expect(ring.readFrom(4).chunks).toEqual([{ at: 3, text: 'def' }])
+    expect(ring.readFrom(6)).toEqual({ chunks: [], next: 6, lossy: false })
+  })
+
+  it('trims whole head chunks past the cap and reports the evicted span as lossy', () => {
+    const ring = new OutputRing()
+    ring.append('aaaa', undefined, 8)
+    ring.append('bbbb', undefined, 8)
+    ring.append('cc', undefined, 8)
+    // 10 bytes retained > cap 8: the oldest whole chunk goes.
+    expect(ring.earliest).toBe(4)
+    expect(ring.retainedBytes).toBe(6)
+    expect(ring.readFrom(0)).toEqual({ chunks: [{ at: 4, text: 'bbbb' }, { at: 8, text: 'cc' }], next: 10, lossy: true })
+    expect(ring.readFrom(4).lossy).toBe(false)
+  })
+
+  it('keeps a lone oversized chunk as a UTF-8-safe tail marked gapBefore', () => {
+    const ring = new OutputRing()
+    // 3 two-byte code points = 6 bytes; a 3-byte cap must not start inside a code point.
+    ring.append('ééé', undefined, 3)
+    expect(ring.retainedBytes).toBe(2)
+    expect(ring.earliest).toBe(4)
+    expect(ring.readFrom(0)).toEqual({ chunks: [{ at: 4, text: 'é', gapBefore: true }], next: 6, lossy: true })
+  })
+
+  it('re-trims to a smaller cap on demand and leaves total untouched', () => {
+    const ring = new OutputRing()
+    ring.append('12345678', undefined, 64)
+    ring.append('abcdefgh', undefined, 64)
+    ring.trim(8)
+    expect(ring.total).toBe(16)
+    expect(ring.earliest).toBe(8)
+    expect(ring.readFrom(8)).toEqual({ chunks: [{ at: 8, text: 'abcdefgh' }], next: 16, lossy: false })
+    // Trimming an empty ring is a no-op that keeps earliest at total.
+    const empty = new OutputRing()
+    empty.trim(1)
+    expect(empty.earliest).toBe(0)
+  })
+})
diff --git a/packages/jobs/jobs/README.i18n.yaml b/packages/jobs/jobs/README.i18n.yaml
index 3c3d1db594..a3a87e082e 100644
--- a/packages/jobs/jobs/README.i18n.yaml
+++ b/packages/jobs/jobs/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/jobs/jobs/README.md
-README.md: a96db102354b41ebd196b0718ed0ef0b97f6935b
-README.zh.md: 7198c8e6a82ed0d4f4d9dd9a3a2a501cfdebcbf2
+README.md: d5c67eccec42a7eb10179495f0397bf394c8d6ff
+README.zh.md: 41899dcd018c0d33ff42a1c3d5b521317c129e11
diff --git a/packages/jobs/jobs/README.md b/packages/jobs/jobs/README.md
index a96db10235..d5c67eccec 100644
--- a/packages/jobs/jobs/README.md
+++ b/packages/jobs/jobs/README.md
@@ -1,5 +1,5 @@
 ---
-description: "The background-job registry contract for users and maintainers composing, implementing, or debugging background work: ids, ownership, lifecycle, and completion listeners."
+description: "The background-job registry contract for users and maintainers composing, implementing, or debugging background work: ids, ownership, lifecycle, the output ring, and the event stream."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-jobs` lets tools keep long-running work active while an agent continues. Each job receives a stable `<kind>-N` id, and its owning agent can read output, wait with a timeout, or request cancellation. Ownership is scoped to the agent session, so other agents cannot inspect or stop the job; completion arrives as an in-session notice without polling. Background jobs can start only when the deployment supplies job execution.
+`dsh-jobs` lets tools keep long-running work active while an agent continues. Each job receives a stable `<kind>-N` id, and its owning agent can read output, wait with a timeout, or request cancellation. Ownership is scoped to the agent session, so other agents cannot inspect or stop the job; completion arrives as an in-session notice without polling. Users can watch retained live output without consuming what the agent can read. Background jobs can start only when the deployment supplies job execution.
 
 ## Table of Contents
 
@@ -29,7 +29,9 @@ Use this package when you are composing a background-job capability or writing a
 
 ### What a background job gives you
 
-A producer registers work with a kind and a one-line label; the registry returns a `<kind>-N` id such as `bash-1`. Anyone who owns the job can read output, list jobs, wait up to a timeout for settlement, and request cancellation — each call returns a fresh snapshot of the job's status, from `running` and `stopping` to the terminal `completed`, `killed`, or `failed`. When a job settles, the owning agent is notified through the completion listener that `dsh-tool-jobs` turns into an in-session notice, so no polling is needed. A producer may attach an optional byte cap so each complete model-facing output read or completion notice stays bounded.
+A producer registers work with a kind and a one-line label; the registry returns a `<kind>-N` id such as `bash-1`. Anyone who owns the job can read output, list jobs, wait up to a timeout for settlement, and request cancellation — each call returns a fresh projection of the job's status, from `running` and `stopping` to the terminal `completed`, `killed`, or `failed`. When a job settles, the registry's event stream announces it and `dsh-tool-jobs` turns the settlement into an in-session notice, so no polling is needed. A producer may attach an optional byte cap so each complete model-facing read or notice stays bounded.
+
+A producer streams output by naming pull sources on its spec — non-consuming offset readers the registry pumps at its own cadence — or by pushing chunks through the `JobHandle` its starter receives; both land in the job's bounded ring, where `stdout` and `stderr` chunks reach the model and `log` chunks reach observers only. Observers read retained chunks at absolute byte offsets and are signaled on advancement; the settlement that ends the job also ends the stream, and `updateProgress` publishes a live progress line into every projection until then. Observation is invisible to the model: `readAt` consumes nothing and never touches notice state.
 
 ### The ownership boundary
 
@@ -67,7 +69,7 @@ This section explains the design decisions behind the contract and points at the
 - **Contract and implementation are separate packages.** `JobRegistry` is an abstract Cordis service; loading the class directly throws, so a misconfigured composition fails at load instead of registering an empty `ctx.jobs`.
 - **One registry per process, owner-relative answers.** One instance serves every composition in the process, so registrations and deliveries are relative to the registering scope: 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.
 - **Access is fenced by the owner's session id.** Ids are predictable, so authorization — not secrecy — is the boundary.
-- **Settlement is first-wins, and completion is announced last.** One terminal record, released waiters, and one round of contained listener notification; completion is announced after the record is committed and every other observer has seen it, because a reporter may open a model turn synchronously.
+- **Settlement is first-wins, and its event follows every released waiter.** One terminal record, released waiters, then one round of contained event delivery; a consumer that claims a settlement while waiting therefore always claims before the event, so `dsh-tool-jobs` never announces a completion the model already collected.
 - **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.
 
 ### Source map
@@ -75,13 +77,14 @@ This section explains the design decisions behind the contract and points at the
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `JobRegistry` service and its contract |
-| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobKindMap`, `JobStart`, `JobHooks`, `JobSnapshot`, listener types |
+| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobSpec`, `JobHandle`, `JobHooks`, `JobOutcome`, `JobEvent`, and the read results |
+| [`src/view.ts`](src/view.ts) | Client-safe leaf: `JobView`, `JobChunk`, `JobStatus`, and the merge-extensible `JobKindMap` |
 | [`src/brand.ts`](src/brand.ts) | `JobId` branded identifier, importable without the agent dependency |
-| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates snapshot identity, status, timestamps, and owner fields |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: checks the announced event protocol per job (registered first, one settlement, removal last) and each announced projection against the registry's own read |
 
 ### Service operations
 
-Every operation is a thin projection over the registered jobs: `get` and `list` return non-consuming snapshots, `read` advances the single stream cursor, `kill` invokes producer cancellation before changing status, `wait` blocks up to a timeout, and `start()` preflights access, validation, and admission before invoking the producer's `run()` once while refusing any owner no attached controller serves; listeners observe terminal records and visible-set changes at owner granularity, and `attachController` scopes controller availability to its effect lifetime. Exact signatures and behavior live in the JSDoc on [`src/index.ts`](src/index.ts) and the generated [`ctx.jobs` Cordis surface](../../../docs/subsystems/jobs.md).
+Each read or control operation accepts an optional caller `SessionId`; omitting it permits only unowned jobs: `list` and `get` return fresh projections, `read` advances the model's cursor and hands out the producer's result once after settlement, `readAt` reads retained chunks at an absolute offset without consuming anything, `kill` invokes producer cancellation before changing status and records the reason for the terminal `detail`, `wait` blocks up to a timeout, and `start()` preflights access, validation, and admission before invoking the producer's `run()` once while refusing any owner no attached controller serves; `events.subscribe` delivers registration, progress, stopping, settlement, removal, and output commits at owner, scope, or process granularity.
 
 </details>
 
@@ -92,12 +95,13 @@ Every operation is a thin projection over the registered jobs: `get` and `list`
 
 Read these pages when the package-level contract is not enough. They move from the job types to the shipped implementation, the model-facing controls, and the design records.
 
-- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, snapshot fields, and `ctx.jobs` Cordis surface.
+- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, projection fields, and `ctx.jobs` Cordis surface.
 - [jobs group map](../README.md) — the sibling group page and its package table.
 - [Process-local registry](../jobs-local/README.md) — the shipped implementation that runs jobs in this process.
 - [Model-facing job controls](../tool-jobs/README.md) — the `job_output`, `job_list`, and `job_kill` tools and completion notices.
 - [Generic long-running tool runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) — the design behind the background-job runtime.
 - [job-registry seam Agent Note](../../../.agents/notes/archived/architecture/2026-07-26-job-registry-seam.md) — the owner-fenced registry contract and its rationale.
+- [Jobs seam consolidation Agent Note](../../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md) — one output ring, one projection, one event stream.
 
 -----
 
@@ -117,8 +121,8 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 These limits define when the contract is a poor fit. They are current package constraints, not a task backlog.
 
-- **The contract is in-process** — `JobStart.run()` passes callbacks and exact `Agent` objects; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam.
-- **Stream output has one consuming cursor** — independent observers need a cursor or snapshot API.
+- **The contract is in-process** — `JobSpec.run()` passes callbacks and the registry resolves the live `Agent` behind the owner session; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam.
+- **The model's cursor is the only consuming read** — independent observers use the non-consuming `readAt` and never move it.
 - **Foreground work cannot be promoted** — producers choose foreground or background before starting.
 
 <a id="dev-note"></a>
diff --git a/packages/jobs/jobs/README.zh.md b/packages/jobs/jobs/README.zh.md
index 7198c8e6a8..41899dcd01 100644
--- a/packages/jobs/jobs/README.zh.md
+++ b/packages/jobs/jobs/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "后台任务注册表约定，供组合、实现或排查后台工作的用户与维护者阅读：id、归属、生命周期与完成监听器。"
+description: "后台任务注册表约定，供组合、实现或排查后台工作的用户与维护者阅读：id、归属、生命周期、输出环与事件流。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-jobs` 让工具可以在 agent（智能体）继续推进时保持长时间工作运行。每项任务都会获得稳定的 `<kind>-N` id，拥有它的 agent 可以读取输出、带超时等待或请求取消。归属范围限定在 agent 会话内，因此其他 agent 无法查看或停止任务；任务完成时会通过会话内通知送达，无需轮询。只有部署提供任务执行能力时，后台任务才能启动。
+`dsh-jobs` 让工具可以在 agent（智能体）继续推进时保持长时间工作运行。每项任务都会获得稳定的 `<kind>-N` id，拥有它的 agent 可以读取输出、带超时等待或请求取消。归属范围限定在 agent 会话内，因此其他 agent 无法查看或停止任务；任务完成时会通过会话内通知送达，无需轮询。用户可以查看保留的实时输出，而不消耗 agent 可读取的内容。只有部署提供任务执行能力时，后台任务才能启动。
 
 ## 目录
 
@@ -29,7 +29,9 @@ kind: "package-reference"
 
 ### 后台任务提供什么
 
-生产方以 kind 和一行标签注册工作；注册表返回 `<kind>-N` id，例如 `bash-1`。拥有任务的任何一方都可以读取输出、列出任务、带超时等待结算或请求取消——每次调用都返回任务状态的全新快照，从 `running`、`stopping` 到终止态的 `completed`、`killed` 或 `failed`。任务结算时，拥有它的 agent 会通过 `dsh-tool-jobs` 转成会话内通知的完成监听器得到通知，因此无需轮询。生产方还可以附加可选的字节上限，让每次完整的模型侧输出读取或完成通知保持有界。
+生产方以 kind 和一行标签注册工作；注册表返回 `<kind>-N` id，例如 `bash-1`。拥有任务的任何一方都可以读取输出、列出任务、带超时等待结算或请求取消——每次调用都返回任务状态的全新投影，从 `running`、`stopping` 到终止态的 `completed`、`killed` 或 `failed`。任务结算时，注册表的事件流宣布它，`dsh-tool-jobs` 把结算变成会话内通知，因此无需轮询。生产方可以附加一个可选的字节上限，让每次完整的模型侧读取或通知保持有界。
+
+生产方通过在 spec 上声明拉取源——由注册表按自己的节奏泵送的非消耗偏移读取器——或经 starter 收到的 `JobHandle` 推送块来流式输出；二者都落入该 job 的有界环，其中 `stdout` 与 `stderr` 块到达模型，`log` 块只到达观察者。观察者按绝对字节偏移读取保留块并在推进时收到信号；结束 job 的结算同时封流，在此之前 `updateProgress` 把实时进度行发布进每个投影。观测对模型不可见：`readAt` 不消耗任何东西，也从不触碰通知状态。
 
 ### 归属边界
 
@@ -67,7 +69,7 @@ kind: "package-reference"
 - **约定与实现分属不同包。** `JobRegistry` 是抽象 Cordis 服务；直接加载该类会抛出异常，因此错误配置的组合会在加载时失败，而不是注册一个空的 `ctx.jobs`。
 - **每个进程一个注册表，按所有者返回结果。** 一个实例服务进程内的每套组合，因此注册与投递都相对注册方所在 scope：从不带 scope 的上下文注册的控制器或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，恰好服务于该组合下组合出的 agent。
 - **访问以所有者的会话 id 为界。** id 可预测，因此是授权——而非保密——构成边界。
-- **结算首次优先，完成最后宣布。** 一条终止记录、释放的等待方，以及一轮受到隔离的监听器通知；完成在记录提交且该结算的所有其他观察者都已看到之后才宣布，因为报告方可能同步开启一个模型轮次。
+- **结算首次优先，其事件跟在每个被释放的等待方之后。** 一条终止记录、释放的等待方，然后是一轮受到隔离的事件投递；在等待中认领结算的消费方因此总是在事件之前认领，`dsh-tool-jobs` 永远不会播报模型已经收走的完成。
 - **注册的存续期长于生产方与控制器 fiber。** 所有者与服务释放会取消正在运行的工作并等待守约的生产方；销毁期间的取消若抛出异常，只会将记录强制标记为失败。
 
 ### 源码地图
@@ -75,13 +77,14 @@ kind: "package-reference"
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：抽象 `JobRegistry` 服务及其约定 |
-| [`src/types.ts`](src/types.ts) | 共享词汇：`JobKindMap`、`JobStart`、`JobHooks`、`JobSnapshot`、监听器类型 |
+| [`src/types.ts`](src/types.ts) | 共享词汇：`JobSpec`、`JobHandle`、`JobHooks`、`JobOutcome`、`JobEvent` 与读取结果 |
+| [`src/view.ts`](src/view.ts) | 客户端安全叶子：`JobView`、`JobChunk`、`JobStatus` 与可合并扩展的 `JobKindMap` |
 | [`src/brand.ts`](src/brand.ts) | `JobId` 带类型标记的标识符，无需 agent 依赖即可导入 |
-| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：校验快照标识、状态、时间戳与所有者字段 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：校验每个 job 的事件协议（先 registered、恰一次结算、最后 removed）以及每个通告的投影与注册表自身读取的一致性 |
 
 ### 服务操作
 
-每个操作都是已注册任务之上的薄投影：`get` 与 `list` 返回非消费式快照，`read` 推进唯一的流游标，`kill` 在改变状态前调用生产方取消，`wait` 最多阻塞至超时，`start()` 在调用生产方 `run()` 一次之前预检访问、校验与准入，同时拒绝任何没有已附加控制器服务的所有者；监听器按所有者粒度观察终止记录与可见集变化，`attachController` 把控制器可用性限定在其 effect 生命周期内。确切签名与行为见 [`src/index.ts`](src/index.ts) 的 JSDoc 与生成的 [`ctx.jobs` Cordis 接口面](../../../docs/subsystems/jobs.zh.md)。
+每个读取或控制操作接收可选的调用方 `SessionId`，省略时仅允许访问无主 job：`list` 与 `get` 返回全新投影，`read` 推进模型游标并在结算后把生产方的 result 交出一次，`readAt` 按绝对偏移读取保留块且不消耗任何东西，`kill` 在改变状态前调用生产方取消并为终态 `detail` 记录原因，`wait` 阻塞至超时，`start()` 在调用生产方 `run()` 一次之前预检访问、校验与准入，同时拒绝任何没有已附加控制器服务的所有者；`events.subscribe` 按所有者、scope 或进程粒度投递注册、进度、停止中、结算、移除与输出提交。
 
 </details>
 
@@ -92,12 +95,13 @@ kind: "package-reference"
 
 当包级约定不够用时阅读以下页面。它们从任务类型逐步进入随附实现、模型侧控制与设计记录。
 
-- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、快照字段与 `ctx.jobs` 的 Cordis 接口面。
+- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、投影字段与 `ctx.jobs` 的 Cordis 接口面。
 - [jobs 组映射](../README.zh.md)——同级组页面及其包表格。
 - [进程本地注册表](../jobs-local/README.zh.md)——在本进程中运行任务的随附实现。
 - [模型侧任务控制](../tool-jobs/README.zh.md)——`job_output`、`job_list` 与 `job_kill` 工具及完成通知。
 - [通用长时间运行工具运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)——后台任务运行时背后的设计。
 - [任务注册表 seam Agent Note](../../../.agents/notes/archived/architecture/2026-07-26-job-registry-seam.md)——按所有者隔离的注册表约定及其理由。
+- [jobs seam 收敛 Agent Note](../../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md)——一个输出环、一个投影、一条事件流。
 
 -----
 
@@ -117,8 +121,8 @@ kind: "package-reference"
 
 这些限制说明约定何时不合适。它们是当前包约束，不是任务积压。
 
-- **约定是进程内的**——`JobStart.run()` 传入回调和确切的 `Agent` 对象；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。
-- **流输出只有一个消费游标**——独立观察者需要游标或快照 API。
+- **约定是进程内的**——`JobSpec.run()` 传入回调，注册表解析拥有者会话背后的活体 `Agent`；持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义，才能实现此 seam。
+- **模型游标是唯一的消耗式读取**——独立观察者使用非消耗的 `readAt`，从不移动它。
 - **前台工作无法转为后台**——生产方在启动前选择前台或后台。
 
 <a id="dev-note"></a>
diff --git a/packages/jobs/jobs/package.json b/packages/jobs/jobs/package.json
index ccbd216368..ea35be2cea 100644
--- a/packages/jobs/jobs/package.json
+++ b/packages/jobs/jobs/package.json
@@ -26,6 +26,10 @@
       "types": "./lib/types/brand.d.ts",
       "default": "./lib/types/brand.js"
     },
+    "./view": {
+      "types": "./lib/types/view.d.ts",
+      "default": "./lib/types/view.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
diff --git a/packages/jobs/jobs/src/index.ts b/packages/jobs/jobs/src/index.ts
index 7d46dfa342..57aebe0d17 100644
--- a/packages/jobs/jobs/src/index.ts
+++ b/packages/jobs/jobs/src/index.ts
@@ -1,29 +1,40 @@
 /**
  * The background-job Service Definition (`ctx.jobs`). It owns the contract for
- * job ids, session-scoped access, lifecycle state, completion listeners, and
- * owner cleanup while producers retain their execution resources. The
- * process-local registry lives in `@deepseek-ai/dsh-jobs-local`.
+ * job ids, session-scoped access, lifecycle state, the per-job output ring —
+ * one bounded stream that the model consumes through a registry-kept cursor
+ * and that any number of observers read at absolute byte offsets — and the
+ * event stream announcing every commit, while producers retain their
+ * execution resources. The process-local registry lives in
+ * `@deepseek-ai/dsh-jobs-local`.
  * @module @deepseek-ai/dsh-jobs
  */
 
 import { Context, Service } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import type {
-  JobDoneListener, JobId, JobRead, JobSnapshot, JobStart, JobsChangedListener,
-} from './types.ts'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { JobEvents, JobId, JobOutputRead, JobRead, JobSpec, JobView } from './types.ts'
 
 export { JobId } from './types.ts'
 export type {
-  JobDoneListener,
+  JobAppendOptions,
+  JobChannel,
+  JobChunk,
+  JobEvent,
+  JobEventFilter,
+  JobEventListener,
+  JobEvents,
+  JobHandle,
   JobHooks,
   JobKind,
   JobKindMap,
   JobOutcome,
+  JobOutputRead,
+  JobOutputSource,
   JobRead,
-  JobSnapshot,
-  JobStart,
+  JobSettleCause,
+  JobSourceRead,
+  JobSpec,
   JobStatus,
-  JobsChangedListener,
+  JobView,
 } from './types.ts'
 
 declare module '@deepseek-ai/cordis' {
@@ -33,7 +44,7 @@ declare module '@deepseek-ai/cordis' {
 }
 
 /**
- * Abstract background job registry. Subclass, implement the abstract methods,
+ * Abstract background job registry. Subclass, implement the abstract members,
  * and load the subclass as a plugin — it registers as `ctx.jobs` (one
  * implementation per context; loading a second throws, which is cordis'
  * standard duplicate-service behavior).
@@ -41,23 +52,30 @@ declare module '@deepseek-ai/cordis' {
  * Implementations must honor these semantics:
  * - 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. Teardown
- *   cancellation also marks the record reported, because a record its owner
- *   is being destroyed for has no reader left.
+ *   throwing teardown cancel force-fails only the record. Such settlements
+ *   announce `cause: 'teardown'`, because a job whose owner is being destroyed
+ *   has no reader left.
  * - Owned-job 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, released waiters, and one
- *   round of contained listener notification, even against a late producer
- *   outcome. Completion is announced last, after the record is committed and
- *   every other observer of the settlement has seen it, because a reporter
- *   may open a model turn synchronously.
+ * - Settlement is first-wins: one terminal record, released waiters, then one
+ *   round of contained event delivery, even against a late producer outcome.
+ *   The `settled` event follows every released waiter, so a consumer that
+ *   claims a settlement while waiting always claims before the event.
  * - {@link start} refuses work while no attached job 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.
+ *   question — and event delivery under `{ owners: 'scope' }` — 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.
+ * - Every job owns one output ring. Pull sources named by the spec are pumped
+ *   by the registry and drained once more before settlement; pushed appends
+ *   land whole. The model's consuming cursor and observers' absolute offsets
+ *   read the same bytes and never disturb each other.
+ * - Ring retention is bounded. Appends past the live cap drop the oldest
+ *   retained bytes; a reader below the retained window gets a lossy read,
+ *   never an error. Settlement trims retention to the settled cap and ends
+ *   the stream; the ring has no separate lifecycle.
  */
 export abstract class JobRegistry extends Service {
   constructor(ctx: Context) {
@@ -70,101 +88,81 @@ export abstract class JobRegistry extends Service {
     super(ctx, 'jobs')
   }
 
+  /** Lifecycle and output events, filtered per subscription. */
+  abstract readonly events: JobEvents
+
   /**
    * Preflight access, validation, owner cleanup, and implementation-owned
    * admission before starting and atomically registering work. Any preflight
    * rejection leaves no job id or execution resource. A throwing starter
    * leaves nothing registered; after it returns, registration cannot fail.
-   * Settlement records the outcome, notifies listeners, and releases waiters.
-   * @param spec - job identity, owner, and synchronous starter.
+   * @param spec - job identity, owner, output sources, and synchronous starter.
    * @returns the registry-issued `<kind>-N` id.
    */
-  abstract start(spec: JobStart): JobId
+  abstract start(spec: JobSpec): JobId
 
   /**
-   * List caller-owned and unowned jobs in registration order without exposing
-   * another session's labels.
-   * @param caller - reading agent; a non-agent caller sees only unowned jobs.
-   * @returns fresh snapshots.
+   * List caller-owned and unowned jobs in registration order.
+   * @param caller - reading session; omission sees only unowned jobs.
+   * @returns fresh projections.
    */
-  abstract list(caller?: Agent): JobSnapshot[]
+  abstract list(caller?: SessionId): JobView[]
 
   /**
-   * Return a non-consuming snapshot without changing its read cursor or notice
-   * state. Throws for an unknown or foreign job.
-   * @param id - job to look up.
-   * @param caller - reading agent checked against the owner.
-   * @returns a fresh snapshot.
-   */
-  abstract get(id: JobId, caller?: Agent): JobSnapshot
-
-  /**
-   * Read the next stream delta, or the idempotent final output after settlement.
-   * A terminal read marks the job reported. Throws for an unknown or foreign
-   * job.
-   * @param id - job to read.
-   * @param caller - reading agent checked against the owner.
-   * @returns output text and the post-read snapshot.
-   */
-  abstract read(id: JobId, caller?: Agent): JobRead
-
-  /**
-   * Request cancellation, then mark the job stopping and reported. A producer
-   * throw propagates without changing job state. Throws for an unknown or
+   * Project one job without changing its cursor. Throws for an unknown or
    * foreign job.
+   * @param id - job to look up.
+   * @param caller - reading session checked against the owner.
+   * @returns a fresh projection.
+   */
+  abstract get(id: JobId, caller?: SessionId): JobView
+
+  /**
+   * Consume the ring from the model cursor and advance it to the current
+   * total. After settlement the first read also carries the producer's
+   * result. Throws for an unknown or foreign job.
+   * @param id - job to read.
+   * @param caller - reading session checked against the owner.
+   * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection.
+   */
+  abstract read(id: JobId, caller?: SessionId): JobRead
+
+  /**
+   * Read retained ring output without moving the model cursor. Resume with
+   * a previous read's `next`; an offset inside a retained chunk returns the
+   * whole chunk (its `at` may precede `from`). Throws for a negative or
+   * non-integer offset, or an unknown or foreign job.
+   * @param id - job to read.
+   * @param from - absolute byte offset to read from (0 for the retained head).
+   * @param caller - reading session checked against the owner.
+   * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.
+   */
+  abstract readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead
+
+  /**
+   * Request cancellation, then mark the job stopping. A producer throw
+   * propagates without changing job state. A supplied reason is merged into
+   * terminal `detail` when the job settles `killed`. Throws for an unknown
+   * or foreign job.
    * @param id - job to cancel.
-   * @param caller - killing agent checked against the owner.
-   * @param reason - logged reason forwarded to the producer.
+   * @param caller - killing session checked against the owner.
+   * @param reason - cancellation reason forwarded verbatim to the producer.
    * @returns `requested` for live work, otherwise `already-finished`.
    */
-  abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+  abstract kill(id: JobId, caller?: SessionId, reason?: string): 'requested' | 'already-finished'
 
   /**
    * Wait for settlement or timeout without cancelling the job. Caller abort
    * rejects only while the job is live; after settlement the terminal
-   * snapshot wins so a notice suppressed for this waiter is still delivered.
-   * Throws for invalid, unknown, or foreign input.
+   * projection wins. Rejects for an invalid timeout or an unknown or foreign
+   * job.
    * @param id - job to wait for.
    * @param timeoutMs - positive finite wait bound in milliseconds.
-   * @param caller - waiting agent checked against the owner.
+   * @param caller - waiting session checked against the owner.
    * @param signal - optional cancellation of the wait itself.
-   * @returns snapshot at settlement or timeout.
+   * @returns projection at settlement or timeout.
    */
-  abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>
-
-  /**
-   * Register an effect-scoped completion listener. It receives the settlements
-   * of the owners its registering context's scope covers; each listener is
-   * contained; returned promises are observed but not awaited. No listener runs
-   * after service disposal.
-   * @param listener - receives each terminal snapshot and its exact owner.
-   * @returns disposer that unregisters the listener.
-   */
-  abstract onJobDone(listener: JobDoneListener): () => void
-
-  /**
-  /**
-   * Register an effect-scoped observer of visible-set changes. It fires after
-   * every commit that changes what {@link list} returns for that owner —
-   * registration, every stopping transition (including the one teardown
-   * performs before it awaits a slow producer), settlement, owner-disposal
-   * removal, and the emptying that service disposal commits — so an observer
-   * re-reads rather than accumulating deltas.
-   *
-   * Delivery is owner-relative on the same terms as {@link onJobDone}: an
-   * observer registered from an unscoped context — a host composition's own
-   * carrier — sees every owner, while one registered under an agent
-   * composition's scope sees exactly the agents composed under it.
-   *
-   * This is not a superset of {@link onJobDone}: that one delivers the terminal
-   * record under first-wins semantics a job 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
-   *   `undefined` when an unowned job changed and every caller's set did.
-   * @returns disposer that unregisters the listener.
-   */
-  abstract onJobsChanged(listener: JobsChangedListener): () => void
+  abstract wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView>
 
   /**
    * Attach an effect-scoped controller that can read and stop jobs. It serves the
diff --git a/packages/jobs/jobs/src/invariant.ts b/packages/jobs/jobs/src/invariant.ts
index 5963179c00..110a94c34b 100644
--- a/packages/jobs/jobs/src/invariant.ts
+++ b/packages/jobs/jobs/src/invariant.ts
@@ -1,51 +1,110 @@
-/** Package-owned background-job snapshot invariants. @module @deepseek-ai/dsh-jobs/invariant */
+/** Package-owned background-job event-protocol invariants. @module @deepseek-ai/dsh-jobs/invariant */
 
 import type { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-import type { JobSnapshot } from './types.ts'
+import type { JobId } from './brand.ts'
+import type { JobEvent, JobView } from './types.ts'
 
 const PACKAGE_NAME = '@deepseek-ai/dsh-jobs'
 const TERMINAL_STATUSES = new Set(['completed', 'killed', 'failed'])
 
+/**
+ * Where one announced job stands: `live` from its first event until its
+ * settlement, `settled` until its removal. An id first seen through a later
+ * event is adopted at that phase, so a companion mounted after the job
+ * started raises nothing.
+ */
+type Phase = 'live' | 'settled'
+
 /** Cordis companion plugin name. */
 export const name = 'jobs-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** Validate the cross-field relationships in one registry snapshot. */
-function validateSnapshot(snapshot: JobSnapshot, owner: Agent | undefined, fail: InvariantFailure): void {
-  const id = String(snapshot.id)
-  const prefix = `${snapshot.kind}-`
-  const ordinal = Number(id.slice(prefix.length))
-  if (snapshot.kind.length === 0 || !id.startsWith(prefix)
-    || !Number.isSafeInteger(ordinal) || ordinal < 1) {
-    fail(`job snapshot id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`)
-  }
-  if (snapshot.label.length === 0) fail(`job ${JSON.stringify(id)} label must be non-empty`)
-  if (!Number.isSafeInteger(snapshot.startedAt) || snapshot.startedAt < 0) {
-    fail(`job ${JSON.stringify(id)} startedAt must be a non-negative epoch integer`)
-  }
-
-  const terminal = TERMINAL_STATUSES.has(snapshot.status)
-  if (terminal !== (snapshot.finishedAt !== undefined)) {
-    fail(`job ${JSON.stringify(id)} finishedAt must be present exactly for a terminal status`)
-  }
-  if (snapshot.finishedAt !== undefined
-    && (!Number.isSafeInteger(snapshot.finishedAt) || snapshot.finishedAt < snapshot.startedAt)) {
-    fail(`job ${JSON.stringify(id)} finishedAt must be an epoch integer no earlier than startedAt`)
-  }
-
-  const expectedOwner = owner?.id
-  if (snapshot.ownerSession !== expectedOwner) {
-    fail(`job ${JSON.stringify(id)} ownerSession does not match its completion owner`)
+/** The registry's own current projection of `id`, or undefined once the record is gone. */
+function readBack(ctx: Context, id: JobId, owner: JobView['owner']): JobView | undefined {
+  try {
+    return ctx.jobs.get(id, owner)
+  } catch {
+    // The registry throws for an id outside the caller's set; after a removal that is the expected answer.
+    return undefined
   }
 }
 
-/** Install checks over current unowned records and every terminal snapshot. */
+/**
+ * The announced projection must agree with the registry's own read: the
+ * immutable identity matches, and the announced output total is not ahead of
+ * the committed one.
+ */
+function checkAnnounced(read: JobView, announced: JobView, what: string, fail: InvariantFailure): void {
+  const id = String(announced.id)
+  for (const key of ['kind', 'label', 'owner', 'startedAt'] as const) {
+    if (read[key] !== announced[key]) {
+      fail(`${what} for job ${id} announces ${key} ${JSON.stringify(announced[key])} while the registry reads ${JSON.stringify(read[key])}`)
+    }
+  }
+  if (announced.output.total > read.output.total) {
+    fail(`${what} for job ${id} announces output total ${announced.output.total} ahead of the registry's ${read.output.total}`)
+  }
+}
+
+/** Install the per-job protocol and event-versus-read checks over the whole event stream. */
 const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
-  for (const snapshot of ctx.jobs.list()) validateSnapshot(snapshot, undefined, fail)
-  ctx.jobs.onJobDone((snapshot, owner) => { validateSnapshot(snapshot, owner, fail) })
+  const phases = new Map<string, Phase>()
+  ctx.jobs.events.subscribe({ owners: 'all' }, (event: JobEvent) => {
+    if (event.type === 'output') {
+      const id = String(event.id)
+      const read = readBack(ctx, event.id, event.owner)
+      if (read === undefined) fail(`output announced for job ${id} that the registry no longer returns`)
+      if (event.total > read.output.total) {
+        fail(`output announced for job ${id} at total ${event.total} ahead of the registry's ${read.output.total}`)
+      }
+      if (!phases.has(id)) phases.set(id, 'live')
+      return
+    }
+    const { job } = event
+    const id = String(job.id)
+    const phase = phases.get(id)
+    const terminal = TERMINAL_STATUSES.has(job.status)
+    switch (event.type) {
+      case 'registered':
+        if (phase !== undefined) fail(`registered announced for job ${id} after earlier events for the same id`)
+        if (terminal || job.finishedAt !== undefined) fail(`registered job ${id} must announce a live status without finishedAt`)
+        break
+      case 'progress':
+      case 'stopping':
+        if (phase === 'settled') fail(`${event.type} announced for job ${id} after its settlement`)
+        if (terminal) fail(`${event.type} announced for job ${id} with a terminal status`)
+        break
+      case 'settled':
+        if (phase === 'settled') fail(`settled announced twice for job ${id}`)
+        if (!terminal) fail(`settled job ${id} must announce a terminal status, got ${JSON.stringify(job.status)}`)
+        if (job.finishedAt === undefined || job.finishedAt < job.startedAt) {
+          fail(`settled job ${id} must announce finishedAt no earlier than startedAt`)
+        }
+        if (job.progress !== undefined) fail(`settled job ${id} must announce a cleared progress line`)
+        break
+      case 'removed':
+        if (phase === 'live') fail(`removed announced for job ${id} before its settlement`)
+        if (readBack(ctx, job.id, job.owner) !== undefined) fail(`removed announced for job ${id} that the registry still returns`)
+        phases.delete(id)
+        return
+      /* v8 ignore start -- defensive: the lifecycle event union is closed and exhaustive here; a new variant fails loudly */
+      default: {
+        const exhaustive: never = event
+        fail(`unknown job event ${String(exhaustive)} for job ${id}`)
+      }
+      /* v8 ignore stop */
+    }
+    const read = readBack(ctx, job.id, job.owner)
+    if (read === undefined) fail(`${event.type} announced for job ${id} that the registry does not return`)
+    checkAnnounced(read, job, event.type, fail)
+    if (event.type === 'settled' && (read.status !== job.status || read.finishedAt !== job.finishedAt)) {
+      fail(`settled job ${id} announces ${job.status} at ${String(job.finishedAt)}`
+        + ` while the registry reads ${read.status} at ${String(read.finishedAt)}`)
+    }
+    phases.set(id, event.type === 'settled' ? 'settled' : 'live')
+  })
 }, { inject: ['jobs'] })
 
 /**
diff --git a/packages/jobs/jobs/src/types.ts b/packages/jobs/jobs/src/types.ts
index 2842f6a3a5..e607ee99f9 100644
--- a/packages/jobs/jobs/src/types.ts
+++ b/packages/jobs/jobs/src/types.ts
@@ -1,71 +1,104 @@
 /**
- * Types shared by job producers, the registry, and controllers. The
- * service implementation lives in `./index.ts`.
+ * Types shared by job producers, the registry, and its consumers. The
+ * client-safe projection vocabulary lives in `./view.ts`; the service
+ * implementation lives in `./index.ts`.
  * @module @deepseek-ai/dsh-jobs/types
  */
 
-import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type { JobId } from './brand.ts'
+import type { JobChannel, JobChunk, JobKind, JobView } from './view.ts'
 
 export { JobId } from './brand.ts'
-
-/**
- * Task lifecycle: `running`, optionally `stopping`, then exactly one terminal
- * status. Producer-specific facts belong in {@link JobSnapshot.detail}.
- */
-export type JobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
-
-/**
- * Producer-defined job kinds. Plugins extend this map by declaration merging;
- * the registry treats every value as an opaque id namespace.
- */
-export interface JobKindMap {
-  bash: 'bash'
-  subagent: 'subagent'
-}
-
-/** The merge-extensible union of registered producer kind names. */
-export type JobKind = JobKindMap[keyof JobKindMap]
+export type { JobChannel, JobChunk, JobKind, JobKindMap, JobStatus, JobView } from './view.ts'
 
 /** Terminal result supplied by a producer through {@link JobHooks.done}. */
 export interface JobOutcome {
   /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
   status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
+  /**
+   * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`).
+   * When the job settles `killed` after a {@link JobRegistry.kill} with a
+   * reason, the registry appends that reason.
+   */
   detail?: string
-  /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
-  output?: string
+  /**
+   * Return value for jobs whose result is a value rather than a stream (a
+   * workflow's rendered result, a subagent's report). The output ring carries
+   * the stream; this is handed out once by the model's next {@link JobRegistry.read}.
+   */
+  result?: string
+}
+
+/** One incremental read from a {@link JobOutputSource}. */
+export interface JobSourceRead {
+  /** Text captured since the requested offset (the whole retained tail when lossy). */
+  text: string
+  /** Whole-stream offset to resume from on the next read. */
+  nextOffset: number
+  /** True when the requested offset slid out of the source's retained window. */
+  lossy: boolean
+  /**
+   * Host path of a file holding the complete stream, when the source
+   * currently keeps an intact one. Reported on every read, so the registry
+   * tracks it as source metadata: a later read without it withdraws the file.
+   */
+  spillPath?: string
 }
 
 /**
- * Producer declaration passed to {@link JobRegistry.start}. The runtime
- * preflights access and cleanup before invoking {@link run}; the producer owns
- * execution resources while the runtime owns identity and lifecycle state.
+ * A pull source the registry pumps into the job's output ring — the subprocess
+ * `readFrom` family. The registry owns the cadence and drains every source one
+ * last time before settlement closes the ring, so a producer folds nothing
+ * into its `done`.
  */
-export interface JobStart {
-  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
-  kind: JobKind
-  /** One-line model-facing label (the command; the delegation description). */
-  label: string
+export interface JobOutputSource {
+  /** Stream label attached to every chunk this source yields. */
+  channel?: JobChannel
   /**
-   * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including controller status metadata.
+   * Read everything captured since `fromByte` without consuming it.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first).
+   * @returns the delta text, the next offset, the lossy flag, and the spill path the source currently keeps.
    */
-  outputLimitBytes?: number
+  read(fromByte: number): JobSourceRead
+}
+
+/** Options for one {@link JobHandle.append}. */
+export interface JobAppendOptions {
+  /** Stream label for the chunk; omitted for producers without distinct streams. */
+  channel?: JobChannel
   /**
-   * Owning live agent. Access is fenced by its session id, and agent disposal
-   * cancels and awaits the job. The instance must be the one currently
-   * registered under its agent id. Omitting the owner creates an unowned job,
-   * open to any caller until service disposal.
+   * Marks that producer-side bytes between the previous chunk and this one
+   * were lost, so an observer can render the discontinuity instead of a
+   * silent splice.
    */
-  owner?: Agent
+  gapBefore?: true
+}
+
+/**
+ * Producer face of one registered job, handed to {@link JobSpec.run} and
+ * valid for the job's whole life. All methods are synchronous. Writes staged
+ * inside the starter call are retained and become visible with the
+ * registration commit; after settlement — the producer's own outcome, a kill,
+ * or a registry-forced teardown end — writes log and drop instead of
+ * throwing, so a producer's trailing flush cannot break its own teardown path.
+ */
+export interface JobHandle {
+  /** The registry-issued id (`<kind>-N`). */
+  readonly id: JobId
   /**
-   * Start the work after preflight and synchronously return its hooks. Called
-   * once; a throw leaves nothing registered, and the producer must clean up any
-   * partially started resources.
+   * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8
+   * byte length; an empty chunk is dropped without waking observers.
+   * @param text - the chunk text, exactly as produced.
+   * @param options - stream label and gap marker.
    */
-  run(): JobHooks
+  append(text: string, options?: JobAppendOptions): void
+  /**
+   * Replace the live progress line (`3/10`, the current phase). Settlement
+   * clears it; the terminal reason travels in {@link JobOutcome.detail}.
+   * @param line - the new progress line.
+   */
+  updateProgress(line: string): void
 }
 
 /** Hooks through which the runtime controls and observes producer work. */
@@ -82,79 +115,132 @@ export interface JobHooks {
    * registry record without claiming that the work stopped.
    */
   done: Promise<JobOutcome>
-  /**
-   * Consume output produced since the previous call. The producer formats
-   * truncation and spill notices. Absence marks a final-output-only job; each
-   * job has one consuming cursor.
-   */
-  readOutput?(): string
 }
 
 /**
- * A read-only projection of one job, safe to hand to listeners and tools —
- * a fresh object per call, never live registry state.
+ * Producer declaration passed to {@link JobRegistry.start}. The runtime
+ * preflights access and cleanup before invoking {@link run}; the producer owns
+ * execution resources while the runtime owns identity, lifecycle state, and
+ * the output ring.
  */
-export interface JobSnapshot {
-  /** The registry-issued id (`<kind>-N`). */
-  id: JobId
-  /** The producer kind the job was registered with. */
+export interface JobSpec {
+  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
   kind: JobKind
-  /** The producer-supplied one-line label. */
+  /** One-line model-facing label (the command; the delegation description). */
   label: string
-  /** Producer-owned cap for complete model-facing notices and output reads. */
+  /**
+   * Owning session. Access is fenced by it, and the owner's live Agent must be
+   * the one currently registered under that id: its disposal cancels and
+   * awaits the job. Omitting the owner creates an unowned job, open to any
+   * caller until service disposal.
+   */
+  owner?: SessionId
+  /**
+   * Optional UTF-8 byte cap for each complete model-facing completion notice or
+   * output read, including controller status metadata. Independent of ring
+   * retention: it bounds the consuming model surface, never observers.
+   */
   outputLimitBytes?: number
   /**
-   * Owner session id used for authorization and correlation; absent for
-   * unowned jobs. Completion listeners receive the exact {@link Agent}
-   * separately through {@link JobDoneListener}.
+   * Pull sources the registry pumps into the ring at its own cadence.
+   * Producers that narrate their own progress use {@link JobHandle.append}
+   * instead; a job may use both.
    */
-  ownerSession?: SessionId
-  /** Current lifecycle state. */
-  status: JobStatus
-  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
-  detail?: string
-  /** Epoch ms when the job was registered. */
-  startedAt: number
-  /** Epoch ms when the job settled; absent while `running`/`stopping`. */
-  finishedAt?: number
+  output?: readonly JobOutputSource[]
   /**
-   * True when a kill, read, wait, or teardown cancel has reported or committed
-   * to report the terminal state. Completion reporters suppress redundant
-   * notices when set. Teardown claims it because the owner or service being
-   * destroyed leaves no reader: a reporter that opens a turn on notice would
-   * otherwise spend a model request per teardown layer.
+   * Start the work after preflight and synchronously return its hooks. Called
+   * once with the job's producer face; a throw leaves nothing registered (the
+   * spent ordinal is skipped), and the producer must clean up any partially
+   * started resources.
+   * @param job - the issued id plus the ring append and progress writers.
    */
-  reported: boolean
+  run(job: JobHandle): JobHooks
 }
 
-/** Output and post-read state returned by {@link JobRegistry.read}. */
+/** Output and post-read state returned by the consuming {@link JobRegistry.read}. */
 export interface JobRead {
-  /**
-   * Stream kinds: the consuming delta since the previous read. Final-output
-   * kinds: empty while live, the terminal {@link JobOutcome.output} (or
-   * empty) once settled — idempotent, never consumed.
-   */
-  text: string
+  /** Ring chunks appended since the model cursor, in offset order; every channel included. */
+  chunks: readonly JobChunk[]
+  /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
+  /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */
+  result?: string
   /** The job's state at read time. */
-  snapshot: JobSnapshot
+  job: JobView
+}
+
+/** Result of one non-consuming {@link JobRegistry.readAt}. */
+export interface JobOutputRead {
+  /** Retained chunks overlapping `[from, total)`, in offset order. */
+  chunks: readonly JobChunk[]
+  /**
+   * Offset to resume from — the ring's current `total`. Always a chunk
+   * boundary: appends land whole and trimming only advances chunk starts, and
+   * consumers concatenate `chunks` under that assumption, so a provider
+   * serving partial chunks would silently duplicate text.
+   */
+  next: number
+  /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
 }
 
 /**
- * Completion callback with the exact owner supplied at start, or `undefined`
- * for an unowned job. Returned promises are observed but not awaited.
+ * Why a job settled: its producer finished (`producer`), a
+ * {@link JobRegistry.kill} ran first (`kill`), or owner or service teardown
+ * cancelled it (`teardown`) — a settlement whose owner has no reader left.
  */
-export type JobDoneListener = (
-  snapshot: JobSnapshot,
-  owner: Agent | undefined,
-) => void | PromiseLike<void>
+export type JobSettleCause = 'producer' | 'kill' | 'teardown'
 
 /**
- * Observation callback for a change to what one owner's {@link JobRegistry.list}
- * would return. It is owner-granular rather than job-granular because the
- * change may be a removal, which no per-job record can express, and because
- * its consumers re-read the whole visible set anyway.
- *
- * An `undefined` owner means an unowned job changed, so every caller's visible
- * set changed with it.
+ * One lifecycle or output event. Lifecycle events carry the job's projection
+ * after the commit they announce; `output` carries only the id and the new
+ * total, so an observer schedules a {@link JobRegistry.readAt} from its own
+ * cursor and the registry never pushes payloads.
  */
-export type JobsChangedListener = (owner: Agent | undefined) => void
+export type JobEvent =
+  | {
+    /** Registration commit, progress line change, stopping transition, or removal from the visible set. */
+    readonly type: 'registered' | 'progress' | 'stopping' | 'removed'
+    readonly job: JobView
+  }
+  | {
+    readonly type: 'settled'
+    readonly job: JobView
+    readonly cause: JobSettleCause
+  }
+  | {
+    readonly type: 'output'
+    readonly id: JobId
+    /** Owning session, absent for an unowned job. */
+    readonly owner?: SessionId
+    /** The ring's total after the append (or at settlement, which ends the stream). */
+    readonly total: number
+  }
+
+/**
+ * Who a subscription hears about. `{ owner }` delivers that session's jobs
+ * plus every unowned job (the set that session can see). `{ owners: 'scope' }`
+ * delivers the owners composed under the subscribing context — one registry
+ * serves every composition in the process, and a mount under one preset must
+ * not hear another preset's agents. `{ owners: 'all' }` delivers everything.
+ */
+export type JobEventFilter =
+  | { readonly owner: SessionId }
+  | { readonly owners: 'all' | 'scope' }
+
+/** Event callback; contained by the registry, never awaited. */
+export type JobEventListener = (event: JobEvent) => void
+
+/** The registry's event stream. */
+export interface JobEvents {
+  /**
+   * Register an effect-scoped listener. Events are dispatched synchronously
+   * after the commit they announce; a job's first event is `registered`, and
+   * a `settled` event follows the release of every waiter. No listener runs
+   * after service disposal.
+   * @param filter - which owners' events to deliver.
+   * @param listener - receives each matching event.
+   * @returns disposer that unregisters the listener.
+   */
+  subscribe(filter: JobEventFilter, listener: JobEventListener): () => void
+}
diff --git a/packages/jobs/jobs/src/view.ts b/packages/jobs/jobs/src/view.ts
new file mode 100644
index 0000000000..39a1eb45d1
--- /dev/null
+++ b/packages/jobs/jobs/src/view.ts
@@ -0,0 +1,91 @@
+/**
+ * Client-safe job vocabulary: the read-only projection of one job and the
+ * chunks its output ring hands out. This leaf reaches no Host package, so
+ * browser programs and Remote wire types import it without pulling the
+ * registry's Host declaration merges.
+ * @module @deepseek-ai/dsh-jobs/view
+ */
+
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import type { JobId } from './brand.ts'
+
+/**
+ * Job lifecycle: `running`, optionally `stopping`, then exactly one terminal
+ * status. Producer-specific facts belong in {@link JobView.progress} and
+ * {@link JobView.detail}.
+ */
+export type JobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
+
+/**
+ * Producer-defined job kinds. Plugins extend this map by declaration merging;
+ * the registry treats every value as an opaque id namespace.
+ */
+export interface JobKindMap {
+  bash: 'bash'
+  subagent: 'subagent'
+}
+
+/** The merge-extensible union of registered producer kind names. */
+export type JobKind = JobKindMap[keyof JobKindMap]
+
+/**
+ * Stream label of one output chunk. `stdout` and `stderr` reach the model's
+ * consuming read; `log` marks producer narration (a workflow's phase lines)
+ * that only observers see. Consumers treat an unrecognized label like an
+ * absent one.
+ */
+export type JobChannel = 'stdout' | 'stderr' | 'log'
+
+/** One chunk of a job's output ring: absolute offset, text, channel, and loss marker. */
+export interface JobChunk {
+  /** Absolute offset of the chunk's first byte; offsets never move once assigned. */
+  readonly at: number
+  /** Chunk text exactly as appended (possibly tail-trimmed by retention). */
+  readonly text: string
+  /** Stream label, when the producer supplied one. */
+  readonly channel?: JobChannel
+  /** Bytes immediately before this chunk were lost, at the producer or to retention. */
+  readonly gapBefore?: true
+}
+
+/**
+ * Read-only projection of one job — a fresh object per call, never live
+ * registry state. The model tools, the browser roster, and the observation
+ * stream all consume this one shape.
+ */
+export interface JobView {
+  /** The registry-issued id (`<kind>-N`). */
+  readonly id: JobId
+  /**
+   * The producer kind the job was registered with: a Host-registered
+   * `JobKind`, carried as an open string because a browser bundle or a Remote
+   * codec sees only the `JobKindMap` merges its own program compiles.
+   */
+  readonly kind: string
+  /** The producer-supplied one-line label. */
+  readonly label: string
+  /** Owning session; absent for an unowned job, which every caller can see. */
+  readonly owner?: SessionId
+  /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */
+  readonly outputLimitBytes?: number
+  /** Current lifecycle state. */
+  readonly status: JobStatus
+  /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */
+  readonly progress?: string
+  /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */
+  readonly detail?: string
+  /** Epoch ms when the job was registered. */
+  readonly startedAt: number
+  /** Epoch ms when the job settled; absent while live. */
+  readonly finishedAt?: number
+  /**
+   * The output ring's absolute coordinates and the complete-stream files
+   * behind it. `total` is the offset the next chunk starts at (0 while
+   * nothing was written); `earliest` is the oldest retained byte, greater
+   * than zero exactly when retention dropped the head. `spillPaths` lists the
+   * spill files the job's pull sources currently keep, in source order and
+   * deduplicated, and is absent while no source keeps one: it outlives any
+   * chunk, so a reader below `earliest` can still name where the bytes went.
+   */
+  readonly output: { readonly total: number; readonly earliest: number; readonly spillPaths?: readonly string[] }
+}
diff --git a/packages/jobs/jobs/tests/invariant.spec.ts b/packages/jobs/jobs/tests/invariant.spec.ts
index 5cbaf94b11..df52f9780f 100644
--- a/packages/jobs/jobs/tests/invariant.spec.ts
+++ b/packages/jobs/jobs/tests/invariant.spec.ts
@@ -1,87 +1,193 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import JobRegistry, { JobId } from '@deepseek-ai/dsh-jobs'
-import type { JobDoneListener, JobSnapshot } from '@deepseek-ai/dsh-jobs'
+import type { JobEvent, JobEventFilter, JobEventListener, JobView } from '@deepseek-ai/dsh-jobs'
 import * as JobsInvariant from '@deepseek-ai/dsh-jobs/invariant'
 import InvariantRegistry from '@deepseek-ai/dsh-invariants'
 
-const BASE: JobSnapshot = {
-  id: JobId('bash-1'),
-  kind: 'bash',
-  label: 'compile',
-  status: 'completed',
-  startedAt: 10,
-  finishedAt: 20,
-  reported: false,
-}
+const ID = JobId('bash-1')
 
-const RUNNING: JobSnapshot = {
-  id: JobId('bash-1'),
+const RUNNING: JobView = {
+  id: ID,
   kind: 'bash',
   label: 'compile',
   status: 'running',
   startedAt: 10,
-  reported: false,
+  output: { total: 0, earliest: 0 },
 }
 
-const TERMINAL_WITHOUT_FINISH: JobSnapshot = {
-  id: JobId('bash-1'),
-  kind: 'bash',
-  label: 'compile',
-  status: 'completed',
-  startedAt: 10,
-  reported: false,
-}
+const DONE: JobView = { ...RUNNING, status: 'completed', finishedAt: 20 }
 
-async function setup(seed: JobSnapshot[] = []): Promise<(snapshot: unknown, owner?: Agent) => void> {
+/**
+ * A stub registry whose reads come from a map the test edits: the companion
+ * compares every announced projection against these reads.
+ */
+async function setup() {
   const ctx = new Context()
-  let listener: JobDoneListener | undefined
-  const probe = {
-    list: () => seed,
-    onJobDone(value: JobDoneListener) {
-      listener = value
-      return () => { listener = undefined }
-    },
-  } as unknown as JobRegistry
+  const reads = new Map<string, JobView>()
+  let listener: JobEventListener | undefined
+  /** A registry serving only the reads and the subscription the companion uses. */
+  class ProbeRegistry extends JobRegistry {
+    readonly events = {
+      subscribe: (_filter: JobEventFilter, value: JobEventListener): (() => void) => {
+        listener = value
+        return () => { listener = undefined }
+      },
+    }
+    get(id: JobId, caller?: SessionId): JobView {
+      const view = reads.get(String(id))
+      if (view === undefined || view.owner !== caller) throw new Error(`unknown job ${String(id)}`)
+      return view
+    }
+    start(): never { throw new Error('unsupported') }
+    list(): never { throw new Error('unsupported') }
+    read(): never { throw new Error('unsupported') }
+    readAt(): never { throw new Error('unsupported') }
+    kill(): never { throw new Error('unsupported') }
+    wait(): never { throw new Error('unsupported') }
+    attachController(): never { throw new Error('unsupported') }
+  }
   await ctx.plugin(InvariantRegistry)
-  await ctx.plugin({
-    name: 'job-invariant-probe',
-    apply(child: Context) { child.provide('jobs', probe) },
-  })
+  await ctx.plugin(ProbeRegistry)
   await ctx.plugin(JobsInvariant)
-  if (listener === undefined) throw new Error('job invariant did not subscribe to terminal snapshots')
-  return (snapshot, owner) => { listener!(snapshot as JobSnapshot, owner) }
+  if (listener === undefined) throw new Error('job invariant did not subscribe to the event stream')
+  const emit = (event: JobEvent): void => { listener!(event) }
+  const read = (view: JobView | undefined): void => {
+    if (view === undefined) reads.delete(String(ID))
+    else reads.set(String(view.id), view)
+  }
+  return { emit, read }
 }
 
 describe('job-registry invariants', () => {
-  it('accepts coherent current and terminal snapshots', async () => {
-    const notify = await setup([RUNNING])
-    expect(() => { notify(BASE) }).not.toThrow()
-    const owner = { id: SessionId('owner') } as Agent
-    expect(() => { notify({ ...BASE, id: JobId('subagent-2'), kind: 'subagent', ownerSession: owner.id }, owner) })
-      .not.toThrow()
+  it('accepts one job announced from registration to removal, each event agreeing with the read', async () => {
+    const { emit, read } = await setup()
+    read(RUNNING)
+    emit({ type: 'registered', job: RUNNING })
+    read({ ...RUNNING, progress: '1/2' })
+    emit({ type: 'progress', job: { ...RUNNING, progress: '1/2' } })
+    read({ ...RUNNING, progress: '1/2', output: { total: 4, earliest: 0 } })
+    emit({ type: 'output', id: ID, total: 4 })
+    read({ ...RUNNING, status: 'stopping', output: { total: 4, earliest: 0 } })
+    emit({ type: 'stopping', job: { ...RUNNING, status: 'stopping', output: { total: 4, earliest: 0 } } })
+    read({ ...DONE, status: 'killed', output: { total: 4, earliest: 0 } })
+    emit({ type: 'settled', job: { ...DONE, status: 'killed', output: { total: 4, earliest: 0 } }, cause: 'kill' })
+    emit({ type: 'output', id: ID, total: 4 })
+    read(undefined)
+    expect(() => { emit({ type: 'removed', job: { ...DONE, status: 'killed', output: { total: 4, earliest: 0 } } }) }).not.toThrow()
+  })
+
+  it('adopts a job first seen through a later event, so a companion mounted late raises nothing', async () => {
+    const { emit, read } = await setup()
+    read({ ...RUNNING, progress: '3/4' })
+    expect(() => { emit({ type: 'progress', job: { ...RUNNING, progress: '3/4' } }) }).not.toThrow()
+    read(DONE)
+    expect(() => { emit({ type: 'settled', job: DONE, cause: 'producer' }) }).not.toThrow()
+    read(undefined)
+    expect(() => { emit({ type: 'removed', job: DONE }) }).not.toThrow()
+  })
+
+  it('accepts an unowned job read through the unowned view and an owned job through its owner', async () => {
+    const { emit, read } = await setup()
+    const owner = SessionId('owner')
+    const owned: JobView = { ...RUNNING, id: JobId('subagent-2'), kind: 'subagent', owner }
+    read(RUNNING)
+    read(owned)
+    expect(() => { emit({ type: 'registered', job: RUNNING }) }).not.toThrow()
+    expect(() => { emit({ type: 'registered', job: owned }) }).not.toThrow()
+    expect(() => { emit({ type: 'output', id: owned.id, owner, total: 0 }) }).not.toThrow()
   })
 
   it.each([
-    [{ ...BASE, id: JobId('-1'), kind: '' }, undefined, /positive ordinal/],
-    [{ ...BASE, id: JobId('other-1') }, undefined, /must be "bash-" followed by a positive ordinal/],
-    [{ ...BASE, id: JobId('bash-x') }, undefined, /positive ordinal/],
-    [{ ...BASE, id: JobId('bash-0') }, undefined, /positive ordinal/],
-    [{ ...BASE, startedAt: -1 }, undefined, /startedAt must be a non-negative epoch integer/],
-    [{ ...BASE, startedAt: 0.5 }, undefined, /startedAt must be a non-negative epoch integer/],
-    [{ ...BASE, status: 'running' }, undefined, /finishedAt must be present exactly for a terminal status/],
-    [TERMINAL_WITHOUT_FINISH, undefined, /finishedAt must be present exactly for a terminal status/],
-    [{ ...BASE, finishedAt: 9 }, undefined, /no earlier than startedAt/],
-    [{ ...BASE, finishedAt: 20.5 }, undefined, /no earlier than startedAt/],
-    [{ ...BASE, ownerSession: SessionId('recorded') }, { id: SessionId('actual') } as Agent, /does not match its completion owner/],
-  ] as const)('rejects an incoherent registry snapshot', async (snapshot, owner, message) => {
-    const notify = await setup()
-    expect(() => { notify(snapshot, owner) }).toThrow(message)
-  })
-
-  it('rejects an incoherent record already present at installation', async () => {
-    await expect(setup([{ ...BASE, label: '' }])).rejects.toThrow(/label must be non-empty/)
-  })
+    ['registered after an earlier event for the same id', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'output', id: ID, total: 0 })
+      emit({ type: 'registered', job: RUNNING })
+    }, /registered announced for job bash-1 after earlier events/],
+    ['registered twice', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'registered', job: RUNNING })
+      emit({ type: 'registered', job: RUNNING })
+    }, /registered announced for job bash-1 after earlier events/],
+    ['registered with a terminal status', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'registered', job: DONE })
+    }, /must announce a live status without finishedAt/],
+    ['progress after settlement', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'settled', job: DONE, cause: 'producer' })
+      emit({ type: 'progress', job: { ...DONE, progress: 'late' } })
+    }, /progress announced for job bash-1 after its settlement/],
+    ['stopping with a terminal status', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'stopping', job: DONE })
+    }, /stopping announced for job bash-1 with a terminal status/],
+    ['settled twice', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'settled', job: DONE, cause: 'producer' })
+      emit({ type: 'settled', job: DONE, cause: 'producer' })
+    }, /settled announced twice for job bash-1/],
+    ['settled with a live status', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'settled', job: { ...RUNNING, finishedAt: 20 }, cause: 'producer' })
+    }, /must announce a terminal status, got "running"/],
+    ['settled without finishedAt', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'settled', job: { ...RUNNING, status: 'completed' }, cause: 'producer' })
+    }, /finishedAt no earlier than startedAt/],
+    ['settled before it started', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'settled', job: { ...DONE, finishedAt: 9 }, cause: 'producer' })
+    }, /finishedAt no earlier than startedAt/],
+    ['settled with a progress line', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'settled', job: { ...DONE, progress: '9/10' }, cause: 'producer' })
+    }, /must announce a cleared progress line/],
+    ['settled while the registry still reads it live', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'settled', job: DONE, cause: 'producer' })
+    }, /announces completed at 20 while the registry reads running at undefined/],
+    ['removed before settlement', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'registered', job: RUNNING })
+      read(undefined)
+      emit({ type: 'removed', job: RUNNING })
+    }, /removed announced for job bash-1 before its settlement/],
+    ['removed while the registry still returns the job', ({ emit, read }) => {
+      read(DONE)
+      emit({ type: 'settled', job: DONE, cause: 'producer' })
+      emit({ type: 'removed', job: DONE })
+    }, /removed announced for job bash-1 that the registry still returns/],
+    ['output ahead of the read total', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'output', id: ID, total: 8 })
+    }, /output announced for job bash-1 at total 8 ahead of the registry's 0/],
+    ['output for a job the registry no longer returns', ({ emit }) => {
+      emit({ type: 'output', id: ID, total: 0 })
+    }, /output announced for job bash-1 that the registry no longer returns/],
+    ['a lifecycle event for a job the registry does not return', ({ emit }) => {
+      emit({ type: 'registered', job: RUNNING })
+    }, /registered announced for job bash-1 that the registry does not return/],
+    ['an announced label the registry does not read', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'registered', job: { ...RUNNING, label: 'link' } })
+    }, /announces label "link" while the registry reads "compile"/],
+    ['an announced owner the registry does not read', ({ emit, read }) => {
+      read({ ...RUNNING, owner: SessionId('alice') })
+      emit({ type: 'registered', job: { ...RUNNING, owner: SessionId('alice') } })
+      read({ ...RUNNING, owner: SessionId('alice'), startedAt: 11 })
+      emit({ type: 'progress', job: { ...RUNNING, owner: SessionId('alice'), progress: 'x' } })
+    }, /announces startedAt 10 while the registry reads 11/],
+    ['an announced output total ahead of the read', ({ emit, read }) => {
+      read(RUNNING)
+      emit({ type: 'registered', job: { ...RUNNING, output: { total: 2, earliest: 0 } } })
+    }, /announces output total 2 ahead of the registry's 0/],
+  ] as const satisfies readonly (readonly [string, (probe: Awaited<ReturnType<typeof setup>>) => void, RegExp])[])(
+    'rejects %s',
+    async (_name, script, message) => {
+      const probe = await setup()
+      expect(() => { script(probe) }).toThrow(message)
+    },
+  )
 })
diff --git a/packages/jobs/jobs/tests/service.spec.ts b/packages/jobs/jobs/tests/service.spec.ts
index 6e6ef6accb..3b87863c70 100644
--- a/packages/jobs/jobs/tests/service.spec.ts
+++ b/packages/jobs/jobs/tests/service.spec.ts
@@ -1,59 +1,72 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import { JobId, JobRegistry } from '@deepseek-ai/dsh-jobs'
 import type {
-  JobDoneListener, JobRead, JobSnapshot, JobStart, JobsChangedListener,
+  JobEvent, JobEventFilter, JobEventListener, JobHooks, JobOutputSource, JobOutputRead, JobRead, JobSpec, JobView,
 } from '@deepseek-ai/dsh-jobs'
 
+/** Compile-time probe: does `Shape` carry a `Key` member? */
+type HasKey<Shape, Key extends string> = Key extends keyof Shape ? true : false
+
 /**
- * Minimal concrete registry: one canned record. The Service Definition owns the contract
- * only (ids, snapshots, authorization-shaped signatures); the registry
+ * Minimal concrete registry: one canned row. The Service Definition owns the
+ * contract only (ids, caller-scoped operations, the event stream); the registry
  * behavior suite lives with `@deepseek-ai/dsh-jobs-local`.
  */
 class StubJobRegistry extends JobRegistry {
-  snapshotOf(id: JobId): JobSnapshot {
+  readonly subscriptions: { filter: JobEventFilter; listener: JobEventListener }[] = []
+  readonly started: JobSpec[] = []
+
+  readonly events = {
+    subscribe: (filter: JobEventFilter, listener: JobEventListener): (() => void) => {
+      const entry = { filter, listener }
+      this.subscriptions.push(entry)
+      return () => { this.subscriptions.splice(this.subscriptions.indexOf(entry), 1) }
+    },
+  }
+
+  private view(id: JobId, owner: SessionId | undefined): JobView {
     return {
       id,
       kind: 'bash',
       label: 'sleep 60',
+      ...owner !== undefined ? { owner } : {},
       status: 'running',
       startedAt: 0,
-      reported: false,
+      output: { total: 0, earliest: 0 },
     }
   }
 
-  start(spec: JobStart): JobId {
-    spec.run()
-    return JobId(`${spec.kind}-1`)
+  start(spec: JobSpec): JobId {
+    this.started.push(spec)
+    const id = JobId(`${spec.kind}-1`)
+    spec.run({ id, append() {}, updateProgress() {} })
+    return id
   }
 
-  list(): JobSnapshot[] {
-    return [this.snapshotOf(JobId('bash-1'))]
+  list(caller?: SessionId): JobView[] {
+    return [this.view(JobId('bash-1'), caller)]
   }
 
-  get(id: JobId): JobSnapshot {
-    return this.snapshotOf(id)
+  get(id: JobId, caller?: SessionId): JobView {
+    return this.view(id, caller)
   }
 
-  read(id: JobId): JobRead {
-    return { text: '', snapshot: this.snapshotOf(id) }
+  read(id: JobId, caller?: SessionId): JobRead {
+    return { chunks: [], lossy: false, job: this.view(id, caller) }
   }
 
-  kill(): 'requested' | 'already-finished' {
+  readAt(_id: JobId, from: number): JobOutputRead {
+    return { chunks: [], next: from, lossy: false }
+  }
+
+  kill(): 'requested' {
     return 'requested'
   }
 
-  wait(id: JobId, _timeoutMs: number, _caller?: Agent, _signal?: AbortSignal): Promise<JobSnapshot> {
-    return Promise.resolve(this.snapshotOf(id))
-  }
-
-  onJobDone(_listener: JobDoneListener): () => void {
-    return () => {}
-  }
-
-  onJobsChanged(_listener: JobsChangedListener): () => void {
-    return () => {}
+  wait(id: JobId, _timeoutMs: number, caller?: SessionId): Promise<JobView> {
+    return Promise.resolve(this.view(id, caller))
   }
 
   attachController(_name: string): () => void {
@@ -65,22 +78,63 @@ describe('JobRegistry seam', () => {
   it('a concrete subclass registers as ctx.jobs and serves the abstract API', async () => {
     const ctx = new Context()
     await ctx.plugin(StubJobRegistry)
+    const caller = SessionId('session-1')
+    const hooks: JobHooks = { cancel() {}, done: new Promise(() => {}) }
 
     const detachController = ctx.jobs.attachController('seam-test')
-    const id = ctx.jobs.start({ kind: 'bash', label: 'sleep 60', run: () => ({ cancel() {}, done: new Promise(() => {}) }) })
+    const id = ctx.jobs.start({ kind: 'bash', label: 'sleep 60', owner: caller, run: () => hooks })
     expect(id).toBe('bash-1')
-    expect(ctx.jobs.list()).toHaveLength(1)
-    expect(ctx.jobs.get(id).status).toBe('running')
-    expect(ctx.jobs.read(id).text).toBe('')
-    expect(ctx.jobs.kill(id)).toBe('requested')
-    await expect(ctx.jobs.wait(id, 5)).resolves.toMatchObject({ id })
-    const detachListener = ctx.jobs.onJobDone(() => {})
-    detachListener()
-    const detachChanges = ctx.jobs.onJobsChanged(() => {})
-    detachChanges()
+
+    const jobs = ctx.jobs
+    expect(jobs.list(caller)).toHaveLength(1)
+    expect(jobs.get(id, caller).status).toBe('running')
+    expect(jobs.get(id, caller).owner).toBe(caller)
+    expect(jobs.read(id, caller)).toMatchObject({ chunks: [], lossy: false, job: { id } })
+    expect(jobs.readAt(id, 7, caller)).toEqual({ chunks: [], next: 7, lossy: false })
+    expect(jobs.kill(id, caller, 'seam test')).toBe('requested')
+    await expect(jobs.wait(id, 5, caller)).resolves.toMatchObject({ id })
+    // Omission selects unowned jobs.
+    expect(ctx.jobs.get(id).owner).toBeUndefined()
+
+    const events: JobEvent[] = []
+    const unsubscribe = ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { events.push(event) })
+    unsubscribe()
     detachController()
   })
 
+  it('types every start the same way: one handle, pull sources optional', () => {
+    const hooks: JobHooks = { cancel() {}, done: new Promise(() => {}) }
+    const source: JobOutputSource = {
+      channel: 'stdout',
+      read: fromByte => ({ text: '', nextOffset: fromByte, lossy: false }),
+    }
+    const spec: JobSpec = {
+      kind: 'bash',
+      label: 'x',
+      output: [source],
+      run: (job) => {
+        job.append('lands in the ring', { channel: 'log' })
+        job.updateProgress('1/2')
+        return hooks
+      },
+    }
+    expect(spec.output).toHaveLength(1)
+    // Bookkeeping never reaches the public view, and the record declaration is gone.
+    const viewHasReported: HasKey<JobView, 'reported'> = false
+    const specHasRecord: HasKey<JobSpec, 'record'> = false
+    const hooksHaveReadOutput: HasKey<JobHooks, 'readOutput'> = false
+    expect([viewHasReported, specHasRecord, hooksHaveReadOutput]).toEqual([false, false, false])
+  })
+
+  it('keeps the projection kind an open string, so a program compiling fewer JobKindMap merges accepts every Host kind', () => {
+    // A browser bundle or a generated Remote codec sees only the merges its
+    // own program compiles; a literal union here would reject `pwsh`,
+    // `pty-send`, and every kind another package registers.
+    type KindIsOpenString = string extends JobView['kind'] ? true : false
+    const viewKindOpen: KindIsOpenString = true
+    expect(viewKindOpen).toBe(true)
+  })
+
   it('loading a second implementation throws (one jobs service per context — cordis standard)', async () => {
     const ctx = new Context()
     await ctx.plugin(StubJobRegistry)
diff --git a/packages/jobs/tool-jobs/README.i18n.yaml b/packages/jobs/tool-jobs/README.i18n.yaml
index f7986ed7c0..6185c49fd5 100644
--- a/packages/jobs/tool-jobs/README.i18n.yaml
+++ b/packages/jobs/tool-jobs/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/jobs/tool-jobs/README.md
-README.md: 8f3de4276d766f931f9461d25d15bf33aec26856
-README.zh.md: 83f8fca0cd7e74f4c4687351752bd8c36b002647
+README.md: 1c4c60a32e628963b4751702d522b66b73dae411
+README.zh.md: ff730b7b53d1f45cd2c5004b5d5b1df975ef53c8
diff --git a/packages/jobs/tool-jobs/README.md b/packages/jobs/tool-jobs/README.md
index 8f3de4276d..1c4c60a32e 100644
--- a/packages/jobs/tool-jobs/README.md
+++ b/packages/jobs/tool-jobs/README.md
@@ -25,19 +25,19 @@ Use `dsh-tool-jobs` to inspect and control background commands, PTY work, and su
 <a id="use-this-package"></a>
 ## Use this package
 
-Load this plugin in any composition where the agent should start, observe, and stop background jobs: it registers the three tools, attaches the controller producers need, and delivers completion notices. It requires the `ctx.tools`, `ctx.jobs`, and `ctx.systemPrompt` services from the composed harness.
+Load this plugin in any composition where the agent should start, observe, and stop background jobs: it registers the three tools, attaches the controller producers need, and delivers completion notices. It requires the `ctx.tools`, `ctx.jobs`, and `ctx.systemPrompt` services from the composed harness; completion notices resolve their destination through `ctx.agents`, which every composition with owned jobs already provides.
 
 ### The three tools
 
-- `job_output(job_id, wait?, timeout_ms?)` — Read a job's output. Stream jobs return only the output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap and leaves a still-running job alive on timeout.
+- `job_output(job_id, wait?, timeout_ms?)` — Read a job's output. Stream jobs return only the output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap and leaves a still-running job alive on timeout. A read renders stdout first and stderr in one `[stderr]` section, notes output that left memory before the read, and carries a job's result (a subagent's answer) exactly once, on the first read after settlement.
 - `job_list()` — List your background jobs with their ids, kinds, and statuses, one per line: `<id> [<kind>] <status> — <label>`.
 - `job_kill(job_id, reason?)` — Request cancellation of a running job immediately; the job settles as `killed` once its work actually stops. A terminal job returns its current snapshot, and the optional reason is recorded and forwarded to the job.
 
-The three tools return `{ text, job }`, `PublicJobSnapshot[]`, and `{ outcome: 'cancellation-requested' | 'already-finished', job }` respectively. A public snapshot carries id, kind, label, status/detail, and start/finish times and omits ownership and notification bookkeeping. All three render through generic UI cards: `read` for output and list, `execute` for kill.
+The three tools return `{ text, job }`, `PublicJobSnapshot[]`, and `{ outcome: 'cancellation-requested' | 'already-finished', job }` respectively. A public snapshot carries id, kind, label, status with the live progress line or the terminal detail, and start/finish times, and omits ownership and ring offsets. All three render through generic UI cards: `read` for output and list, `execute` for kill.
 
 ### Completion notices
 
-When a job finishes, the owning agent receives `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.` as an in-session message. A busy agent has the notice injected into its next step — the turn cannot close while the inbox holds it, so several jobs settling together cost one step rather than one turn each. An idle agent is instead woken with a follow-up turn, because an unclaimed notice is a completion the model never learns about. A kill or a terminal read/wait marks the completion reported and suppresses the redundant notice, as does the teardown cancel that drains an owner or the service.
+When a job finishes, the owning agent receives `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.` as an in-session message. A busy agent has the notice injected into its next step — the turn cannot close while the inbox holds it, so several jobs settling together cost one step rather than one turn each. An idle agent is instead woken with a follow-up turn, because an unclaimed notice is a completion the model never learns about. The plugin keeps its own ledger of what the model already collected: a `job_kill` it accepted and a `wait` that returned the terminal state claim the job, so no redundant notice follows, and a settlement caused by owner or service teardown is skipped because nobody is left to read it.
 
 Waking is bounded: each owner may be woken `maxConsecutiveWakes` times before further notices degrade to injection, and claiming any user-authored message restores the budget. The bound exists because the chain is self-exciting — a woken turn may start the background job whose completion wakes it again. `completionDelivery: quiet` keeps even idle owners on the injection lane, which deterministic transcripts need.
 
@@ -82,7 +82,8 @@ This section explains the design decisions behind the tools and points at the co
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: tool registrations, completion listener, prompt section, output capping |
+| [`src/index.ts`](src/index.ts) | Plugin entry: tool registrations, the notice ledger and settlement subscription, prompt section, output capping |
+| [`src/render.ts`](src/render.ts) | Model-facing rendering: the public projection, status lines, and the consuming delta (stdout, `[stderr]` section, dropped-output notice) |
 | — | No runtime invariant companion is published; this model-facing adapter has no independent lifecycle stream; execution relations are owned by the capability seam it calls. |
 
 ### Output capping
@@ -91,7 +92,7 @@ This section explains the design decisions behind the tools and points at the co
 
 ### Notice delivery lanes
 
-`onJobDone` skips jobs already reported or unowned. A `wakeup` delivery opens a turn on an idle owner while the budget lasts, tracked per exact `Agent` in a `WeakMap`; claiming a user-authored message (`agent/inbox/claimed`) resets that owner's budget. A busy owner — or any notice past the budget, or `quiet` delivery — is injected into the next-step inbox instead. Teardown settlements arrive already `reported`, so disposal never spends a model request announcing a notice nobody can read.
+The settlement subscription (`{ owners: 'scope' }`) skips jobs the ledger already claimed, unowned jobs, and teardown settlements, then resolves the agent registered for the owner session. A `wakeup` delivery opens a turn on an idle owner while the budget lasts, tracked per exact `Agent` in a `WeakMap`; claiming a user-authored message (`agent/inbox/claimed`) resets that owner's budget. A busy owner — or any notice past the budget, or `quiet` delivery — is injected into the next-step inbox instead. A wait claims when it starts and withdraws on timeout or abort; a removal drops the ledger entry, so the ledger only ever holds live jobs the model touched.
 
 </details>
 
@@ -153,7 +154,7 @@ Prefix-stable while tool definitions and visibility are unchanged. Registration
 
 #### What the model sees
 
-Reads return output or `(no new output)` followed by `[status: <status>]` and optional detail. An empty list returns `(no background jobs)`. Kill returns `requested cancellation of job <id>` or the existing terminal status. An unreported owned completion uses the notice above.
+Reads return output or `(no new output)` followed by `[status: <status>]` and optional detail. An empty list returns `(no background jobs)`. Kill returns `requested cancellation of job <id>` or the existing terminal status. An owned completion the model has not already collected uses the notice above.
 
 #### Token effect
 
@@ -173,7 +174,7 @@ These limits define when the tools are a poor fit. They are current package cons
 - **A settlement inside the driver's retirement window still strands its notice** — between the turn loop's last inbox check and the driver committing its idle phase the owner still reads as busy, so the notice is injected and nothing wakes. Steering has the same hole; closing it belongs to `agent-loop`.
 - **A spent wake budget is not restored by time** — only user-authored input refills it, so an unattended agent whose budget ran out collects its remaining notices on the next turn something else opens.
 - **A notice pending on an idle owner does not survive that owner's disposal** — the disposal cancel clears the unclaimed inbox, and the log keeps the insert/cancel pair as the record.
-- **Stream reads are single-consumer** — independent observers need another runtime API.
+- **Model reads are single-consumer** — independent observers use the registry's non-consuming `readAt` (the Web client's `job.follow`), not these tools.
 - **Unowned jobs have no session fence** — external callers must supply policy or avoid them.
 
 <a id="dev-note"></a>
diff --git a/packages/jobs/tool-jobs/README.zh.md b/packages/jobs/tool-jobs/README.zh.md
index 83f8fca0cd..ff730b7b53 100644
--- a/packages/jobs/tool-jobs/README.zh.md
+++ b/packages/jobs/tool-jobs/README.zh.md
@@ -25,19 +25,19 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-在 agent 需要启动、观察和停止后台任务的任何组合中加载本插件：它注册三个工具、附加生产方所需的控制器，并投递完成通知。它需要组合中已提供的 `ctx.tools`、`ctx.jobs` 与 `ctx.systemPrompt` 服务。
+在 agent 需要启动、观察和停止后台任务的任何组合中加载本插件：它注册三个工具、附加生产方所需的控制器，并投递完成通知。它需要组合中已提供的 `ctx.tools`、`ctx.jobs` 与 `ctx.systemPrompt` 服务；完成通知经 `ctx.agents` 解析投递目标，凡有归属任务的组合都已提供它。
 
 ### 三个工具
 
-- `job_output(job_id, wait?, timeout_ms?)`——读取任务输出。流任务只返回自上次读取以来的输出；最终输出任务在结算后返回其结果。每个响应都以 `[status: ...]` 结尾。除非 `wait: true`，否则读取是非阻塞的；`wait: true` 最多等待到配置上限，超时时仍让运行中的任务保持存活。
+- `job_output(job_id, wait?, timeout_ms?)`——读取任务输出。流任务只返回自上次读取以来的输出；最终输出任务在结算后返回其结果。每个响应都以 `[status: ...]` 结尾。除非 `wait: true`，否则读取是非阻塞的；`wait: true` 最多等待到配置上限，超时时仍让运行中的任务保持存活。一次读取先渲染 stdout，再把 stderr 放进一段 `[stderr]`，标注读取前已离开内存的输出，并在结算后的第一次读取恰好携带一次任务的结果（subagent 的回答）。
 - `job_list()`——列出你的后台任务及其 id、kind 与状态，每行一个：`<id> [<kind>] <status> — <label>`。
 - `job_kill(job_id, reason?)`——立即请求取消运行中的任务；任务在其工作真正停止后以 `killed` 结算。终止任务返回其当前快照，可选的原因会被记录并转发给任务。
 
-三个工具依次返回 `{ text, job }`、`PublicJobSnapshot[]` 与 `{ outcome: 'cancellation-requested' | 'already-finished', job }`。公共快照携带 id、kind、label、status/detail 及开始／结束时间，并省略归属与通知簿记字段。三个工具都通过通用 UI 卡片渲染：output 和 list 用 `read`，kill 用 `execute`。
+三个工具依次返回 `{ text, job }`、`PublicJobSnapshot[]` 与 `{ outcome: 'cancellation-requested' | 'already-finished', job }`。公共快照携带 id、kind、label、带实时进度行或终态 detail 的状态，以及开始／结束时间，并省略归属与环偏移。三个工具都通过通用 UI 卡片渲染：output 和 list 用 `read`，kill 用 `execute`。
 
 ### 完成通知
 
-任务完成时，拥有它的 agent 会收到会话内消息 `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.`。繁忙的 agent 会在下一步收到注入的通知——inbox 尚有内容时轮次无法结束，因此同时结算的多个任务只花掉一步，而不是各占一轮。空闲的 agent 则被一个 follow-up 轮次唤醒，因为无人领取的通知等于模型永远不会知道的完成。kill 或针对终止任务的 read/wait 会把完成标为已报告并抑制重复通知；排空 owner 或服务的 teardown 取消同样如此。
+任务完成时，拥有它的 agent 会收到会话内消息 `background job <id> (<kind>: <label>) finished [status: ...]. Read its output with job_output.`。繁忙的 agent 会在下一步收到注入的通知——inbox 尚有内容时轮次无法结束，因此同时结算的多个任务只花掉一步，而不是各占一轮。空闲的 agent 则被一个 follow-up 轮次唤醒，因为无人领取的通知就是模型永远不会知道的完成。插件自己记着模型已经收走了什么：被接受的 `job_kill` 与返回终态的 `wait` 会认领该任务，之后不再有多余通知；所有者或服务 teardown 导致的结算会被跳过，因为没有人能读它。
 
 唤醒是有界的：每个所有者最多可被唤醒 `maxConsecutiveWakes` 次，此后的通知降级为注入；领取任何用户撰写的消息都会恢复预算。设界是因为这条链会自激——被唤醒的一轮可能启动某个后台任务，而它的完成又会唤醒同一个所有者。`completionDelivery: quiet` 让空闲所有者也在注入通道上，确定性 transcript（文本记录）需要的正是这一点。
 
@@ -82,8 +82,9 @@ kind: "package-reference"
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、完成监听器、提示词区段、输出上限 |
-| — | 不发布运行时不变式伴生入口；这个面向模型的适配器没有独立的生命周期流；执行关系归其调用的能力 seam 所有。 |
+| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、播报台账与结算订阅、提示词区段、输出上限 |
+| [`src/render.ts`](src/render.ts) | 面向模型的渲染：公共投影、状态行与消耗式增量（stdout、`[stderr]` 段、丢失输出提示） |
+| — | 不发布运行时不变式伴生入口；执行关系归能力 seam 所有。 |
 
 ### 输出上限
 
@@ -91,7 +92,7 @@ kind: "package-reference"
 
 ### 通知投递通道
 
-`onJobDone` 跳过已报告或无所有者的任务。`wakeup` 投递在预算内为空闲所有者开启一轮，按确切 `Agent` 记录在 `WeakMap` 中；领取用户撰写的消息（`agent/inbox/claimed`）会重置该所有者的预算。繁忙的所有者——或超出预算的任何通知，以及 `quiet` 投递——改为注入 next-step inbox。teardown 结算抵达时已标记为 `reported`，因此释放永远不会花一次模型请求来宣布无人能读的通知。
+结算订阅（`{ owners: 'scope' }`）跳过台账已认领的任务、无所有者的任务与 teardown 结算，然后解析登记在拥有者会话下的 agent。`wakeup` 投递在预算内为空闲所有者开启一轮，按确切 `Agent` 记录在 `WeakMap` 中；领取用户撰写的消息（`agent/inbox/claimed`）会重置该所有者的预算。繁忙的所有者——或超出预算的任何通知，以及 `quiet` 投递——改为注入 next-step inbox。等待在开始时认领、在超时或中止时撤回；移除会删除台账条目，因此台账只保有模型触碰过的存活任务。
 
 </details>
 
@@ -153,7 +154,7 @@ Track every background job id you start. You are notified in-session when a job
 
 #### 模型看到什么
 
-读取会返回输出或 `(no new output)`，随后是 `[status: <status>]` 和可选 detail。空列表返回 `(no background jobs)`。kill 返回 `requested cancellation of job <id>` 或现有终止状态。尚未报告且有所有者归属的完成使用上述通知。
+读取会返回输出或 `(no new output)`，随后是 `[status: <status>]` 和可选 detail。空列表返回 `(no background jobs)`。kill 返回 `requested cancellation of job <id>` 或现有终止状态。模型尚未收走且有所有者归属的完成使用上述通知。
 
 #### Token 影响
 
@@ -173,7 +174,7 @@ Track every background job id you start. You are notified in-session when a job
 - **落在 driver 退休窗口内的结算仍会让通知搁浅**——在轮次循环最后一次检查 inbox 与 driver 提交 idle 相位之间，所有者读起来仍是繁忙，因此通知走注入且无人唤醒。steering（中途引导）存在同样的问题；修复它属于 `agent-loop`。
 - **已花掉的唤醒预算不会随时间恢复**——只有用户撰写的输入才能补充，因此预算耗尽的无人值守 agent 要等到其他原因开启下一轮时才收走剩余通知。
 - **待领于空闲所有者的通知无法在该所有者释放后存活**——释放时的取消会清空未领取的 inbox，日志保留插入/取消这一对作为记录。
-- **流读取只有单一消费方**——独立观察者需要另一套运行时 API。
+- **模型读取只有单一消费方**——独立观察者使用注册表非消耗的 `readAt`（Web 客户端的 `job.follow`），而不是这些工具。
 - **无 owner 的任务没有会话隔离**——外部调用方必须提供策略或避开这些任务。
 
 <a id="dev-note"></a>
diff --git a/packages/jobs/tool-jobs/src/index.ts b/packages/jobs/tool-jobs/src/index.ts
index 210005be6a..cd75bb3a8b 100644
--- a/packages/jobs/tool-jobs/src/index.ts
+++ b/packages/jobs/tool-jobs/src/index.ts
@@ -1,9 +1,10 @@
 /**
  * Model-facing `job_output`, `job_list`, and `job_kill` tools over
  * `ctx.jobs`. Loading the plugin attaches the controller required by
- * producers. It also delivers unreported completions to the owning agent:
- * injected into a busy owner's next step, or opening a turn on an idle one
- * under the default `wakeup` delivery, bounded per owner.
+ * producers. It also delivers completions the model has not already
+ * collected to the owning agent: injected into a busy owner's next step, or
+ * opening a turn on an idle one under the default `wakeup` delivery, bounded
+ * per owner.
  * @module @deepseek-ai/dsh-tool-jobs
  */
 
@@ -15,8 +16,11 @@ import { TextRetainer } from '@deepseek-ai/dsh-output-retention'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, ToolDefinition, ToolExecution } from '@deepseek-ai/dsh-tools'
 import { JobId } from '@deepseek-ai/dsh-jobs'
-import type { JobSnapshot } from '@deepseek-ai/dsh-jobs'
+import type { JobView, JobRead } from '@deepseek-ai/dsh-jobs'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-agent'
+import { publicJob, renderModelDelta, statusLine } from './render.ts'
+import type { PublicJobSnapshot } from './render.ts'
 declare module '@deepseek-ai/dsh-llm' {
   interface MessageSourceMap {
     'tool-jobs': { kind: 'tool-jobs' } & ContextFormed
@@ -27,12 +31,23 @@ export const name = 'tool-jobs'
 export const inject = ['tools', 'jobs', 'systemPrompt']
 
 /**
- * How an unreported completion reaches an owner that is already idle: `wakeup`
+ * How an uncollected completion reaches an owner that is already idle: `wakeup`
  * opens a turn for it, `quiet` leaves it pending until something else wakes the
  * owner. A busy owner is injected either way.
  */
 export type CompletionDelivery = 'quiet' | 'wakeup'
 
+/**
+ * One model touch of a live job's settlement: a wait in flight or a kill the
+ * model requested. `live` says whether the tool result that made the claim
+ * will still carry the settlement; a wait's claim dies the moment its caller
+ * aborts, before the registry's rejection reaches the tool.
+ */
+interface Claim {
+  readonly id: JobId
+  live: boolean
+}
+
 /** Configures bounded `job_output` waits and completion-notice delivery. */
 export interface Config {
   /** Wait duration applied when `job_output` sets `wait` without `timeout_ms` (default 30s). */
@@ -57,17 +72,6 @@ export const Config: z<Config> = z.object({
   maxConsecutiveWakes: z.number().min(1).default(3),
 })
 
-/** Task state safe for model-authored programs; ownership/bookkeeping fields are omitted. */
-export interface PublicJobSnapshot {
-  id: string
-  kind: string
-  label: string
-  status: JobSnapshot['status']
-  detail?: string
-  startedAt: number
-  finishedAt?: number
-}
-
 /** Shared schema for job-control outputs. */
 const PUBLIC_JOB_SCHEMA = {
   type: 'object',
@@ -87,30 +91,6 @@ const PUBLIC_JOB_SCHEMA = {
   },
 } as const
 
-/** Remove job ownership and notification bookkeeping from a registry snapshot. */
-function publicJob(snapshot: JobSnapshot): PublicJobSnapshot {
-  return {
-    id: snapshot.id,
-    kind: snapshot.kind,
-    label: snapshot.label,
-    status: snapshot.status,
-    ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {},
-    startedAt: snapshot.startedAt,
-    ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {},
-  }
-}
-
-/**
- * Render generic status with optional producer detail.
- * @param snapshot - job state to render.
- * @returns a bracketed status line.
- */
-export function statusLine(snapshot: Pick<JobSnapshot, 'status' | 'detail'>): string {
-  return snapshot.detail !== undefined
-    ? `[status: ${snapshot.status}, ${snapshot.detail}]`
-    : `[status: ${snapshot.status}]`
-}
-
 const encoder = new TextEncoder()
 
 function retainTail(text: string, maxBytes: number): string {
@@ -141,19 +121,19 @@ function fitWithSuffix(
 
 /**
  * One-line account of a settled job for the `notice` form's collapsed row.
- * @param snapshot - the settled job.
+ * @param job - the settled job.
  * @returns its kind, label, and status, bounded like every notice summary.
  */
-function completionSummary(snapshot: JobSnapshot): string {
-  return boundContextSummary(`${snapshot.kind} ${snapshot.label} ${statusLine(snapshot)}`)
+function completionSummary(job: JobView): string {
+  return boundContextSummary(`${job.kind} ${job.label} ${statusLine(publicJob(job))}`)
 }
 
-function fitCompletionNotice(snapshot: JobSnapshot): string {
-  const prefix = `background job ${snapshot.id}`
-  const detail = ` (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}`
+function fitCompletionNotice(job: JobView): string {
+  const prefix = `background job ${job.id}`
+  const detail = ` (${job.kind}: ${job.label}) finished ${statusLine(publicJob(job))}`
   const action = '\nDone; job_output.'
   const complete = `${prefix}${detail}. Read its output with job_output.`
-  const maxBytes = snapshot.outputLimitBytes
+  const maxBytes = job.outputLimitBytes
   if (maxBytes === undefined || encoder.encode(complete).byteLength <= maxBytes) return complete
   const omitted = '\n[notice truncated]'
   const fixed = `${prefix}${omitted}${action}`
@@ -187,11 +167,12 @@ function boundSingleText(content: readonly ContentBlock[], maxBytes: number): Co
   }]
 }
 
+/** The producer's cap for the job a `job_output` or `job_kill` call names, when it is visible to the caller. */
 function visibleOutputLimit(ctx: Context, exec: ToolExecution): number | undefined {
   if (exec.name !== 'job_output' && exec.name !== 'job_kill') return undefined
   const jobId = (exec.arguments as { job_id?: unknown } | null | undefined)?.job_id
   if (typeof jobId !== 'string' || jobId.length === 0) return undefined
-  return ctx.jobs.list(exec.agent).find(snapshot => snapshot.id === jobId)?.outputLimitBytes
+  return ctx.jobs.list(exec.agent?.id).find(job => job.id === jobId)?.outputLimitBytes
 }
 
 /** Validate the non-empty constraint that ParameterSchemaSpec cannot express. */
@@ -207,6 +188,20 @@ function presentJobCall(title: string, kind: 'read' | 'execute', rawInput?: stri
   return { card: 'generic', title, kind, ...rawInput !== undefined ? { rawInput } : {} }
 }
 
+/** True for the three terminal statuses. */
+function isTerminal(job: JobView): boolean {
+  return job.status === 'completed' || job.status === 'killed' || job.status === 'failed'
+}
+
+/** The consuming read as the model sees it: the delta, then the result once, then the status line. */
+function readBody(read: JobRead): { text: string; job: PublicJobSnapshot } {
+  const delta = renderModelDelta(read.chunks, read.lossy, read.job.output.spillPaths ?? [])
+  const text = read.result === undefined
+    ? delta
+    : `${delta}${delta.length > 0 && !delta.endsWith('\n') ? '\n' : ''}${read.result}`
+  return { text, job: publicJob(read.job) }
+}
+
 export function apply(ctx: Context, config: Config): void {
   const waitDefault = config.waitTimeoutMs ?? 30_000
   const waitCap = config.maxWaitTimeoutMs ?? 600_000
@@ -271,27 +266,62 @@ export function apply(ctx: Context, config: Config): void {
     text: 'Track every background job id you start. You are notified in-session when a job finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running job\'s work. Before giving a final answer, collect every still-relevant job with job_output (set wait: true only when you are genuinely blocked on it), and job_kill jobs that stopped mattering.',
   })
 
-  // Use the exact lifecycle owner; reusable ids could resolve to a replacement.
+  // Jobs whose terminal state this plugin already handed to the model through
+  // a tool result: a terminal `job_output`, a wait that returned it, or a
+  // `job_kill` it requested. A wait claims when it starts, not when it
+  // returns — settlement releases waiters before it announces, but their
+  // continuations run after the event. Each call holds its own claim, so a
+  // timed-out wait drops only its own while a concurrent wait on the same job
+  // keeps the settlement covered. The settlement event drops every claim on
+  // the job, so the ledger holds only live jobs the model already touched.
+  const claims = new Set<Claim>()
+  const claim = (id: JobId): Claim => {
+    const entry: Claim = { id, live: true }
+    claims.add(entry)
+    return entry
+  }
+  // Drop every claim on the job; true when one of them still covered the settlement.
+  const settleClaims = (id: JobId): boolean => {
+    let covered = false
+    for (const entry of claims) {
+      if (entry.id !== id) continue
+      claims.delete(entry)
+      if (entry.live) covered = true
+    }
+    return covered
+  }
+
   // A busy owner is injected: the notice waits in its next-step inbox, which
   // the turn cannot close over, so jobs settling together cost one step. An
   // idle owner is woken instead, because an unclaimed notice is a completion
   // the model never learns about. Either way, disposal before the claim
-  // discards it with the owner, and teardown settlements arrive `reported`.
+  // discards it with the owner, and a teardown settlement has no reader left.
   //
-  // The registry routes each settlement to the listeners its owner's scope
-  // chain reaches, so a mount under one preset never sees another preset's
-  // agents; this listener owns delivery, not the choice of whom to deliver to.
-  ctx.jobs.onJobDone((snapshot, owner) => {
-    if (snapshot.reported || owner === undefined) return
+  // The registry routes each settlement to the scope this plugin was mounted
+  // under, so a mount under one preset never sees another preset's agents;
+  // this listener owns delivery, not the choice of whom to deliver to.
+  ctx.jobs.events.subscribe({ owners: 'scope' }, (event) => {
+    if (event.type === 'removed') {
+      settleClaims(event.job.id)
+      return
+    }
+    if (event.type !== 'settled') return
+    const claimed = settleClaims(event.job.id)
+    if (claimed || event.cause === 'teardown' || event.job.owner === undefined) return
+    // The destination is the agent registered for the owner session now. An
+    // owned job needed the agent registry to start, so the registry is only
+    // absent here when it left before settlement — and then no inbox is left.
+    const owner = ctx.get('agents')?.get(event.job.owner)
+    if (owner === undefined) return
     const message = createUserMessage({
       content: [{
         type: 'text',
-        text: fitCompletionNotice(snapshot),
+        text: fitCompletionNotice(event.job),
       }],
       source: {
         kind: 'tool-jobs',
         form: 'notice',
-        summary: completionSummary(snapshot),
+        summary: completionSummary(event.job),
       },
     })
     const spent = spentWakes.get(owner) ?? 0
@@ -333,12 +363,30 @@ export function apply(ctx: Context, config: Config): void {
     },
     async execute(args, exec) {
       const id = validateJobId(args.job_id)
+      const jobs = ctx.jobs
       if (args.wait === true) {
         const timeout = Math.min(args.timeout_ms ?? waitDefault, waitCap)
-        await ctx.jobs.wait(id, timeout, exec.agent, exec.signal)
+        const entry = claim(id)
+        // The registry rejects an aborted wait on a later microtask, and a
+        // settlement announced in between must not find this claim live: the
+        // tool result carries the abort, so the notice is the model's only
+        // completion record. ToolRuntime never dispatches an aborted call, so
+        // the listener covers every abort. A timeout needs no such guard —
+        // the registry resolves it from a timer callback, and the wait's
+        // continuation runs before anything else can settle the job.
+        const abandon = (): void => { entry.live = false }
+        exec.signal.addEventListener('abort', abandon, { once: true })
+        try {
+          const view = await jobs.wait(id, timeout, exec.agent?.id, exec.signal)
+          if (!isTerminal(view)) claims.delete(entry)
+        } catch (error: unknown) {
+          claims.delete(entry)
+          throw error
+        } finally {
+          exec.signal.removeEventListener('abort', abandon)
+        }
       }
-      const read = ctx.jobs.read(id, exec.agent)
-      return { text: read.text, job: publicJob(read.snapshot) }
+      return readBody(jobs.read(id, exec.agent?.id))
     },
     presentCall: args => presentJobCall(`Read output from background job ${args.job_id}`, 'read', args.job_id),
   }))
@@ -357,7 +405,7 @@ export function apply(ctx: Context, config: Config): void {
       }],
     },
     execute(_args, exec) {
-      const jobs = ctx.jobs.list(exec.agent)
+      const jobs = ctx.jobs.list(exec.agent?.id)
       return Promise.resolve(jobs.map(publicJob))
     },
     presentCall: () => presentJobCall('List background jobs', 'read'),
@@ -393,12 +441,16 @@ export function apply(ctx: Context, config: Config): void {
     },
     execute(args, exec) {
       const id = validateJobId(args.job_id)
-      const result = ctx.jobs.kill(id, exec.agent, args.reason)
-      // A snapshot describes current state without consuming pending output.
-      const snapshot = publicJob(ctx.jobs.get(id, exec.agent))
+      const jobs = ctx.jobs
+      const result = jobs.kill(id, exec.agent?.id, args.reason)
+      // The model's own kill is its delivery: the settlement notice would only
+      // repeat what this tool result already said.
+      if (result === 'requested') claim(id)
+      // A projection describes current state without consuming pending output.
+      const job = publicJob(jobs.get(id, exec.agent?.id))
       return Promise.resolve({
         outcome: result === 'already-finished' ? 'already-finished' as const : 'cancellation-requested' as const,
-        job: snapshot,
+        job,
       })
     },
     presentCall: args => presentJobCall(`Kill background job ${args.job_id}`, 'execute', args.job_id),
diff --git a/packages/jobs/tool-jobs/src/render.ts b/packages/jobs/tool-jobs/src/render.ts
new file mode 100644
index 0000000000..b95eb4393b
--- /dev/null
+++ b/packages/jobs/tool-jobs/src/render.ts
@@ -0,0 +1,84 @@
+/**
+ * Model-facing rendering of registry reads: the consuming delta as the
+ * shell tools have always shown it (stdout, then one marked stderr section),
+ * the `[status: …]` line, and the public job projection the tool schemas
+ * expose.
+ * @module @deepseek-ai/dsh-tool-jobs/render
+ */
+
+import type { JobChunk, JobView } from '@deepseek-ai/dsh-jobs/view'
+
+/** Job state safe for model-authored programs; ownership and offsets are omitted. */
+export interface PublicJobSnapshot {
+  id: string
+  kind: string
+  label: string
+  status: JobView['status']
+  /** The live progress line while running, the terminal reason once settled. */
+  detail?: string
+  startedAt: number
+  finishedAt?: number
+}
+
+/**
+ * The one-line qualifier the model reads beside a status: live progress while
+ * the job runs, the terminal reason once it settled.
+ * @param job - the job projection.
+ * @returns the qualifier, or undefined when the job carries neither.
+ */
+export function jobDetail(job: Pick<JobView, 'progress' | 'detail'>): string | undefined {
+  return job.progress ?? job.detail
+}
+
+/**
+ * Remove ownership, offsets, and limits from a registry projection.
+ * @param job - the registry projection.
+ * @returns the model-safe projection.
+ */
+export function publicJob(job: JobView): PublicJobSnapshot {
+  const detail = jobDetail(job)
+  return {
+    id: job.id,
+    kind: job.kind,
+    label: job.label,
+    status: job.status,
+    ...detail !== undefined ? { detail } : {},
+    startedAt: job.startedAt,
+    ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {},
+  }
+}
+
+/**
+ * Render generic status with optional detail.
+ * @param snapshot - job state to render.
+ * @returns a bracketed status line.
+ */
+export function statusLine(snapshot: Pick<PublicJobSnapshot, 'status' | 'detail'>): string {
+  return snapshot.detail !== undefined
+    ? `[status: ${snapshot.status}, ${snapshot.detail}]`
+    : `[status: ${snapshot.status}]`
+}
+
+/**
+ * Render one consuming read for the model: stdout and unlabeled chunks in
+ * order, then every stderr chunk in one `[stderr]` section, exactly as the
+ * shell tools render a foreground result. `log` chunks are producer
+ * narration for observers and never reach the model. Lost bytes — the cursor
+ * fell behind the ring's retention, or a model-visible chunk carries a
+ * producer-side gap — end the read with the shell tools' dropped-output
+ * notice, naming the spill files the job's sources keep.
+ * @param chunks - the chunks since the model cursor, in offset order.
+ * @param lossy - whether bytes before `chunks` were evicted unread.
+ * @param spillPaths - the complete-stream files the job currently advertises (`JobView.output.spillPaths`).
+ * @returns the delta text, possibly empty.
+ */
+export function renderModelDelta(chunks: readonly JobChunk[], lossy: boolean, spillPaths: readonly string[]): string {
+  const visible = chunks.filter(chunk => chunk.channel !== 'log')
+  const out = visible.filter(chunk => chunk.channel !== 'stderr').map(chunk => chunk.text).join('')
+  const err = visible.filter(chunk => chunk.channel === 'stderr').map(chunk => chunk.text).join('')
+  const separator = out.length > 0 && !out.endsWith('\n') ? '\n' : ''
+  const body = out + (err.length > 0 ? `${separator}[stderr]\n${err}` : '')
+  if (!lossy && !visible.some(chunk => chunk.gapBefore === true)) return body
+  const notice = `[some output was dropped from memory; full output: ${spillPaths.length > 0 ? spillPaths.join(', ') : '(unavailable)'}]`
+  return `${body}${body.length > 0 && !body.endsWith('\n') ? '\n' : ''}${notice}`
+}
diff --git a/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts b/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts
index f7c543c024..f9ffa2a8b4 100644
--- a/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts
+++ b/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts
@@ -10,21 +10,26 @@ import { SessionId } from '@deepseek-ai/dsh-session'
 import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope'
 import { JobId } from '@deepseek-ai/dsh-jobs'
 import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
-import type { JobHooks, JobOutcome, JobSnapshot, JobStart } from '@deepseek-ai/dsh-jobs'
+import type { JobAppendOptions, JobHandle, JobHooks, JobOutcome, JobOutputSource, JobSpec, JobView } from '@deepseek-ai/dsh-jobs'
 import * as ToolJobs from '@deepseek-ai/dsh-tool-jobs'
-import { statusLine } from '@deepseek-ai/dsh-tool-jobs'
+import { publicJob, renderModelDelta, statusLine } from '../src/render.ts'
 
 const testToolSignal = new AbortController().signal
 
 const agentRegistryDisposers = new WeakMap<Agent, () => Promise<void>>()
 const agentScopeFibers = new WeakMap<Agent, { dispose: () => Promise<void> }>()
 
-async function setup(config: ToolJobs.Config = {}) {
+/** Registry knobs a test may narrow; every producer here pushes, so the pump stays idle. */
+interface RegistryConfig {
+  retainBytes?: number
+}
+
+async function setup(config: ToolJobs.Config = {}, registry: RegistryConfig = {}) {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRuntime)
   const agentsFiber = await ctx.plugin(AgentRegistry)
-  await ctx.plugin(LocalJobRegistry)
+  await ctx.plugin(LocalJobRegistry, registry)
   const toolsFiber = await ctx.plugin(ToolJobs, config)
   return { ctx, agentsFiber, toolsFiber }
 }
@@ -70,9 +75,13 @@ async function disposeAgentScope(agent: Agent): Promise<void> {
   await fiber.dispose()
 }
 
-/** A controllable producer start-spec (settle `done` on demand, record cancels). */
-function producer(overrides: Partial<Omit<JobStart, 'run'> & JobHooks> = {}) {
+/**
+ * A controllable producer spec: pushes output and progress through the handle
+ * the registry hands its starter, settles `done` on demand, records cancels.
+ */
+function producer(overrides: Partial<Omit<JobSpec, 'run' | 'output'> & JobHooks> = {}) {
   let settle!: (outcome: JobOutcome) => void
+  let handle: JobHandle | undefined
   const cancels: (string | undefined)[] = []
   const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, ...hookOverrides } = overrides
   const hooks: JobHooks = {
@@ -80,14 +89,24 @@ function producer(overrides: Partial<Omit<JobStart, 'run'> & JobHooks> = {}) {
     done: new Promise<JobOutcome>((res) => { settle = res }),
     ...hookOverrides,
   }
-  const spec: JobStart = {
+  const spec: JobSpec = {
     kind,
     label,
     ...owner !== undefined ? { owner } : {},
     ...outputLimitBytes !== undefined ? { outputLimitBytes } : {},
-    run: () => hooks,
+    run: (job) => { handle = job; return hooks },
+  }
+  const started = (): JobHandle => {
+    if (handle === undefined) throw new Error('producer not started')
+    return handle
+  }
+  return {
+    spec,
+    settle,
+    cancels,
+    append: (text: string, options?: JobAppendOptions) => { started().append(text, options) },
+    progress: (line: string) => { started().updateProgress(line) },
   }
-  return { spec, settle, cancels }
 }
 
 let callCounter = 0
@@ -104,7 +123,7 @@ const tick = () => new Promise<void>(r => setTimeout(r, 0))
 /** Start and settle `count` owned jobs one at a time, letting each notice land. */
 async function settleTasks(ctx: Context, owner: Agent, count: number): Promise<void> {
   for (let i = 0; i < count; i += 1) {
-    const p = producer({ owner })
+    const p = producer({ owner: owner.id })
     ctx.jobs.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
@@ -119,10 +138,26 @@ describe('tool-jobs setup', () => {
     expect(() => ctx.jobs.start(producer().spec)).toThrow('no job controller serves this agent')
   })
 
+  it('serves unowned jobs in a composition without an agent registry', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRuntime)
+    await ctx.plugin(LocalJobRegistry)
+    await ctx.plugin(ToolJobs)
+    const p = producer()
+    ctx.jobs.start(p.spec)
+    p.append('open\n')
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('open\n[status: running]')
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(text(await call(ctx, 'job_list', {}))).toBe('bash-1 [bash] completed — sleep 60')
+  })
+
   it('rejects a config whose default wait exceeds the cap', async () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRuntime)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(LocalJobRegistry)
     await expect(ctx.plugin(ToolJobs, { waitTimeoutMs: 100, maxWaitTimeoutMs: 50 }))
       .rejects.toThrow('waitTimeoutMs (100) exceeds maxWaitTimeoutMs (50)')
@@ -141,6 +176,7 @@ describe('tool-jobs setup', () => {
       const ctx = new Context()
       await ctx.plugin(SystemPrompt)
       await ctx.plugin(ToolRuntime)
+      await ctx.plugin(AgentRegistry)
       await ctx.plugin(LocalJobRegistry)
       try {
         await ctx.plugin(ToolJobs, { maxConsecutiveWakes })
@@ -158,9 +194,78 @@ describe('tool-jobs setup', () => {
   })
 
   it('renders status lines with and without producer detail', () => {
-    const base = { id: 'bash-1', kind: 'bash', label: 'x', startedAt: 0, reported: false } as unknown as JobSnapshot
-    expect(statusLine({ ...base, status: 'running' })).toBe('[status: running]')
-    expect(statusLine({ ...base, status: 'completed', detail: 'exit code: 0' })).toBe('[status: completed, exit code: 0]')
+    expect(statusLine({ status: 'running' })).toBe('[status: running]')
+    expect(statusLine({ status: 'completed', detail: 'exit code: 0' })).toBe('[status: completed, exit code: 0]')
+  })
+
+  it('projects the public job: live progress or terminal detail, never ownership or offsets', () => {
+    const live: JobView = {
+      id: JobId('bash-1'), kind: 'bash', label: 'x', owner: SessionId('sess-1'), outputLimitBytes: 8,
+      status: 'running', progress: '3/10 files', startedAt: 5, output: { total: 12, earliest: 0 },
+    }
+    expect(publicJob(live)).toEqual({ id: 'bash-1', kind: 'bash', label: 'x', status: 'running', detail: '3/10 files', startedAt: 5 })
+    const settled: JobView = {
+      id: JobId('bash-1'), kind: 'bash', label: 'x', status: 'completed', detail: 'exit code: 0',
+      startedAt: 5, finishedAt: 9, output: { total: 12, earliest: 0 },
+    }
+    expect(publicJob(settled)).toEqual({ id: 'bash-1', kind: 'bash', label: 'x', status: 'completed', detail: 'exit code: 0', startedAt: 5, finishedAt: 9 })
+  })
+
+  it('renders a model delta as stdout, one stderr section, and a dropped-output notice', () => {
+    expect(renderModelDelta([], false, [])).toBe('')
+    expect(renderModelDelta([], true, [])).toBe('[some output was dropped from memory; full output: (unavailable)]')
+    expect(renderModelDelta([
+      { at: 0, text: 'a' },
+      { at: 1, text: 'e1\n', channel: 'stderr' },
+      { at: 4, text: 'narration', channel: 'log' },
+      { at: 13, text: 'b', channel: 'stdout' },
+      { at: 14, text: 'e2', channel: 'stderr' },
+    ], false, [])).toBe('ab\n[stderr]\ne1\ne2')
+    expect(renderModelDelta([{ at: 0, text: 'tail' }], true, [])).toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
+    expect(renderModelDelta([{ at: 0, text: 'line\n' }], true, [])).toBe('line\n[some output was dropped from memory; full output: (unavailable)]')
+    // Ring eviction names the files the job's sources keep, whether or not a retained chunk carries a gap.
+    expect(renderModelDelta([{ at: 8, text: 'tail' }], true, ['/spill/out.log', '/spill/err.log']))
+      .toBe('tail\n[some output was dropped from memory; full output: /spill/out.log, /spill/err.log]')
+  })
+
+  it('reports a producer-side gap as dropped output and names the spill files the job advertises', () => {
+    // The ring itself lost nothing (`lossy: false`); the source did, between two pumps.
+    expect(renderModelDelta([{ at: 0, text: 'head' }, { at: 4, text: 'tail', gapBefore: true }], false, ['/spill/out.log']))
+      .toBe('headtail\n[some output was dropped from memory; full output: /spill/out.log]')
+    expect(renderModelDelta([
+      { at: 0, text: 'o', gapBefore: true },
+      { at: 1, text: 'e', channel: 'stderr', gapBefore: true },
+    ], false, ['/spill/out.log', '/spill/err.log'])).toBe('o\n[stderr]\ne\n[some output was dropped from memory; full output: /spill/out.log, /spill/err.log]')
+    // A gap while no source keeps a file yields the generic notice.
+    expect(renderModelDelta([{ at: 0, text: 'tail', gapBefore: true }], false, []))
+      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
+    // A gap on observer-only narration never reaches the model.
+    expect(renderModelDelta([{ at: 0, text: 'phase', channel: 'log', gapBefore: true }], false, ['/spill/log'])).toBe('')
+  })
+
+  it('names the spill file when the ring evicted output the model never read', async () => {
+    const { ctx } = await setup({}, { retainBytes: 8 })
+    const owner = await fakeAgent(ctx, 'sess-1')
+    let settle!: (outcome: JobOutcome) => void
+    // The source never reads lossy: the pump keeps up, and only the ring's live cap drops bytes.
+    const source: JobOutputSource = {
+      channel: 'stdout',
+      read: from => from === 0
+        ? { text: 'x'.repeat(32), nextOffset: 32, lossy: false, spillPath: '/spill/out.log' }
+        : { text: '', nextOffset: from, lossy: false, spillPath: '/spill/out.log' },
+    }
+    ctx.jobs.start({
+      kind: 'bash',
+      label: 'noisy',
+      owner: owner.id,
+      output: [source],
+      run: () => ({ cancel() {}, done: new Promise<JobOutcome>((resolve) => { settle = resolve }) }),
+    })
+
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }, owner)))
+      .toBe(`${'x'.repeat(8)}\n[some output was dropped from memory; full output: /spill/out.log]\n[status: running]`)
+    settle({ status: 'completed' })
+    await tick()
   })
 
   it('applies the built-in wait bounds when apply() receives a bare config', async () => {
@@ -169,6 +274,7 @@ describe('tool-jobs setup', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRuntime)
+    await ctx.plugin(AgentRegistry)
     await ctx.plugin(LocalJobRegistry)
     ToolJobs.apply(ctx, {})
     expect(ctx.tools.get('job_output')).toBeDefined()
@@ -179,8 +285,9 @@ describe('tool-jobs setup', () => {
 describe('job_output', () => {
   it('reads a consuming delta with a trailing status line', async () => {
     const { ctx } = await setup()
-    const chunks = ['line one\n', '']
-    ctx.jobs.start(producer({ readOutput: () => chunks.shift() ?? '' }).spec)
+    const p = producer()
+    ctx.jobs.start(p.spec)
+    p.append('line one\n')
 
     // A body already ending in a newline gets no doubled separator.
     const first = await call(ctx, 'job_output', { job_id: 'bash-1' })
@@ -190,29 +297,75 @@ describe('job_output', () => {
       text: 'line one\n',
       job: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'running' },
     })
-    expect(firstValue.job).not.toHaveProperty('ownerSession')
-    expect(firstValue.job).not.toHaveProperty('reported')
+    expect(firstValue.job).not.toHaveProperty('owner')
+    expect(firstValue.job).not.toHaveProperty('output')
     expect(text(first)).toBe('line one\n[status: running]')
     expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running]')
   })
 
-  it('returns the final output of a settled final-output job', async () => {
+  it('renders stderr in a trailing section and never shows log narration', async () => {
+    const { ctx } = await setup()
+    const p = producer()
+    ctx.jobs.start(p.spec)
+    p.append('out\n')
+    p.append('warn\n', { channel: 'stderr' })
+    p.append('observer-only narration', { channel: 'log' })
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('out\n[stderr]\nwarn\n[status: running]')
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running]')
+  })
+
+  it('shows live progress beside the status until settlement replaces it with the terminal detail', async () => {
+    const { ctx } = await setup()
+    const p = producer()
+    ctx.jobs.start(p.spec)
+    p.progress('3/10 files')
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running, 3/10 files]')
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: completed, exit code: 0]')
+  })
+
+  it('flags a read whose cursor fell behind the ring', async () => {
+    const { ctx } = await setup({}, { retainBytes: 16 })
+    const p = producer()
+    ctx.jobs.start(p.spec)
+    p.append('x'.repeat(40))
+    const first = text(await call(ctx, 'job_output', { job_id: 'bash-1' }))
+    expect(first).toContain('[some output was dropped from memory; full output: (unavailable)]')
+    expect(first).toContain('[status: running]')
+    expect(first).not.toContain('x'.repeat(17))
+    // The cursor now sits at the ring's end: the next read is clean.
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running]')
+  })
+
+  it('returns the result of a settled job exactly once, after the pending delta', async () => {
     const { ctx } = await setup()
     const p = producer({ kind: 'subagent', label: 'research' })
     ctx.jobs.start(p.spec)
     expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('(no new output)\n[status: running]')
 
-    p.settle({ status: 'completed', detail: 'completed', output: 'the answer' })
+    p.append('partial')
+    p.settle({ status: 'completed', detail: 'completed', result: 'the answer' })
     await tick()
-    expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('the answer\n[status: completed, completed]')
+    expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('partial\nthe answer\n[status: completed, completed]')
+    expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('(no new output)\n[status: completed, completed]')
+  })
+
+  it('keeps a newline-terminated delta and the result on separate lines', async () => {
+    const { ctx } = await setup()
+    const p = producer({ kind: 'subagent', label: 'research' })
+    ctx.jobs.start(p.spec)
+    p.append('progress log\n')
+    p.settle({ status: 'completed', result: 'the answer' })
+    await tick()
+    expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('progress log\nthe answer\n[status: completed]')
   })
 
   it('applies a producer limit to the complete body and status result', async () => {
     const { ctx } = await setup()
-    ctx.jobs.start(producer({
-      outputLimitBytes: 48,
-      readOutput: () => '界'.repeat(100),
-    }).spec)
+    const p = producer({ outputLimitBytes: 48 })
+    ctx.jobs.start(p.spec)
+    p.append('界'.repeat(100))
 
     const output = text(await call(ctx, 'job_output', { job_id: 'bash-1' }))
     expect(Buffer.byteLength(output)).toBeLessThanOrEqual(48)
@@ -221,24 +374,21 @@ describe('job_output', () => {
 
   it('preserves empty and newline-terminated output under a producer limit', async () => {
     const { ctx } = await setup()
-    const chunks = ['', 'line\n']
-    ctx.jobs.start(producer({
-      outputLimitBytes: 64,
-      readOutput: () => chunks.shift() ?? '',
-    }).spec)
+    const p = producer({ outputLimitBytes: 64 })
+    ctx.jobs.start(p.spec)
 
     expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' })))
       .toBe('(no new output)\n[status: running]')
+    p.append('line\n')
     expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' })))
       .toBe('line\n[status: running]')
   })
 
   it('bounds post-policy output without restoring the canonical status rendering', async () => {
     const { ctx } = await setup()
-    ctx.jobs.start(producer({
-      outputLimitBytes: 64,
-      readOutput: () => 'canonical output',
-    }).spec)
+    const p = producer({ outputLimitBytes: 64 })
+    ctx.jobs.start(p.spec)
+    p.append('canonical output')
     ctx.on('tools/post-execute', (exec, _result, next) => {
       if (exec.name !== 'job_output') return next()
       return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'p'.repeat(1_000) }] })
@@ -250,17 +400,30 @@ describe('job_output', () => {
     expect(text(result)).not.toContain('[status: running]')
   })
 
-  it('applies a producer limit to a normalized read failure', async () => {
+  it('does not double a truncation marker a policy already appended', async () => {
     const { ctx } = await setup()
-    ctx.jobs.start(producer({
-      outputLimitBytes: 64,
-      readOutput: () => { throw new Error('read failed: '.repeat(100)) },
-    }).spec)
+    ctx.jobs.start(producer({ outputLimitBytes: 64 }).spec)
+    ctx.on('tools/post-execute', (exec, _result, next) => {
+      if (exec.name !== 'job_output') return next()
+      return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: `${'z'.repeat(1_000)}\n[result truncated]` }] })
+    })
 
     const result = await call(ctx, 'job_output', { job_id: 'bash-1' })
-    expect(result.isError).toBe(true)
     expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64)
-    expect(text(result)).toContain('[result truncated]')
+    expect(text(result).match(/\[result truncated\]/g)).toHaveLength(1)
+  })
+
+  it('refuses a job owned by another session as an errored result', async () => {
+    const { ctx } = await setup()
+    const alice = await fakeAgent(ctx, 'sess-alice')
+    ctx.jobs.start(producer({ owner: alice.id }).spec)
+    const bob = await fakeAgent(ctx, 'sess-bob')
+
+    const result = await call(ctx, 'job_output', { job_id: 'bash-1' }, bob)
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('belongs to another session')
+    expect((await call(ctx, 'job_output', { job_id: 'bash-1' })).isError).toBe(true)
+    expect((await call(ctx, 'job_output', { job_id: 'bash-1' }, alice)).isError).toBe(false)
   })
 
   it('bounds pre-, around-, and post-execute policy outcomes and failures', async () => {
@@ -325,7 +488,7 @@ describe('job_output', () => {
     ctx.jobs.start(p.spec)
 
     const pending = call(ctx, 'job_output', { job_id: 'subagent-1', wait: true })
-    p.settle({ status: 'completed', output: 'done deal' })
+    p.settle({ status: 'completed', result: 'done deal' })
     expect(text(await pending)).toBe('done deal\n[status: completed]')
   })
 
@@ -354,9 +517,9 @@ describe('job_list', () => {
     expect(text(await call(ctx, 'job_list', {}))).toBe('(no background jobs)')
 
     const alice = await fakeAgent(ctx, 'sess-alice')
-    ctx.jobs.start(producer({ owner: alice, label: 'pnpm test' }).spec)
+    ctx.jobs.start(producer({ owner: alice.id, label: 'pnpm test' }).spec)
     ctx.jobs.start(producer({ kind: 'subagent', label: 'open research' }).spec)
-    const p = producer({ owner: alice, label: 'build' })
+    const p = producer({ owner: alice.id, label: 'build' })
     ctx.jobs.start(p.spec)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
@@ -368,8 +531,8 @@ describe('job_list', () => {
     expect(listedValue[0]).toMatchObject({ id: 'bash-1', kind: 'bash', label: 'pnpm test', status: 'running' })
     expect(listedValue[2]).toMatchObject({ id: 'bash-2', kind: 'bash', label: 'build', status: 'completed', detail: 'exit code: 0' })
     for (const job of listedValue) {
-      expect(job).not.toHaveProperty('ownerSession')
-      expect(job).not.toHaveProperty('reported')
+      expect(job).not.toHaveProperty('owner')
+      expect(job).not.toHaveProperty('output')
     }
     expect(text(listed)).toBe([
       'bash-1 [bash] running — pnpm test',
@@ -395,8 +558,8 @@ describe('job_kill', () => {
       outcome: 'cancellation-requested',
       job: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'stopping' },
     })
-    expect(killValue.job).not.toHaveProperty('ownerSession')
-    expect(killValue.job).not.toHaveProperty('reported')
+    expect(killValue.job).not.toHaveProperty('owner')
+    expect(killValue.job).not.toHaveProperty('output')
     expect(text(result)).toBe('requested cancellation of job bash-1')
     expect(p.cancels).toEqual(['superseded'])
   })
@@ -422,7 +585,7 @@ describe('job_kill', () => {
     expect(result.isError).toBe(true)
     expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64)
     expect(text(result)).toContain('[result truncated]')
-    expect(ctx.jobs.get(JobId('bash-1'))).toMatchObject({ status: 'running', reported: false })
+    expect(ctx.jobs.get(JobId('bash-1')).status).toBe('running')
   })
 
   it('bounds single-text post policy while preserving structured policy results', async () => {
@@ -470,9 +633,9 @@ describe('job_kill', () => {
 
   it('reports an already-finished job without consuming its pending delta', async () => {
     const { ctx } = await setup()
-    let delta = 'unread tail'
-    const p = producer({ readOutput: () => { const d = delta; delta = ''; return d } })
+    const p = producer()
     ctx.jobs.start(p.spec)
+    p.append('unread tail')
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
@@ -483,7 +646,7 @@ describe('job_kill', () => {
       job: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'completed', detail: 'exit code: 0' },
     })
     expect(text(killed)).toBe('job bash-1 had already finished [status: completed, exit code: 0]')
-    // The kill described the job via a non-consuming snapshot: the delta is intact.
+    // The kill described the job via a non-consuming projection: the delta is intact.
     expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('unread tail\n[status: completed, exit code: 0]')
   })
 
@@ -508,9 +671,9 @@ describe('tool-owned UI presentation (presentCall)', () => {
 describe('completion notices across scoped mounts', () => {
   /**
    * Two agent presets mounting `tool-jobs` over ONE host registry: each mount
-   * registers its own `onJobDone` listener on the shared service, and
-   * `settle()` broadcasts one snapshot to every listener with no scope filter.
-   * Only the mount whose scope the owner belongs to may deliver the notice.
+   * subscribes with `{ owners: 'scope' }`, which the registry files into the
+   * mount's own scope layer and reaches along the owner's scope chain. Only
+   * the mount whose scope the owner belongs to sees the settlement.
    */
   it('delivers one notice from the owning scope when two mounts share the registry', async () => {
     const ctx = new Context()
@@ -539,9 +702,7 @@ describe('completion notices across scoped mounts', () => {
     const dispose = await ctx.agents.register(owner)
 
     try {
-      // No waiter: `settle()` leaves `reported` false, which is the only path
-      // that reaches the notice listeners at all.
-      const p = producer({ owner, label: 'pnpm test' })
+      const p = producer({ owner: owner.id, label: 'pnpm test' })
       ctx.jobs.start(p.spec)
       p.settle({ status: 'completed', detail: 'exit code: 0' })
       await tick()
@@ -559,7 +720,7 @@ describe('completion notice delivery', () => {
     const inject = vi.fn()
     const followup = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject, followup, status: 'idle' })
-    const p = producer({ owner, label: 'pnpm test' })
+    const p = producer({ owner: owner.id, label: 'pnpm test' })
     ctx.jobs.start(p.spec)
 
     p.settle({ status: 'completed', detail: 'exit code: 0' })
@@ -573,7 +734,7 @@ describe('completion notice delivery', () => {
     const inject = vi.fn()
     const followup = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject, followup, status: 'idle' })
-    const p = producer({ owner })
+    const p = producer({ owner: owner.id })
     ctx.jobs.start(p.spec)
 
     p.settle({ status: 'completed' })
@@ -621,15 +782,15 @@ describe('completion notice delivery', () => {
     ctx.jobs.start({
       kind: 'bash',
       label: 'sleep 60',
-      owner,
+      owner: owner.id,
       run: () => ({
         cancel() { settle({ status: 'killed' }) },
         done: new Promise<JobOutcome>((res) => { settle = res }),
       }),
     })
 
-    // Disposal cancels and settles the owned job. Waking here would spend a
-    // model request on an agent the host is destroying, once per tree layer.
+    // Disposal cancels and settles the owned job with a teardown cause. Waking
+    // here would spend a model request on an agent the host is destroying.
     await disposeAgentScope(owner)
     await tick()
     expect(followup).not.toHaveBeenCalled()
@@ -645,17 +806,16 @@ describe('completion notice delivery', () => {
     ctx.jobs.start({
       kind: 'bash',
       label: 'broken producer',
-      owner,
+      owner: owner.id,
       run: () => ({
         cancel() { throw new Error('cancel boom') },
         done: new Promise<JobOutcome>(() => {}),
       }),
     })
 
-    // The registry force-fails the record instead of deadlocking. That path
-    // settles the job too, so it must claim the report as the ordinary
-    // teardown cancel does — otherwise a throwing producer is all it takes to
-    // spend a model request on an owner being destroyed.
+    // The registry force-fails the record instead of deadlocking. That
+    // settlement also announces a teardown cause, so a throwing producer is
+    // not enough to spend a model request on an owner being destroyed.
     await disposeAgentScope(owner)
     await tick()
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned'))
@@ -682,11 +842,11 @@ describe('completion notice delivery', () => {
 })
 
 describe('completion notices', () => {
-  it('injects a notice into the owning agent when an unreported job settles', async () => {
+  it('injects a notice into the owning agent when an uncollected job settles', async () => {
     const { ctx } = await setup()
     const inject = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject })
-    const p = producer({ owner, label: 'pnpm test' })
+    const p = producer({ owner: owner.id, label: 'pnpm test' })
     ctx.jobs.start(p.spec)
 
     p.settle({ status: 'completed', detail: 'exit code: 0' })
@@ -709,7 +869,7 @@ describe('completion notices', () => {
     const inject = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject })
     const first = producer({
-      owner,
+      owner: owner.id,
       kind: 'subagent',
       label: 'x'.repeat(1_000),
       outputLimitBytes: 61,
@@ -735,7 +895,7 @@ describe('completion notices', () => {
     )
 
     const second = producer({
-      owner,
+      owner: owner.id,
       kind: 'subagent',
       label: 'x'.repeat(1_000),
       outputLimitBytes: 80,
@@ -762,7 +922,7 @@ describe('completion notices', () => {
     const inject = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject })
     const target = producer({
-      owner,
+      owner: owner.id,
       kind: 'pty-send',
       label: 'x'.repeat(1_000),
       outputLimitBytes: 64,
@@ -782,8 +942,8 @@ describe('completion notices', () => {
     const { ctx } = await setup()
     const inject = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject })
-    const tiny = producer({ owner, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 8 })
-    const short = producer({ owner, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 32 })
+    const tiny = producer({ owner: owner.id, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 8 })
+    const short = producer({ owner: owner.id, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 32 })
     ctx.jobs.start(tiny.spec)
     ctx.jobs.start(short.spec)
 
@@ -803,7 +963,7 @@ describe('completion notices', () => {
     const { ctx } = await setup()
     const inject = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject })
-    const p = producer({ owner })
+    const p = producer({ owner: owner.id })
     ctx.jobs.start(p.spec)
 
     await call(ctx, 'job_kill', { job_id: 'bash-1' }, owner)
@@ -816,15 +976,117 @@ describe('completion notices', () => {
     const { ctx } = await setup()
     const inject = vi.fn()
     const owner = await fakeAgent(ctx, 'sess-1', { inject })
-    const p = producer({ owner, kind: 'subagent' })
+    const p = producer({ owner: owner.id, kind: 'subagent' })
     ctx.jobs.start(p.spec)
 
     const pending = call(ctx, 'job_output', { job_id: 'subagent-1', wait: true }, owner)
-    p.settle({ status: 'completed', output: 'answer' })
+    p.settle({ status: 'completed', result: 'answer' })
     expect(text(await pending)).toContain('answer')
+    await tick()
     expect(inject).not.toHaveBeenCalled()
   })
 
+  it('a timed-out wait withdraws only its own claim; a concurrent wait keeps the settlement covered', async () => {
+    const { ctx } = await setup({ waitTimeoutMs: 10, maxWaitTimeoutMs: 1000 })
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const p = producer({ owner: owner.id })
+    ctx.jobs.start(p.spec)
+
+    const patient = call(ctx, 'job_output', { job_id: 'bash-1', wait: true, timeout_ms: 1000 }, owner)
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1', wait: true, timeout_ms: 10 }, owner))).toBe('(no new output)\n[status: running]')
+    p.settle({ status: 'completed' })
+    expect(text(await patient)).toBe('(no new output)\n[status: completed]')
+    await tick()
+    expect(inject).not.toHaveBeenCalled()
+  })
+
+  it('withdraws the wait claim when the wait times out, so the later settlement still notifies', async () => {
+    const { ctx } = await setup({ waitTimeoutMs: 10, maxWaitTimeoutMs: 20 })
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const p = producer({ owner: owner.id })
+    ctx.jobs.start(p.spec)
+
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1', wait: true }, owner))).toBe('(no new output)\n[status: running]')
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
+  it('withdraws the wait claim when the caller aborts the wait', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const p = producer({ owner: owner.id })
+    ctx.jobs.start(p.spec)
+
+    const aborter = new AbortController()
+    const pending = ctx.tools.execute({
+      signal: aborter.signal,
+      callId: ToolCallId('call-aborted-wait'),
+      name: 'job_output',
+      arguments: { job_id: 'bash-1', wait: true },
+      agent: owner,
+    })
+    await tick()
+    aborter.abort()
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('wait aborted')
+
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
+  it('delivers the notice when the wait aborts and the job settles before the rejection lands', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const p = producer({ owner: owner.id, kind: 'subagent' })
+    ctx.jobs.start(p.spec)
+
+    const aborter = new AbortController()
+    const pending = ctx.tools.execute({
+      signal: aborter.signal,
+      callId: ToolCallId('call-abort-then-settle'),
+      name: 'job_output',
+      arguments: { job_id: 'subagent-1', wait: true },
+      agent: owner,
+    })
+    await tick()
+    // One synchronous span: the registry rejects the aborted wait on a later
+    // microtask, and a push producer's settlement lands before that rejection
+    // reaches the tool. The tool result carries the abort, not the outcome, so
+    // the settlement notice is the model's only completion record.
+    aborter.abort()
+    p.settle({ status: 'completed', result: 'answer' })
+    const result = await pending
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('wait aborted')
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps a claim on one job while another job settles', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const killed = producer({ owner: owner.id })
+    const other = producer({ owner: owner.id })
+    ctx.jobs.start(killed.spec)
+    ctx.jobs.start(other.spec)
+
+    await call(ctx, 'job_kill', { job_id: 'bash-1' }, owner)
+    other.settle({ status: 'completed' })
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+    killed.settle({ status: 'killed' })
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
   it('drops the notice for unowned jobs without throwing', async () => {
     const { ctx } = await setup()
     // Unowned: settles with nobody to notify — nothing throws.
@@ -834,31 +1096,58 @@ describe('completion notices', () => {
     await tick()
   })
 
-  it('does not route an old owner completion notice to a same-session replacement', async () => {
+  it('delivers to the agent currently registered for the owner session', async () => {
     const { ctx } = await setup()
-    // Delivery into a tearing-down owner is a plain inject: the loop has no
-    // terminal state, so the notice lands in the old owner's (detached)
-    // session instead of throwing or re-routing.
+    // The settlement names the owner session; the notice goes to whichever
+    // agent holds that session when the job settles, which can read the job
+    // through the same session id.
     const oldInject = vi.fn()
     const oldOwner = await fakeAgent(ctx, 'shared', { inject: oldInject })
-    const p = producer({ owner: oldOwner })
+    const p = producer({ owner: oldOwner.id })
     ctx.jobs.start(p.spec)
 
     await detachAgent(oldOwner)
     const replacementInject = vi.fn()
-    await fakeAgent(ctx, 'shared', { inject: replacementInject })
+    const replacement = await fakeAgent(ctx, 'shared', { inject: replacementInject })
     p.settle({ status: 'completed' })
     await tick()
 
-    expect(oldInject).toHaveBeenCalledTimes(1)
-    expect(replacementInject).not.toHaveBeenCalled()
+    expect(oldInject).not.toHaveBeenCalled()
+    expect(replacementInject).toHaveBeenCalledTimes(1)
+    expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }, replacement))).toBe('(no new output)\n[status: completed]')
+  })
+
+  it('drops the notice when the agent registry left before settlement', async () => {
+    const { ctx, agentsFiber } = await setup()
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const p = producer({ owner: owner.id })
+    ctx.jobs.start(p.spec)
+
+    await agentsFiber.dispose()
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(inject).not.toHaveBeenCalled()
+  })
+
+  it('drops the notice when the owner session has no live agent at settlement', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = await fakeAgent(ctx, 'sess-1', { inject })
+    const p = producer({ owner: owner.id })
+    ctx.jobs.start(p.spec)
+
+    await detachAgent(owner)
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(inject).not.toHaveBeenCalled()
   })
 
   it('surfaces an inject failure through listener containment (a real bug must be visible)', async () => {
     const { ctx } = await setup()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
     const owner = await fakeAgent(ctx, 'sess-1', { inject: () => { throw new Error('unexpected inject bug') } })
-    const p = producer({ owner })
+    const p = producer({ owner: owner.id })
     ctx.jobs.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
@@ -866,23 +1155,4 @@ describe('completion notices', () => {
     // registry's per-listener containment — visible, not swallowed.
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('unexpected inject bug'))
   })
-
-  it('keeps using the exact owner after the agent registry is gone', async () => {
-    const { ctx, agentsFiber } = await setup()
-    const inject = vi.fn()
-    const owner = await fakeAgent(ctx, 'sess-1', { inject })
-
-    // Settlement must not depend on a later registry lookup: the exact owner
-    // supplied at start remains the destination while its own scope is live.
-    const p1 = producer({ owner })
-    ctx.jobs.start(p1.spec)
-    const p2 = producer({ owner })
-    ctx.jobs.start(p2.spec)
-
-    await agentsFiber.dispose()
-    p1.settle({ status: 'completed' })
-    p2.settle({ status: 'failed' })
-    await tick()
-    expect(inject).toHaveBeenCalledTimes(2)
-  })
 })
diff --git a/packages/llm/README.i18n.yaml b/packages/llm/README.i18n.yaml
index f98e218e74..8b480a856c 100644
--- a/packages/llm/README.i18n.yaml
+++ b/packages/llm/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/README.md
-README.md: 9f7e8f444345bb60677a57679ad559f1e06be83f
-README.zh.md: fbb27ed1567fa3319a7fc1bdf61b6436113e0aba
+README.md: cbd9e386f0f219eea4f41470bd5da076db00ebe0
+README.zh.md: a3a31dfddd38a07ac95aae037f157ac12763974e
diff --git a/packages/llm/README.md b/packages/llm/README.md
index 9f7e8f4443..cbd9e386f0 100644
--- a/packages/llm/README.md
+++ b/packages/llm/README.md
@@ -25,7 +25,7 @@ The llm group provides the harness's model-call capability: one provider-neutral
 | Package | Role | ctx key |
 |---|---|---|
 | [`llm/`](llm/README.md) | Streams one model call through a registered provider adapter and shares the harness message, block, and chunk vocabulary | `ctx.llm` |
-| [`llm-deepseek/`](llm-deepseek/README.md) | Serves the `deepseek-official` route with direct DeepSeek chat-completions, thinking, and image input | registers on `ctx.llm` |
+| [`llm-deepseek/`](llm-deepseek/README.md) | Serves the `deepseek-official` route through DeepSeek Messages with thinking and image input | registers on `ctx.llm` |
 | [`llm-pi-ai/`](llm-pi-ai/README.md) | Serves configured provider routes through pi-ai catalogs and wire protocols, including hand-declared gateways | registers on `ctx.llm` |
 | [`deepseek-llm-api-extensions/`](deepseek-llm-api-extensions/README.md) | Registers lifecycle-owned top-level fields on official DeepSeek requests | `ctx.deepseekLlmApiExtensions` |
 | [`plugin-package-inventory-deepseek/`](plugin-package-inventory-deepseek/README.md) | Contributes the active Loader package inventory to official DeepSeek requests | contributes `dsh_plugin_packages` |
diff --git a/packages/llm/README.zh.md b/packages/llm/README.zh.md
index fbb27ed156..a3a31dfddd 100644
--- a/packages/llm/README.zh.md
+++ b/packages/llm/README.zh.md
@@ -25,7 +25,7 @@ llm 组提供 harness 的模型调用能力：一个提供方无关的服务，
 | 包 | 职责 | ctx key |
 |---|---|---|
 | [`llm/`](llm/README.zh.md) | 通过已注册的提供方适配器流式发起一次模型调用，并共享 harness 的消息、块与分片词汇 | `ctx.llm` |
-| [`llm-deepseek/`](llm-deepseek/README.zh.md) | 以 DeepSeek chat-completions 直连、thinking 与图片输入服务 `deepseek-official` 路由 | 注册到 `ctx.llm` |
+| [`llm-deepseek/`](llm-deepseek/README.zh.md) | 通过 DeepSeek Messages 为 `deepseek-official` 路由提供思考与图片输入 | 注册到 `ctx.llm` |
 | [`llm-pi-ai/`](llm-pi-ai/README.zh.md) | 通过 pi-ai 目录与协议格式服务配置的提供方路由，包括手工声明的网关 | 注册到 `ctx.llm` |
 | [`deepseek-llm-api-extensions/`](deepseek-llm-api-extensions/README.zh.md) | 在官方 DeepSeek 请求上注册具有生命周期归属的顶层字段 | `ctx.deepseekLlmApiExtensions` |
 | [`plugin-package-inventory-deepseek/`](plugin-package-inventory-deepseek/README.zh.md) | 为官方 DeepSeek 请求贡献当前启用的 Loader 包清单 | 贡献 `dsh_plugin_packages` |
diff --git a/packages/llm/deepseek-llm-api-extensions/README.i18n.yaml b/packages/llm/deepseek-llm-api-extensions/README.i18n.yaml
index caa80e03ad..44a416eea5 100644
--- a/packages/llm/deepseek-llm-api-extensions/README.i18n.yaml
+++ b/packages/llm/deepseek-llm-api-extensions/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/deepseek-llm-api-extensions/README.md
-README.md: 45a4182d77eb293b55d39d043bf8a1e1075873cf
-README.zh.md: 0131791ca5837d3143c17640bf10cb1f4d215555
+README.md: 1505c644a32a8c90c38720ac6229eb3b654693a1
+README.zh.md: d27eca175c19bb914045958d1d748f427a4971b7
diff --git a/packages/llm/deepseek-llm-api-extensions/README.md b/packages/llm/deepseek-llm-api-extensions/README.md
index 45a4182d77..1505c644a3 100644
--- a/packages/llm/deepseek-llm-api-extensions/README.md
+++ b/packages/llm/deepseek-llm-api-extensions/README.md
@@ -27,7 +27,7 @@ Provider-specific registry for additive top-level fields on official DeepSeek LL
 - `prepare(request)` snapshots the registered providers, prepares them concurrently, clones and freezes returned JSON values, and returns `{ fields, accept }`. A preparation failure rejects before HTTP dispatch; request cancellation stops awaiting providers even when one ignores its signal.
 - `accept()` runs every captured post-2xx callback once. Concurrent calls join the same settlement, every callback settles before failures are reported, and several failures become one `AggregateError`.
 
-Both Chat Completions and Messages prepare these fields. Each provider sees the exact serialized base body in the selected protocol, the request `AbortSignal`, plus optional `sessionId` and auxiliary-call `purpose`. It must stop its own work promptly after cancellation and returns `undefined` when its field does not apply to that request. A prepared operation retains the providers it captured even if HMR removes their registrations before HTTP acceptance.
+Each provider sees the exact serialized Messages body, the request `AbortSignal`, plus optional `sessionId` and auxiliary-call `purpose`. It must stop its own work promptly after cancellation and returns `undefined` when its field does not apply to that request. A prepared operation retains the providers it captured even if HMR removes their registrations before HTTP acceptance.
 
 The registry owns addition and lifecycle, not field semantics. `@deepseek-ai/dsh-session-log-deepseek` owns `dsh_session_log`; `@deepseek-ai/dsh-plugin-package-inventory-deepseek` owns `dsh_plugin_packages`. The provider-neutral LLM seam and `llm-pi-ai` do not consume this registry.
 
diff --git a/packages/llm/deepseek-llm-api-extensions/README.zh.md b/packages/llm/deepseek-llm-api-extensions/README.zh.md
index 0131791ca5..d27eca175c 100644
--- a/packages/llm/deepseek-llm-api-extensions/README.zh.md
+++ b/packages/llm/deepseek-llm-api-extensions/README.zh.md
@@ -27,7 +27,7 @@ kind: "package-reference"
 - `prepare(request)` 对已注册提供方取快照，并发准备贡献，克隆并冻结返回的 JSON 值，然后返回 `{ fields, accept }`。准备失败会在 HTTP 分发前拒绝请求；请求取消后，即使某个提供方忽略信号，注册表也会停止等待。
 - `accept()` 对每个捕获的 2xx 后回调只运行一次。并发调用会等待同一次结算，所有回调都在报告失败前完成，多个失败会合并为一个 `AggregateError`。
 
-Chat Completions 和 Messages 都会准备这些字段。每个提供方都会看到所选协议中确切的已序列化基础请求体、请求 `AbortSignal`，以及可选的 `sessionId` 与辅助调用 `purpose`。提供方必须在取消后迅速停止自身工作；字段不适用于当前请求时返回 `undefined`。即使 HMR（热模块替换）在 HTTP 接受前移除了注册，已准备的操作仍会保留其捕获的提供方。
+每个提供方都会看到确切的已序列化 Messages 请求体、请求 `AbortSignal`，以及可选的 `sessionId` 与辅助调用 `purpose`。提供方必须在取消后迅速停止自身工作；字段不适用于当前请求时返回 `undefined`。即使 HMR（热模块替换）在 HTTP 接受前移除了注册，已准备的操作仍会保留其捕获的提供方。
 
 注册表拥有字段添加与生命周期，不拥有字段语义。`@deepseek-ai/dsh-session-log-deepseek` 拥有 `dsh_session_log`；`@deepseek-ai/dsh-plugin-package-inventory-deepseek` 拥有 `dsh_plugin_packages`。提供方无关的 LLM seam 与 `llm-pi-ai` 都不消费该注册表。
 
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index bcc2683e92..ac07d1a93c 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-deepseek/README.md
-README.md: 5bad4d36296c350ef2bc88ad2ff58fec33b93805
-README.zh.md: 1c1c5a8255c3cd894e0aeecfe49079a78fd03eeb
+README.md: e03b1024bf83fa39603c3c2413c3270df70b7bda
+README.zh.md: 9f14e175d95ff0cac3e77c972a9bbc940c9d9e9f
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 5bad4d3629..e03b1024bf 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -1,5 +1,5 @@
 ---
-description: "Configure DeepSeek Messages, Chat Completions overrides, reasoning, and image input through one first-party provider."
+description: "Configure DeepSeek Messages, reasoning, and image input."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Stream DeepSeek models through `deepseek-official` with Messages by default, or select Chat Completions in Cordis YAML. Both protocols share credentials, endpoint settings, image handling, and the model catalog. Valid settings changes affect subsequent calls while in-flight calls retain their configuration. Web shows one DeepSeek provider with an editable API base and key. This package can run beside the [pi-ai adapter](../llm-pi-ai/README.md).
+Stream DeepSeek models through `deepseek-official` using the Messages API. Configure the endpoint, credentials, reasoning, and image handling from Cordis YAML or Web settings. Valid settings changes affect subsequent calls while in-flight calls retain their configuration. This package can run beside the [pi-ai adapter](../llm-pi-ai/README.md).
 
 ## Table of Contents
 
@@ -27,11 +27,11 @@ Stream DeepSeek models through `deepseek-official` with Messages by default, or
 
 Mount this plugin when a composition streams DeepSeek models through the harness LLM service. It registers the single `deepseek-official` route and resolves connection facts per request, so a composition entry plus an optional user settings section drive the whole adapter.
 
-Both protocols accept the LLM service's [request-only user inputs](../llm/README.md#use-this-package) alongside durable history; omitting request-only identity and attribution does not alter provider content.
+The adapter accepts the LLM service's [request-only user inputs](../llm/README.md#use-this-package) alongside durable history; omitting request-only identity and attribution does not alter provider content.
 
 ### When to choose it
 
-Choose this adapter for DeepSeek's official API or a gateway that supports the selected protocol through `baseURL`. Choose `dsh-llm-pi-ai` when the same composition also routes other providers or hand-declared gateways through pi-ai's catalogs; the two adapters can be mounted together because their route names do not collide. Registering any other adapter for `deepseek-official` fails with `DUPLICATE_ADAPTER`.
+Choose this adapter for DeepSeek's official API or a Messages-compatible gateway through `baseURL`. Choose `dsh-llm-pi-ai` when the same composition also routes other providers or hand-declared gateways through pi-ai's catalogs; the two adapters can be mounted together because their route names do not collide. Registering any other adapter for `deepseek-official` fails with `DUPLICATE_ADAPTER`.
 
 ### Minimal configuration
 
@@ -51,9 +51,8 @@ A request selects the route with `provider: deepseek-official`; the model id pas
 
 | Field | Default | Meaning |
 |---|---|---|
-| `protocol` | `messages` | Choose `messages` or `chat-completions` in Cordis YAML; Web has no protocol selector |
 | `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved per request through the credentials seam, then the environment |
-| `baseURL` | Selected protocol’s official root | Explicit value, then `$DEEPSEEK_BASE_URL`, then the selected protocol default |
+| `baseURL` | `https://api.deepseek.com/anthropic` | Explicit value, then `$DEEPSEEK_BASE_URL`, then the official root |
 | `thinking` | `enabled` | Deployment policy; `disabled` locks every request to `off` |
 | `reasoningEffort` | `high` | Default effort: `off`, `low`, `high`, or `max` |
 | `maxTokens` | `256,000` | Per-request output cap; a model's own cap and explicit request values win |
@@ -76,32 +75,24 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 When [proactive compaction](../../compaction/compaction-basic/README.md#use-this-package) is enabled, `models[].contextWindow` (or `defaultContextWindow` when absent) must exceed the effective request `maxTokens` plus the compaction policy’s `headroomTokens`. Requests without an explicit output cap use the model’s `maxTokens` or the adapter default. For small-window deployments, configure headroom within that capacity; lower `thresholdRatio` to compact earlier.
 
-<a id="choose-a-protocol"></a>
-### Choose a protocol
+<a id="endpoint-and-wire-format"></a>
+### Endpoint and wire format
 
-To select Chat Completions explicitly, patch the existing plugin:
+The official root is `https://api.deepseek.com/anthropic`. An explicit `baseURL` or `$DEEPSEEK_BASE_URL` supplies a Messages-compatible root. Model and Files requests append `/v1/messages` and `/v1/files`, except that an exact final `/v1` segment is reused. Trailing slashes do not change these results. A base URL must use HTTP(S) without credentials, query, or fragment.
 
-```yaml
-- id: llm-deepseek
-  config:
-    protocol: chat-completions
-```
-
-`protocol` defaults to `messages`, with official root `https://api.deepseek.com/anthropic`; `chat-completions` uses `https://api.deepseek.com`. Shipped first-party compositions inherit this default. Neither protocol requires `baseURL`: its official default applies when both `baseURL` and `$DEEPSEEK_BASE_URL` are absent. Switching protocols retains endpoint overrides, so users must supply an address compatible with the selected protocol. An explicit `https://api.deepseek.com` override selects the Chat root: remove that override to use the official Messages default, or set it to `https://api.deepseek.com/anthropic`. Chat appends `/chat/completions`. Messages and its Files API treat only an exact final `/v1` path segment as the existing Anthropic API version and append `/messages` or `/files`; every other base receives `/v1/messages` or `/v1/files`. The official Messages root therefore retains its recommended `/anthropic/v1` request paths without granting compatibility to arbitrary version-like suffixes. Trailing slashes do not change these results. Both protocols share the `llm-deepseek` settings section, `apiKeyEnv`, and `deepseek-official`, so saved model selections remain valid.
-
-Messages sends text, thinking, tool calls, and tool results as content blocks, reasoning effort as `output_config.effort`, and images as Files references or inline base64. Models declaring `systemPromptUpdate: in-history` retain the initial top-level system and send new system snapshots after their corresponding user/tool-result turn; undeclared models use the latest snapshot as the top-level system. Replay metadata identifies the Messages format, model, and signatures. Chat requests serialize durable content without those signatures. Invalid Messages replay metadata emits a warning and omits signatures while retaining text and tool history.
+Messages sends text, thinking, tool calls, and tool results as content blocks, reasoning effort as `output_config.effort`, and images as Files references or inline base64. Models declaring `systemPromptUpdate: in-history` retain the initial top-level system and send new system snapshots after their corresponding user/tool-result turn; undeclared models use the latest snapshot as the top-level system. Replay metadata preserves the model and thinking signatures. Invalid replay metadata emits a warning and omits signatures while retaining text and tool history.
 
 ### Streaming with thinking and images
 
 An image-capable route chooses each durable reference's request target and resolves it into a deterministic request version. Omitting `imagePixelBudget` sizes the target on the published vision token grid of 14px patches, 3:1 downsampling, and at most 1024 tokens per image, so a square image keeps up to 1302×1302 pixels and a 16:9 image is sent as 1708×961 for the provider's 1708×966 grid; a positive integer replaces the grid with a total-pixel budget, and `low` uses 512×512 total pixels. Every request image is capped at 4096 pixels per side, the provider limit for requests carrying 15 or more images, and `imageMaxBytes` defaults to 2 MiB. Alpha images use WebP effort 0 and opaque images use JPEG on the 85/75/60 quality ladder, keeping the smallest output when every candidate exceeds the target. Every retained image is preceded by text naming its complete attachment id and actual request dimensions. When the current filesystem maps the attachment provider's host object, that text also carries a read-only execution-world path and the extension for a writable copy. Text-only and unlisted routes receive stable attachment placeholders while durable history keeps the image references.
 
-Both protocols normally upload those exact request bytes through their DeepSeek Files endpoint and send file-id references. Messages uses `/v1/files` under its configured base and includes `anthropic-beta: files-api-2025-04-14` on Files requests and Messages requests containing file ids; Chat uses `/files`. Messages model requests and all Files requests reject redirects so credentials remain on the configured origin. A failed or timed-out file resolution rebuilds the whole model request with inline base64 under the inline budget; one request never mixes file ids and inline images. Caller cancellation stops the request.
+The adapter normally uploads those exact request bytes through `/v1/files` and sends file-id references. Files requests and model requests containing file ids include `anthropic-beta: files-api-2025-04-14`. All requests reject redirects so credentials remain on the configured origin. A failed or timed-out file resolution rebuilds the whole model request with inline base64 under the inline budget; one request never mixes file ids and inline images. Caller cancellation stops the request.
 
-Cached ids are scoped by endpoint and API key, refreshed before expiry, invalidated from provider stale-file errors, and resolved through singleflight with waiter-local cancellation. Both uploads request expiry through `expires_after[anchor]=created_at` and `expires_after[seconds]`. Messages file metadata omits remote expiry, so its local reuse deadline uses the original upload time plus `fileExpiresAfterSeconds`; this does not guarantee remote deletion. Quota failure deletes one configured batch of the oldest harness-owned files before one upload retry.
+Cached ids are scoped by endpoint and API key, refreshed before expiry, invalidated from provider stale-file errors, and resolved through singleflight with waiter-local cancellation. Uploads request expiry through `expires_after[anchor]=created_at` and `expires_after[seconds]`. Messages file metadata omits remote expiry, so its local reuse deadline uses the original upload time plus `fileExpiresAfterSeconds`; this does not guarantee remote deletion. Quota failure deletes one configured batch of the oldest harness-owned files before one upload retry.
 
 Files mode bounds retained request versions by `maxRequestFilesBytes` and `maxImagesPerRequest`; inline fallback has its own base64 budget. Both remove an oldest prefix in configured byte or count quanta. Each omitted image gets its own model-visible placeholder with its display name or attachment id and, when available, normalized dimensions, media type, and current read-only path. The stepped high-watermark policy avoids rewriting an old request prefix after every new image.
 
-`reasoningEffort` selects the advertised default. Exact-model metadata exposes ordered `off`, `low`, `high`, and `max` efforts with selection guidance when deployment policy permits thinking. `low`, `high`, and `max` enable thinking and serialize as `reasoning_effort` for Chat Completions or `output_config.effort` for Messages, while adapter-owned `off` sends `thinking.type: disabled` instead. An unsupported value fails with `UNSUPPORTED_REASONING_EFFORT` before network I/O, and `thinking: disabled` rejects any non-`off` effort at plugin load. Requests with `purpose: 'session-title'` force thinking off to reserve output for visible title text. Both protocols forward an explicit `temperature`; DeepSeek accepts it with thinking enabled but ignores its value in that mode.
+`reasoningEffort` selects the advertised default. Exact-model metadata exposes ordered `off`, `low`, `high`, and `max` efforts with selection guidance when deployment policy permits thinking. `low`, `high`, and `max` enable thinking and serialize as `output_config.effort`, while adapter-owned `off` sends `thinking.type: disabled` instead. An unsupported value fails with `UNSUPPORTED_REASONING_EFFORT` before network I/O, and `thinking: disabled` rejects any non-`off` effort at plugin load. Requests with `purpose: 'session-title'` force thinking off to reserve output for visible title text. The adapter forwards an explicit `temperature`; DeepSeek accepts it with thinking enabled but ignores its value in that mode.
 
 ### Dynamic configuration
 
@@ -109,10 +100,12 @@ Connection facts are re-read once per operation through the optional settings an
 
 ### Provider-specific request fields
 
-For either protocol, when `ctx.deepseekLlmApiExtensions` is present, the adapter prepares its registered top-level fields from the exact serialized base request before `fetch`. Preparation or field collisions fail before HTTP; after a 2xx response, the adapter accepts every captured contribution before consuming SSE. Transport and non-2xx failures do not accept them. Shipped compositions use this for the default-on incremental `dsh_session_log` field and the default-on active `dsh_plugin_packages` inventory; both stay outside model input.
+When `ctx.deepseekLlmApiExtensions` is present, the adapter prepares its registered top-level fields from the exact serialized base request before `fetch`. Preparation or field collisions fail before HTTP; after a 2xx response, the adapter accepts every captured contribution before consuming SSE. Transport and non-2xx failures do not accept them. Shipped compositions use this for the default-on incremental `dsh_session_log` field and the default-on active `dsh_plugin_packages` inventory; both stay outside model input.
 
 ### Failures and recovery
 
+Configuration accepts Messages only and has no `protocol` field. If resolution reports `protocol is not configurable`, remove `protocol` from the `llm-deepseek` section in `<harness home>/settings.yaml` and from any matching Cordis entry or overlay. Keep the intended `baseURL`, `apiKeyEnv`, and `models` fields. An invalid live section keeps the complete last good configuration; saving other fields in the Models card does not remove an unknown property. Edit the configuration file, then let settings reload or restart the profile; composition edits require a profile restart.
+
 Successful Files responses must contain valid JSON. JSON decoding failures from upload, list, retrieve, and delete throw `INVALID_RESPONSE` with the operation and HTTP status in the message, the status in `LlmError.failure`, and the original parser error as `cause`. Body-read transport and cancellation errors retain their identity.
 
 Non-2xx responses fail with stable codes: `AUTH` (401/403), `QUOTA`, `RATE_LIMIT`, `CONTEXT_WINDOW_EXCEEDED`, `INVALID_REQUEST`, `SERVER`, and `HTTP_<status>` otherwise; pre-response transport failures throw `TRANSPORT`, caller aborts throw `ABORTED`, and stream-idle expiry throws `TIMEOUT`. Request-extension preparation, field collision, or post-2xx acceptance fails with `REQUEST_EXTENSION`. A normalized-image rejection names every plausible attachment and its durable position when the provider does not identify a file id. Stale-file rejection invalidates the named mappings (or every mapping used by the attempt) and permits one replacement model request. Protocol violations throw `STREAM_CLOSED` or `MALFORMED_RESPONSE`, and a terminal `stop` with no content blocks becomes `EMPTY_RESPONSE`, which the default retry policy retries. A request with no key anywhere fails with `MISSING_CREDENTIAL`, and a malformed credential fails with `INVALID_CREDENTIAL` naming the reference to fix — never any part of the key.
@@ -133,17 +126,7 @@ The plugin is built on one explicit resolve step and one registration fact. `res
 
 ### Source map
 
-| File | Role |
-|---|---|
-| [`src/index.ts`](src/index.ts) | Settings, credentials, and provider registration |
-| [`src/config.ts`](src/config.ts) | Schema and request-local configuration resolution |
-| [`src/adapter.ts`](src/adapter.ts) | Protocol dispatch with frozen prepared-call configuration |
-| [`src/common/models.ts`](src/common/models.ts) | Shared model catalog |
-| [`src/common/model-info.ts`](src/common/model-info.ts) | Shared model capabilities and reasoning choices |
-| [`src/common/file-store.ts`](src/common/file-store.ts) | Shared Files cache, refresh, quota cleanup, and cancellation |
-| [`src/common/files-api.ts`](src/common/files-api.ts) | Protocol-specific Files endpoints and response mapping |
-| [`src/protocols/chat-completions/adapter.ts`](src/protocols/chat-completions/adapter.ts) | Chat transport, image projection, and request extensions |
-| [`src/protocols/messages/adapter.ts`](src/protocols/messages/adapter.ts) | Messages transport, image projection, request extensions, and native replay |
+[`src/index.ts`](src/index.ts) registers the provider and resolves settings and credentials. [`src/adapter.ts`](src/adapter.ts) owns the request lifecycle; [`src/serialize.ts`](src/serialize.ts) and [`src/translate.ts`](src/translate.ts) map model input and streamed output. [`src/file-store.ts`](src/file-store.ts) owns upload reuse and recovery through [`src/files-api.ts`](src/files-api.ts).
 
 ### Wire flow
 
@@ -177,11 +160,11 @@ Read these pages when the package-level contract is not enough. They move from t
 
 #### What the model sees
 
-The selected DeepSeek model receives the harness system prompt, message history, tool schemas, stop sequences, and call config (`maxTokens`, `reasoningEffort`, `temperature`) without adapter-authored prompt prose. Provider-specific request-extension fields remain outside model input. The vision model normally receives retained user and tool-result images as Files API references beside attachment handles and request-preview dimensions. It also receives a normalized-object path when the current execution filesystem maps the attachment provider's host object; the descriptor marks this copy read-only and warns that normalization may have resized or re-encoded the upload. A Files resolution failure sends all retained images as inline base64 instead, and an over-budget older image keeps the access resolved for that request in its placeholder. Reasoning content from a prior assistant turn is passed back verbatim, whether or not that turn called a tool. Messages sends `{}` for historical tool arguments that are malformed JSON or are not objects. This argument fallback preserves call ids, tool names, and tool results; the original arguments stay in the Session log. This silent fallback also applies after switching from Chat Completions. Newly generated Messages tool arguments still require valid JSON objects. Messages omits `reasoning` and `tool-call` blocks inside user messages and tool results; omission of these two block types matches Chat Completions and the pi-ai adapter. This also permits replay of saved subagent notices containing assistant output; the original Session content remains intact. Empty user messages are skipped after conversion, while empty tool results retain their call ids and error flags. Other unsupported input blocks still fail with `UNSUPPORTED_CONTENT`.
+The selected DeepSeek model receives the harness system prompt, message history, tool schemas, stop sequences, and call config (`maxTokens`, `reasoningEffort`, `temperature`) without adapter-authored prompt prose. Provider-specific request-extension fields remain outside model input. The vision model normally receives retained user and tool-result images as Files API references beside attachment handles and request-preview dimensions. It also receives a normalized-object path when the current execution filesystem maps the attachment provider's host object; the descriptor marks this copy read-only and warns that normalization may have resized or re-encoded the upload. A Files resolution failure sends all retained images as inline base64 instead, and an over-budget older image keeps the access resolved for that request in its placeholder. Reasoning content from a prior assistant turn is passed back verbatim, whether or not that turn called a tool. Messages sends `{}` for historical tool arguments that are malformed JSON or are not objects. This argument fallback preserves call ids, tool names, and tool results; the original arguments stay in the Session log. Newly generated Messages tool arguments still require valid JSON objects. Messages omits `reasoning` and `tool-call` blocks inside user messages and tool results. This also permits replay of saved subagent notices containing assistant output; the original Session content remains intact. Empty user messages are skipped after conversion, while empty tool results retain their call ids and error flags. Other unsupported input blocks still fail with `UNSUPPORTED_CONTENT`.
 
 #### Token effect
 
-Provider tokenization governs exact text and image-token input. The adapter declares per-route `imageRequestPricing`: it prices each occurrence selected by a logged image-offload decision as its placeholder text and each retained image at its projected dimensions with the published vision accounting (14px patch grid, 3:1 downsampling, 544×544 scale-up floor, 1024-token cap). This lets the token meter price image pressure before a request; reported usage remains authoritative. Reasoning passback carries every reasoned turn's chain of thought into later requests, while offloaded images stop costing visual tokens. A request whose retained occurrences exceed the file-mode or inline-fallback budget (`maxRequestFilesBytes`, `maxImagesPerRequest`, both quanta) at their exact request-version bytes fails with `IMAGE_OFFLOAD_REQUIRED` naming the additional oldest occurrences to offload, and `dsh-compaction-image-offload` records the selected occurrences in an `image/offload` event and retries. Cache-read usage is reported when available. Messages totals include uncached input, output, cache-read, and cache-write tokens. Chat Completions uses `prompt_tokens + completion_tokens` and omits `totalTokens` if a supplied `total_tokens` disagrees.
+Provider tokenization governs exact text and image-token input. The adapter declares per-route `imageRequestPricing`: it prices each occurrence selected by a logged image-offload decision as its placeholder text and each retained image at its projected dimensions with the published vision accounting (14px patch grid, 3:1 downsampling, 544×544 scale-up floor, 1024-token cap). This lets the token meter price image pressure before a request; reported usage remains authoritative. Reasoning passback carries every reasoned turn's chain of thought into later requests, while offloaded images stop costing visual tokens. A request whose retained occurrences exceed the file-mode or inline-fallback budget (`maxRequestFilesBytes`, `maxImagesPerRequest`, both quanta) at their exact request-version bytes fails with `IMAGE_OFFLOAD_REQUIRED` naming the additional oldest occurrences to offload, and `dsh-compaction-image-offload` records the selected occurrences in an `image/offload` event and retries. Cache-read usage is reported when available. Messages totals include uncached input, output, cache-read, and cache-write tokens.
 
 #### KV Cache effect
 
@@ -203,7 +186,6 @@ Loop-retained response blocks append to the next request and preserve its earlie
 
 ## Known Limitations and Deferred Work
 
-- Responses is not implemented; configuration rejects `responses`.
 
 <a id="known-limitations-and-deferred-work"></a>
 
@@ -213,23 +195,14 @@ These limits define where the adapter stops and future work begins. They are cur
 - **A settings `models` list replaces the composition list wholesale** — settings-layer merging is per-field, and arrays are one field; per-entry catalog merging would need a keyed shape.
 - **`tool_choice` is not mapped** — not part of the core vocabulary (shared with the pi-ai twin).
 - **Requests use raw `fetch`, not `@cordisjs/plugin-http`** — no shared proxy or interception configuration.
-- **Chat Completions skips plugin-added content block types** — core text and supported image blocks are serialized, and empty tool output crosses the wire as the literal `(no output)`.
 - **Messages in-history system updates require a retained user or tool-result turn** — if all user input after an update is omitted and the preceding wire turn is assistant, serialization fails with `UNSUPPORTED_CONTENT` before the next assistant or at the end of the request. Text or an empty tool result can retain that turn. Moving the update to an earlier turn is not supported; the [input-history decision](../../../.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.md) records the ordering constraint.
 - **Images are input-only durable attachments** — direct external URLs and assistant image output are not supported; DeepSeek input normally uses the Files API and uses inline base64 only for per-request recovery.
-- The default catalog pre-registers `deepseek-flash` and its text/image and in-history capabilities without probing gateway availability. Requests can fail with `INVALID_REQUEST` until the gateway enables the id. With `DEEPSEEK_API_KEY` and a supporting gateway configured, `DEEPSEEK_FLASH_E2E=1` enables the Chat Completions check in [this package's e2e suite](tests/adapter.e2e.ts).
-- The [Messages system-update e2e checks](tests/messages/adapter.e2e.ts) require `DEEPSEEK_IN_HISTORY_MODEL` to name a supported model, such as `deepseek-flash`, and run with `high` effort. They skip when that variable is unset or empty; ordinary `off` text checks remain enabled with credentials. Known instruction-following instability with thinking disabled makes these system-update checks unsuitable for `off`.
+- The default catalog advertises `deepseek-flash` and its text/image and in-history capabilities without probing gateway availability. Requests can fail with `INVALID_REQUEST` until the gateway enables the id.
+- Real API checks in [adapter.e2e.ts](tests/adapter.e2e.ts) and [runtime.e2e.ts](tests/runtime.e2e.ts) require `DEEPSEEK_API_KEY`. Set `DEEPSEEK_IN_HISTORY_MODEL` to a supported nonempty model id to run system-update checks: the adapter suite uses `high` effort, while the runtime suite compares cache reuse with thinking disabled and can be sensitive to instruction-following instability. The runtime image cases additionally require `DEEPSEEK_FLASH_E2E=1` or `DEEPSEEK_VISION_E2E=1`.
 
 <a id="dev-note"></a>
 ### Dev Note
 
-<details>
-<summary>Working context for maintainers — click to expand</summary>
-
-This Dev Note is non-authoritative working context: undecided directions and notes for maintainers. Shipped behavior and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
-
-- OpenRouter-specific app attribution headers are deferred to a future explicit OpenRouter adapter or mode; OpenAI-compatible gateway requests carry only the shared attribution baseline.
-- The `off` reasoning effort never crosses the wire as `reasoning_effort: 'off'`; it serializes as `thinking: { type: 'disabled' }` and omits the field, which keeps the wire spelling valid for gateways that reject unknown effort values.
-
-</details>
+None.
 
 **Runtime invariant:** No companion is published. This package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam.
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 1c1c5a8255..9f14e175d9 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "通过同一官方提供方配置 DeepSeek Messages、Chat Completions 覆盖、推理与图片输入。"
+description: "配置 DeepSeek Messages、推理与图片输入。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-通过 `deepseek-official` 流式调用 DeepSeek 模型，默认使用 Messages，也可在 Cordis YAML 中选择 Chat Completions。两种协议共用凭据、端点配置、图片处理和模型目录。有效的设置更改在后续请求生效，进行中的请求保留原配置。Web 显示一个 DeepSeek 提供方，并提供 API 地址和密钥编辑。本包可与 [pi-ai 适配器](../llm-pi-ai/README.zh.md)并用。
+通过 `deepseek-official` 使用 Messages API 流式调用 DeepSeek 模型。在 Cordis YAML 或 Web 设置中配置端点、凭据、推理与图片处理。有效的设置更改在后续请求生效，进行中的请求保留原配置。本包可与 [pi-ai 适配器](../llm-pi-ai/README.zh.md)并用。
 
 ## 目录
 
@@ -27,11 +27,11 @@ kind: "package-reference"
 
 当组合需要通过 harness LLM（大语言模型）服务流式调用 DeepSeek 模型时挂载本插件。它注册唯一的 `deepseek-official` 路由，并按请求解析连接事实，因此组合条目加可选用户设置分节即可驱动整个适配器。
 
-两种协议都接受 LLM 服务的[仅供请求使用的 user 输入](../llm/README.zh.md#use-this-package)，并可将其与持久历史混用；省略请求输入的身份与来源不会改变提供方内容。
+适配器接受 LLM 服务的[仅供请求使用的 user 输入](../llm/README.zh.md#use-this-package)，并可将其与持久历史混用；省略请求输入的身份与来源不会改变提供方内容。
 
 ### 何时选择
 
-面向 DeepSeek 官方 API，或通过 `baseURL` 连接支持所选协议的网关时，选择本适配器。当同一组合还要通过 pi-ai 目录路由其他提供方或手工声明的网关时，选择 `dsh-llm-pi-ai`；两个适配器可以同时挂载，因为它们的路由名不冲突。为 `deepseek-official` 注册任何其他适配器会以 `DUPLICATE_ADAPTER` 失败。
+面向 DeepSeek 官方 API，或通过 `baseURL` 连接兼容 Messages 的网关时，选择本适配器。当同一组合还要通过 pi-ai 目录路由其他提供方或手工声明的网关时，选择 `dsh-llm-pi-ai`；两个适配器可以同时挂载，因为它们的路由名不冲突。为 `deepseek-official` 注册任何其他适配器会以 `DUPLICATE_ADAPTER` 失败。
 
 ### 最小配置
 
@@ -51,9 +51,8 @@ kind: "package-reference"
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `protocol` | `messages` | Cordis YAML 中选择 `messages` 或 `chat-completions`；Web 不提供选择器 |
 | `apiKeyEnv` | `DEEPSEEK_API_KEY` | 按请求解析的凭据引用：先经凭据 seam，再到环境变量 |
-| `baseURL` | 按协议选择官方根地址 | 显式值优先，其次 `$DEEPSEEK_BASE_URL`，最后采用当前协议的官方端点 |
+| `baseURL` | `https://api.deepseek.com/anthropic` | 显式值优先，其次为 `$DEEPSEEK_BASE_URL`，最后为官方根地址 |
 | `thinking` | `enabled` | 部署策略；`disabled` 把所有请求锁定为 `off` |
 | `reasoningEffort` | `high` | 默认强度：`off`、`low`、`high` 或 `max` |
 | `maxTokens` | `256,000` | 单次请求输出上限；模型自身上限与显式请求值优先 |
@@ -76,32 +75,24 @@ kind: "package-reference"
 
 启用[主动压缩](../../compaction/compaction-basic/README.zh.md#use-this-package)时，`models[].contextWindow`（未声明时使用 `defaultContextWindow`）必须大于生效请求的 `maxTokens` 与压缩策略 `headroomTokens` 之和。请求未覆盖输出上限时，使用模型的 `maxTokens` 或适配器默认值。小窗口部署应在容量范围内配置余量；降低 `thresholdRatio` 可以提早压缩。
 
-<a id="choose-a-protocol"></a>
-### 选择协议
+<a id="endpoint-and-wire-format"></a>
+### 端点与协议格式
 
-通过补丁为已有插件显式选择 Chat Completions：
+官方根地址为 `https://api.deepseek.com/anthropic`。显式 `baseURL` 或 `$DEEPSEEK_BASE_URL` 提供兼容 Messages 的根地址。模型与 Files 请求分别追加 `/v1/messages` 和 `/v1/files`，但末尾严格匹配的 `/v1` 路径段会直接复用。末尾斜线不改变这些结果。基址必须使用 HTTP(S)，且不含凭据、查询或片段。
 
-```yaml
-- id: llm-deepseek
-  config:
-    protocol: chat-completions
-```
-
-`protocol` 默认为 `messages`，官方根地址为 `https://api.deepseek.com/anthropic`；`chat-completions` 使用 `https://api.deepseek.com`。随产品交付的官方组合继承该默认值。两种协议都不要求填写 `baseURL`：当 `baseURL` 与 `$DEEPSEEK_BASE_URL` 均未设置时使用当前协议的官方默认值。切换协议保留已有端点覆盖，用户需要填写与选定协议兼容的地址。显式填写的 `https://api.deepseek.com` 是 Chat 根地址：删除该覆盖即可使用官方 Messages 默认值，也可以改填 `https://api.deepseek.com/anthropic`。Chat 追加 `/chat/completions`。Messages 与其 Files API 仅把末尾严格匹配的 `/v1` 路径段视为已有 Anthropic API 版本，并追加 `/messages` 或 `/files`；其他基址均追加 `/v1/messages` 或 `/v1/files`。因此，官方 Messages 根地址仍使用推荐的 `/anthropic/v1` 请求路径，同时不为任意版本式后缀提供兼容性。末尾斜线不改变这些结果。两种协议共用 `llm-deepseek` 设置、`apiKeyEnv` 与 `deepseek-official`，因此已保存的模型选择仍然有效。
-
-Messages 以内容块发送文本、思考、工具调用和工具结果，以 `output_config.effort` 发送推理强度，并以 Files 引用或内联 base64 发送图片。声明 `systemPromptUpdate: in-history` 的模型保留初始顶层 system，在对应 user/tool-result 轮次之后发送新的 system 快照；未声明能力时，使用最新快照作为顶层 system。回放元数据记录 Messages 格式、模型和签名；Chat 请求只序列化持久化内容，不发送这些签名。无效的 Messages 回放元数据产生警告并省略签名，不丢弃文本或工具历史。
+Messages 以内容块发送文本、思考、工具调用和工具结果，以 `output_config.effort` 发送推理强度，并以 Files 引用或内联 base64 发送图片。声明 `systemPromptUpdate: in-history` 的模型保留初始顶层 system，在对应 user/tool-result 轮次之后发送新的 system 快照；未声明能力时，使用最新快照作为顶层 system。回放元数据保留模型与思考签名。无效的回放元数据产生警告并省略签名，不丢弃文本或工具历史。
 
 ### 带 thinking 与图片的流式调用
 
 支持图片的路由为每个持久引用选定请求目标，再把它解析为确定性请求版本。省略 `imagePixelBudget` 时按官方公布的视觉 token 网格定目标，即 14 px patch、3:1 降采样、单图最多 1024 token，因此正方形图片最多保留 1302×1302 像素，16:9 图片以 1708×961 发送、对应提供方 1708×966 的网格；正整数会用总像素预算取代网格，`low` 使用总计 512×512 像素。每张请求图片单边最多 4096 像素，这是提供方对包含 15 张及以上图片的请求的限制；`imageMaxBytes` 默认为 2 MiB。带 alpha 的图片使用 effort 0 的 WebP，不透明图片使用 JPEG，并采用 85/75/60 质量阶梯；全部候选都超过目标时保留最小输出。每张保留图片前都有文本，注明完整附件 id 与实际请求尺寸。当前文件系统可以映射附件提供方的宿主对象时，该文本还携带只读执行世界路径与可写副本使用的扩展名。纯文本与未列出路由接收稳定附件占位符，而持久历史继续保留图片引用。
 
-两种协议通常通过各自的 DeepSeek Files 端点上传这些确切请求字节，并发送 file-id 引用。Messages 在配置的基址下使用 `/v1/files`，Files 请求与包含 file id 的 Messages 请求均携带 `anthropic-beta: files-api-2025-04-14`；Chat 使用 `/files`。Messages 模型请求与所有 Files 请求拒绝重定向，确保凭据仅发送到配置的源。文件解析失败或超时会按内联预算，用内联 base64 重建整份模型请求；一次请求绝不混用 file id 与内联图片。调用方取消会停止请求。
+适配器通常通过 `/v1/files` 上传这些确切请求字节，并发送 file-id 引用。Files 请求与包含 file id 的模型请求均携带 `anthropic-beta: files-api-2025-04-14`。全部请求拒绝重定向，确保凭据仅发送到配置的源。文件解析失败或超时会按内联预算，用内联 base64 重建整份模型请求；一次请求绝不混用 file id 与内联图片。调用方取消会停止请求。
 
-缓存 id 按端点与 API key 限定作用域，在到期前刷新，根据提供方的陈旧文件错误失效，并通过带等待方局部取消的 singleflight 解析。两种上传都通过 `expires_after[anchor]=created_at` 与 `expires_after[seconds]` 请求过期。Messages 文件元数据不含远端过期时间，因此本地复用期限使用原始上传时间加 `fileExpiresAfterSeconds`；这不保证远端文件删除。配额失败会先删除一批配置数量的最旧 harness 文件，再重试一次上传。
+缓存 id 按端点与 API key 限定作用域，在到期前刷新，根据提供方的陈旧文件错误失效，并通过带等待方局部取消的 singleflight 解析。上传通过 `expires_after[anchor]=created_at` 与 `expires_after[seconds]` 请求过期。Messages 文件元数据不含远端过期时间，因此本地复用期限使用原始上传时间加 `fileExpiresAfterSeconds`；这不保证远端文件删除。配额失败会先删除一批配置数量的最旧 harness 文件，再重试一次上传。
 
 Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留请求版本；内联回退有独立 base64 预算。两种模式都按配置的字节或数量量子移除最旧前缀。每张省略图片都有自己的模型可见占位符，包含显示名或附件 id，以及可用时的规范化尺寸、媒体类型与当前只读路径。分阶高水位策略避免每新增一张图片都改写旧请求前缀。
 
-`reasoningEffort` 选择公布的默认值。当部署策略允许 thinking 时，确切模型元数据会按顺序公开 `off`、`low`、`high` 与 `max` 强度及选择指引。`low`、`high` 与 `max` 启用 thinking，在 Chat Completions 中以 `reasoning_effort` 序列化，在 Messages 中以 `output_config.effort` 序列化，适配器自有的 `off` 则发送 `thinking.type: disabled`。不支持的取值会在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败；`thinking: disabled` 会在插件加载时拒绝任何非 `off` 强度。`purpose: 'session-title'` 的请求会强制关闭 thinking，把有界输出留给可见标题文本。两种协议都转发显式 `temperature`；DeepSeek 在启用 thinking 时接受该参数，但忽略其值。
+`reasoningEffort` 选择公布的默认值。当部署策略允许 thinking 时，确切模型元数据会按顺序公开 `off`、`low`、`high` 与 `max` 强度及选择指引。`low`、`high` 与 `max` 启用 thinking，并以 `output_config.effort` 序列化，适配器自有的 `off` 则发送 `thinking.type: disabled`。不支持的取值会在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败；`thinking: disabled` 会在插件加载时拒绝任何非 `off` 强度。`purpose: 'session-title'` 的请求会强制关闭 thinking，把有界输出留给可见标题文本。适配器转发显式 `temperature`；DeepSeek 在启用 thinking 时接受该参数，但忽略其值。
 
 ### 动态配置
 
@@ -109,10 +100,12 @@ Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留
 
 ### 提供方专用请求字段
 
-两种协议中，存在 `ctx.deepseekLlmApiExtensions` 时，适配器都会在 `fetch` 前根据确切序列化基础请求准备已注册顶层字段。准备或字段冲突在 HTTP 前失败；2xx 响应后，适配器会在消费 SSE（Server-Sent Events）前接受每项已捕获贡献。传输与非 2xx 失败不会接受它们。随产品交付的组合用它提供默认启用的增量 `dsh_session_log` 字段和默认启用的活跃 `dsh_plugin_packages` 清单；两者都留在模型输入之外。
+存在 `ctx.deepseekLlmApiExtensions` 时，适配器会在 `fetch` 前根据确切序列化基础请求准备已注册顶层字段。准备或字段冲突在 HTTP 前失败；2xx 响应后，适配器会在消费 SSE（Server-Sent Events）前接受每项已捕获贡献。传输与非 2xx 失败不会接受它们。随产品交付的组合用它提供默认启用的增量 `dsh_session_log` 字段和默认启用的活跃 `dsh_plugin_packages` 清单；两者都留在模型输入之外。
 
 ### 失败与恢复
 
+配置仅接受 Messages，不提供 `protocol` 字段。若解析报告 `protocol is not configurable`，请从 `<harness home>/settings.yaml` 的 `llm-deepseek` 分节以及对应 Cordis 条目或 overlay 中删除 `protocol`，保留需要的 `baseURL`、`apiKeyEnv` 和 `models` 字段。无效的实时分节会继续使用完整的最后有效配置；在模型设置卡中保存其他字段不会移除未知属性。请编辑配置文件，等待设置重新加载或重启 profile；组装配置变更需要重启 profile。
+
 成功的 Files 响应必须包含有效 JSON。上传、列举、获取和删除操作的 JSON 解码失败抛出 `INVALID_RESPONSE`，消息包含操作名称与 HTTP 状态，`LlmError.failure` 保留该状态，`cause` 保留原始解析错误。读取响应体时的传输和取消错误保留其原有身份。
 
 非 2xx 响应以稳定 code 失败：`AUTH`（401/403）、`QUOTA`、`RATE_LIMIT`、`CONTEXT_WINDOW_EXCEEDED`、`INVALID_REQUEST`、`SERVER` 以及其他情况的 `HTTP_<status>`；响应前传输失败抛出 `TRANSPORT`，调用方中止抛出 `ABORTED`，流空闲超时抛出 `TIMEOUT`。请求扩展准备、字段冲突或 2xx 后接受失败使用 `REQUEST_EXTENSION`。当提供方未指出 file id 时，规范化图片拒绝会列出所有可能附件及其持久位置。陈旧文件拒绝会使点名映射（或该次尝试使用的全部映射）失效，并允许一次替换模型请求。协议违规抛出 `STREAM_CLOSED` 或 `MALFORMED_RESPONSE`；不带内容块的终止 `stop` 变成 `EMPTY_RESPONSE`，默认重试策略会重试它。任何位置都没有密钥的请求以 `MISSING_CREDENTIAL` 失败；格式错误的凭据以 `INVALID_CREDENTIAL` 失败，并点名需要修复的引用——绝不包含密钥的任何部分。
@@ -131,19 +124,9 @@ Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留
 
 插件建立在一个显式解析步骤与一条注册事实之上。`resolveAdapterOptions()` 是从原始配置到已校验连接事实的唯一路径，适配器通过 thunk 每次操作重新读取这些事实——基址、目录、请求默认值、图片与 Files 策略及空闲预算都会作用于下一个请求，而进行中的流保持其启动时的事实。注册时捕获的唯一事实是重试策略：解析值变化时，插件会在一个同步区段内原位重新注册路由，因此任何请求都观察不到空档。
 
-### 源码地图
+### 源码导航
 
-| 文件 | 职责 |
-|---|---|
-| [`src/index.ts`](src/index.ts) | settings、凭据与提供方注册 |
-| [`src/config.ts`](src/config.ts) | schema 与请求配置解析 |
-| [`src/adapter.ts`](src/adapter.ts) | 按协议分派，并冻结已准备请求的配置 |
-| [`src/common/models.ts`](src/common/models.ts) | 共享模型目录 |
-| [`src/common/model-info.ts`](src/common/model-info.ts) | 共享模型能力与推理选项 |
-| [`src/common/file-store.ts`](src/common/file-store.ts) | 共享 Files 缓存、刷新、配额清理与取消 |
-| [`src/common/files-api.ts`](src/common/files-api.ts) | 各协议的 Files 端点与响应映射 |
-| [`src/protocols/chat-completions/adapter.ts`](src/protocols/chat-completions/adapter.ts) | Chat 传输、图片投影与请求扩展 |
-| [`src/protocols/messages/adapter.ts`](src/protocols/messages/adapter.ts) | Messages 传输、图片投影、请求扩展与原生回放 |
+[`src/index.ts`](src/index.ts) 注册提供方并解析设置与凭据。[`src/adapter.ts`](src/adapter.ts) 管理请求生命周期；[`src/serialize.ts`](src/serialize.ts) 和 [`src/translate.ts`](src/translate.ts) 映射模型输入与流式输出。[`src/file-store.ts`](src/file-store.ts) 通过 [`src/files-api.ts`](src/files-api.ts) 管理上传复用与恢复。
 
 ### 协议流程
 
@@ -177,11 +160,11 @@ Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留
 
 #### 模型看到什么
 
-所选 DeepSeek 模型会收到 harness 系统提示词、消息历史、工具 schema、停止序列与调用配置（`maxTokens`、`reasoningEffort`、`temperature`），不包含适配器撰写的提示词散文。提供方专用请求扩展字段留在模型输入之外。视觉模型通常接收 Files API 引用形式的用户与工具结果图片，其旁带附件句柄和请求预览尺寸。当前执行文件系统可以映射附件提供方的宿主对象时，它还会收到规范化对象路径；描述符会把该副本标记为只读，并警告规范化可能缩放或重新编码上传内容。Files 解析失败时，全部保留图片改用内联 base64；超出预算的较旧图片则在占位文本中保留当前请求已解析的访问方式。此前 assistant 轮次的推理内容会原样传回，无论该轮次是否调用了工具。 对于非法 JSON 或非对象的历史工具参数，Messages 发送 `{}`。此参数兜底保留调用 ID、工具名和工具结果；原始参数仍保留在 Session 日志中。从 Chat Completions 切换后也适用此静默兜底。新生成的 Messages 工具参数仍须是有效 JSON 对象。 Messages 会省略用户消息和工具结果中的 `reasoning` 与 `tool-call` 块；对这两类块的省略行为与 Chat Completions 和 pi-ai 适配器一致。这也允许回放包含助手输出的已保存子 Agent 通知；原始 Session 内容保持完整。转换后的空用户消息会被跳过，空工具结果则保留调用 id 和错误标记。其他不支持的输入块仍会以 `UNSUPPORTED_CONTENT` 失败。
+所选 DeepSeek 模型会收到 harness 系统提示词、消息历史、工具 schema、停止序列与调用配置（`maxTokens`、`reasoningEffort`、`temperature`），不包含适配器撰写的提示词散文。提供方专用请求扩展字段留在模型输入之外。视觉模型通常接收 Files API 引用形式的用户与工具结果图片，其旁带附件句柄和请求预览尺寸。当前执行文件系统可以映射附件提供方的宿主对象时，它还会收到规范化对象路径；描述符会把该副本标记为只读，并警告规范化可能缩放或重新编码上传内容。Files 解析失败时，全部保留图片改用内联 base64；超出预算的较旧图片则在占位文本中保留当前请求已解析的访问方式。此前 assistant 轮次的推理内容会原样传回，无论该轮次是否调用了工具。 对于非法 JSON 或非对象的历史工具参数，Messages 发送 `{}`。此参数兜底保留调用 ID、工具名和工具结果；原始参数仍保留在 Session 日志中。新生成的 Messages 工具参数仍须是有效 JSON 对象。 Messages 会省略用户消息和工具结果中的 `reasoning` 与 `tool-call` 块。这也允许回放包含助手输出的已保存子 Agent 通知；原始 Session 内容保持完整。转换后的空用户消息会被跳过，空工具结果则保留调用 id 和错误标记。其他不支持的输入块仍会以 `UNSUPPORTED_CONTENT` 失败。
 
 #### Token 影响
 
-提供方分词决定精确的文本与图片 token 输入。适配器声明按路由的 `imageRequestPricing`：把日志中的图片省略决策选中的每个出现位置按其占位文本计价，并按投影后的尺寸使用公开的视觉计量规则（14 px patch 网格、3:1 降采样、544×544 放大下限、单图 1024 token 上限）为每张保留图片计价。这使 token 计量服务可以在请求发出前为图片压力定价；上报的 usage 仍是权威值。推理回传会把每个推理轮次的思维链带进后续请求，而已省略的图片不再消耗视觉 token。保留的出现位置按精确请求版本字节超过 file 模式或内联回退预算（`maxRequestFilesBytes`、`maxImagesPerRequest` 与两个量子）的请求，以 `IMAGE_OFFLOAD_REQUIRED` 失败并说明还需省略多少最老的出现位置，由 `dsh-compaction-image-offload` 用 `image/offload` 事件记录所选位置并重试。可用时报告缓存读取用量。Messages 的 token 总数包含未缓存输入、输出、缓存读取与缓存写入 token。Chat Completions 使用 `prompt_tokens + completion_tokens`，提供方给出的 `total_tokens` 不一致时省略 `totalTokens`。
+提供方分词决定精确的文本与图片 token 输入。适配器声明按路由的 `imageRequestPricing`：把日志中的图片省略决策选中的每个出现位置按其占位文本计价，并按投影后的尺寸使用公开的视觉计量规则（14 px patch 网格、3:1 降采样、544×544 放大下限、单图 1024 token 上限）为每张保留图片计价。这使 token 计量服务可以在请求发出前为图片压力定价；上报的 usage 仍是权威值。推理回传会把每个推理轮次的思维链带进后续请求，而已省略的图片不再消耗视觉 token。保留的出现位置按精确请求版本字节超过 file 模式或内联回退预算（`maxRequestFilesBytes`、`maxImagesPerRequest` 与两个量子）的请求，以 `IMAGE_OFFLOAD_REQUIRED` 失败并说明还需省略多少最老的出现位置，由 `dsh-compaction-image-offload` 用 `image/offload` 事件记录所选位置并重试。可用时报告缓存读取用量。Messages 的 token 总数包含未缓存输入、输出、缓存读取与缓存写入 token。
 
 #### KV Cache 影响
 
@@ -203,7 +186,6 @@ loop 保留的响应块会追加到下一个请求，并保留其更早的可复
 
 ## 已知限制与延期工作
 
-- Responses 协议尚未实现，配置值 `responses` 会被拒绝。
 
 <a id="known-limitations-and-deferred-work"></a>
 
@@ -213,23 +195,14 @@ loop 保留的响应块会追加到下一个请求，并保留其更早的可复
 - **设置中的 `models` 列表会整体替换组合列表**——设置层按字段合并，数组只算一个字段；按条目合并目录需要带键的形状。
 - **不映射 `tool_choice`**——不属于核心词汇（与 pi-ai 孪生共享）。
 - **请求使用原始 `fetch`，而非 `@cordisjs/plugin-http`**——没有共享代理或拦截配置。
-- **Chat Completions 跳过插件新增的内容块类型**——核心文本与受支持图片块会被序列化，空工具输出以字面量 `(no output)` 过线。
 - **Messages 历史内 system 更新需要保留用户或工具结果轮次**——若更新后的全部用户输入都被省略，且前一个协议轮次是 assistant，序列化会在下一个 assistant 之前或请求结束处以 `UNSUPPORTED_CONTENT` 失败。文本或空工具结果可以保留该轮次。不支持将更新移到更早的轮次；[输入历史决策](../../../.agents/notes/implemented/bug-fix/2026-09-18-messages-input-history-compatibility.zh.md)记录了排序约束。
 - **图片是仅用于输入的持久附件**——不支持直接外部 URL 与 assistant 图片输出；DeepSeek 输入通常使用 Files API，仅在单次请求恢复时使用内联 base64。
-- 默认目录预注册 `deepseek-flash` 及其文本、图片和历史内更新能力，不探测网关可用性。网关开放该 ID 前，请求可能以 `INVALID_REQUEST` 失败。配置 `DEEPSEEK_API_KEY` 和支持该 ID 的网关后，设置 `DEEPSEEK_FLASH_E2E=1` 可启用[本包 e2e 测试文件](tests/adapter.e2e.ts)中的 Chat Completions 协议验证。
-- [Messages system 更新 e2e](tests/messages/adapter.e2e.ts) 要求通过 `DEEPSEEK_IN_HISTORY_MODEL` 指定支持该能力的模型，例如 `deepseek-flash`，并使用 `high` 思考强度。该变量未设置或为空时跳过；普通 `off` 文本检查仍在有凭据时运行。关闭思考时已知的指令遵循不稳定，使这些 system 更新检查不适合使用 `off`。
+- 默认目录公布 `deepseek-flash` 及其文本、图片和历史内更新能力，不探测网关可用性。网关开放该 ID 前，请求可能以 `INVALID_REQUEST` 失败。
+- [adapter.e2e.ts](tests/adapter.e2e.ts) 与 [runtime.e2e.ts](tests/runtime.e2e.ts) 中的真实 API 检查需要 `DEEPSEEK_API_KEY`。将 `DEEPSEEK_IN_HISTORY_MODEL` 设为受支持的非空模型 ID 可运行 system 更新检查：适配器套件使用 `high` 思考强度，运行时套件则在关闭思考时比较缓存复用，可能受到指令遵循不稳定的影响。运行时图片用例还需要 `DEEPSEEK_FLASH_E2E=1` 或 `DEEPSEEK_VISION_E2E=1`。
 
 <a id="dev-note"></a>
 ### 开发备注
 
-<details>
-<summary>维护者的工作上下文——点击展开</summary>
-
-本开发备注是不具权威性的工作上下文：尚未决定的探索方向与维护者备注。已交付的行为与既定理由以上文、包代码和相关 Agent Note 为准。
-
-- OpenRouter 专属应用归因标头延期到未来显式 OpenRouter 适配器或模式；OpenAI 兼容网关请求只携带共享归因基线。
-- `off` 推理强度绝不会以 `reasoning_effort: 'off'` 过线；它序列化为 `thinking: { type: 'disabled' }` 并省略该字段，从而对拒绝未知强度取值的网关保持协议拼写有效。
-
-</details>
+无。
 
 **运行时不变式：** 不发布伴生入口。本包没有独立事件序列或可变数据关系，相关约定在所属 seam 强制执行。
diff --git a/packages/llm/llm-deepseek/package.json b/packages/llm/llm-deepseek/package.json
index e3f69ca464..92a8643857 100644
--- a/packages/llm/llm-deepseek/package.json
+++ b/packages/llm/llm-deepseek/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-llm-deepseek",
-  "description": "DeepSeek adapter with Chat Completions and Messages protocols",
+  "description": "DeepSeek Messages adapter",
   "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 8e46799185..4b0f3704b9 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -1,58 +1,140 @@
-/** Select a DeepSeek wire implementation from one validated configuration generation. */
-import { assertNever } from '@deepseek-ai/dsh-util-values'
-import { LlmAdapter } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm'
-import type { DeepSeekAdapterOptions } from './common/types.ts'
-import { ChatCompletionsAdapter } from './protocols/chat-completions/adapter.ts'
-import { DeepSeekFileStore } from './common/file-store.ts'
-import { DeepSeekMessagesAdapter } from './protocols/messages/adapter.ts'
+/** Direct Messages transport with one cancellable lifecycle per model request. */
 
-/** One provider route with protocol-local transport and shared credentials and model configuration. */
+import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, ImageAttachmentAccessResolver, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { DeepSeekLlmApiJson } from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
+import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { catalogModelInfo, modelInfo } from './model-info.ts'
+import type { DeepSeekAdapterOptions, DeepSeekConnectionOptions as Connection } from './types.ts'
+import { DeepSeekFileStore } from './file-store.ts'
+import { MESSAGES_FILES_BETA, messagesApiRoot } from './messages-api.ts'
+import { FileResolutionFailure, RequestFiles } from './request-files.ts'
+import { prepareRequestExtensions } from './request-extensions.ts'
+import { imagePricing, inlineImages, prepareFileIds, prepareImages } from './images.ts'
+import { serialize } from './serialize.ts'
+import { parseSse } from './sse.ts'
+import { translate } from './translate.ts'
+import { providerError, providerErrorDetail } from './transport.ts'
+
+/** DeepSeek provider using Messages content and native thinking replay. */
 export class DeepSeekAdapter extends LlmAdapter {
   private readonly files: DeepSeekFileStore
+  private readonly imageAccess: ImageAttachmentAccessResolver = (ref) => {
+    const attachments = this.dependencies.resolveAttachments?.()
+    return attachments === undefined ? undefined : this.dependencies.resolveImageAccess?.(attachments, ref)
+  }
 
   constructor(private readonly dependencies: DeepSeekAdapterOptions) {
     super()
     this.files = dependencies.resolveFiles?.() ?? new DeepSeekFileStore()
   }
 
-  private implementation(): LlmAdapter {
+  override providerInfo(provider: string) { return { id: provider, name: 'DeepSeek' } }
+  override providerRetryPolicy(_provider: string) { return this.dependencies.options().retryPolicy }
+  override listModels(provider: string) {
     const connection = this.dependencies.options()
-    switch (connection.protocol) {
-      case 'messages':
-        return new DeepSeekMessagesAdapter({
-          connection: () => connection,
-          apiKey: this.dependencies.resolveApiKey,
-          userId: this.dependencies.resolveUserId,
-          attachments: () => this.dependencies.resolveAttachments?.(),
-          imageAccess: (ref) => {
-            const attachments = this.dependencies.resolveAttachments?.()
-            return attachments === undefined ? undefined : this.dependencies.resolveImageAccess?.(attachments, ref)
-          },
-          files: () => this.files,
-          prepareExtensions: this.dependencies.prepareExtensions,
-          ...this.dependencies.onReplayDegrade === undefined ? {} : { onReplayDegrade: this.dependencies.onReplayDegrade },
-        })
-      case 'chat-completions':
-        return new ChatCompletionsAdapter({ ...this.dependencies, options: () => connection, resolveFiles: () => this.files })
-      /* v8 ignore next -- protocol is validated at configuration resolution. */
-      default: return assertNever(connection.protocol, 'DeepSeek protocol')
+    return Promise.resolve(connection.models.map(model => catalogModelInfo(provider, model)))
+  }
+  override resolveModel(provider: string, model: string, _signal?: AbortSignal) {
+    return Promise.resolve(modelInfo(this.dependencies.options(), provider, model))
+  }
+  override imageRequestPricing(_provider: string, model: string) {
+    return imagePricing(this.dependencies.options(), model, this.imageAccess)
+  }
+  override prepareCall(provider: string, model: string, _signal?: AbortSignal): Promise<PreparedAdapterCall> {
+    const connection = this.dependencies.options()
+    return Promise.resolve({ model: modelInfo(connection, provider, model), stream: options => this.generate(options, connection) })
+  }
+  stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    return this.generate(options, this.dependencies.options())
+  }
+
+  private async * generate(options: GenerateOptions, connection: Connection): AsyncGenerator<StreamChunk> {
+    const consumer = new AbortController()
+    const signal = options.signal === undefined ? consumer.signal : AbortSignal.any([consumer.signal, options.signal])
+    using watchdog = idleWatchdog(signal, connection.streamIdleTimeoutMs, 'MESSAGES_IDLE')
+    const iterator = this.request(options, connection, watchdog.signal, () => { watchdog.pulse() })
+    try {
+      while (true) {
+        const next = await watchdog.next(iterator)
+        if (next.done) return
+        yield next.value
+      }
+    } catch (error) {
+      if (timeoutOf(watchdog.signal, 'MESSAGES_IDLE') !== undefined) throw new LlmError('DeepSeek Messages stream idle timeout', 'TIMEOUT', { cause: error })
+      if (options.signal?.aborted) throw new LlmError('DeepSeek Messages request aborted', 'ABORTED', { cause: error })
+      if (error instanceof LlmError) throw error
+      throw new LlmError('DeepSeek Messages transport failed', 'TRANSPORT', { cause: error })
+    } finally {
+      consumer.abort()
+      try { await iterator.return(undefined) } catch (_abortedRequestCleanup) {
+        // The request already settled; aborting its reader cannot replace that outcome.
+      }
     }
   }
 
-  override providerInfo(provider: string) { return this.implementation().providerInfo(provider) }
-  override providerRetryPolicy(provider: string) { return this.implementation().providerRetryPolicy(provider) }
-  override listModels(provider: string) { return this.implementation().listModels(provider) }
-  override resolveModel(provider: string, model: string, signal?: AbortSignal) {
-    return this.implementation().resolveModel(provider, model, signal)
-  }
-  override imageRequestPricing(provider: string, model: string) {
-    return this.implementation().imageRequestPricing(provider, model)
-  }
-  override prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall> {
-    return this.implementation().prepareCall(provider, model, signal)
-  }
-  stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    return this.implementation().stream(options)
+  private async * request(
+    options: GenerateOptions, connection: Connection, signal: AbortSignal, activity: () => void,
+  ): AsyncGenerator<StreamChunk> {
+    signal.throwIfAborted()
+    const { messages, versions } = await prepareImages(
+      options.messages, connection, options.model, this.dependencies.resolveAttachments?.(), this.imageAccess, signal,
+    )
+    const key = await this.dependencies.resolveApiKey(connection)
+    const files = new RequestFiles(this.files, { baseURL: connection.baseURL, apiKey: key },
+      connection.filePolicy, connection.filesApiTimeoutMs, signal, activity)
+    let inline = false
+    while (true) {
+      signal.throwIfAborted()
+      files.beginAttempt()
+      let fileIds: Awaited<ReturnType<typeof prepareFileIds>> | undefined
+      if (!inline) {
+        try {
+          fileIds = await prepareFileIds(messages, versions, files)
+        } catch (error) {
+          if (!(error instanceof FileResolutionFailure)) throw error
+          inline = true
+          continue
+        }
+      }
+      const history = inline ? inlineImages(messages, versions, connection) : messages
+      const body = serialize(options, connection, history, versions, this.imageAccess, (reason) => {
+        this.dependencies.onReplayDegrade?.({ provider: options.provider, model: options.model, reason })
+      }, fileIds)
+      const extensions = await prepareRequestExtensions(body as Readonly<Record<string, DeepSeekLlmApiJson>>, {
+        signal,
+        ...options.sessionId === undefined ? {} : { sessionId: String(options.sessionId) },
+        ...options.purpose === undefined ? {} : { purpose: options.purpose },
+      }, this.dependencies.prepareExtensions)
+      signal.throwIfAborted()
+      const response = await fetch(`${messagesApiRoot(connection.baseURL)}/messages`, {
+        method: 'POST', signal, body: extensions.payload, redirect: 'error',
+        headers: {
+          ...attributionHeaders(),
+          'content-type': 'application/json', 'accept': 'text/event-stream',
+          'x-api-key': key, 'anthropic-version': '2023-06-01',
+          ...fileIds === undefined || fileIds.size === 0 ? {} : { 'anthropic-beta': MESSAGES_FILES_BETA },
+          'x-deepseek-harness-user-id': this.dependencies.resolveUserId(),
+          ...options.sessionId === undefined ? {} : { 'x-deepseek-harness-session-id': String(options.sessionId) },
+          ...options.purpose === 'compaction' ? { 'x-deepseek-harness-compact': '1' } : {},
+        },
+      })
+      if (!response.ok) {
+        const text = await response.text()
+        let raw: unknown
+        try { raw = JSON.parse(text) } catch (_nonJsonGatewayError) {
+          // HTTP status is authoritative when a gateway does not return JSON.
+        }
+        const detail = providerErrorDetail(raw)
+        if (await files.retry(detail)) continue
+        const failure = providerError(raw, response.status, response.headers)
+        const message = files.errorMessage(response.status, failure.message, detail)
+        throw new LlmError(message, failure.code, { ...failure.failure, cause: new Error(text) })
+      }
+      await extensions.accept()
+      if (response.body === null) throw new LlmError('DeepSeek Messages returned no response body', 'EMPTY_RESPONSE')
+      yield* translate(parseSse(response.body, activity), options.model)
+      return
+    }
   }
 }
diff --git a/packages/llm/llm-deepseek/src/config.ts b/packages/llm/llm-deepseek/src/config.ts
index 3bf9f5a6d2..edfbc252b4 100644
--- a/packages/llm/llm-deepseek/src/config.ts
+++ b/packages/llm/llm-deepseek/src/config.ts
@@ -5,10 +5,10 @@ import type { ModelModality, RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import type { LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment'
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import type { DeepSeekCatalogModel, DeepSeekConnectionOptions, DeepSeekProtocol } from './common/types.ts'
-import { DEFAULT_MODELS } from './common/models.ts'
-import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES, DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM, DEFAULT_FILE_EXPIRY_SECONDS, DEFAULT_FILE_REFRESH_MARGIN_SECONDS, DEFAULT_FILE_QUOTA_CLEANUP_BATCH, DEFAULT_FILES_API_TIMEOUT_MS } from './common/defaults.ts'
-import { DEFAULT_MAX_IMAGES_PER_REQUEST, DEFAULT_MAX_REQUEST_FILES_BYTES, DEFAULT_REQUEST_IMAGE_MAX_BYTES } from './common/request-pricing.ts'
+import type { DeepSeekCatalogModel, DeepSeekConnectionOptions } from './types.ts'
+import { DEFAULT_MODELS } from './models.ts'
+import { DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES, DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM, DEFAULT_FILE_EXPIRY_SECONDS, DEFAULT_FILE_REFRESH_MARGIN_SECONDS, DEFAULT_FILE_QUOTA_CLEANUP_BATCH, DEFAULT_FILES_API_TIMEOUT_MS } from './defaults.ts'
+import { DEFAULT_MAX_IMAGES_PER_REQUEST, DEFAULT_MAX_REQUEST_FILES_BYTES, DEFAULT_REQUEST_IMAGE_MAX_BYTES } from './request-pricing.ts'
 
 const DEFAULT_API_KEY_ENV = 'DEEPSEEK_API_KEY'
 
@@ -23,8 +23,6 @@ const MODEL_MODALITIES = ['text', 'image'] as const satisfies readonly ModelModa
  * reasoning effort resolves to `high`.
  */
 export interface Config {
-  /** Wire protocol; defaults to messages. Configure through Cordis YAML. */
-  protocol?: DeepSeekProtocol
   /** Credential reference (environment-variable name) resolved per request; defaults to `DEEPSEEK_API_KEY`. */
   apiKeyEnv?: string
   /** Endpoint base; falls back to $DEEPSEEK_BASE_URL from a trusted environment layer, then the public API. */
@@ -78,7 +76,6 @@ const catalogModel: z<DeepSeekCatalogModel> = z.object({
 })
 
 export const Config: z<Config> = z.object({
-  protocol: z.union(['chat-completions', 'messages']).default('messages'),
   apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
   baseURL: z.string(),
   thinking: z.union(['enabled', 'disabled']),
@@ -101,10 +98,7 @@ export const Config: z<Config> = z.object({
 })
 
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
-export const PUBLIC_BASE_URL = 'https://api.deepseek.com'
-
-/** Official Messages protocol root. */
-export const MESSAGES_BASE_URL = 'https://api.deepseek.com/anthropic'
+export const PUBLIC_BASE_URL = 'https://api.deepseek.com/anthropic'
 
 /** Environment variable naming this provider's endpoint, honored only from trusted layers. */
 const BASE_URL_ENV = 'DEEPSEEK_BASE_URL'
@@ -204,9 +198,8 @@ function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): Dee
  */
 export function resolveAdapterOptions(config: Config, environment?: LaunchEnvironmentSnapshot): ResolvedDeepSeekOptions {
   // Settings updates can reach this resolver without schema validation.
-  const protocol: string = config.protocol ?? 'messages'
-  if (protocol !== 'chat-completions' && protocol !== 'messages') {
-    throw new Error('llm-deepseek: protocol must be chat-completions or messages')
+  if (Object.hasOwn(config, 'protocol')) {
+    throw new Error('llm-deepseek: protocol is not configurable; remove it and use a Messages-compatible baseURL')
   }
   if (config.thinking === 'disabled'
     && config.reasoningEffort !== undefined
@@ -289,16 +282,12 @@ export function resolveAdapterOptions(config: Config, environment?: LaunchEnviro
     || fileQuotaCleanupBatch > 1_000) {
     throw new Error('llm-deepseek: fileQuotaCleanupBatch must be an integer from 1 through 1000')
   }
-  const baseURL = config.baseURL ?? environment?.get(BASE_URL_ENV)?.value
-    ?? (protocol === 'messages' ? MESSAGES_BASE_URL : PUBLIC_BASE_URL)
-  if (protocol === 'messages') {
-    const parsed = new URL(baseURL)
-    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) {
-      throw new Error('llm-deepseek: Messages baseURL must be an HTTP(S) root without credentials, query, or fragment')
-    }
+  const baseURL = config.baseURL ?? environment?.get(BASE_URL_ENV)?.value ?? PUBLIC_BASE_URL
+  const parsed = new URL(baseURL)
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error('llm-deepseek: Messages baseURL must be an HTTP(S) root without credentials, query, or fragment')
   }
   return {
-    protocol,
     apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
     baseURL,
     defaults: {
diff --git a/packages/llm/llm-deepseek/src/common/defaults.ts b/packages/llm/llm-deepseek/src/defaults.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/defaults.ts
rename to packages/llm/llm-deepseek/src/defaults.ts
diff --git a/packages/llm/llm-deepseek/src/common/file-id.ts b/packages/llm/llm-deepseek/src/file-id.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/file-id.ts
rename to packages/llm/llm-deepseek/src/file-id.ts
diff --git a/packages/llm/llm-deepseek/src/common/file-store.ts b/packages/llm/llm-deepseek/src/file-store.ts
similarity index 93%
rename from packages/llm/llm-deepseek/src/common/file-store.ts
rename to packages/llm/llm-deepseek/src/file-store.ts
index 5fcab0cbe1..0963d2eeab 100644
--- a/packages/llm/llm-deepseek/src/common/file-store.ts
+++ b/packages/llm/llm-deepseek/src/file-store.ts
@@ -7,7 +7,6 @@ import type { DeepSeekFileId } from './file-id.ts'
 import { messagesApiRoot } from './messages-api.ts'
 import { deepSeekFileScope, DeepSeekUploadIndex } from './upload-index.ts'
 import type { DeepSeekUploadRecord } from './upload-index.ts'
-import type { DeepSeekProtocol } from './types.ts'
 
 /** Shared Files-store limit for each request image, including file-id references. */
 export const MAX_IMAGE_BYTES = 32 * 1024 * 1024
@@ -24,8 +23,6 @@ export interface DeepSeekFilePolicy {
 export interface DeepSeekFileConnection {
   baseURL: string
   apiKey: string
-  /** Files wire protocol selected by the resolved connection. */
-  protocol: DeepSeekProtocol
 }
 
 /** Result of one file-id resolution. */
@@ -47,10 +44,10 @@ interface SharedUpload {
   waiters: number
 }
 
-/** The Files resource's parent URL distinguishes custom protocol namespaces. */
+/** The Files resource's parent URL identifies the upload namespace. */
 function fileScope(connection: DeepSeekFileConnection) {
   return deepSeekFileScope(
-    connection.protocol === 'messages' ? messagesApiRoot(connection.baseURL) : connection.baseURL,
+    messagesApiRoot(connection.baseURL),
     connection.apiKey,
   )
 }
@@ -139,7 +136,6 @@ export class DeepSeekFileStore {
     return new DeepSeekFilesClient({
       baseURL: connection.baseURL,
       apiKey: connection.apiKey,
-      protocol: connection.protocol,
       ...this.fetchImpl === undefined ? {} : { fetch: this.fetchImpl },
     })
   }
@@ -306,23 +302,19 @@ export class DeepSeekFileStore {
     const client = this.client(connection)
     let after: DeepSeekFileId | undefined
     const owned: { id: DeepSeekFileId; createdAt: number }[] = []
-    while (connection.protocol === 'messages' || owned.length < count) {
+    while (true) {
       const page = await client.list({
         ...after === undefined ? {} : { after },
         limit: 1_000,
-        order: 'asc',
         ...signal === undefined ? {} : { signal },
       })
       for (const file of page.data) {
         if (!file.filename.startsWith(OWNED_FILE_PREFIX)) continue
         owned.push({ id: file.id, createdAt: file.createdAt })
-        if (connection.protocol === 'chat-completions' && owned.length === count) break
-      }
-      if (connection.protocol === 'messages') {
-        // Messages offers no ascending-order query; retain the oldest candidates across every page.
-        owned.sort((left, right) => left.createdAt - right.createdAt)
-        owned.splice(count)
       }
+      // The API offers no ascending-order query; retain the oldest candidates across every page.
+      owned.sort((left, right) => left.createdAt - right.createdAt)
+      owned.splice(count)
       if (!page.hasMore || page.lastId === undefined || page.lastId === after) break
       after = page.lastId
     }
diff --git a/packages/llm/llm-deepseek/src/common/files-api.ts b/packages/llm/llm-deepseek/src/files-api.ts
similarity index 63%
rename from packages/llm/llm-deepseek/src/common/files-api.ts
rename to packages/llm/llm-deepseek/src/files-api.ts
index 8c05165bea..abf9f12191 100644
--- a/packages/llm/llm-deepseek/src/common/files-api.ts
+++ b/packages/llm/llm-deepseek/src/files-api.ts
@@ -1,11 +1,10 @@
-/** DeepSeek Files API transport for Chat Completions and Messages endpoints. @module dsh-llm-deepseek/files-api */
+/** DeepSeek Files API transport. @module dsh-llm-deepseek/files-api */
 
 import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm'
 import type { ImageMediaType } from '@deepseek-ai/dsh-attachment'
 import { DeepSeekFileId } from './file-id.ts'
 import type { DeepSeekFileId as DeepSeekFileIdType } from './file-id.ts'
 import { messagesApiRoot, MESSAGES_FILES_BETA } from './messages-api.ts'
-import type { DeepSeekProtocol } from './types.ts'
 
 /** Minimum provider-supported file lifetime. */
 export const MIN_FILE_EXPIRY_SECONDS = 3_600
@@ -18,15 +17,13 @@ export const MAX_STORED_FILE_COUNT = 10_000
 /** Current per-key storage quota. */
 export const MAX_STORED_FILE_BYTES = 25 * 1024 * 1024 * 1024
 
-/** Validated file metadata normalized from either DeepSeek Files protocol. */
+/** Validated provider file metadata. */
 export interface DeepSeekFileObject {
   id: DeepSeekFileIdType
   bytes: number
   createdAt: number
   filename: string
-  /** Chat Completions purpose; synthesized as `user_data` for Messages. */
-  purpose: 'user_data'
-  /** Remote Chat Completions expiry or the upload-time Messages reuse deadline; Messages list/retrieve omit this field. */
+  /** Upload-time reuse deadline; list and retrieve responses omit this field. */
   expiresAt?: number
 }
 
@@ -74,20 +71,9 @@ export function isFilesQuotaError(error: unknown): error is DeepSeekFilesError {
 interface FilesApiOptions {
   baseURL: string
   apiKey: string
-  protocol: DeepSeekProtocol
   fetch?: typeof fetch
 }
 
-interface WireFileObject {
-  id?: unknown
-  object?: unknown
-  bytes?: unknown
-  created_at?: unknown
-  filename?: unknown
-  purpose?: unknown
-  expires_at?: unknown
-}
-
 function invalidResponse(operation: string): LlmError {
   return new LlmError(`DeepSeek Files API returned an invalid ${operation} response.`, 'INVALID_RESPONSE')
 }
@@ -107,39 +93,25 @@ async function responseJson(response: Response, operation: string): Promise<unkn
 
 function parseFileObject(value: unknown, operation: string): DeepSeekFileObject {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) throw invalidResponse(operation)
-  const wire = value as WireFileObject
+  const wire = value as Record<string, unknown>
+  const createdAt = typeof wire.created_at === 'string' ? Math.floor(Date.parse(wire.created_at) / 1_000) : NaN
   if (typeof wire.id !== 'string' || wire.id.length === 0
-    || wire.object !== 'file'
-    || !Number.isSafeInteger(wire.bytes) || (wire.bytes as number) < 0
-    || !Number.isSafeInteger(wire.created_at) || (wire.created_at as number) < 0
+    || wire.type !== 'file'
+    || typeof wire.mime_type !== 'string'
+    || typeof wire.size_bytes !== 'number' || !Number.isSafeInteger(wire.size_bytes) || wire.size_bytes < 0
+    || !Number.isSafeInteger(createdAt) || createdAt < 0
     || typeof wire.filename !== 'string' || wire.filename.length === 0
-    || wire.purpose !== 'user_data'
-    || (wire.expires_at !== undefined
-      && (!Number.isSafeInteger(wire.expires_at) || (wire.expires_at as number) < 0))) {
+  ) {
     throw invalidResponse(operation)
   }
   return {
     id: DeepSeekFileId(wire.id),
-    bytes: wire.bytes as number,
-    createdAt: wire.created_at as number,
+    bytes: wire.size_bytes,
+    createdAt,
     filename: wire.filename,
-    purpose: 'user_data',
-    ...wire.expires_at === undefined ? {} : { expiresAt: wire.expires_at as number },
   }
 }
 
-/** Normalize the Messages wire object without interpreting omitted expiration as permanence. */
-function parseMessagesFile(value: unknown, operation: string): DeepSeekFileObject {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw invalidResponse(operation)
-  const wire = value as Record<string, unknown>
-  const createdAt = typeof wire.created_at === 'string' ? Math.floor(Date.parse(wire.created_at) / 1_000) : NaN
-  if (wire.type !== 'file' || typeof wire.mime_type !== 'string' || !Number.isSafeInteger(createdAt)) throw invalidResponse(operation)
-  return parseFileObject({
-    id: wire.id, object: 'file', bytes: wire.size_bytes, created_at: createdAt,
-    filename: wire.filename, purpose: 'user_data',
-  }, operation)
-}
-
 function providerErrorDetail(value: unknown): { message?: string; detail: string } {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return { detail: '' }
   const error = (value as { error?: unknown }).error
@@ -159,8 +131,6 @@ export class DeepSeekFilesClient {
   private readonly baseURL: string
   private readonly apiKey: string
   private readonly fetchImpl: typeof fetch
-  private readonly protocol: DeepSeekProtocol
-  private readonly path: string
 
   /**
    * @param options - endpoint, API-key snapshot, and optional test transport.
@@ -168,26 +138,16 @@ export class DeepSeekFilesClient {
   constructor(options: FilesApiOptions) {
     this.apiKey = options.apiKey
     this.fetchImpl = options.fetch ?? globalThis.fetch
-    this.protocol = options.protocol
-    this.baseURL = this.protocol === 'messages'
-      ? messagesApiRoot(options.baseURL)
-      : options.baseURL.replace(/\/+$/u, '')
-    this.path = '/files'
-  }
-
-  private parseFile(value: unknown, operation: string): DeepSeekFileObject {
-    return this.protocol === 'messages' ? parseMessagesFile(value, operation) : parseFileObject(value, operation)
+    this.baseURL = messagesApiRoot(options.baseURL)
   }
 
   private async request(path: string, init: RequestInit, signal?: AbortSignal): Promise<Response> {
     let response: Response
     try {
       const headers = new Headers(attributionHeaders())
-      if (this.protocol === 'messages') {
-        headers.set('x-api-key', this.apiKey)
-        headers.set('anthropic-version', '2023-06-01')
-        headers.set('anthropic-beta', MESSAGES_FILES_BETA)
-      } else headers.set('authorization', `Bearer ${this.apiKey}`)
+      headers.set('x-api-key', this.apiKey)
+      headers.set('anthropic-version', '2023-06-01')
+      headers.set('anthropic-beta', MESSAGES_FILES_BETA)
       response = await this.fetchImpl(`${this.baseURL}${path}`, {
         ...init,
         redirect: 'error',
@@ -235,45 +195,40 @@ export class DeepSeekFilesClient {
       throw new LlmError('DeepSeek file expiry must be between 3600 and 2592000 seconds.', 'INVALID_REQUEST')
     }
     const form = new FormData()
-    if (this.protocol === 'chat-completions') form.set('purpose', 'user_data')
     form.set('expires_after[anchor]', 'created_at')
     form.set('expires_after[seconds]', String(input.expiresAfterSeconds))
     form.set('file', new Blob([Uint8Array.from(input.data).buffer], { type: input.mediaType }), input.filename)
-    const response = await this.request(this.path, { method: 'POST', body: form }, input.signal)
-    const file = this.parseFile(await responseJson(response, 'upload'), 'upload')
-    if (this.protocol === 'messages') return { ...file, expiresAt: file.createdAt + input.expiresAfterSeconds }
-    if (file.expiresAt === undefined) throw invalidResponse('upload')
-    return { ...file, expiresAt: file.expiresAt }
+    const response = await this.request('/files', { method: 'POST', body: form }, input.signal)
+    const file = parseFileObject(await responseJson(response, 'upload'), 'upload')
+    return { ...file, expiresAt: file.createdAt + input.expiresAfterSeconds }
   }
 
   /**
-   * List one page of files. Ordering applies only to Chat Completions; Messages owns its page order.
-   * @param options - pagination, ordering, and cancellation.
-   * @returns the validated page with null Messages cursors omitted.
+   * List one provider-ordered page of files.
+   * @param options - pagination and cancellation.
+   * @returns the validated page with null cursors omitted.
    */
   async list(options: {
     after?: DeepSeekFileIdType
     limit?: number
-    order?: 'asc' | 'desc'
     signal?: AbortSignal
   } = {}): Promise<DeepSeekFilePage> {
-    const query = new URLSearchParams(this.protocol === 'messages' ? {} : { purpose: 'user_data' })
-    if (options.after !== undefined) query.set(this.protocol === 'messages' ? 'after_id' : 'after', options.after)
+    const query = new URLSearchParams()
+    if (options.after !== undefined) query.set('after_id', options.after)
     if (options.limit !== undefined) query.set('limit', String(options.limit))
-    if (options.order !== undefined && this.protocol === 'chat-completions') query.set('order', options.order)
-    const response = await this.request(`${this.path}?${query.toString()}`, { method: 'GET' }, options.signal)
+    const response = await this.request(`/files?${query.toString()}`, { method: 'GET' }, options.signal)
     const value: unknown = await responseJson(response, 'list')
     if (value === null || typeof value !== 'object' || Array.isArray(value)) throw invalidResponse('list')
-    const wire = value as { object?: unknown; data?: unknown; first_id?: unknown; last_id?: unknown; has_more?: unknown }
-    const firstId = this.protocol === 'messages' ? wire.first_id ?? undefined : wire.first_id
-    const lastId = this.protocol === 'messages' ? wire.last_id ?? undefined : wire.last_id
-    if ((this.protocol === 'chat-completions' && wire.object !== 'list') || !Array.isArray(wire.data) || typeof wire.has_more !== 'boolean'
+    const wire = value as { data?: unknown; first_id?: unknown; last_id?: unknown; has_more?: unknown }
+    const firstId = wire.first_id ?? undefined
+    const lastId = wire.last_id ?? undefined
+    if (!Array.isArray(wire.data) || typeof wire.has_more !== 'boolean'
       || (firstId !== undefined && typeof firstId !== 'string')
       || (lastId !== undefined && typeof lastId !== 'string')) {
       throw invalidResponse('list')
     }
     return {
-      data: wire.data.map(item => this.parseFile(item, 'list')),
+      data: wire.data.map(item => parseFileObject(item, 'list')),
       ...typeof firstId === 'string' ? { firstId: DeepSeekFileId(firstId) } : {},
       ...typeof lastId === 'string' ? { lastId: DeepSeekFileId(lastId) } : {},
       hasMore: wire.has_more,
@@ -287,8 +242,8 @@ export class DeepSeekFilesClient {
    * @returns the validated file object.
    */
   async retrieve(fileId: DeepSeekFileIdType, signal?: AbortSignal): Promise<DeepSeekFileObject> {
-    const response = await this.request(`${this.path}/${encodeURIComponent(fileId)}`, { method: 'GET' }, signal)
-    return this.parseFile(await responseJson(response, 'retrieve'), 'retrieve')
+    const response = await this.request(`/files/${encodeURIComponent(fileId)}`, { method: 'GET' }, signal)
+    return parseFileObject(await responseJson(response, 'retrieve'), 'retrieve')
   }
 
   /**
@@ -297,12 +252,10 @@ export class DeepSeekFilesClient {
    * @param signal - request cancellation.
    */
   async delete(fileId: DeepSeekFileIdType, signal?: AbortSignal): Promise<void> {
-    const response = await this.request(`${this.path}/${encodeURIComponent(fileId)}`, { method: 'DELETE' }, signal)
+    const response = await this.request(`/files/${encodeURIComponent(fileId)}`, { method: 'DELETE' }, signal)
     const value: unknown = await responseJson(response, 'delete')
     if (value === null || typeof value !== 'object' || Array.isArray(value)) throw invalidResponse('delete')
-    const wire = value as { id?: unknown; object?: unknown; deleted?: unknown; type?: unknown }
-    if (wire.id !== fileId || (this.protocol === 'messages'
-      ? wire.type !== 'file_deleted'
-      : wire.object !== 'file' || wire.deleted !== true)) throw invalidResponse('delete')
+    const wire = value as { id?: unknown; type?: unknown }
+    if (wire.id !== fileId || wire.type !== 'file_deleted') throw invalidResponse('delete')
   }
 }
diff --git a/packages/llm/llm-deepseek/src/common/image-tokens.ts b/packages/llm/llm-deepseek/src/image-tokens.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/image-tokens.ts
rename to packages/llm/llm-deepseek/src/image-tokens.ts
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/images.ts b/packages/llm/llm-deepseek/src/images.ts
similarity index 93%
rename from packages/llm/llm-deepseek/src/protocols/messages/images.ts
rename to packages/llm/llm-deepseek/src/images.ts
index f2f32f003e..9d72f4c5dc 100644
--- a/packages/llm/llm-deepseek/src/protocols/messages/images.ts
+++ b/packages/llm/llm-deepseek/src/images.ts
@@ -3,12 +3,12 @@
 import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
 import { contentHasImage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmError, offloadedImageText, projectOffloadedImages, requiredImageOffload } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, ImageAttachmentAccessResolver, RequestMessage } from '@deepseek-ai/dsh-llm'
-import type { DeepSeekConnectionOptions as Connection } from '../../common/types.ts'
-import { resolveRequestImageTarget } from '../../common/request-pricing.ts'
-import type { DeepSeekFileId } from '../../common/file-id.ts'
-import type { RequestFiles } from '../../common/request-files.ts'
+import type { DeepSeekConnectionOptions as Connection } from './types.ts'
+import { resolveRequestImageTarget } from './request-pricing.ts'
+import type { DeepSeekFileId } from './file-id.ts'
+import type { RequestFiles } from './request-files.ts'
 
-export { deepSeekImageRequestPricing as imagePricing } from '../../common/request-pricing.ts'
+export { deepSeekImageRequestPricing as imagePricing } from './request-pricing.ts'
 
 function bounds(connection: Connection, representation: 'raw' | 'base64') {
   return {
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index d38246b971..cc5cfdc52f 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -1,4 +1,4 @@
-/** Register DeepSeek with protocol selection and request-local settings and credentials. */
+/** Register DeepSeek Messages with request-local settings and credentials. */
 import type { Context } from '@deepseek-ai/cordis'
 import { assertUsableApiKey, LlmError, resolveImageAttachmentAccess } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-fs'
@@ -10,7 +10,7 @@ import { DeepSeekAdapter } from './adapter.ts'
 import { Config, resolveAdapterOptions } from './config.ts'
 import type { ResolvedDeepSeekOptions } from './config.ts'
 
-export { Config, resolveAdapterOptions, PUBLIC_BASE_URL, MESSAGES_BASE_URL } from './config.ts'
+export { Config, resolveAdapterOptions, PUBLIC_BASE_URL } from './config.ts'
 export type { ResolvedDeepSeekOptions } from './config.ts'
 export {
   DEFAULT_CONTEXT_WINDOW,
@@ -24,10 +24,9 @@ export {
   DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES,
   DEFAULT_MAX_TOKENS,
   DEFAULT_STREAM_IDLE_TIMEOUT_MS,
-} from './common/defaults.ts'
+} from './defaults.ts'
 export { DeepSeekAdapter } from './adapter.ts'
-export type { DeepSeekProtocol } from './common/types.ts'
-export type { DeepSeekAdapterOptions, DeepSeekCatalogModel, DeepSeekConnectionOptions } from './common/types.ts'
+export type { DeepSeekAdapterOptions, DeepSeekCatalogModel, DeepSeekConnectionOptions } from './types.ts'
 export {
   DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET,
   DEFAULT_MAX_IMAGES_PER_REQUEST,
@@ -37,18 +36,17 @@ export {
   deepSeekImageRequestPricing,
   resolveRequestImageMaxBytes,
   resolveRequestImageTarget,
-} from './common/request-pricing.ts'
-export { deepSeekImageTokens, deepSeekRequestImageDimensions } from './common/image-tokens.ts'
-export { DeepSeekFileStore, MAX_IMAGE_BYTES } from './common/file-store.ts'
-export type { DeepSeekFileConnection, DeepSeekFilePolicy, DeepSeekFileReference } from './common/file-store.ts'
-export { DeepSeekFilesClient, MAX_FILE_EXPIRY_SECONDS, MAX_FILE_UPLOAD_BYTES, MAX_STORED_FILE_BYTES, MAX_STORED_FILE_COUNT, MIN_FILE_EXPIRY_SECONDS } from './common/files-api.ts'
-export type { DeepSeekFileObject, DeepSeekFilePage } from './common/files-api.ts'
-export { DeepSeekFileId } from './common/file-id.ts'
-export type { DeepSeekFileId as DeepSeekFileIdType } from './common/file-id.ts'
-export { DeepSeekUploadIndex, deepSeekFileScope } from './common/upload-index.ts'
-export type { DeepSeekUploadRecord } from './common/upload-index.ts'
-export type { RequestDefaults } from './common/types.ts'
-export type * from './protocols/chat-completions/types.ts'
+} from './request-pricing.ts'
+export { deepSeekImageTokens, deepSeekRequestImageDimensions } from './image-tokens.ts'
+export { DeepSeekFileStore, MAX_IMAGE_BYTES } from './file-store.ts'
+export type { DeepSeekFileConnection, DeepSeekFilePolicy, DeepSeekFileReference } from './file-store.ts'
+export { DeepSeekFilesClient, MAX_FILE_EXPIRY_SECONDS, MAX_FILE_UPLOAD_BYTES, MAX_STORED_FILE_BYTES, MAX_STORED_FILE_COUNT, MIN_FILE_EXPIRY_SECONDS } from './files-api.ts'
+export type { DeepSeekFileObject, DeepSeekFilePage } from './files-api.ts'
+export { DeepSeekFileId } from './file-id.ts'
+export type { DeepSeekFileId as DeepSeekFileIdType } from './file-id.ts'
+export { DeepSeekUploadIndex, deepSeekFileScope } from './upload-index.ts'
+export type { DeepSeekUploadRecord } from './upload-index.ts'
+export type { RequestDefaults } from './types.ts'
 
 export const name = 'llm-deepseek'
 export const inject = ['llm']
diff --git a/packages/llm/llm-deepseek/src/common/messages-api.ts b/packages/llm/llm-deepseek/src/messages-api.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/messages-api.ts
rename to packages/llm/llm-deepseek/src/messages-api.ts
diff --git a/packages/llm/llm-deepseek/src/common/model-info.ts b/packages/llm/llm-deepseek/src/model-info.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/model-info.ts
rename to packages/llm/llm-deepseek/src/model-info.ts
diff --git a/packages/llm/llm-deepseek/src/common/models.ts b/packages/llm/llm-deepseek/src/models.ts
similarity index 92%
rename from packages/llm/llm-deepseek/src/common/models.ts
rename to packages/llm/llm-deepseek/src/models.ts
index 8f614db47b..6bad9113ce 100644
--- a/packages/llm/llm-deepseek/src/common/models.ts
+++ b/packages/llm/llm-deepseek/src/models.ts
@@ -1,4 +1,4 @@
-/** Default catalog shared by every DeepSeek protocol. */
+/** Default DeepSeek model catalog. */
 import { DEFAULT_CONTEXT_WINDOW } from './defaults.ts'
 import type { DeepSeekCatalogModel } from './types.ts'
 
diff --git a/packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts b/packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts
deleted file mode 100644
index 77d2bf6ca5..0000000000
--- a/packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts
+++ /dev/null
@@ -1,378 +0,0 @@
-/**
- * `DeepSeekAdapter`: fetch + SSE against a DeepSeek (OpenAI-compatible)
- * chat-completions endpoint, emitting harness StreamChunks. The adapter is
- * transport-only: connection facts arrive through a thunk resolved once per
- * operation and the bearer token through a per-request resolver, so the
- * registering plugin owns validation, layering, and credential policy.
- *
- * @module dsh-llm-deepseek/adapter
- */
-
-import { attributionHeaders, contentHasImage, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
-import type {
-  ContentBlock,
-  GenerateOptions,
-  ImageAttachmentAccess,
-  LlmModelInfo,
-  LlmProviderInfo,
-  PreparedAdapterCall,
-  LlmResolvedModelInfo,
-  ResolvedRetryPolicy,
-  StreamChunk,
-} from '@deepseek-ai/dsh-llm'
-import type {
-  AttachmentId,
-  AttachmentStore,
-  ImageAttachmentRef,
-  RequestImageAttachment,
-} from '@deepseek-ai/dsh-attachment'
-import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
-import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import type {
-  DeepSeekLlmApiJson,
-} from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import { serializeRequest, serializeRequestWithImages } from './serialize.ts'
-import { deepSeekImageRequestPricing, resolveRequestImageTarget } from '../../common/request-pricing.ts'
-import { catalogModelInfo, modelInfo } from '../../common/model-info.ts'
-import type { DeepSeekAdapterOptions, DeepSeekCatalogModel, DeepSeekConnectionOptions } from '../../common/types.ts'
-import type { DeepSeekFileStore } from '../../common/file-store.ts'
-import { FileResolutionFailure, RequestFiles } from '../../common/request-files.ts'
-import { prepareRequestExtensions } from '../../common/request-extensions.ts'
-import { parseSse } from './sse.ts'
-import { translate } from './translate.ts'
-import type { WireError, WireRequest } from './types.ts'
-
-const STREAM_IDLE_TIMEOUT_CODE = 'LLM_STREAM_IDLE_TIMEOUT'
-
-function collectImageRefs(
-  content: readonly ContentBlock[],
-  refs: Map<AttachmentId, ImageAttachmentRef>,
-): void {
-  for (const block of content) {
-    if (block.type === 'image' && block.offloaded !== true) refs.set(block.attachment.attachmentId, block.attachment)
-  }
-}
-
-async function prepareRequestImages(
-  options: GenerateOptions,
-  attachments: AttachmentStore,
-  model: DeepSeekCatalogModel,
-  signal: AbortSignal,
-): Promise<Map<AttachmentId, RequestImageAttachment>> {
-  const refs = new Map<AttachmentId, ImageAttachmentRef>()
-  for (const message of options.messages) collectImageRefs(message.content, refs)
-  const orderedRefs = [...refs.values()]
-  const projected = await Promise.all(orderedRefs.map(
-    ref => attachments.readImageRequest(ref, resolveRequestImageTarget(model, ref), signal),
-  ))
-  return new Map(orderedRefs.map((ref, index) => (
-    [ref.attachmentId, projected[index] as RequestImageAttachment]
-  )))
-}
-
-
-
-function providerRetryAfterMs(value: string | null): number | undefined {
-  if (value === null) return undefined
-  if (/^\d+$/.test(value)) {
-    const delay = Number(value) * 1_000
-    return Number.isFinite(delay) && delay > 0 ? delay : undefined
-  }
-  const delay = Date.parse(value) - Date.now()
-  return Number.isFinite(delay) && delay > 0 ? delay : undefined
-}
-
-function requestId(headers: Headers): ReturnType<typeof ProviderRequestId> | undefined {
-  const value = headers.get('x-request-id') ?? headers.get('x-deepseek-request-id')
-  return value === null || value.length === 0 ? undefined : ProviderRequestId(value)
-}
-
-/**
- * Map an HTTP status to a stable LlmError code.
- * @param status - status of a non-2xx provider response.
- * @param error - parsed provider error body, when available.
- * @returns the normalized harness error code.
- */
-export function httpErrorCode(status: number, error?: WireError['error']): string {
-  if (status === 401 || status === 403) return 'AUTH'
-  if (status === 413) return 'INVALID_REQUEST'
-  const detail = [error?.code, error?.type, error?.message].filter(Boolean).join(' ')
-  if (isQuotaExceededError(detail)) return QUOTA_EXCEEDED_CODE
-  if (status === 429) return 'RATE_LIMIT'
-  if (status === 400) {
-    if (isContextWindowExceededError(detail)) return CONTEXT_WINDOW_EXCEEDED_CODE
-    return 'INVALID_REQUEST'
-  }
-  if (status >= 500) return 'SERVER'
-  return `HTTP_${status}`
-}
-
-/**
- * The first real `LlmAdapter`. One instance serves every model name it was
- * registered under (the harness model name IS the wire model name).
- *
- * One stable signal reaches both initial fetch and body reads. Caller aborts
- * map to `ABORTED`; the configured per-read idle watchdog maps to `TIMEOUT`.
- */
-export class ChatCompletionsAdapter extends LlmAdapter {
-  private readonly files: DeepSeekFileStore
-
-  constructor(private readonly config: DeepSeekAdapterOptions & { resolveFiles: () => DeepSeekFileStore }) {
-    super()
-    this.files = config.resolveFiles()
-  }
-
-  override providerInfo(provider: string): LlmProviderInfo {
-    return { id: provider, name: 'DeepSeek' }
-  }
-
-  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
-    return this.config.options().retryPolicy
-  }
-
-  override imageRequestPricing(_provider: string, model: string): ReturnType<LlmAdapter['imageRequestPricing']> {
-    // The same access resolution the serializer uses, so priced handle and
-    // placeholder text matches what the request actually sends.
-    const attachments = this.config.resolveAttachments?.()
-    const resolveAccess = attachments === undefined
-      ? undefined
-      : (ref: ImageAttachmentRef): ImageAttachmentAccess | undefined => (
-        this.config.resolveImageAccess?.(attachments, ref)
-      )
-    return deepSeekImageRequestPricing(this.config.options(), model, resolveAccess)
-  }
-
-  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
-    return Promise.resolve(this.config.options().models.map(model => catalogModelInfo(provider, model)))
-  }
-
-  override resolveModel(
-    provider: string,
-    model: string,
-    _signal?: AbortSignal,
-  ): Promise<LlmResolvedModelInfo> {
-    return Promise.resolve(modelInfo(this.config.options(), provider, model))
-  }
-
-  override prepareCall(provider: string, model: string, _signal?: AbortSignal): Promise<PreparedAdapterCall> {
-    const connection = this.config.options()
-    return Promise.resolve({
-      model: modelInfo(connection, provider, model),
-      stream: options => this.streamWithConnection(options, connection),
-    })
-  }
-
-  stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    return this.streamWithConnection(options, this.config.options())
-  }
-
-  private async * streamWithConnection(
-    options: GenerateOptions,
-    connection: DeepSeekConnectionOptions,
-  ): AsyncIterable<StreamChunk> {
-    // One resolution per stream call: connection facts and the credential
-    // freeze here and hold for this whole request, so an in-flight stream
-    // never observes a configuration change and the next call re-resolves.
-    // The key resolves *from this snapshot*, so an endpoint and the secret
-    // sent to it can never come from different configuration generations.
-    const hasImages = options.messages.some(message => contentHasImage(message.content))
-    let attachments: AttachmentStore | undefined
-    if (hasImages) {
-      const model = connection.models.find(entry => entry.id === options.model)
-      if (model?.inputModalities?.includes('image') !== true) {
-        throw new LlmError(
-          `DeepSeek model "${options.model}" does not accept image input.`,
-          'UNSUPPORTED_CONTENT',
-        )
-      }
-      attachments = this.config.resolveAttachments?.()
-      if (attachments === undefined) {
-        throw new LlmError(
-          'DeepSeek image conversion requires the durable attachment service.',
-          'UNSUPPORTED_CONTENT',
-        )
-      }
-    }
-    const apiKey = await this.config.resolveApiKey(connection)
-    const userId = this.config.resolveUserId()
-    const consumer = new AbortController()
-    const upstream = options.signal === undefined
-      ? consumer.signal
-      : AbortSignal.any([options.signal, consumer.signal])
-    using watchdog = idleWatchdog(upstream, connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE)
-    const iterator = this.request(
-      options,
-      watchdog.signal,
-      connection,
-      apiKey,
-      userId,
-      attachments,
-      () => { watchdog.pulse() },
-    )[Symbol.asyncIterator]()
-    let exhausted = false
-    try {
-      while (true) {
-        const result = await watchdog.next(iterator)
-        if (result.done) {
-          exhausted = true
-          return
-        }
-        yield result.value
-      }
-    } catch (error: unknown) {
-      if (timeoutOf(watchdog.signal, STREAM_IDLE_TIMEOUT_CODE) !== undefined) {
-        throw new LlmError(
-          `DeepSeek stream idle timeout after ${connection.streamIdleTimeoutMs}ms`,
-          'TIMEOUT',
-          { cause: error },
-        )
-      }
-      if (options.signal?.aborted) {
-        throw new LlmError('DeepSeek request aborted by caller', 'ABORTED', { cause: error })
-      }
-      if (error instanceof LlmError) throw error
-      throw new LlmError(`DeepSeek API stream from ${connection.baseURL} failed`, 'TRANSPORT', { cause: error })
-    } finally {
-      consumer.abort('DeepSeek stream consumer stopped')
-      if (!exhausted && iterator.return !== undefined) {
-        try {
-          await iterator.return()
-        } catch (_abortedTransportTeardown) {
-          // The consumer controller already owns termination; a return-time abort cannot add a second outcome.
-        }
-      }
-    }
-  }
-
-  private async * request(
-    options: GenerateOptions,
-    signal: AbortSignal,
-    connection: DeepSeekConnectionOptions,
-    apiKey: string,
-    userId: AnonymousUserId,
-    attachments: AttachmentStore | undefined,
-    onActivity: () => void,
-  ): AsyncIterable<StreamChunk> {
-    const headers = {
-      'authorization': `Bearer ${apiKey}`,
-      'content-type': 'application/json',
-      'accept': 'text/event-stream',
-      ...attributionHeaders(),
-      'x-deepseek-harness-user-id': String(userId),
-      ...options.sessionId !== undefined
-        ? { 'x-deepseek-harness-session-id': String(options.sessionId) }
-        : {},
-      ...options.purpose === 'compaction'
-        ? { 'x-deepseek-harness-compact': '1' }
-        : {},
-    }
-
-    const fileConnection = { baseURL: connection.baseURL, apiKey, protocol: connection.protocol }
-    const model = connection.models.find(entry => entry.id === options.model)
-    const resolveImageAccess = attachments === undefined
-      ? undefined
-      : (ref: ImageAttachmentRef): ImageAttachmentAccess | undefined => this.config.resolveImageAccess?.(attachments, ref)
-    const imageAccessOptions = resolveImageAccess === undefined ? {} : { resolveImageAccess }
-    const requestOptions = options
-    const requestImages = attachments === undefined || model === undefined
-      ? new Map<AttachmentId, RequestImageAttachment>()
-      : await prepareRequestImages(requestOptions, attachments, model, signal)
-    let representation: 'file' | 'base64' = 'file'
-    const requestFiles = new RequestFiles(
-      this.files, fileConnection, connection.filePolicy, connection.filesApiTimeoutMs, signal, onActivity,
-    )
-    while (true) {
-      requestFiles.beginAttempt()
-      let body: WireRequest
-      if (attachments === undefined) {
-        body = serializeRequest(requestOptions, connection.defaults)
-      } else if (representation === 'base64') {
-        body = await serializeRequestWithImages(requestOptions, {
-          representation: { kind: 'base64' },
-          requestImages,
-          ...imageAccessOptions,
-          maxRequestImageBytes: connection.maxInlineRequestImageBytes,
-          maxImagesPerRequest: connection.maxImagesPerRequest,
-          byteQuantum: connection.inlineImageOffloadByteQuantum,
-          countQuantum: connection.imageOffloadCountQuantum,
-        }, connection.defaults)
-      } else {
-        try {
-          body = await serializeRequestWithImages(requestOptions, {
-            representation: {
-              kind: 'file',
-              resolveFileId: (version, _block, location) => requestFiles.resolve(version, location),
-            },
-            requestImages,
-            ...imageAccessOptions,
-            maxRequestImageBytes: connection.maxRequestFilesBytes,
-            maxImagesPerRequest: connection.maxImagesPerRequest,
-            byteQuantum: connection.imageOffloadByteQuantum,
-            countQuantum: connection.imageOffloadCountQuantum,
-          }, connection.defaults)
-        } catch (error: unknown) {
-          if (!(error instanceof FileResolutionFailure)) throw error
-          representation = 'base64'
-          continue
-        }
-      }
-      const extensions = await prepareRequestExtensions(body as unknown as Readonly<Record<string, DeepSeekLlmApiJson>>, {
-        signal,
-        ...options.sessionId === undefined ? {} : { sessionId: String(options.sessionId) },
-        ...options.purpose === undefined ? {} : { purpose: options.purpose },
-      }, this.config.prepareExtensions)
-
-      // TODO(http): adopt the Cordis HTTP service when shared transport configuration
-      // outweighs its additional runtime dependencies.
-      let response: Response
-      try {
-        response = await fetch(`${connection.baseURL}/chat/completions`, {
-          method: 'POST',
-          headers,
-          body: extensions.payload,
-          signal,
-        })
-      } catch (error: unknown) {
-        if (signal.aborted) throw error
-        throw new LlmError(
-          `DeepSeek API request to ${connection.baseURL} failed`,
-          'TRANSPORT',
-          { cause: error },
-        )
-      }
-
-      if (!response.ok) {
-        let message = `DeepSeek API error (HTTP ${response.status})`
-        let providerError: WireError['error']
-        const rawResponse = await response.text()
-        try {
-          const parsed = JSON.parse(rawResponse) as WireError
-          providerError = parsed.error
-          if (providerError?.message) message = providerError.message
-        } catch {
-          // The HTTP status remains authoritative when a gateway returns malformed JSON.
-        }
-        const detail = [providerError?.code, providerError?.type, providerError?.message]
-          .filter((field): field is string => typeof field === 'string')
-          .join(' ')
-        if (await requestFiles.retry(detail)) continue
-        message = requestFiles.errorMessage(response.status, message, detail)
-        const delay = providerRetryAfterMs(response.headers.get('retry-after'))
-        const id = requestId(response.headers)
-        throw new LlmError(message, httpErrorCode(response.status, providerError), {
-          cause: new Error(rawResponse.length > 0 ? rawResponse : `DeepSeek HTTP ${response.status}`),
-          status: response.status,
-          ...delay === undefined ? {} : { providerRetryAfterMs: delay },
-          ...id === undefined ? {} : { requestId: id },
-        })
-      }
-      await extensions.accept()
-      if (!response.body) {
-        throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')
-      }
-
-      yield* translate(parseSse(response.body, onActivity))
-      return
-    }
-  }
-}
diff --git a/packages/llm/llm-deepseek/src/protocols/chat-completions/serialize.ts b/packages/llm/llm-deepseek/src/protocols/chat-completions/serialize.ts
deleted file mode 100644
index 803e4c6877..0000000000
--- a/packages/llm/llm-deepseek/src/protocols/chat-completions/serialize.ts
+++ /dev/null
@@ -1,444 +0,0 @@
-/**
- * Serialize harness messages into DeepSeek chat completions. Text-only
- * requests retain string user content; the image path resolves durable
- * attachments into ordered file-id or inline parts. Tool-role messages map to
- * string-only `tool` wire messages; their image parts follow in one shared
- * trailing user message.
- * @module dsh-llm-deepseek/serialize
- */
-
-import { contentHasImage, IMAGE_OFFLOAD_REQUIRED_CODE, LlmError, offloadedImageText, projectOffloadedImages, requestImageHandleText, requiredImageOffload } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, GenerateOptions, ImageAttachmentAccessResolver, Message, RequestMessage } from '@deepseek-ai/dsh-llm'
-import type { ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import type {
-  WireImageContentPart,
-  WireMessage,
-  WireRequest,
-  WireTextContentPart,
-  WireTool,
-  WireUserContentPart,
-} from './types.ts'
-
-import type { RequestDefaults } from '../../common/types.ts'
-
-interface ResolvedThinking {
-  thinking?: 'enabled' | 'disabled'
-  reasoningEffort?: 'low' | 'high' | 'max'
-}
-
-/** Provider representation for every retained image in one request. */
-export type ImageRequestRepresentation =
-  | {
-    kind: 'file'
-    /** Resolve a retained request version to a reusable DeepSeek file id. */
-    resolveFileId: (
-      version: RequestImageAttachment,
-      block: Extract<ContentBlock, { type: 'image' }>,
-      location: ImageWireLocation,
-    ) => Promise<string>
-  }
-  | { kind: 'base64' }
-
-/** Dependencies required only when the request contains image input. */
-export interface ImageSerializationOptions {
-  /** One representation used for every retained image in this request. */
-  representation: ImageRequestRepresentation
-  /** Request versions prepared for the conservatively retained normalized attachments, keyed by attachment id. */
-  requestImages: ReadonlyMap<ImageAttachmentRef['attachmentId'], RequestImageAttachment>
-  /** Resolve current tool access independently from deterministic request-image versions. */
-  resolveImageAccess?: ImageAttachmentAccessResolver
-  /** Positive bound on accumulated represented image bytes. */
-  maxRequestImageBytes: number
-  /** Maximum represented images in one request. */
-  maxImagesPerRequest?: number
-  /** Represented-byte removal step applied after the request exceeds its byte bound. */
-  byteQuantum?: number
-  /** Image-count removal step applied after the request exceeds its count bound. */
-  countQuantum?: number
-}
-
-export type { ImageWireLocation } from '../../common/request-files.ts'
-import type { ImageWireLocation } from '../../common/request-files.ts'
-
-const TOOL_RESULT_IMAGE_TEXT = 'Attached image(s) from tool result:'
-
-/** Validate the adapter-owned effort before resolving its DeepSeek wire fields. */
-function reasoningEffort(effort: NonNullable<GenerateOptions['reasoningEffort']>): 'off' | 'low' | 'high' | 'max' {
-  if (effort === 'off' || effort === 'low' || effort === 'high' || effort === 'max') {
-    return effort as 'off' | 'low' | 'high' | 'max'
-  }
-  throw new LlmError(
-    `DeepSeek does not support reasoning effort "${effort}"`,
-    'UNSUPPORTED_REASONING_EFFORT',
-  )
-}
-
-/** Resolve one legal thinking/effort pair without exposing `off` as a wire effort. */
-function resolveThinking(options: GenerateOptions, defaults: RequestDefaults): ResolvedThinking {
-  if (options.purpose === 'session-title') return { thinking: 'disabled' }
-  const effort = options.reasoningEffort === undefined
-    ? defaults.reasoningEffort
-    : reasoningEffort(options.reasoningEffort)
-  if (defaults.thinking === 'disabled' && effort !== undefined && effort !== 'off') {
-    throw new LlmError(
-      `DeepSeek deployment does not support reasoning effort "${effort}"`,
-      'UNSUPPORTED_REASONING_EFFORT',
-    )
-  }
-  if (effort === 'off') return { thinking: 'disabled' }
-  if (effort === 'low' || effort === 'high' || effort === 'max') {
-    return { thinking: 'enabled', reasoningEffort: effort }
-  }
-  return defaults.thinking === undefined ? {} : { thinking: defaults.thinking }
-}
-
-/** Join the text blocks of a message (used for user and tool-role content). */
-function flattenText(blocks: readonly ContentBlock[]): string {
-  return blocks
-    .filter(block => block.type === 'text')
-    .map(block => block.text)
-    .join('')
-}
-
-/** Reject core image content before any text-flattening path can silently erase it. */
-function assertTextOnly(blocks: readonly ContentBlock[]): void {
-  if (contentHasImage(blocks)) {
-    throw new LlmError('The DeepSeek chat-completions adapter does not support image content.', 'UNSUPPORTED_CONTENT')
-  }
-}
-
-/** Reject developer history before text serialization or image offloading. */
-function assertSupportedRole(message: RequestMessage): void {
-  // Developer history is persisted for V4; provider serialization is intentionally deferred.
-  if (message.role === 'developer') throw new LlmError('Developer messages are not supported yet', 'UNSUPPORTED_CONTENT')
-  if (message.content.some(block => block.type === 'tool-addition' || block.type === 'tool-removal')) {
-    throw new LlmError('Tool-change blocks require developer role', 'UNSUPPORTED_CONTENT')
-  }
-}
-
-/** Reject unsupported roles, tool-change blocks, and image roles before history conversion. */
-function assertSupportedHistory(messages: readonly RequestMessage[]): void {
-  for (const message of messages) {
-    assertSupportedRole(message)
-    if (message.role !== 'user' && message.role !== 'tool' && contentHasImage(message.content)) {
-      throw new LlmError(
-        `The DeepSeek chat-completions adapter cannot represent image content in a ${message.role} message.`,
-        'UNSUPPORTED_CONTENT',
-      )
-    }
-  }
-}
-
-/** Describe the exact request preview and its model-callable coordinate system. */
-function imageHandle(
-  ref: ImageAttachmentRef,
-  version: RequestImageAttachment,
-  resolveAccess: ImageAttachmentAccessResolver | undefined,
-  precededByContent: boolean,
-): WireTextContentPart {
-  return {
-    type: 'text',
-    text: `${precededByContent ? '\n' : ''}${requestImageHandleText(ref, version, resolveAccess?.(ref))}`,
-  }
-}
-
-/** Resolve one durable image into its descriptor and transient DeepSeek image part. */
-async function imageParts(
-  block: Extract<ContentBlock, { type: 'image' }>,
-  images: ImageSerializationOptions,
-  location: ImageWireLocation,
-  precededByContent: boolean,
-): Promise<[WireTextContentPart, WireImageContentPart]> {
-  const version = images.requestImages.get(block.attachment.attachmentId)
-  if (version === undefined) {
-    throw new LlmError(
-      `DeepSeek request image ${block.attachment.attachmentId} was not prepared.`,
-      'INVALID_REQUEST',
-    )
-  }
-  const image: WireImageContentPart = images.representation.kind === 'file'
-    ? { type: 'file', file_id: await images.representation.resolveFileId(version, block, location) }
-    : {
-      type: 'image_url',
-      image_url: { url: `data:${version.mediaType};base64,${Buffer.from(version.data).toString('base64')}` },
-    }
-  return [imageHandle(block.attachment, version, images.resolveImageAccess, precededByContent), image]
-}
-
-/** Convert one message's content blocks into ordered wire parts. */
-async function contentParts(
-  blocks: readonly ContentBlock[],
-  images: ImageSerializationOptions,
-  message: number,
-  nextImage: { value: number },
-): Promise<WireUserContentPart[]> {
-  const parts: WireUserContentPart[] = []
-  for (const block of blocks) {
-    switch (block.type) {
-      case 'text':
-        if (block.text.length > 0) parts.push({ type: 'text', text: block.text })
-        break
-      case 'image':
-        nextImage.value += 1
-        parts.push(...await imageParts(block, images, { message, image: nextImage.value }, parts.length > 0))
-        break
-      default:
-        // Other merge-extensible blocks are not DeepSeek user-input vocabulary.
-        break
-    }
-  }
-  return parts
-}
-
-/** Keep text-only user messages on the compact string wire form. */
-function userContent(parts: readonly WireUserContentPart[]): string | WireUserContentPart[] {
-  const text: string[] = []
-  for (const part of parts) {
-    if (part.type !== 'text') return [...parts]
-    text.push(part.text)
-  }
-  return text.join('')
-}
-
-/** Serialize one assistant message (text + reasoning + tool calls). */
-function serializeAssistant(message: Message): WireMessage {
-  const text = flattenText(message.content)
-  const reasoning = message.content
-    .filter(block => block.type === 'reasoning')
-    .map(block => block.text)
-    .join('')
-  const toolCalls = message.content
-    .filter(block => block.type === 'tool-call')
-    .map(block => ({
-      id: block.id,
-      type: 'function' as const,
-      function: { name: block.name, arguments: block.arguments },
-    }))
-
-  return {
-    role: 'assistant',
-    // Text-less turns send "" — NEVER null. Pure tool-call turns: the
-    // official samples replay message.content verbatim (which is "") and
-    // some gateways reject null outright. Reasoning-ONLY turns (the model
-    // can answer entirely in the reasoning channel, e.g. a v4-flash
-    // greeting): the live API rejects null-content/no-tool_calls assistant
-    // messages with a 400 ("content or tool_calls must be set"), and since
-    // the message sits durably in the session log, a null here bricks every
-    // later turn of that session.
-    content: text,
-    // CoT passback on every reasoning-carrying turn. The official rule
-    // (guides/thinking_mode.mdx) requires it on tool-call turns and ignores it
-    // elsewhere; a gateway re-encoding the conversation for another vendor
-    // recovers that turn's upstream thinking signature by hashing this exact
-    // text, which a tool-call-free turn carries nowhere else.
-    ...reasoning.length > 0 ? { reasoning_content: reasoning } : {},
-    ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {},
-  }
-}
-
-/**
- * Serialize the conversation. Tool-role messages map one-to-one onto
- * `{role: 'tool'}` wire messages; user messages contribute their text as a
- * plain `{role: 'user'}` wire message.
- * @param messages - the harness conversation, in order.
- * @returns the wire messages; order preserved.
- */
-export function serializeMessages(messages: RequestMessage[]): WireMessage[] {
-  const wire: WireMessage[] = []
-  for (const message of messages) {
-    assertSupportedRole(message)
-    assertTextOnly(message.content)
-    if (message.role === 'system') {
-      wire.push({ role: 'system', content: flattenText(message.content) })
-      continue
-    }
-    if (message.role === 'assistant') {
-      wire.push(serializeAssistant(message))
-      continue
-    }
-    if (message.role === 'tool') {
-      wire.push({
-        role: 'tool',
-        tool_call_id: message.toolCallId,
-        // Empty tool output still needs SOME content on the wire.
-        content: flattenText(message.content) || '(no output)',
-      })
-      continue
-    }
-    // User text always lands on the wire, including empty ones.
-    wire.push({ role: 'user', content: flattenText(message.content) })
-  }
-  return wire
-}
-
-/**
- * Serialize image-capable history after resolving durable attachments.
- * Consecutive tool messages keep string `tool` wire messages and share one
- * following user message containing their images.
- * @param messages - request history whose offloaded occurrences are already placeholder text.
- * @param images - prepared request versions, one provider representation, and its budget.
- * @returns ordered DeepSeek wire messages.
- */
-export async function serializeMessagesWithImages(
-  messages: readonly RequestMessage[],
-  images: ImageSerializationOptions,
-): Promise<WireMessage[]> {
-  assertSupportedHistory(messages)
-  const wire: WireMessage[] = []
-  let pendingToolImages: WireImageContentPart[] = []
-  const flushToolImages = (): void => {
-    if (pendingToolImages.length === 0) return
-    wire.push({
-      role: 'user',
-      content: [{ type: 'text', text: TOOL_RESULT_IMAGE_TEXT }, ...pendingToolImages],
-    })
-    pendingToolImages = []
-  }
-
-  for (const [messageIndex, message] of messages.entries()) {
-    const nextImage = { value: 0 }
-    if (message.role === 'system') {
-      flushToolImages()
-      wire.push({ role: 'system', content: flattenText(message.content) })
-      continue
-    }
-    if (message.role === 'assistant') {
-      flushToolImages()
-      wire.push(serializeAssistant(message))
-      continue
-    }
-    if (message.role === 'tool') {
-      const parts = await contentParts(message.content, images, messageIndex + 1, nextImage)
-      const imageParts = parts.filter((part): part is WireImageContentPart => part.type !== 'text')
-      const text = parts.filter(part => part.type === 'text').map(part => part.text).join('')
-      wire.push({
-        role: 'tool',
-        tool_call_id: message.toolCallId,
-        content: text || '(no output)',
-      })
-      pendingToolImages.push(...imageParts)
-      continue
-    }
-    // User text serializes as a user message, including empty content. This
-    // keeps the image-capable route aligned with the text-only route.
-    const content = userContent(await contentParts(message.content, images, messageIndex + 1, nextImage))
-    flushToolImages()
-    wire.push({ role: 'user', content })
-  }
-  flushToolImages()
-  return wire
-}
-
-/** Assemble request fields shared by text-only and image-capable conversion. */
-function requestWithMessages(
-  options: GenerateOptions,
-  messages: WireMessage[],
-  defaults: RequestDefaults,
-): WireRequest {
-  // Deferred definitions are persisted for V4; provider loading is intentionally deferred.
-  if (options.tools?.some(tool => tool.deferLoading === true)) {
-    throw new LlmError('Deferred tool loading is not supported yet', 'UNSUPPORTED_CONTENT')
-  }
-  const tools: WireTool[] | undefined = options.tools?.map(tool => ({
-    type: 'function',
-    function: {
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.parameters,
-    },
-  }))
-  const resolvedThinking = resolveThinking(options, defaults)
-  return {
-    model: options.model,
-    messages,
-    stream: true,
-    stream_options: { include_usage: true },
-    ...resolvedThinking.thinking !== undefined ? { thinking: { type: resolvedThinking.thinking } } : {},
-    ...resolvedThinking.reasoningEffort !== undefined
-      ? { reasoning_effort: resolvedThinking.reasoningEffort }
-      : {},
-    ...tools !== undefined && tools.length > 0 ? { tools } : {},
-    ...options.temperature !== undefined ? { temperature: options.temperature } : {},
-    ...options.maxTokens === undefined ? {} : { max_tokens: options.maxTokens },
-    ...options.stop !== undefined ? { stop: options.stop } : {},
-  }
-}
-
-/**
- * Build the full wire request. Always streaming (`stream: true`, usage
- * reporting on); optional fields are omitted rather than sent as null, so
- * provider defaults apply.
- * @param options - the harness request (model, history, system, tools, sampling).
- * @param defaults - adapter-level thinking defaults; undefined fields put nothing on the wire.
- * @returns the chat-completions request body.
- */
-export function serializeRequest(
-  options: GenerateOptions,
-  defaults: RequestDefaults = {},
-): WireRequest {
-  const messages: WireMessage[] = []
-  if (options.system !== undefined) {
-    messages.push({ role: 'system', content: options.system })
-  }
-  messages.push(...serializeMessages(options.messages))
-
-  return requestWithMessages(options, messages, defaults)
-}
-
-/**
- * Reject a request whose retained occurrences, at their exact request-version
- * byte lengths under this representation, still exceed the route budget. The
- * failure names how many more oldest retained occurrences need durable
- * omission before the request can be retried.
- */
-function assertRetainedImagesFit(messages: readonly RequestMessage[], images: ImageSerializationOptions): void {
-  const representation = images.representation.kind === 'file' ? 'raw' : 'base64'
-  const offloadImages = requiredImageOffload(messages, {
-    representation,
-    maxBytes: images.maxRequestImageBytes,
-    ...images.maxImagesPerRequest === undefined ? {} : { maxImages: images.maxImagesPerRequest },
-    ...images.byteQuantum === undefined ? {} : { byteQuantum: images.byteQuantum },
-    ...images.countQuantum === undefined ? {} : { countQuantum: images.countQuantum },
-  }, (block) => {
-    const version = images.requestImages.get(block.attachment.attachmentId)
-    if (version === undefined) {
-      throw new LlmError(`DeepSeek request image ${block.attachment.attachmentId} was not prepared.`, 'INVALID_REQUEST')
-    }
-    return version.bytes
-  })
-  if (offloadImages > 0) {
-    throw new LlmError(
-      `DeepSeek ${representation} request images exceed the route budget; ${offloadImages} more oldest occurrence(s) must be offloaded.`,
-      IMAGE_OFFLOAD_REQUIRED_CODE,
-      { offloadImages },
-    )
-  }
-}
-
-/**
- * Build one image-capable request while keeping durable bytes out of session
- * messages. Offloaded occurrences become per-image text; retained occurrences
- * must fit the route budget at their exact request-version byte lengths.
- * @param options - harness request containing image-capable user content.
- * @param images - request versions, optional current access resolver, and request bounds.
- * @param defaults - adapter-level thinking defaults.
- * @returns the fully materialized DeepSeek request body.
- */
-export async function serializeRequestWithImages(
-  options: GenerateOptions,
-  images: ImageSerializationOptions,
-  defaults: RequestDefaults = {},
-): Promise<WireRequest> {
-  assertSupportedHistory(options.messages)
-  assertRetainedImagesFit(options.messages, images)
-  const requestMessages = projectOffloadedImages(
-    options.messages,
-    ref => offloadedImageText(ref, images.resolveImageAccess?.(ref)),
-  )
-  const messages: WireMessage[] = []
-  if (options.system !== undefined) {
-    messages.push({ role: 'system', content: options.system })
-  }
-  messages.push(...await serializeMessagesWithImages(requestMessages, images))
-  return requestWithMessages(options, messages, defaults)
-}
diff --git a/packages/llm/llm-deepseek/src/protocols/chat-completions/sse.ts b/packages/llm/llm-deepseek/src/protocols/chat-completions/sse.ts
deleted file mode 100644
index 9126a18940..0000000000
--- a/packages/llm/llm-deepseek/src/protocols/chat-completions/sse.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-/**
- * Decode an SSE byte stream into event `data` payloads. Framing — chunk
- * reassembly, UTF-8/CRLF/BOM handling, comment and non-data field skipping,
- * multi-`data:` joining — is `eventsource-parser`'s. Comments are reported
- * only through an optional transport-activity callback. This module keeps the
- * DeepSeek protocol: the literal `[DONE]` is yielded so the caller owns final
- * flushing, and EOF before it raises {@link LlmError}. Framing is spec-strict:
- * an event dispatches only on its blank-line terminator, so an unterminated
- * tail at EOF is truncation, not a flushable payload.
- *
- * @module dsh-llm-deepseek/sse
- */
-
-import { EventSourceParserStream } from 'eventsource-parser/stream'
-import { LlmError } from '@deepseek-ai/dsh-llm'
-
-/** The terminal payload DeepSeek (and OpenAI) send after the last chunk. */
-export const DONE = '[DONE]'
-
-/**
- * Parse an SSE byte stream into data payloads. Yields `[DONE]` as the final
- * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
- * without it (truncated response — the model call cannot be trusted).
- * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
- * @param onComment - optional transport-activity callback; comments never enter the yielded payload stream.
- * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
- */
-export async function* parseSse(
-  stream: ReadableStream<BufferSource>,
-  onComment?: (comment: string) => void,
-): AsyncGenerator<string> {
-  const events = stream
-    .pipeThrough(new TextDecoderStream())
-    .pipeThrough(new EventSourceParserStream({ onComment }))
-  for await (const { data } of events) {
-    yield data
-    if (data === DONE) return
-  }
-  throw new LlmError('SSE stream ended without [DONE]', 'STREAM_CLOSED')
-}
diff --git a/packages/llm/llm-deepseek/src/protocols/chat-completions/translate.ts b/packages/llm/llm-deepseek/src/protocols/chat-completions/translate.ts
deleted file mode 100644
index 8dd939e547..0000000000
--- a/packages/llm/llm-deepseek/src/protocols/chat-completions/translate.ts
+++ /dev/null
@@ -1,210 +0,0 @@
-/**
- * Translate DeepSeek SSE payloads with one stateful harness block per content, reasoning, or tool
- * call index. An empty initial reasoning delta does not open a block. Finish reason and the latest
- * usage are deferred until `[DONE]`, covering both finish-attached and trailing usage-only shapes
- * while ensuring no chunk follows `finish`.
- *
- * Translate DeepSeek wire chunks into the harness `StreamChunk` protocol.
- * @module dsh-llm-deepseek/translate
- */
-
-import { brandString } from '@deepseek-ai/dsh-brand'
-import { EMPTY_RESPONSE_CODE, LlmError } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, FinishReason, StreamChunk, TokenUsage, ToolCallId } from '@deepseek-ai/dsh-llm'
-import { DONE } from './sse.ts'
-import type { WireChunk, WireUsage } from './types.ts'
-
-/** One open block under assembly. */
-interface OpenBlock {
-  index: number
-  kind: 'text' | 'reasoning' | 'tool-call'
-  text: string
-  /** tool-call only, absent until a delta carries a non-empty value. */
-  callId?: string | undefined
-  name?: string | undefined
-}
-
-/**
- * Map the wire finish_reason vocabulary to the harness FinishReason.
- * @param reason - the wire `finish_reason` string.
- * @returns the mapped reason; unrecognized values (content_filter, …) become `{kind: 'error'}` with the uppercased value as `code`.
- */
-export function mapFinishReason(reason: string): FinishReason {
-  switch (reason) {
-    case 'stop': return { kind: 'stop' }
-    case 'tool_calls': return { kind: 'tool-calls' }
-    case 'length': return { kind: 'max-tokens' }
-    default:
-      // content_filter, insufficient_system_resource, future additions.
-      return {
-        kind: 'error',
-        failure: { message: `model stopped: ${reason}`, code: reason.toUpperCase() },
-      }
-  }
-}
-
-/**
- * Map wire usage fields. DeepSeek's `prompt_tokens` INCLUDES cache hits
- * (`prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens`,
- * api/create-chat-completion); the harness TokenUsage convention is
- * DISJOINT counts, so cache reads are subtracted out of `inputTokens`.
- * @param usage - wire usage from the finish chunk or the trailing usage-only chunk.
- * @returns disjoint harness counts; an exact total is present only when the
- *   aggregate prompt/completion counters are valid and agree with any wire total.
- */
-export function mapUsage(usage: WireUsage): TokenUsage {
-  const cacheRead = usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens
-  const reasoning = usage.completion_tokens_details?.reasoning_tokens
-  const combined = usage.prompt_tokens + usage.completion_tokens
-  const hasExactTotal = Number.isSafeInteger(usage.prompt_tokens)
-    && usage.prompt_tokens >= 0
-    && Number.isSafeInteger(usage.completion_tokens)
-    && usage.completion_tokens >= 0
-    && Number.isSafeInteger(combined)
-    && (usage.total_tokens === undefined || usage.total_tokens === combined)
-  return {
-    inputTokens: usage.prompt_tokens - (cacheRead ?? 0),
-    outputTokens: usage.completion_tokens,
-    ...hasExactTotal ? { totalTokens: combined } : {},
-    ...cacheRead !== undefined ? { cacheReadTokens: cacheRead } : {},
-    ...reasoning !== undefined ? { reasoningTokens: reasoning } : {},
-  }
-}
-
-/**
- * Accept one streamed identity field for a tool call. `id` and `name` are
- * identity, not accumulation: the wire sends each once, on the call's first
- * delta. A continuation delta that re-sends the field empty — or `null`, which
- * some OpenAI-compatible gateways fill in — means "no update", never "clear".
- * @param current - the identity established by an earlier delta of this call.
- * @param incoming - the field as parsed from this delta. The wire type is a
- *   claim about a remote encoder, so anything but a non-empty string leaves the
- *   established value alone rather than overwriting it.
- * @returns the identity in force after this delta.
- */
-function acceptIdentity(current: string | undefined, incoming: unknown): string | undefined {
-  return typeof incoming === 'string' && incoming.length > 0 ? incoming : current
-}
-
-/** Assemble the final ContentBlock for one open block. */
-function closeBlock(block: OpenBlock): ContentBlock {
-  switch (block.kind) {
-    case 'text': return { type: 'text', text: block.text }
-    case 'reasoning': return { type: 'reasoning', text: block.text }
-    case 'tool-call': return {
-      type: 'tool-call',
-      id: brandString<ToolCallId>(block.callId ?? ''),
-      name: block.name ?? '',
-      arguments: block.text,
-    }
-  }
-}
-
-/**
- * Consume SSE data payloads (ending with `[DONE]`) and yield StreamChunks.
- * Malformed JSON payloads abort the stream with `MALFORMED_RESPONSE`.
- * @param payloads - SSE data payloads from {@link parseSse}, `[DONE]`-terminated.
- * @returns deltas as they arrive; `block-end`s, `usage`, and `finish` are all deferred to the `[DONE]` sentinel.
- *   A `stop` (or absent) finish with no opened blocks is a degenerate provider completion and maps to an
- *   `EMPTY_RESPONSE` error finish instead of a successful empty message.
- */
-export async function* translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk> {
-  let nextIndex = 0
-  let textBlock: OpenBlock | undefined
-  let reasoningBlock: OpenBlock | undefined
-  const toolBlocks = new Map<number, OpenBlock>()
-  const order: OpenBlock[] = []
-  let pendingFinish: FinishReason | undefined
-  let pendingUsage: TokenUsage | undefined
-
-  function open(kind: OpenBlock['kind']): OpenBlock {
-    const block: OpenBlock = { index: nextIndex++, kind, text: '' }
-    order.push(block)
-    return block
-  }
-
-  for await (const payload of payloads) {
-    if (payload === DONE) {
-      for (const block of order) {
-        yield { type: 'block-end', index: block.index, block: closeBlock(block) }
-      }
-      if (pendingUsage) yield { type: 'usage', usage: pendingUsage }
-      const reason = pendingFinish ?? { kind: 'stop' as const }
-      yield {
-        type: 'finish',
-        reason: reason.kind === 'stop' && order.length === 0
-          ? {
-            kind: 'error',
-            failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE },
-          }
-          : reason,
-      }
-      return
-    }
-
-    let chunk: WireChunk
-    try {
-      chunk = JSON.parse(payload) as WireChunk
-    } catch {
-      throw new LlmError(`malformed SSE payload: ${payload.slice(0, 120)}`, 'MALFORMED_RESPONSE')
-    }
-
-    for (const choice of chunk.choices ?? []) {
-      const delta = choice.delta
-
-      // Reasoning first: thinking mode interleaves it before text. The
-      // empty-string first chunk must not open a block.
-      const reasoning = delta?.reasoning_content
-      if (typeof reasoning === 'string' && reasoning.length > 0) {
-        if (!reasoningBlock) {
-          reasoningBlock = open('reasoning')
-          yield { type: 'block-start', index: reasoningBlock.index, blockType: 'reasoning' }
-        }
-        reasoningBlock.text += reasoning
-        yield { type: 'reasoning-delta', index: reasoningBlock.index, text: reasoning }
-      }
-
-      const content = delta?.content
-      if (typeof content === 'string' && content.length > 0) {
-        if (!textBlock) {
-          textBlock = open('text')
-          yield { type: 'block-start', index: textBlock.index, blockType: 'text' }
-        }
-        textBlock.text += content
-        yield { type: 'text-delta', index: textBlock.index, text: content }
-      }
-
-      for (const call of delta?.tool_calls ?? []) {
-        let block = toolBlocks.get(call.index)
-        if (!block) {
-          block = open('tool-call')
-          toolBlocks.set(call.index, block)
-          yield { type: 'block-start', index: block.index, blockType: 'tool-call' }
-        }
-        block.callId = acceptIdentity(block.callId, call.id)
-        block.name = acceptIdentity(block.name, call.function?.name)
-        const fragment = call.function?.arguments ?? ''
-        block.text += fragment
-        yield {
-          type: 'tool-call-delta',
-          index: block.index,
-          id: brandString<ToolCallId>(block.callId ?? ''),
-          ...block.name !== undefined ? { name: block.name } : {},
-          argumentsDelta: fragment,
-        }
-      }
-
-      if (typeof choice.finish_reason === 'string') {
-        pendingFinish = mapFinishReason(choice.finish_reason)
-      }
-    }
-
-    // Usage may arrive attached to the finish chunk or as a trailing
-    // usage-only chunk — keep the latest.
-    if (chunk.usage) pendingUsage = mapUsage(chunk.usage)
-  }
-
-  // parseSse guarantees the [DONE] sentinel (or throws); reaching here means
-  // the payload source violated that contract.
-  throw new LlmError('SSE payload stream ended without [DONE]', 'STREAM_CLOSED')
-}
diff --git a/packages/llm/llm-deepseek/src/protocols/chat-completions/types.ts b/packages/llm/llm-deepseek/src/protocols/chat-completions/types.ts
deleted file mode 100644
index 38e73ed39e..0000000000
--- a/packages/llm/llm-deepseek/src/protocols/chat-completions/types.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-/**
- * DeepSeek chat-completions wire format (OpenAI-compatible). Types only.
- *
- * Source of truth: the official API docs at
- * `~/repos/deepsuite-docs/apps/docs/docs` (api/create-chat-completion,
- * guides/thinking_mode.mdx, guides/tool_calls.md), cross-checked against
- * live streams from the internal endpoint (2026-06).
- *
- * @module dsh-llm-deepseek/types
- */
-
-/** Request body for `POST {baseURL}/chat/completions`. */
-export interface WireRequest {
-  model: string
-  messages: WireMessage[]
-  stream: true
-  stream_options: { include_usage: true }
-  /** Thinking-mode toggle (top level, NOT inside extra_body on the wire). */
-  thinking?: { type: 'enabled' | 'disabled' }
-  /** Thinking effort (official levels). */
-  reasoning_effort?: 'low' | 'high' | 'max'
-  tools?: WireTool[]
-  temperature?: number
-  max_tokens?: number
-  /**
-   * Stop sequences (OpenAI `stop`): generation halts as soon as the model
-   * produces any one of these strings. Mapped from `GenerateOptions.stop`.
-   */
-  stop?: string[]
-}
-
-/** System-role message: a single string of instructions. */
-export interface WireSystemMessage {
-  role: 'system'
-  content: string
-}
-
-/** Text part inside a multimodal user message. */
-export interface WireTextContentPart {
-  type: 'text'
-  text: string
-}
-
-/** Files API reference inside a multimodal user message. */
-export interface WireFileContentPart {
-  type: 'file'
-  file_id: string
-}
-
-/** Inline base64 data URL inside a multimodal user message. */
-export interface WireImageUrlContentPart {
-  type: 'image_url'
-  image_url: { url: string }
-}
-
-/** One image representation accepted by a multimodal user message. */
-export type WireImageContentPart = WireFileContentPart | WireImageUrlContentPart
-
-/** Ordered input part accepted by a multimodal user message. */
-export type WireUserContentPart = WireTextContentPart | WireImageContentPart
-
-/** User-role message: text-only string or ordered multimodal input. */
-export interface WireUserMessage {
-  role: 'user'
-  content: string | WireUserContentPart[]
-}
-
-/** Tool-role message: the result of one tool call, keyed by its call id. */
-export interface WireToolMessage {
-  role: 'tool'
-  tool_call_id: string
-  content: string
-}
-
-/** One entry of the request `messages` array, discriminated on `role`. */
-export type WireMessage =
-  | WireSystemMessage
-  | WireUserMessage
-  | WireAssistantMessage
-  | WireToolMessage
-
-/**
- * Assistant-role history message. The harness replays `content: ""` (never
- * null) on tool-call-only turns — some gateways reject null — and sends null
- * only when the turn carried neither text nor tool calls.
- */
-export interface WireAssistantMessage {
-  role: 'assistant'
-  content: string | null
-  /**
-   * CoT passback, present on every turn whose assistant content carried
-   * reasoning. REQUIRED on tool-call turns in thinking mode (see
-   * guides/thinking_mode.mdx § Tool Calls); DeepSeek ignores it elsewhere,
-   * while a gateway re-encoding for another vendor recovers that turn's
-   * thinking signature by hashing it.
-   */
-  reasoning_content?: string
-  tool_calls?: WireToolCall[]
-}
-
-/** A completed tool call replayed on an assistant history message; `arguments` is the raw JSON string. */
-export interface WireToolCall {
-  id: string
-  type: 'function'
-  function: { name: string; arguments: string }
-}
-
-/** One entry of the request `tools` array; `parameters` is a JSON Schema object. */
-export interface WireTool {
-  type: 'function'
-  function: {
-    name: string
-    description: string
-    parameters: Record<string, unknown>
-  }
-}
-
-/** One parsed SSE `data:` payload (a chat.completion.chunk). */
-export interface WireChunk {
-  choices?: WireChoice[]
-  /** Arrives attached to the finish chunk and/or as a trailing usage-only chunk. */
-  usage?: WireUsage | null
-}
-
-/** One streamed choice (requests always ask for a single one); `finish_reason` is non-null only on its terminal chunk. */
-export interface WireChoice {
-  delta?: WireDelta
-  finish_reason?: string | null
-}
-
-/** The incremental content of one streamed choice; any subset of fields may be present per chunk. */
-export interface WireDelta {
-  role?: string
-  /** Visible text. Null/empty on reasoning/tool-call chunks. */
-  content?: string | null
-  /**
-   * Thinking-mode CoT. The FIRST chunk carries an empty string (must not
-   * open a reasoning block); absent entirely in non-thinking mode.
-   */
-  reasoning_content?: string | null
-  tool_calls?: WireToolCallDelta[]
-}
-
-/** A streamed fragment of one tool call; fragments sharing an `index` concatenate into one call. */
-export interface WireToolCallDelta {
-  /** Disambiguates parallel tool calls; stable across a call's deltas. */
-  index: number
-  /**
-   * Carried by the first delta of each call. Gateways observed in the wild
-   * repeat it on continuation deltas as `''` or `null`; both mean "unchanged".
-   */
-  id?: string | null
-  type?: 'function'
-  function?: {
-    /** Carried by the first delta of each call, with the same `''`/`null` repetition as {@link WireToolCallDelta.id}. */
-    name?: string | null
-    /** Argument JSON fragment (concatenate across deltas). */
-    arguments?: string | null
-  }
-}
-
-/**
- * Wire token accounting. `prompt_tokens` INCLUDES cache hits (it equals
- * `prompt_cache_hit_tokens + prompt_cache_miss_tokens`); `mapUsage` subtracts
- * them to keep the harness convention of disjoint counts.
- * `prompt_tokens_details.cached_tokens` is the OpenAI-compat spelling of the
- * hit count.
- */
-export interface WireUsage {
-  prompt_tokens: number
-  completion_tokens: number
-  /** Provider-reported aggregate across prompt and completion tokens. */
-  total_tokens?: number
-  prompt_cache_hit_tokens?: number
-  prompt_cache_miss_tokens?: number
-  prompt_tokens_details?: { cached_tokens?: number }
-  completion_tokens_details?: { reasoning_tokens?: number }
-}
-
-/** Non-2xx error body. */
-export interface WireError {
-  error?: { message?: string; type?: string; code?: string }
-}
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/adapter.ts b/packages/llm/llm-deepseek/src/protocols/messages/adapter.ts
deleted file mode 100644
index e5304b8380..0000000000
--- a/packages/llm/llm-deepseek/src/protocols/messages/adapter.ts
+++ /dev/null
@@ -1,152 +0,0 @@
-/** Direct Messages transport with one cancellable lifecycle per model request. */
-
-import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, ImageAttachmentAccessResolver, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm'
-import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
-import type { DeepSeekLlmApiJson } from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import { catalogModelInfo, modelInfo } from '../../common/model-info.ts'
-import type { DeepSeekAdapterOptions, DeepSeekConnectionOptions as Connection } from '../../common/types.ts'
-import type { DeepSeekFileStore } from '../../common/file-store.ts'
-import { MESSAGES_FILES_BETA, messagesApiRoot } from '../../common/messages-api.ts'
-import { FileResolutionFailure, RequestFiles } from '../../common/request-files.ts'
-import { prepareRequestExtensions } from '../../common/request-extensions.ts'
-import { imagePricing, inlineImages, prepareFileIds, prepareImages } from './images.ts'
-import { serialize } from './serialize.ts'
-import { parseSse } from './sse.ts'
-import { translate } from './translate.ts'
-import { providerError, providerErrorDetail } from './transport.ts'
-
-/** Request-local dependencies supplied by the owning Cordis plugin. */
-export interface AdapterDependencies {
-  /** Resolve a single validated configuration generation. */
-  connection(): Connection
-  /** Resolve the key named by that same generation. */
-  apiKey(connection: Connection): Promise<string>
-  /** Stable anonymous Harness identity. */
-  userId(): string
-  /** Current attachment service; absence is valid for text requests. */
-  attachments(): AttachmentStore | undefined
-  /** Current execution-world attachment path. */
-  imageAccess: ImageAttachmentAccessResolver
-  /** Process-wide Files upload reuse and recovery. */
-  files(): DeepSeekFileStore
-  /** Prepare plugin-contributed fields for this exact HTTP request. */
-  prepareExtensions: DeepSeekAdapterOptions['prepareExtensions']
-  /** Report discarded replay metadata without exposing durable content or signatures. */
-  onReplayDegrade?: (detail: { provider: string; model: string; reason: string }) => void
-}
-
-/** DeepSeek provider using Messages content and native thinking replay. */
-export class DeepSeekMessagesAdapter extends LlmAdapter {
-  constructor(private readonly dependencies: AdapterDependencies) { super() }
-
-  override providerInfo(provider: string) { return { id: provider, name: 'DeepSeek' } }
-  override providerRetryPolicy(_provider: string) { return this.dependencies.connection().retryPolicy }
-  override listModels(provider: string) {
-    const connection = this.dependencies.connection()
-    return Promise.resolve(connection.models.map(model => catalogModelInfo(provider, model)))
-  }
-  override resolveModel(provider: string, model: string) {
-    return Promise.resolve(modelInfo(this.dependencies.connection(), provider, model))
-  }
-  override imageRequestPricing(_provider: string, model: string) {
-    return imagePricing(this.dependencies.connection(), model, this.dependencies.imageAccess)
-  }
-  override prepareCall(provider: string, model: string): Promise<PreparedAdapterCall> {
-    const connection = this.dependencies.connection()
-    return Promise.resolve({ model: modelInfo(connection, provider, model), stream: options => this.generate(options, connection) })
-  }
-  stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    return this.generate(options, this.dependencies.connection())
-  }
-
-  private async * generate(options: GenerateOptions, connection: Connection): AsyncGenerator<StreamChunk> {
-    const consumer = new AbortController()
-    const signal = options.signal === undefined ? consumer.signal : AbortSignal.any([consumer.signal, options.signal])
-    using watchdog = idleWatchdog(signal, connection.streamIdleTimeoutMs, 'MESSAGES_IDLE')
-    const iterator = this.request(options, connection, watchdog.signal, () => { watchdog.pulse() })
-    try {
-      while (true) {
-        const next = await watchdog.next(iterator)
-        if (next.done) return
-        yield next.value
-      }
-    } catch (error) {
-      if (timeoutOf(watchdog.signal, 'MESSAGES_IDLE') !== undefined) throw new LlmError('DeepSeek Messages stream idle timeout', 'TIMEOUT', { cause: error })
-      if (options.signal?.aborted) throw new LlmError('DeepSeek Messages request aborted', 'ABORTED', { cause: error })
-      if (error instanceof LlmError) throw error
-      throw new LlmError('DeepSeek Messages transport failed', 'TRANSPORT', { cause: error })
-    } finally {
-      consumer.abort()
-      try { await iterator.return(undefined) } catch (_abortedRequestCleanup) {
-        // The request already settled; aborting its reader cannot replace that outcome.
-      }
-    }
-  }
-
-  private async * request(
-    options: GenerateOptions, connection: Connection, signal: AbortSignal, activity: () => void,
-  ): AsyncGenerator<StreamChunk> {
-    signal.throwIfAborted()
-    const { messages, versions } = await prepareImages(
-      options.messages, connection, options.model, this.dependencies.attachments(), this.dependencies.imageAccess, signal,
-    )
-    const key = await this.dependencies.apiKey(connection)
-    const files = new RequestFiles(this.dependencies.files(), { baseURL: connection.baseURL, apiKey: key, protocol: 'messages' },
-      connection.filePolicy, connection.filesApiTimeoutMs, signal, activity)
-    let inline = false
-    while (true) {
-      signal.throwIfAborted()
-      files.beginAttempt()
-      let fileIds: Awaited<ReturnType<typeof prepareFileIds>> | undefined
-      if (!inline) {
-        try {
-          fileIds = await prepareFileIds(messages, versions, files)
-        } catch (error) {
-          if (!(error instanceof FileResolutionFailure)) throw error
-          inline = true
-          continue
-        }
-      }
-      const history = inline ? inlineImages(messages, versions, connection) : messages
-      const body = serialize(options, connection, history, versions, this.dependencies.imageAccess, (reason) => {
-        this.dependencies.onReplayDegrade?.({ provider: options.provider, model: options.model, reason })
-      }, fileIds)
-      const extensions = await prepareRequestExtensions(body as unknown as Readonly<Record<string, DeepSeekLlmApiJson>>, {
-        signal,
-        ...options.sessionId === undefined ? {} : { sessionId: String(options.sessionId) },
-        ...options.purpose === undefined ? {} : { purpose: options.purpose },
-      }, this.dependencies.prepareExtensions)
-      signal.throwIfAborted()
-      const response = await fetch(`${messagesApiRoot(connection.baseURL)}/messages`, {
-        method: 'POST', signal, body: extensions.payload, redirect: 'error',
-        headers: {
-          ...attributionHeaders(),
-          'content-type': 'application/json', 'accept': 'text/event-stream',
-          'x-api-key': key, 'anthropic-version': '2023-06-01',
-          ...fileIds === undefined || fileIds.size === 0 ? {} : { 'anthropic-beta': MESSAGES_FILES_BETA },
-          'x-deepseek-harness-user-id': this.dependencies.userId(),
-          ...options.sessionId === undefined ? {} : { 'x-deepseek-harness-session-id': String(options.sessionId) },
-          ...options.purpose === 'compaction' ? { 'x-deepseek-harness-compact': '1' } : {},
-        },
-      })
-      if (!response.ok) {
-        const text = await response.text()
-        let raw: unknown
-        try { raw = JSON.parse(text) } catch (_nonJsonGatewayError) {
-          // HTTP status is authoritative when a gateway does not return JSON.
-        }
-        const detail = providerErrorDetail(raw)
-        if (await files.retry(detail)) continue
-        const failure = providerError(raw, response.status, response.headers)
-        const message = files.errorMessage(response.status, failure.message, detail)
-        throw new LlmError(message, failure.code, { ...failure.failure, cause: new Error(text) })
-      }
-      await extensions.accept()
-      if (response.body === null) throw new LlmError('DeepSeek Messages returned no response body', 'EMPTY_RESPONSE')
-      yield* translate(parseSse(response.body, activity), options.model)
-      return
-    }
-  }
-}
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/replay.ts b/packages/llm/llm-deepseek/src/replay.ts
similarity index 93%
rename from packages/llm/llm-deepseek/src/protocols/messages/replay.ts
rename to packages/llm/llm-deepseek/src/replay.ts
index d6ff95804b..f285ebaeae 100644
--- a/packages/llm/llm-deepseek/src/protocols/messages/replay.ts
+++ b/packages/llm/llm-deepseek/src/replay.ts
@@ -56,9 +56,9 @@ function validateReplay(message: Message, model: string): ReplayBlock[] | undefi
   const blocks = envelope.blocks.map((value, index): ReplayBlock => {
     const block = object(value, 'INVALID_REPLAY_STATE')
     if (block.type !== message.content[index]?.type
-      || !['text', 'reasoning', 'tool-call'].includes(String(block.type))) return fail('block type mismatch')
+      || (block.type !== 'text' && block.type !== 'reasoning' && block.type !== 'tool-call')) return fail('block type mismatch')
     if (block.signature !== undefined && (block.type !== 'reasoning' || typeof block.signature !== 'string')) return fail('invalid signature')
-    return block as unknown as ReplayBlock
+    return { type: block.type, ...typeof block.signature === 'string' ? { signature: block.signature } : {} }
   })
   return response.model === model ? blocks : undefined
 }
diff --git a/packages/llm/llm-deepseek/src/common/request-extensions.ts b/packages/llm/llm-deepseek/src/request-extensions.ts
similarity index 87%
rename from packages/llm/llm-deepseek/src/common/request-extensions.ts
rename to packages/llm/llm-deepseek/src/request-extensions.ts
index 906e778382..e1cb10febb 100644
--- a/packages/llm/llm-deepseek/src/common/request-extensions.ts
+++ b/packages/llm/llm-deepseek/src/request-extensions.ts
@@ -5,9 +5,9 @@ import type { DeepSeekLlmApiExtensionRequest, PreparedDeepSeekLlmApiExtensions }
 import type { DeepSeekAdapterOptions } from './types.ts'
 
 /**
- * Merge contributions without replacing protocol-owned fields. Preparation and
- * acceptance failures retain the same error category across DeepSeek protocols.
- * @param body - serialized protocol request before extension fields.
+ * Merge contributions without replacing Messages fields. Preparation and
+ * acceptance failures report REQUEST_EXTENSION.
+ * @param body - serialized Messages request before extension fields.
  * @param options - request identity, purpose, and cancellation.
  * @param prepare - contributor registry captured for this adapter.
  * @returns HTTP payload and a commit to invoke only after a successful HTTP response.
diff --git a/packages/llm/llm-deepseek/src/common/request-files.ts b/packages/llm/llm-deepseek/src/request-files.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/request-files.ts
rename to packages/llm/llm-deepseek/src/request-files.ts
diff --git a/packages/llm/llm-deepseek/src/common/request-pricing.ts b/packages/llm/llm-deepseek/src/request-pricing.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/request-pricing.ts
rename to packages/llm/llm-deepseek/src/request-pricing.ts
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/serialize.ts b/packages/llm/llm-deepseek/src/serialize.ts
similarity index 98%
rename from packages/llm/llm-deepseek/src/protocols/messages/serialize.ts
rename to packages/llm/llm-deepseek/src/serialize.ts
index 78448e6e51..a78767df7d 100644
--- a/packages/llm/llm-deepseek/src/protocols/messages/serialize.ts
+++ b/packages/llm/llm-deepseek/src/serialize.ts
@@ -3,10 +3,10 @@
 import { LlmError, requestImageHandleText } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, GenerateOptions, ImageAttachmentAccessResolver, Message, RequestMessage } from '@deepseek-ai/dsh-llm'
 import type { ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import type { DeepSeekConnectionOptions as Connection } from '../../common/types.ts'
-import type { DeepSeekFileId } from '../../common/file-id.ts'
+import type { DeepSeekConnectionOptions as Connection } from './types.ts'
+import type { DeepSeekFileId } from './file-id.ts'
 import { readReplay } from './replay.ts'
-import type { WireBlock, WireInput, WireMessage, WireRequest } from './types.ts'
+import type { WireBlock, WireInput, WireMessage, WireRequest } from './wire-types.ts'
 
 function unsupported(type: string): never {
   throw new LlmError(`DeepSeek Messages cannot represent ${type}`, 'UNSUPPORTED_CONTENT')
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/sse.ts b/packages/llm/llm-deepseek/src/sse.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/protocols/messages/sse.ts
rename to packages/llm/llm-deepseek/src/sse.ts
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/translate.ts b/packages/llm/llm-deepseek/src/translate.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/protocols/messages/translate.ts
rename to packages/llm/llm-deepseek/src/translate.ts
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/transport.ts b/packages/llm/llm-deepseek/src/transport.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/protocols/messages/transport.ts
rename to packages/llm/llm-deepseek/src/transport.ts
diff --git a/packages/llm/llm-deepseek/src/common/types.ts b/packages/llm/llm-deepseek/src/types.ts
similarity index 92%
rename from packages/llm/llm-deepseek/src/common/types.ts
rename to packages/llm/llm-deepseek/src/types.ts
index d1c4932317..180227f484 100644
--- a/packages/llm/llm-deepseek/src/common/types.ts
+++ b/packages/llm/llm-deepseek/src/types.ts
@@ -1,4 +1,4 @@
-/** Shared catalog and request-local dependencies for DeepSeek protocols. */
+/** Model catalog and request-local dependencies for DeepSeek Messages. */
 import type { ModelModality, SystemPromptUpdate, ResolvedRetryPolicy, ImageAttachmentAccess } from '@deepseek-ai/dsh-llm'
 import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
@@ -6,9 +6,6 @@ import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
 import type { DeepSeekLlmApiExtensionRequest, PreparedDeepSeekLlmApiExtensions } from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
 import type { DeepSeekFileStore, DeepSeekFilePolicy } from './file-store.ts'
 
-/** Supported wire implementations; Responses is not yet implemented. */
-export type DeepSeekProtocol = 'chat-completions' | 'messages'
-
 /** One optional model entry advertised by the direct-fetch adapter. */
 export interface DeepSeekCatalogModel {
   /** Wire model id accepted by the configured endpoint. */
@@ -46,9 +43,7 @@ export interface DeepSeekCatalogModel {
  * makes a configuration change reach the next request without re-registration.
  */
 export interface DeepSeekConnectionOptions {
-  /** Wire protocol selected by plugin configuration. */
-  protocol: DeepSeekProtocol
-  /** Root compatible with the selected protocol; custom paths remain unchanged. */
+  /** Messages API root; custom paths remain unchanged. */
   baseURL: string
   /**
    * Credential reference of this same resolution, resolved per request.
@@ -94,7 +89,7 @@ export interface DeepSeekAdapterOptions {
   /** Current validated connection facts; called once per operation. */
   options: () => DeepSeekConnectionOptions
   /**
-   * Resolve the bearer token for the connection facts of one request. The
+   * Resolve the API key for the connection facts of one request. The
    * snapshot is passed in — never re-read — so the key can only ever come
    * from the same resolution as the endpoint it is sent to. Throws `LlmError`
    * `MISSING_CREDENTIAL` when no key is available anywhere.
diff --git a/packages/llm/llm-deepseek/src/common/upload-index.ts b/packages/llm/llm-deepseek/src/upload-index.ts
similarity index 100%
rename from packages/llm/llm-deepseek/src/common/upload-index.ts
rename to packages/llm/llm-deepseek/src/upload-index.ts
diff --git a/packages/llm/llm-deepseek/src/protocols/messages/types.ts b/packages/llm/llm-deepseek/src/wire-types.ts
similarity index 95%
rename from packages/llm/llm-deepseek/src/protocols/messages/types.ts
rename to packages/llm/llm-deepseek/src/wire-types.ts
index 582ffc7545..c72f0c9d47 100644
--- a/packages/llm/llm-deepseek/src/protocols/messages/types.ts
+++ b/packages/llm/llm-deepseek/src/wire-types.ts
@@ -13,13 +13,13 @@ export type WireBlock = WireInput
   | { type: 'tool_result'; tool_use_id: string; content: WireInput[]; is_error?: boolean }
 
 /** Conversation turn; capable routes retain later system updates in message history. */
-export interface WireMessage {
+export type WireMessage = {
   role: 'user' | 'assistant' | 'system'
   content: WireBlock[]
 }
 
 /** JSON body submitted to the resolved Messages endpoint. */
-export interface WireRequest {
+export type WireRequest = {
   model: string
   stream: true
   max_tokens: number
diff --git a/packages/llm/llm-deepseek/tests/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
index 2a68e915cc..bffec7e6ce 100644
--- a/packages/llm/llm-deepseek/tests/adapter.e2e.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.e2e.ts
@@ -1,466 +1,282 @@
-import { readFileSync } from 'node:fs'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+/**
+ * Real Messages round trips use the official root and require credentials.
+ * System-update checks additionally require DEEPSEEK_IN_HISTORY_MODEL.
+ */
+import { randomUUID } from 'node:crypto'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { randomBytes } from 'node:crypto'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { Context } from '@deepseek-ai/cordis'
+import { createRequire } from 'node:module'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context, LoggerLevel } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
-import LlmRuntime, { createToolResultMessage, createUserMessage, ToolCallId, ReasoningEffortId, createMessage, createSystemMessage } from '@deepseek-ai/dsh-llm'
-import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
-import AttachmentStore, { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
 import LocalAttachments from '@deepseek-ai/dsh-attachment-local'
-import type {
-  ImageAttachmentLimits,
-  ImageAttachmentRef,
-  ImageRequestTarget,
-  RequestImageAttachment,
-  SaveImageAttachment,
-  StoredImageAttachment,
-} from '@deepseek-ai/dsh-attachment'
-import { LocalCredentialProvider } from '@deepseek-ai/dsh-credentials-local'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
+import LlmRuntime, { BlockAssembler, createAssistantMessage, createSystemMessage, createToolResultMessage, ReasoningEffortId, ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import * as PluginPackageInventoryDeepSeek from '@deepseek-ai/dsh-plugin-package-inventory-deepseek'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import * as SessionLogDeepSeek from '@deepseek-ai/dsh-session-log-deepseek'
-import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
-import type { Config } from '@deepseek-ai/dsh-llm-deepseek'
-import type { WireMessage, WireRequest } from '../src/protocols/chat-completions/types.ts'
-import { assemble, type AssembledResult } from './assemble.ts'
+import * as Messages from '../src/index.ts'
+import { DeepSeekFilesClient } from '../src/files-api.ts'
+import { MESSAGES_FILES_BETA } from '../src/messages-api.ts'
+import { assemble, options, user, sourceModuleLoader } from './helpers.ts'
 
-/**
- * Real-API e2e for the direct-fetch adapter: V4 Flash across thinking modes
- * and a max-effort tool round trip with reasoning passback. The suite skips
- * entirely without $DEEPSEEK_API_KEY; the pre-release vision smoke additionally
- * requires $DEEPSEEK_VISION_E2E=1, and the Flash image/system-update smoke
- * requires $DEEPSEEK_FLASH_E2E=1 (see vitest.e2e.config.ts).
- */
-
-const FLASH = 'deepseek-v4-flash'
-const VISION = 'deepseek-v4-flash-vision-exp'
-const VISION_E2E_ENABLED = process.env.DEEPSEEK_VISION_E2E === '1'
-/** A model whose endpoint reads the latest `system` message at any position; unset skips the in-history smoke. */
 const IN_HISTORY_MODEL = process.env.DEEPSEEK_IN_HISTORY_MODEL
-const TEST_PNG = Uint8Array.from(readFileSync(
-  new URL('../../llm-pi-ai/tests/fixtures/qr-code.png', import.meta.url),
-))
-const contexts: Context[] = []
-let identityHome: string
-
-class E2eAttachmentStore extends AttachmentStore {
-  readonly imageLimits: ImageAttachmentLimits = {
-    maxImageBytes: TEST_PNG.byteLength,
-    maxImagesPerMessage: 1,
-    maxMessageImageBytes: TEST_PNG.byteLength,
-    maxImagePixels: 256 * 256,
-    maxImageDimension: 256,
-    mediaTypes: ['image/png'],
-  }
-  readonly ref: ImageAttachmentRef = {
-    attachmentId: AttachmentId(`sha256:${randomBytes(32).toString('hex')}`),
-    mediaType: 'image/png',
-    bytes: TEST_PNG.byteLength,
-    width: 256,
-    height: 256,
-    name: 'files-api-e2e.png',
-  }
-  readonly version: RequestImageAttachment = {
-    variantId: ImageVariantId(`sha256:${randomBytes(32).toString('hex')}`),
-    attachment: this.ref,
-    data: TEST_PNG,
-    mediaType: 'image/png',
-    bytes: TEST_PNG.byteLength,
-    width: 256,
-    height: 256,
-    depth: 'uchar',
-    space: 'srgb',
-    hasAlpha: false,
-  }
-
-  validateImage(_input: SaveImageAttachment): Promise<void> {
-    return Promise.resolve()
-  }
-
-  saveImage(_input: SaveImageAttachment): Promise<ImageAttachmentRef> {
-    return Promise.resolve(this.ref)
-  }
-
-  readImage(ref: ImageAttachmentRef, _signal?: AbortSignal): Promise<StoredImageAttachment> {
-    return Promise.resolve({ ref, data: TEST_PNG })
-  }
-
-  override readImageRequest(
-    _ref: ImageAttachmentRef,
-    _target: ImageRequestTarget,
-    _signal?: AbortSignal,
-  ): Promise<RequestImageAttachment> {
-    return Promise.resolve(this.version)
-  }
-}
-
-beforeEach(async () => {
-  identityHome = await mkdtemp(join(tmpdir(), 'dsh-e2e-user-id-'))
-  vi.stubEnv('DSH_HOME', identityHome)
+const cleanups: (() => Promise<unknown>)[] = []
+afterEach(async () => {
+  while (cleanups.length) await cleanups.pop()!()
+  vi.unstubAllEnvs()
+  vi.unstubAllGlobals()
 })
-
-async function harness(model: string, config: Partial<Config> = {}) {
+async function boot(models?: Messages.Config['models']) {
+  const home = await mkdtemp(join(tmpdir(), 'dsh-messages-e2e-'))
+  cleanups.push(() => rm(home, { recursive: true, force: true }))
+  vi.stubEnv('DSH_HOME', home)
   const ctx = new Context()
-  contexts.push(ctx)
+  cleanups.push(() => ctx.fiber.dispose())
   await ctx.plugin(LlmRuntime)
-  await ctx.plugin(E2eAttachmentStore)
-  await ctx.plugin(LlmDeepSeek, {
-    protocol: 'chat-completions',
-    baseURL: LlmDeepSeek.PUBLIC_BASE_URL,
-    ...model === VISION ? { models: [{ id: VISION, inputModalities: ['text', 'image'] }] } : {},
-    ...config,
+  await ctx.plugin(Messages, {
+    baseURL: Messages.PUBLIC_BASE_URL,
+    maxTokens: 4096,
+    ...models === undefined ? {} : { models },
   })
   return ctx
 }
+const tool = { name: 'lookup_value', description: 'Read the requested value. Always call this tool to obtain a value.', parameters: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] } }
 
-afterEach(async () => {
-  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
-  vi.unstubAllGlobals()
-  vi.unstubAllEnvs()
-  await rm(identityHome, { recursive: true, force: true })
-})
-
-function ask(text: string): Message[] {
-  return [createUserMessage({
-    content: [{ type: 'text', text }],
-    source: { kind: 'user' },
-  })]
-}
-
-function textOf(result: AssembledResult): string {
-  return result.message.content
-    .filter(block => block.type === 'text')
-    .map(block => block.text)
-    .join('')
-}
-
-const weatherTool: ToolSchema = {
-  name: 'get_weather',
-  description: 'Get the current weather for a city.',
-  parameters: {
-    type: 'object',
-    properties: { city: { type: 'string', description: 'City name' } },
-    required: ['city'],
-  },
-}
-
-describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', () => {
-  it.skipIf(process.env.DEEPSEEK_FLASH_E2E !== '1')('deepseek-flash accepts images and retains system updates', async () => {
-    const ctx = new Context()
-    contexts.push(ctx)
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LocalAttachments)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: LlmDeepSeek.PUBLIC_BASE_URL, maxTokens: 4096 })
-    const model = 'deepseek-flash'
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', model)).resolves.toMatchObject({
-      inputModalities: ['text', 'image'], systemPromptUpdate: 'in-history',
-    })
-    const attachment = await ctx.attachments.saveImage({ data: readFileSync(new URL('fixtures/red.png', import.meta.url)), mediaType: 'image/png' })
-    const message = ask('What is the dominant color of this image?')[0]!
-    const history: Message[] = [
-      createSystemMessage('Answer with one English color word.'),
-      { ...message, content: [...message.content, { type: 'image', attachment }] },
-    ]
-    const reply = async () => {
-      const response = await assemble(ctx, { model, messages: history, reasoningEffort: ReasoningEffortId('high') })
-      expect(response.finish.kind, JSON.stringify(response.finish)).toBe('stop')
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('DeepSeek Messages real API', () => {
+  it.skipIf(!IN_HISTORY_MODEL).each([false, true])('updates system instructions during a conversation, in-history=%s', async (inHistory) => {
+    const model = IN_HISTORY_MODEL as string
+    // Each case owns the capability, even for a model with an in-history catalog default.
+    const ctx = await boot([{ id: model, ...inHistory ? { systemPromptUpdate: 'in-history' as const } : {} }])
+    const history: Message[] = [createSystemMessage('Reply to every user message with exactly PROMPT_FIRST.'), user('Answer now.')]
+    const reply = async (expected: string) => {
+      const saved = JSON.stringify(history)
+      const response = await assemble(ctx.llm.stream(options({ model, messages: history, reasoningEffort: ReasoningEffortId('high') })), model)
+      expect(response.assembler.finish.kind).toBe('stop')
+      expect(response.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain(expected)
+      expect(JSON.stringify(history)).toBe(saved)
       history.push(response.message)
-      return textOf(response).trim().toLowerCase()
     }
-    expect(await reply()).toMatch(/^red[.!]?$/)
-    history.push(createSystemMessage('Reply to every user message with exactly banana.'), ...ask('Answer now.'))
-    expect(await reply()).toBe('banana')
-    history.push(...ask('Answer again.'))
-    expect(await reply()).toBe('banana')
+    await reply('PROMPT_FIRST')
+    history.push(createSystemMessage('Reply to every user message with exactly PROMPT_SECOND.'), user('Answer again.'))
+    await reply('PROMPT_SECOND')
+    const withoutSystem = history.filter(message => message.role !== 'system')
+    history.splice(0, history.length, createSystemMessage(''), ...withoutSystem, user('Reply with exactly PROMPT_CLEARED.'))
+    await reply('PROMPT_CLEARED')
   })
 
-  it.skipIf(!VISION_E2E_ENABLED)('uses the built-in official route to upload, reference, and delete one image', async () => {
-    const key = process.env.DEEPSEEK_API_KEY
-    if (key === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
-    const baseURL = LlmDeepSeek.PUBLIC_BASE_URL
-    const ctx = await harness(VISION, { baseURL })
-    await ctx.plugin(E2eAttachmentStore)
-    const attachments = ctx.attachments as E2eAttachmentStore
-    let uploadedFile: LlmDeepSeek.DeepSeekFileIdType | undefined
-    const nativeFetch = globalThis.fetch
-    const observedFetch: typeof fetch = async (input, init) => {
-      const response = await nativeFetch(input, init)
-      const url = new URL(input instanceof Request ? input.url : input)
-      const method = init?.method ?? (input instanceof Request ? input.method : 'GET')
-      if (method === 'POST' && url.pathname.endsWith('/files') && response.ok) {
-        const value = await response.clone().json() as { id?: unknown }
-        if (typeof value.id === 'string') uploadedFile = LlmDeepSeek.DeepSeekFileId(value.id)
+  it('uploads, lists, retrieves, reuses, and replaces a deleted Files image across Messages requests', async () => {
+    const ctx = await boot()
+    await ctx.plugin(LocalAttachments)
+    const fetchImpl = globalThis.fetch
+    const uploads: string[] = []
+    const bodies: string[] = []
+    const files = new DeepSeekFilesClient({
+      baseURL: Messages.PUBLIC_BASE_URL, apiKey: process.env.DEEPSEEK_API_KEY as string, fetch: fetchImpl,
+    })
+    const ownedFiles = new Set<ReturnType<typeof Messages.DeepSeekFileId>>()
+    cleanups.push(async () => {
+      for (const id of ownedFiles) await files.delete(id)
+    })
+    vi.stubGlobal('fetch', async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      const response = await fetchImpl(input, init)
+      if (url === `${Messages.PUBLIC_BASE_URL}/v1/files` && init?.method === 'POST' && response.ok) {
+        const file = await response.clone().json() as { id: string }
+        uploads.push(file.id)
+        ownedFiles.add(Messages.DeepSeekFileId(file.id))
+      }
+      if (url === `${Messages.PUBLIC_BASE_URL}/v1/messages`) {
+        expect(new Headers(init?.headers).get('anthropic-beta')).toBe(MESSAGES_FILES_BETA)
+        if (typeof init?.body !== 'string') throw new Error('expected a JSON Messages request')
+        bodies.push(init.body)
       }
       return response
+    })
+    const attachment = await ctx.attachments.saveImage({ data: await readFile(new URL('fixtures/red.png', import.meta.url)), mediaType: 'image/png' })
+    const message = user('What is the dominant color of this image? Reply with one English color word.')
+    const request = options({
+      model: 'deepseek-flash', reasoningEffort: ReasoningEffortId('off'),
+      messages: [{ ...message, content: [...message.content, { type: 'image', attachment }] }],
+    })
+    for (let run = 0; run < 2; run++) {
+      const result = await assemble(ctx.llm.stream(request), request.model)
+      expect(result.assembler.finish.kind).toBe('stop')
+      expect(result.message.content.filter(block => block.type === 'text').map(block => block.text).join('').toLowerCase()).toContain('red')
     }
-    vi.stubGlobal('fetch', observedFetch)
-    const files = new LlmDeepSeek.DeepSeekFilesClient({ protocol: 'chat-completions', baseURL, apiKey: key })
-
-    try {
-      const result = await assemble(ctx, {
-        model: VISION,
-        messages: [createUserMessage({
-          content: [
-            { type: 'text', text: 'Briefly describe this image.' },
-            { type: 'image', attachment: attachments.ref },
-          ],
-          source: { kind: 'user' },
-        })],
-        maxTokens: 100,
-      })
-      expect(
-        result.finish.kind,
-        `DeepSeek vision result: ${JSON.stringify(result.finish)}`,
-      ).toBe('stop')
-      expect(textOf(result).trim().length).toBeGreaterThan(0)
-      expect(uploadedFile).toMatch(/^file-api-/u)
-    } finally {
-      if (uploadedFile !== undefined) await files.delete(uploadedFile)
+    expect(uploads).toHaveLength(1)
+    expect(bodies).toHaveLength(2)
+    expect(bodies.every(body => body.includes(`"file_id":"${uploads[0]}"`) && !body.includes('"type":"base64"'))).toBe(true)
+    const fileId = Messages.DeepSeekFileId(uploads[0]!)
+    const retrieved = await files.retrieve(fileId)
+    expect(retrieved).toMatchObject({ id: fileId, bytes: attachment.bytes })
+    expect(retrieved.expiresAt).toBeUndefined()
+    let page = await files.list({ limit: 1_000 })
+    const cursors = new Set<string>()
+    while (!page.data.some(file => file.id === fileId) && page.hasMore) {
+      expect(page.lastId).toBeDefined()
+      const after = page.lastId!
+      expect(cursors.has(after)).toBe(false)
+      cursors.add(after)
+      page = await files.list({ after, limit: 1_000 })
     }
+    expect(page.data).toContainEqual(retrieved)
+    await files.delete(fileId)
+    ownedFiles.delete(fileId)
+    const recovered = await assemble(ctx.llm.stream(request), request.model)
+    expect(recovered.assembler.finish.kind).toBe('stop')
+    expect(recovered.message.content.filter(block => block.type === 'text').map(block => block.text).join('').toLowerCase()).toContain('red')
+    expect(uploads).toHaveLength(2)
+    expect(uploads[1]).not.toBe(fileId)
+    expect(bodies).toHaveLength(4)
+    expect(bodies[2]).toContain(`"file_id":"${fileId}"`)
+    expect(bodies[3]).toContain(`"file_id":"${uploads[1]}"`)
+    expect(bodies[3]).not.toContain('"type":"base64"')
   })
 
-  it('accepts the session-log and plugin-package request extension fields', async () => {
-    const ctx = new Context()
-    contexts.push(ctx)
+  it.each([false, true])('submits Loader package inventory and records HTTP acceptance with session-log enabled=%s', async (enabled) => {
+    const ctx = await boot()
     await ctx.plugin(Loader)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(LlmRuntime)
     await ctx.plugin(SessionStore)
     await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
-    await ctx.plugin(SessionLogDeepSeek, { enabled: true })
-    await ctx.plugin(PluginPackageInventoryDeepSeek)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: LlmDeepSeek.PUBLIC_BASE_URL, thinking: 'disabled' })
-    const session = ctx.sessions.create(SessionId('real-extension-fields'))
+    await ctx.plugin(SessionLogDeepSeek, enabled ? {} : { enabled: false })
+    ctx.baseUrl = import.meta.url
+    // Select the source module while Loader owns its active package entry.
+    ctx.loader.internal = sourceModuleLoader(async (specifier) => {
+      if (specifier !== '@deepseek-ai/dsh-plugin-package-inventory-deepseek') throw new Error(`unexpected Loader import: ${specifier}`)
+      return PluginPackageInventoryDeepSeek
+    })
+    await ctx.loader.create({ name: '@deepseek-ai/dsh-plugin-package-inventory-deepseek' })
+    await ctx.loader.await()
+    const packagePath = createRequire(import.meta.url).resolve('@deepseek-ai/dsh-plugin-package-inventory-deepseek/package.json')
+    const packageIdentity = JSON.parse(await readFile(packagePath, 'utf8')) as { name: string; version: string }
+    const session = ctx.sessions.create(SessionId(`real-messages-extensions-${randomUUID()}`))
     session.append('turn/start', { turn: 1 })
-
-    const result = await assemble(ctx, {
-      model: FLASH,
-      messages: ask('Reply with exactly the word: pong'),
-      maxTokens: 50,
-      sessionId: session.id,
+    const fetchImpl = globalThis.fetch
+    let afterSeq: number = -1
+    let throughSeq = 0
+    let requests = 0
+    vi.stubGlobal('fetch', async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+      if (url !== `${Messages.PUBLIC_BASE_URL}/v1/messages`) return fetchImpl(input, init)
+      if (typeof init?.body !== 'string') throw new Error('expected a JSON Messages request')
+      const body = JSON.parse(init.body) as Record<string, unknown>
+      expect(body).toMatchObject({ dsh_plugin_packages: {
+        version: 1, packages: [{ name: packageIdentity.name, version: packageIdentity.version }],
+      } })
+      if (enabled) {
+        expect(body).toMatchObject({ dsh_session_log: {
+          version: 1, sessionFormatVersion: session.header.version, session: { id: session.id },
+          afterSeq, throughSeq,
+          events: Array.from({ length: throughSeq - afterSeq }, (_, index) => ({ seq: afterSeq + index + 1 })),
+        } })
+      } else expect(body).not.toHaveProperty('dsh_session_log')
+      expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(afterSeq)
+      const response = await fetchImpl(input, init)
+      expect(response.ok).toBe(true)
+      expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(afterSeq)
+      requests += 1
+      return response
     })
-    expect(result.finish.kind).toBe('stop')
-    expect(textOf(result).toLowerCase()).toContain('pong')
-    expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(0)
-  })
-
-  it('serves a real request with the key held only by a credentials-local document', async () => {
-    const key = process.env.DEEPSEEK_API_KEY
-    if (key === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
-    const dir = await mkdtemp(join(tmpdir(), 'dsh-e2e-credentials-'))
-    try {
-      // JSON.stringify quotes the value: YAML is a JSON superset, so a real
-      // key survives whatever characters it happens to carry.
-      await writeFile(join(dir, '.credentials.yaml'), `version: 1\nrefs:\n  DEEPSEEK_API_KEY: ${JSON.stringify(key)}\n`, { mode: 0o600 })
-      // Scrub the ambient variable so only the credential seam can supply the
-      // key: this request proves the per-request resolution path end to end.
-      vi.stubEnv('DEEPSEEK_API_KEY', '')
-      const ctx = new Context()
-      contexts.push(ctx)
-      await ctx.plugin(LlmRuntime)
-      await ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
-      await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: LlmDeepSeek.PUBLIC_BASE_URL })
-
-      const result = await assemble(ctx, {
-        model: FLASH,
-        messages: ask('Reply with exactly the word: pong'),
-        maxTokens: 50,
-      })
-      expect(result.finish.kind).toBe('stop')
-      expect(textOf(result).toLowerCase()).toContain('pong')
-    } finally {
-      vi.unstubAllEnvs()
-      await rm(dir, { recursive: true, force: true })
-    }
-  })
-
-  it('flash dynamically switches from off to low', async () => {
-    const ctx = await harness(FLASH, { reasoningEffort: 'off' })
-    const withoutThinking = await assemble(ctx,{
-      model: FLASH,
-      messages: ask('Reply with exactly the word: pong'),
-      maxTokens: 50,
-    })
-    expect(withoutThinking.finish.kind).toBe('stop')
-    expect(textOf(withoutThinking).toLowerCase()).toContain('pong')
-    expect(withoutThinking.message.content.some(block => block.type === 'reasoning')).toBe(false)
-    expect(withoutThinking.usage?.inputTokens).toBeGreaterThan(0)
-    expect(withoutThinking.usage?.outputTokens).toBeGreaterThan(0)
-
-    const withThinking = await assemble(ctx,{
-      model: FLASH,
-      reasoningEffort: ReasoningEffortId('low'),
-      messages: ask('Which is larger, 9.11 or 9.8? Answer with just the number.'),
-      maxTokens: 2000,
-    })
-    expect(withThinking.finish.kind).toBe('stop')
-    expect(withThinking.message.content.some(block => block.type === 'reasoning')).toBe(true)
-    expect(textOf(withThinking)).toContain('9.8')
-    expect(withThinking.usage?.reasoningTokens).toBeGreaterThan(0)
-  })
-
-  it(
-    'flash + thinking enabled (effort max): tool-call round trip with reasoning passback',
-    async () => {
-      const ctx = await harness(FLASH, { thinking: 'enabled' })
-
-      // Turn 1: the model must call the tool (and think before it).
-      const first = await assemble(ctx,{
-        model: FLASH,
-        reasoningEffort: ReasoningEffortId('max'),
-        messages: ask('What is the weather in Paris right now? Use the get_weather tool.'),
-        tools: [weatherTool],
-        maxTokens: 2000,
-      })
-      expect(
-        first.finish.kind,
-        `DeepSeek Flash tool-call turn finished as ${JSON.stringify(first.finish)}`,
-      ).toBe('tool-calls')
-      const call = first.message.content.find(block => block.type === 'tool-call')
-      expect(call).toBeDefined()
-      expect(call!.name).toBe('get_weather')
-      expect(JSON.parse(call!.arguments)).toMatchObject({ city: expect.stringMatching(/paris/i) as string })
-
-      // Turn 2: send the tool result back WITH the assistant's reasoning
-      // block in history (the official thinking+tools passback rule).
-      const second = await assemble(ctx,{
-        model: FLASH,
-        reasoningEffort: ReasoningEffortId('max'),
-        messages: [
-          ...ask('What is the weather in Paris right now? Use the get_weather tool.'),
-          createMessage({
-            role: 'assistant', content: first.message.content,
-            source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-          }),
-          createToolResultMessage({
-            callId: ToolCallId(call!.id),
-            content: [{ type: 'text', text: 'Sunny, 22°C' }],
-            isError: false,
-          }),
-        ],
-        tools: [weatherTool],
-        maxTokens: 2000,
-      })
-      expect(
-        second.finish.kind,
-        `DeepSeek Flash tool-result turn finished as ${JSON.stringify(second.finish)}`,
-      ).toBe('stop')
-      expect(textOf(second).toLowerCase()).toMatch(/sunny|22/)
-    },
-  )
-
-  it.skipIf(IN_HISTORY_MODEL === undefined)(
-    'an in-history model follows a mid-history system message and keeps the cached prefix',
-    async () => {
-      const model = IN_HISTORY_MODEL as string
-      const ctx = await harness(model, {
-        thinking: 'disabled',
-        models: [{ id: model, systemPromptUpdate: 'in-history' }],
-      })
-      await expect(ctx.llm.resolveModelInfo('deepseek-official', model))
-        .resolves.toMatchObject({ systemPromptUpdate: 'in-history' })
-      const system = (text: string) => createSystemMessage(text)
-      // A nonce before the padding isolates the provider cache across runs and retries.
-      const nonce = randomBytes(16).toString('hex')
-      const padding = Array.from({ length: 40 }, (_, index) => `Rule ${String(index + 1)}: keep every answer short and factual.`).join('\n')
-      // Both update strategies use identical prompt bytes, with the changed instruction near the head.
-      const prompt = (word: string) => `Test ${nonce}. When the user says ping, reply with exactly the word: ${word}\n${padding}`
-      const initial = prompt('pong')
-      const latest = prompt('banana')
-      const history = [system(initial), ...ask('ping')]
-      const wireRequests: WireMessage[][] = []
-      const nativeFetch = globalThis.fetch
-      const observedFetch: typeof fetch = async (input, init) => {
-        if (init?.method !== 'POST' || typeof init.body !== 'string') return nativeFetch(input, init)
-        const body = JSON.parse(init.body) as WireRequest
-        if (body.model === model) {
-          wireRequests.push(body.messages)
-          if (wireRequests.length === 1) {
-            expect(body.messages).toEqual([
-              { role: 'system', content: initial }, { role: 'user', content: 'ping' },
-            ])
-          } else if (wireRequests.length === 2) {
-            expect(JSON.stringify(body.messages)).toBe(JSON.stringify(wireRequests[0]))
-          } else if (wireRequests.length === 3) {
-            expect(JSON.stringify(body.messages.slice(0, history.length)))
-              .toBe(JSON.stringify(wireRequests[0]))
-            expect(body.messages[3]).toEqual({ role: 'system', content: latest })
-          } else if (wireRequests.length === 4) {
-            expect(body.messages[0]).toEqual(wireRequests[2]![3])
-            expect(body.messages.slice(1)).toEqual([
-              wireRequests[2]![1], wireRequests[2]![2], wireRequests[2]![4],
-            ])
-          }
-        }
-        return nativeFetch(input, init)
+    for (let run = 0; run < 2; run++) {
+      afterSeq = SessionLogDeepSeek.acceptedThrough(session)
+      throughSeq = Number(session.seq) - 1
+      const assembler = new BlockAssembler()
+      for await (const chunk of ctx.llm.stream(options({ sessionId: session.id, reasoningEffort: ReasoningEffortId('off'), messages: [user('Reply with exactly PONG.')] }))) {
+        expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(enabled ? throughSeq : -1)
+        assembler.push(chunk)
       }
-      vi.stubGlobal('fetch', observedFetch)
-      try {
-        const first = await assemble(ctx, { model, messages: history, maxTokens: 50 })
-        expect(first.finish.kind).toBe('stop')
-        expect(textOf(first).trim()).toBe('pong')
-        const initialTokens = first.usage?.inputTokens ?? 0
-        expect(initialTokens).toBeGreaterThan(0)
-
-        // Measure reusable tokens rather than assuming a provider cache-block size.
-        const warm = await assemble(ctx, { model, messages: history, maxTokens: 50 })
-        expect(warm.finish.kind).toBe('stop')
-        expect(textOf(warm).trim()).toBe('pong')
-        const reusableTokens = warm.usage?.cacheReadTokens ?? 0
-        expect(reusableTokens).toBeLessThanOrEqual(initialTokens)
-        expect(reusableTokens).toBeGreaterThan(0)
-        const assistant = createMessage({
-          role: 'assistant', content: first.message.content, source: first.message.source,
-        })
-
-        const updated = await assemble(ctx, {
-          model,
-          messages: [...history, assistant, system(latest), ...ask('ping')],
-          maxTokens: 50,
-        })
-        expect(updated.finish.kind).toBe('stop')
-        expect(textOf(updated).trim()).toBe('banana')
-
-        const replaced = await assemble(ctx, {
-          model,
-          messages: [system(latest), ...ask('ping'), assistant, ...ask('ping')],
-          maxTokens: 50,
-        })
-        expect(replaced.finish.kind).toBe('stop')
-        expect(textOf(replaced).trim()).toBe('banana')
-        expect(wireRequests).toHaveLength(4)
-
-        const cached = updated.usage?.cacheReadTokens ?? 0
-        expect(replaced.usage?.cacheReadTokens).toBeDefined()
-        const baselineCached = replaced.usage?.cacheReadTokens ?? 0
-        expect(cached).toBeGreaterThanOrEqual(reusableTokens)
-        expect(cached).toBeGreaterThan(baselineCached)
-      } finally {
-        vi.stubGlobal('fetch', nativeFetch)
-      }
-    },
-  )
-
-  it('streams raw chunks in protocol order', async () => {
-    const ctx = await harness(FLASH, { thinking: 'disabled' })
-    const kinds: string[] = []
-    for await (const chunk of ctx.llm.stream({
-      provider: 'deepseek-official',
-      model: FLASH,
-      messages: ask('Count from 1 to 5, digits only.'),
-      maxTokens: 50,
-    })) {
-      kinds.push(chunk.type)
+      expect(assembler.finish.kind).toBe('stop')
+      expect(assembler.blocks().filter(block => block.type === 'text').map(block => block.text).join('')).toContain('PONG')
+      expect(requests).toBe(run + 1)
+      if (run === 0) session.append('step/start', { turn: 1, step: 1 })
     }
-    expect(kinds[0]).toBe('block-start')
-    expect(kinds.at(-1)).toBe('finish')
-    expect(kinds.filter(kind => kind === 'finish')).toHaveLength(1)
-    // usage precedes finish (deferred-emit contract)
-    expect(kinds.indexOf('usage')).toBeLessThan(kinds.indexOf('finish'))
+    expect(session.snapshotEvents().filter(event => event.type === 'session-log-deepseek/delivery-accepted')).toHaveLength(enabled ? 2 : 0)
+  })
+
+  it.each(['off', 'low', 'high', 'max'])('streams text with %s effort', async (effort) => {
+    const ctx = await boot()
+    const result = await assemble(ctx.llm.stream(options({ reasoningEffort: ReasoningEffortId(effort), temperature: 0, messages: [user('Reply with exactly PONG.')] })))
+    expect(result.assembler.finish).toEqual({ kind: 'stop' })
+    expect(result.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('PONG')
+    expect(result.assembler.usage?.outputTokens).toBeGreaterThan(0)
+    expect(result.message.source.replayState).toBeDefined()
+  })
+
+  it('replays a JSON-persisted thinking/tool turn and an error result before continuing', async () => {
+    const ctx = await boot()
+    const history: Message[] = [user('Use lookup_value with key secret. If the tool returns an error, report its exact error text and stop.')]
+    const request = options({ messages: history, tools: [tool], reasoningEffort: ReasoningEffortId('high') })
+    const first = await assemble(ctx.llm.stream(request))
+    expect(first.assembler.finish.kind).toBe('tool-calls')
+    const calls = first.message.content.filter(block => block.type === 'tool-call')
+    expect(calls).toHaveLength(1)
+    const restored = JSON.parse(JSON.stringify(first.message)) as Message
+    history.push(restored)
+    for (const call of calls) history.push(createToolResultMessage({ callId: call.id, content: [{ type: 'text', text: 'LOOKUP_DENIED_731' }], isError: true }))
+    const second = await assemble(ctx.llm.stream({ ...request, messages: history }))
+    expect(second.assembler.finish.kind).toBe('stop')
+    expect(second.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('LOOKUP_DENIED_731')
+    history.push(second.message, user('Reply with exactly DONE.'))
+    const third = await assemble(ctx.llm.stream({ ...request, messages: history }))
+    expect(third.assembler.finish.kind).toBe('stop')
+  })
+
+  it('continues persisted foreign history containing malformed tool arguments', async () => {
+    const ctx = await boot()
+    const callId = ToolCallId('historical_lookup')
+    const history = [
+      user('Look up the secret value.'),
+      createAssistantMessage({ source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' }, content: [
+        { type: 'tool-call', id: callId, name: 'lookup_value', arguments: '{"key":"the "secret""}' },
+      ] }),
+      createToolResultMessage({ callId, content: [{ type: 'text', text: 'Invalid arguments: expected an object' }], isError: true }),
+      user('Do not retry the lookup. Reply with exactly HISTORY_RECOVERED_731.'),
+    ]
+    const saved = JSON.stringify(history)
+    const restored = JSON.parse(saved) as Message[]
+    const response = await assemble(ctx.llm.stream(options({ messages: restored, tools: [tool], reasoningEffort: ReasoningEffortId('off') })))
+    expect(response.assembler.finish.kind).toBe('stop')
+    expect(response.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('HISTORY_RECOVERED_731')
+    expect(JSON.stringify(restored)).toBe(saved)
+  })
+
+  it('cancels an active stream without committing a successful response', async () => {
+    const ctx = await boot()
+    const controller = new AbortController()
+    const stream = ctx.llm.stream(options({ signal: controller.signal, messages: [user('List the integers from one to one thousand, one per line.')] }))
+    let cancelled = false
+    let finish: unknown
+    for await (const chunk of stream) {
+      if (!cancelled && (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta')) { cancelled = true; controller.abort() }
+      if (chunk.type === 'finish') finish = chunk.reason
+    }
+    expect(cancelled).toBe(true)
+    expect(finish).toMatchObject({ kind: 'aborted' })
+  })
+
+  it('continues a thinking/tool turn after degrading unusable persisted replay metadata', async () => {
+    const ctx = await boot()
+    const warnings: unknown[][] = []
+    ctx.logger.exporter({ levels: { default: LoggerLevel.WARN }, export: (message) => { if (message.type === 'warn') warnings.push(message.args) } })
+    const history: Message[] = [user('Use lookup_value with key secret. Then reply with the exact tool result and stop.')]
+    const request = options({ messages: history, tools: [tool], reasoningEffort: ReasoningEffortId('high') })
+    const first = await assemble(ctx.llm.stream(request))
+    expect(first.assembler.finish.kind).toBe('tool-calls')
+    const calls = first.message.content.filter(block => block.type === 'tool-call')
+    expect(calls).toHaveLength(1)
+    const restored = JSON.parse(JSON.stringify(first.message)) as typeof first.message
+    restored.source.replayState = { response: { kind: 'deepseek-messages', version: 2 }, blocks: [] }
+    const saved = JSON.stringify(restored)
+    history.push(restored, ...calls.map(call => createToolResultMessage({ callId: call.id, content: [{ type: 'text', text: 'REPLAY_RECOVERED_731' }], isError: false })))
+    const second = await assemble(ctx.llm.stream({ ...request, messages: history }))
+    expect(second.assembler.finish.kind).toBe('stop')
+    expect(second.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('REPLAY_RECOVERED_731')
+    expect(warnings).toEqual([[expect.stringContaining('unsupported kind or version')]])
+    expect(JSON.stringify(restored)).toBe(saved)
   })
 })
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index ea6ba2bf8f..f12fe10e87 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -1,2358 +1,448 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { mkdtempSync, rmSync } from 'node:fs'
+/** HTTP lifecycle, routing and optional Cordis services under real composition. */
+import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { Context } from '@deepseek-ai/cordis'
-import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
-import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import { createLaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment'
-import LlmRuntime, { ToolCallId, createUserMessage,
-  CONTEXT_WINDOW_EXCEEDED_CODE,
-  createToolResultMessage,
-  LlmError,
-  ProviderRequestId,
-  QUOTA_EXCEEDED_CODE,
-  ReasoningEffortId,
-  userAgent,
-} from '@deepseek-ai/dsh-llm'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { getOrCreateAnonymousUserId, type AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import type { PreparedDeepSeekLlmApiExtensions } from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
-import { DeepSeekAdapter, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
-import type { ContextFormed } from '@deepseek-ai/dsh-llm'
-import { httpErrorCode } from '../src/protocols/chat-completions/adapter.ts'
-import { resolveRequestImageTarget } from '../src/common/request-pricing.ts'
-import { assemble } from './assemble.ts'
-import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
-import type { Behavior } from './mock-server.ts'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context, LoggerLevel, Service } from '@deepseek-ai/cordis'
+import LocalAttachments from '@deepseek-ai/dsh-attachment-local'
+import AgentRegistry, { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { Agent, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import { AttachmentId } from '@deepseek-ai/dsh-attachment'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import LlmRuntime, { createAssistantMessage, createSystemMessage, createToolResultMessage, createUserMessage, ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import LocalCredentials from '@deepseek-ai/dsh-credentials-local'
+import FileSettings from '@deepseek-ai/dsh-settings-file'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import { DeepSeekAdapter } from '../src/adapter.ts'
+import { object } from '../src/replay.ts'
+import { DeepSeekFileStore } from '../src/file-store.ts'
+import * as Messages from '../src/index.ts'
+import { adapter, assemble, chunks, MODEL, options, prepareExtensions, server, sse, textEvents, user, sourceModuleLoader } from './helpers.ts'
+
+const cleanup: (() => Promise<unknown>)[] = []
+afterEach(async () => {
+  while (cleanup.length) await cleanup.pop()!()
+  vi.unstubAllEnvs()
+  vi.unstubAllGlobals()
+})
+async function endpoint(...args: Parameters<typeof server>) {
+  const instance = await server(...args)
+  cleanup.push(() => instance.close())
+  return instance
+}
+async function context() {
+  const home = await mkdtemp(join(tmpdir(), 'dsh-messages-test-'))
+  cleanup.push(() => rm(home, { recursive: true, force: true }))
+  vi.stubEnv('DSH_HOME', home)
+  const ctx = new Context()
+  cleanup.push(() => ctx.fiber.dispose())
+  return { ctx, home }
+}
+
+async function send(agent: Agent, text: string) {
+  agent.followup(user(text))
+  await agent.whenIdle()
+  expect(agent.session.snapshotEvents().at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } } })
+}
 
 declare module '@deepseek-ai/dsh-llm' {
   interface MessageSourceMap {
-    'test': { kind: 'test' } & ContextFormed
+    'saved-notice': { kind: 'saved-notice' }
   }
 }
 
-const TEST_USER_ID = '00000000-0000-4000-8000-000000000001' as AnonymousUserId
-let testHome: string
+describe('direct Messages HTTP', () => {
+  it('continues through Messages with assistant blocks in saved user history', async () => {
+    const http = await endpoint()
+    const notice = createUserMessage({ source: { kind: 'saved-notice' }, content: [
+      { type: 'text', text: 'Background subagent finished.' },
+      { type: 'reasoning', text: 'child reasoning' },
+      { type: 'tool-call', id: ToolCallId('child-call'), name: 'read', arguments: '{}' },
+      { type: 'text', text: 'Its closing message: answer.' },
+    ] })
+    const empty = createUserMessage({ source: { kind: 'user' }, content: [{ type: 'reasoning', text: 'no closing text' }] })
+    const history = [notice, empty]
+    const saved = JSON.stringify(history)
+    const llm = adapter({ baseURL: http.url })
+    const first = await assemble(llm.stream(options({ messages: history })))
+    const second = await assemble(llm.stream(options({ messages: [...history, first.message, user('continue')] })))
 
-beforeEach(() => {
-  testHome = mkdtempSync(join(tmpdir(), 'dsh-llm-deepseek-'))
-  vi.stubEnv('DSH_HOME', testHome)
-})
-
-afterEach(async () => {
-  await closeMockServers()
-  vi.unstubAllEnvs()
-  vi.useRealTimers()
-  rmSync(testHome, { recursive: true, force: true })
-})
-
-async function harness(baseURL: string, config: object = {}) {
-  // Configuration carries only the reference; the key comes from the
-  // environment, which is the whole credential plane without a mounted seam.
-  vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
-  const ctx = new Context()
-  await ctx.plugin(LlmRuntime)
-  await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
-  await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL, ...config })
-  return ctx
-}
-
-/** Direct adapter over the plugin's real resolve step, with a static key. */
-function noExtensions(): Promise<PreparedDeepSeekLlmApiExtensions> {
-  return Promise.resolve({ fields: {}, accept: () => Promise.resolve() })
-}
-
-/** Direct adapter over the plugin's real resolve step, with a static key. */
-function adapterOf(
-  config: Partial<LlmDeepSeek.Config> & { apiKey?: string } = {},
-  attachments?: AttachmentStore,
-  files?: LlmDeepSeek.DeepSeekFileStore,
-): DeepSeekAdapter {
-  const { apiKey, ...rest } = config
-  return new DeepSeekAdapter({
-    options: () => resolveAdapterOptions({ protocol: 'chat-completions', ...rest }),
-    resolveApiKey: () => Promise.resolve(apiKey ?? 'k'),
-    resolveUserId: () => TEST_USER_ID,
-    resolveAttachments: () => attachments,
-    ...files === undefined ? {} : { resolveFiles: () => files },
-    prepareExtensions: noExtensions,
-  })
-}
-
-async function drain(stream: AsyncIterable<unknown>): Promise<void> {
-  for await (const _chunk of stream) { /* drain */ }
-}
-
-const imageRef: ImageAttachmentRef = {
-  attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`),
-  mediaType: 'image/png',
-  bytes: 3,
-  width: 1,
-  height: 1,
-}
-
-function requestImage(ref = imageRef): RequestImageAttachment {
-  return {
-    variantId: ImageVariantId(`sha256:${'b'.repeat(64)}`),
-    attachment: ref,
-    data: Uint8Array.of(1, 2, 3),
-    mediaType: 'image/png',
-    bytes: 3,
-    width: 1,
-    height: 1,
-    depth: 'uchar',
-    space: 'srgb',
-    hasAlpha: true,
-  }
-}
-
-function attachmentStoreOf(
-  project: (ref: ImageAttachmentRef, policy: unknown, signal?: AbortSignal) => Promise<RequestImageAttachment>,
-): {
-  store: AttachmentStore
-  readImageRequest: ReturnType<typeof vi.fn<typeof project>>
-} {
-  const readImageRequest = vi.fn(project)
-  return {
-    store: { readImageRequest, imageHostPath: () => undefined } as unknown as AttachmentStore,
-    readImageRequest,
-  }
-}
-
-function fileStoreOf(
-  implementation: (...args: Parameters<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>) => ReturnType<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>,
-) {
-  const ensureUploaded = vi.fn(implementation)
-  const invalidate = vi.fn(() => Promise.resolve())
-  return {
-    store: { ensureUploaded, invalidate } as unknown as LlmDeepSeek.DeepSeekFileStore,
-    ensureUploaded,
-    invalidate,
-  }
-}
-
-function fileReference(fileId: string): Awaited<ReturnType<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>> {
-  return {
-    record: { fileId: LlmDeepSeek.DeepSeekFileId(fileId) },
-    uploaded: true,
-  } as Awaited<ReturnType<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>>
-}
-
-function successfulSseResponse(): Response {
-  return new Response(textEvents.map(event => `data: ${event}\n\n`).join(''), {
-    status: 200,
-    headers: { 'content-type': 'text/event-stream' },
-  })
-}
-
-describe('request image target', () => {
-  it.each([
-    [
-      { id: 'default' },
-      { width: 1302, height: 1302, maxBytes: 2 * 1024 * 1024 },
-    ],
-    [
-      { id: 'low', imagePixelBudget: 'low' as const },
-      { width: 512, height: 512, maxBytes: 2 * 1024 * 1024 },
-    ],
-    [
-      { id: 'custom', imagePixelBudget: 320_000, imageMaxBytes: 512_000 },
-      { width: 565, height: 565, maxBytes: 512_000 },
-    ],
-  ])('resolves route-owned defaults and overrides for %s on a 4096x4096 source', (model, expected) => {
-    expect(resolveRequestImageTarget(model, { width: 4096, height: 4096 })).toEqual(expected)
-  })
-
-  it('caps every request image at the provider per-side limit', () => {
-    expect(resolveRequestImageTarget({ id: 'default' }, { width: 8192, height: 78 }))
-      .toEqual({ width: 4096, height: 39, maxBytes: 2 * 1024 * 1024 })
-    expect(resolveRequestImageTarget({ id: 'custom', imagePixelBudget: 640_000 }, { width: 10_000, height: 100 }))
-      .toEqual({ width: 4096, height: 41, maxBytes: 2 * 1024 * 1024 })
-  })
-
-  it('answers image request pricing from the current connection snapshot', () => {
-    const adapter = adapterOf({
-      models: [{ id: 'vision', inputModalities: ['text', 'image'] }],
-    })
-    const priced = adapter.imageRequestPricing('deepseek-official', 'vision')?.priceImages([{ type: 'image', attachment: imageRef }])
-    expect(priced).toHaveLength(1)
-    expect(priced?.[0]!.visualTokens).toBeGreaterThan(0)
-    const textOnly = adapter.imageRequestPricing('deepseek-official', 'unlisted')?.priceImages([{ type: 'image', attachment: imageRef }])
-    expect(textOnly?.[0]!.visualTokens).toBe(0)
-  })
-
-  it('prices descriptor text through the serializer\'s access resolution', () => {
-    const attachments = {} as AttachmentStore
-    const adapter = new DeepSeekAdapter({
-      options: () => resolveAdapterOptions({ protocol: 'chat-completions', models: [{ id: 'vision', inputModalities: ['text', 'image'] }] }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-      resolveAttachments: () => attachments,
-      resolveImageAccess: (store, ref) => (store === attachments && ref === imageRef
-        ? { readonlyPath: '/world/img.png' }
-        : undefined),
-      prepareExtensions: noExtensions,
-    })
-    const priced = adapter.imageRequestPricing('deepseek-official', 'vision')?.priceImages([{ type: 'image', attachment: imageRef }])
-    expect(priced?.[0]?.text).toContain('/world/img.png')
-  })
-})
-
-describe('DeepSeekAdapter against a mock server', () => {
-  it('merges prepared extension fields and accepts them once after HTTP 2xx', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const accept = vi.fn()
-    const prepareExtensions = vi.fn(async () => ({
-      fields: { dsh_test: { version: 1 } },
-      accept: async () => { accept() },
-    }))
-    const adapter = new DeepSeekAdapter({
-      options: () => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-      prepareExtensions: prepareExtensions as never,
-    })
-
-    await drain(adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [], sessionId: SessionId('s') }))
-    expect(server.requests[0]).toMatchObject({ dsh_test: { version: 1 } })
-    expect(prepareExtensions).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 's' }))
-    expect(accept).toHaveBeenCalledOnce()
-  })
-
-  it('fails before fetch on extension preparation or base-field collision', async () => {
-    const server = await mockServer([])
-    const base = {
-      options: () => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-    }
-    const failed = new DeepSeekAdapter({
-      ...base,
-      prepareExtensions: () => Promise.reject(new Error('metadata unavailable')),
-    })
-    await expect(drain(failed.stream({ provider: 'deepseek-official', model: 'm', messages: [] })))
-      .rejects.toMatchObject({ code: 'REQUEST_EXTENSION' })
-
-    const collision = new DeepSeekAdapter({
-      ...base,
-      prepareExtensions: (() => Promise.resolve({ fields: { model: 'replacement' }, accept: () => Promise.resolve() })) as never,
-    })
-    await expect(drain(collision.stream({ provider: 'deepseek-official', model: 'm', messages: [] })))
-      .rejects.toMatchObject({ code: 'REQUEST_EXTENSION' })
-    expect(server.requests).toHaveLength(0)
-  })
-
-  it('passes cancellation into extension preparation and aborts before fetch', async () => {
-    const server = await mockServer([])
-    const controller = new AbortController()
-    const started = Promise.withResolvers<undefined>()
-    let signalSeen: AbortSignal | undefined
-    const adapter = new DeepSeekAdapter({
-      options: () => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-      prepareExtensions: ((request: { signal: AbortSignal }) => {
-        signalSeen = request.signal
-        started.resolve(undefined)
-        if (request.signal === undefined) return new Promise(() => {})
-        return new Promise((_resolve, reject) => {
-          request.signal.addEventListener('abort', () => {
-            const reason: unknown = request.signal.reason
-            reject(reason instanceof Error ? reason : new Error('extension preparation aborted', { cause: reason }))
-          }, { once: true })
-        })
-      }) as never,
-    })
-
-    const pending = drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'm',
-      messages: [],
-      signal: controller.signal,
-    }))
-    await started.promise
-    expect(signalSeen).toBeInstanceOf(AbortSignal)
-    controller.abort()
-    await expect(pending).rejects.toMatchObject({ code: 'ABORTED' })
-    expect(server.requests).toHaveLength(0)
-  })
-
-  it('passes cancellation through an outstanding fetch', async () => {
-    const controller = new AbortController()
-    const started = Promise.withResolvers<undefined>()
-    const fetch = vi.spyOn(globalThis, 'fetch').mockImplementation((_input, init) => {
-      const signal = init?.signal
-      return new Promise<Response>((_resolve, reject) => {
-        started.resolve(undefined)
-        signal?.addEventListener('abort', () => {
-          const reason: unknown = signal.reason
-          reject(reason instanceof Error ? reason : new Error('fetch aborted', { cause: reason }))
-        }, { once: true })
-      })
-    })
-    try {
-      const adapter = adapterOf({ baseURL: 'https://provider.invalid' })
-      const pending = drain(adapter.stream({
-        provider: 'deepseek-official',
-        model: 'm',
-        messages: [],
-        signal: controller.signal,
-      }))
-      await started.promise
-      controller.abort()
-      await expect(pending).rejects.toMatchObject({ code: 'ABORTED' })
-    } finally {
-      fetch.mockRestore()
-    }
-  })
-
-  it('does not accept extensions on non-2xx and does accept before a later stream failure', async () => {
-    const server = await mockServer([
-      { kind: 'http-error', status: 500, body: '{}' },
-      { kind: 'close-early', events: ['{"choices":[{"delta":{"content":"partial"}}]}'] },
+    expect(first.assembler.finish.kind).toBe('stop')
+    expect(second.assembler.finish.kind).toBe('stop')
+    expect(http.requests).toHaveLength(2)
+    const wireNotice = { role: 'user', content: [
+      { type: 'text', text: 'Background subagent finished.' },
+      { type: 'text', text: 'Its closing message: answer.' },
+    ] }
+    expect(http.requests[0]?.body.messages).toEqual([wireNotice])
+    expect(http.requests[1]?.body.messages).toEqual([
+      wireNotice,
+      { role: 'assistant', content: [{ type: 'text', text: 'Hello 世界' }] },
+      { role: 'user', content: [{ type: 'text', text: 'continue' }] },
     ])
-    const accept = vi.fn()
-    const adapter = new DeepSeekAdapter({
-      options: () => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-      prepareExtensions: () => Promise.resolve({ fields: { dsh_test: 1 }, accept: async () => { accept() } }) as never,
-    })
-    const request = { provider: 'deepseek-official', model: 'm', messages: [] }
+    expect(JSON.stringify(history)).toBe(saved)
+  })
 
-    await expect(drain(adapter.stream(request))).rejects.toMatchObject({ code: 'SERVER' })
+  it('continues without a diagnostic callback when replay metadata is unusable', async () => {
+    const http = await endpoint()
+    const message = createAssistantMessage({ content: [{ type: 'text', text: 'Remember 731.' }], source: {
+      provider: 'deepseek-official', model: MODEL, replayState: { response: {}, blocks: [] },
+    } })
+    const response = await assemble(adapter({ baseURL: http.url }).stream(options({ messages: [user(), message, user()] })))
+    expect(response.assembler.finish.kind).toBe('stop')
+    expect(http.requests[0]?.body.messages).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'Remember 731.' }] },
+      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+    ])
+  })
+
+  it('uses the Messages endpoint, authentication, attribution and final usage', async () => {
+    const http = await endpoint()
+    const llm = adapter({ baseURL: http.url })
+    const response = await assemble(llm.stream(options({ model: 'deepseek-flash', sessionId: SessionId('session-test'), purpose: 'compaction' })), 'deepseek-flash')
+    expect(response.message.content).toEqual([{ type: 'text', text: 'Hello 世界' }])
+    expect(response.message.source).toMatchObject({
+      model: 'deepseek-flash', replayState: { response: { model: 'deepseek-flash' } },
+    })
+    expect(http.requests[0]).toMatchObject({ path: '/anthropic/v1/messages', headers: {
+      'x-api-key': 'test-key', 'anthropic-version': '2023-06-01',
+      'user-agent': expect.stringContaining('deepseek-harness/') as string, 'x-deepseek-harness-user-id': 'test-user',
+      'x-deepseek-harness-session-id': 'session-test', 'x-deepseek-harness-compact': '1',
+    }, body: { thinking: { type: 'enabled' }, output_config: { effort: 'high' } } })
+    expect(llm.providerInfo('deepseek-official')).toEqual({ id: 'deepseek-official', name: 'DeepSeek' })
+    expect((await llm.listModels('deepseek-official')).map(model => model.id)).toEqual([
+      'deepseek-flash', 'deepseek-v4-pro',
+    ])
+    expect(await llm.resolveModel('deepseek-official', 'deepseek-flash')).toMatchObject({
+      name: 'DeepSeek-V41-Flash', inputModalities: ['text', 'image'], systemPromptUpdate: 'in-history',
+    })
+    expect(await llm.resolveModel('deepseek-official', MODEL)).toMatchObject({ id: MODEL })
+    expect(llm.imageRequestPricing('deepseek-official', MODEL)).toBeDefined()
+  })
+
+  it.each([
+    ['https://provider.example', 'https://provider.example/v1/messages'],
+    ['https://provider.example/v1/', 'https://provider.example/v1/messages'],
+    ['https://provider.example/v1beta', 'https://provider.example/v1beta/v1/messages'],
+    ['https://provider.example/v2', 'https://provider.example/v2/v1/messages'],
+    ['https://provider.example/anthropic', 'https://provider.example/anthropic/v1/messages'],
+    ['https://v1.provider.example', 'https://v1.provider.example/v1/messages'],
+  ])('resolves the Messages endpoint from %s', async (baseURL, expected) => {
+    const fetchImpl = vi.fn<typeof fetch>(async () => new Response(sse(textEvents), {
+      headers: { 'content-type': 'text/event-stream' },
+    }))
+    vi.stubGlobal('fetch', fetchImpl)
+
+    await chunks(adapter({ baseURL }).stream(options()))
+
+    expect(fetchImpl.mock.calls[0]?.[0]).toBe(expected)
+  })
+
+  it.each([true, false])('maps non-2xx responses (JSON=%s)', async (json) => {
+    const http = await endpoint((response) => { response.statusCode = 429; response.setHeader('retry-after', '3'); response.end(json ? JSON.stringify({ error: { type: 'rate_limit_error', message: 'slow down' } }) : '<html>busy</html>') })
+    await expect(chunks(adapter({ baseURL: http.url }).stream(options()))).rejects.toMatchObject({ code: 'RATE_LIMIT', failure: { status: 429, providerRetryAfterMs: 3000 } })
+  })
+
+  it('refuses redirects before credentials reach another origin or request extensions are accepted', async () => {
+    const destination = await endpoint()
+    const source = await endpoint((response) => {
+      response.writeHead(307, { location: `${destination.url}/v1/messages` })
+      response.end()
+    })
+    const accept = vi.fn(async () => {})
+    const prepare = vi.fn(async () => ({ fields: {}, accept }))
+    const files = new DeepSeekFileStore()
+    const llm = new DeepSeekAdapter({
+      options: () => Messages.resolveAdapterOptions({ baseURL: source.url }),
+      resolveApiKey: () => Promise.resolve('test-key'), resolveUserId: () => 'test-user' as AnonymousUserId,
+      resolveAttachments: () => undefined, resolveImageAccess: () => undefined, resolveFiles: () => files,
+      prepareExtensions: prepare,
+    })
+    const error = await chunks(llm.stream(options())).catch((cause: unknown) => cause)
+    expect(source.requests).toHaveLength(1)
+    expect(source.requests[0]?.headers['x-api-key']).toBe('test-key')
+    expect(destination.requests).toEqual([])
+    expect(error).toMatchObject({ code: 'TRANSPORT' })
+    expect(prepare).toHaveBeenCalledOnce()
     expect(accept).not.toHaveBeenCalled()
-    await expect(drain(adapter.stream(request))).rejects.toBeDefined()
-    expect(accept).toHaveBeenCalledOnce()
   })
 
-  it('reports a post-2xx extension acceptance failure without relabelling it as transport', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const failure = new Error('watermark append failed')
-    const adapter = new DeepSeekAdapter({
-      options: () => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-      prepareExtensions: () => Promise.resolve({
-        fields: { dsh_test: 1 },
-        accept: () => Promise.reject(failure),
-      }) as never,
+  it('freezes endpoint and defaults for a prepared call while the next call sees new settings', async () => {
+    const first = await endpoint(), second = await endpoint()
+    let config = Messages.resolveAdapterOptions({ baseURL: first.url, maxTokens: 10, models: [{ id: MODEL, systemPromptUpdate: 'in-history' }] })
+    const files = new DeepSeekFileStore()
+    const llm = new DeepSeekAdapter({ options: () => config, resolveApiKey: snapshot => Promise.resolve(snapshot.maxTokens === 10 ? 'first' : 'second'), resolveUserId: () => 'user' as AnonymousUserId, resolveAttachments: () => undefined, resolveImageAccess: () => undefined, resolveFiles: () => files, prepareExtensions })
+    const prepared = await llm.prepareCall('deepseek-official', MODEL)
+    config = Messages.resolveAdapterOptions({ baseURL: second.url, maxTokens: 20 })
+    expect(prepared.model.systemPromptUpdate).toBe('in-history')
+    expect((await llm.resolveModel('deepseek-official', MODEL)).systemPromptUpdate).toBeUndefined()
+    await chunks(prepared.stream(options()))
+    await chunks(llm.stream(options()))
+    expect(first.requests[0]).toMatchObject({ headers: { 'x-api-key': 'first' }, body: { max_tokens: 10 } })
+    expect(second.requests[0]).toMatchObject({ headers: { 'x-api-key': 'second' }, body: { max_tokens: 20 } })
+  })
+
+  it('aborts an open provider response when its consumer stops', async () => {
+    let closed!: () => void
+    const stopped = new Promise<void>((resolve) => { closed = resolve })
+    const http = await endpoint((response) => {
+      response.once('close', closed)
+      response.write(sse(textEvents.slice(0, 3)))
     })
-
-    await expect(drain(adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })))
-      .rejects.toMatchObject({ code: 'REQUEST_EXTENSION', cause: failure })
-    expect(server.requests).toHaveLength(1)
+    const stream = adapter({ baseURL: http.url }).stream(options())[Symbol.asyncIterator]()
+    expect((await stream.next()).value).toMatchObject({ type: 'block-start' })
+    await stream.return!()
+    await stopped
   })
 
-  it('streams a text generation end to end through the assembler', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const ctx = await harness(server.url)
-
-    const result = await assemble(ctx, {
-      model: 'deepseek-v4-pro',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })
-    expect(result.message.content).toEqual([{ type: 'text', text: 'hello' }])
-    expect(result.finish).toEqual({ kind: 'stop' })
-    expect(result.usage).toEqual({ inputTokens: 3, outputTokens: 1, totalTokens: 4 })
-
-    // The wire request carried the auth header contents we configured.
-    expect(server.requests[0]).toMatchObject({
-      model: 'deepseek-v4-pro',
-      max_tokens: 256_000,
-      reasoning_effort: 'high',
-      stream: true,
-      stream_options: { include_usage: true },
-    })
-    // App attribution and DeepSeek request identity are independent wire facts.
-    expect(server.headers[0]?.['user-agent']).toBe(userAgent())
-    expect(server.headers[0]?.['x-deepseek-harness-user-id']).toBe(getOrCreateAnonymousUserId())
-    expect(server.headers[0]).not.toHaveProperty('x-deepseek-harness-session-id')
-    expect(server.headers[0]).not.toHaveProperty('http-referer')
-    expect(server.headers[0]).not.toHaveProperty('x-openrouter-title')
-    expect(server.headers[0]).not.toHaveProperty('x-openrouter-categories')
-    expect(server.headers[0]).not.toHaveProperty('x-deepseek-harness-compact')
+  it('distinguishes caller cancellation from idle timeout and transport failure', async () => {
+    const http = await endpoint((response) =>{  response.flushHeaders() })
+    await expect(chunks(adapter({ baseURL: http.url, streamIdleTimeoutMs: 30 }).stream(options()))).rejects.toMatchObject({ code: 'TIMEOUT' })
+    const controller = new AbortController(); controller.abort()
+    await expect(chunks(adapter({ baseURL: http.url }).stream(options({ signal: controller.signal })))).rejects.toMatchObject({ code: 'ABORTED' })
+    vi.stubGlobal('fetch', async () => { throw new TypeError('network down') })
+    await expect(chunks(adapter().stream(options()))).rejects.toMatchObject({ code: 'TRANSPORT' })
   })
 
-  it('uploads a durable image once and sends only its Files API id to the vision model', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const signalSeen: (AbortSignal | undefined)[] = []
-    const policies: unknown[] = []
-    const attachmentMocks = attachmentStoreOf((ref, policy, signal) => {
-      signalSeen.push(signal)
-      policies.push(policy)
-      return Promise.resolve(requestImage(ref))
-    })
-    const adapter = adapterOf({ baseURL: server.url }, attachmentMocks.store)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-flash',
-      messages: [createUserMessage({
-        content: [
-          { type: 'text', text: 'describe ' },
-          { type: 'image', attachment: imageRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    expect(server.requests[0]).toMatchObject({
-      model: 'deepseek-flash',
-      messages: [{
-        role: 'user',
-        content: [
-          { type: 'text', text: 'describe ' },
-          { type: 'text', text: expect.stringContaining(`Image ${imageRef.attachmentId}; request preview 1x1px.`) as string },
-          { type: 'file', file_id: 'file-api-1' },
-        ],
-      }],
-    })
-    expect(server.fileRequests).toEqual([{
-      method: 'POST',
-      path: '/files',
-      filename: `dsh-${'a'.repeat(16)}-${'b'.repeat(8)}.png`,
-      bytes: 3,
-    }])
-    expect(signalSeen[0]).toBeInstanceOf(AbortSignal)
-    expect(policies).toEqual([{ width: 1, height: 1, maxBytes: 2 * 1024 * 1024 }])
-  })
-
-  it('keeps images inside plugin content opaque through adapter.stream', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const attachmentMocks = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
-    const adapter = adapterOf({ baseURL: server.url }, attachmentMocks.store)
-    await drain(adapter.stream({ provider: 'deepseek-official', model: 'deepseek-v4-pro', messages: [
-      createUserMessage({ source: { kind: 'user' }, content: [
-        { type: 'plugin:message',
-          message: { role: 'tool', toolCallId: 'foreign', content: [{ type: 'image', attachment: { ...imageRef } }] },
-        } as never,
-        { type: 'text', text: 'context' },
-      ] }),
-    ] }))
-    expect(attachmentMocks.readImageRequest).not.toHaveBeenCalled()
-    expect(server.fileRequests).toHaveLength(0)
-    expect(server.requests).toHaveLength(1)
-    expect(server.requests[0]).toMatchObject({ messages: [{ role: 'user', content: 'context' }] })
-  })
-
-  it('falls back to one all-base64 request when Files API resolution fails', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const secondRef = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`) }
-    const attachments = attachmentStoreOf(ref => Promise.resolve({
-      ...requestImage(ref),
-      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
-    })).store
-    const files = fileStoreOf(() => Promise.reject(new LlmError('Files unavailable', 'SERVER')))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: imageRef },
-          { type: 'image', attachment: secondRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    const body = server.requests[0] as { messages: Array<{ content: unknown }> }
-    expect(JSON.stringify(body.messages[0]?.content).match(/"type":"image_url"/g)).toHaveLength(2)
-    expect(JSON.stringify(body)).not.toContain('file_id')
-    expect(files.ensureUploaded).toHaveBeenCalledTimes(1)
-  })
-
-  it('fails a base64 fallback whose retained images exceed the inline bound with the count to offload', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const files = fileStoreOf(() => Promise.reject(new LlmError('Files unavailable', 'SERVER')))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      maxInlineRequestImageBytes: 80,
-      inlineImageOffloadByteQuantum: 40,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: Array.from({ length: 21 }, () => ({ type: 'image' as const, attachment: imageRef })),
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))).rejects.toMatchObject({ code: 'IMAGE_OFFLOAD_REQUIRED', message: expect.stringContaining('11 more') as string })
-    expect(server.requests).toHaveLength(0)
-  })
-  it('discards partially resolved file ids and falls back with every retained image inline', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const secondRef = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`) }
-    const attachments = attachmentStoreOf(ref => Promise.resolve({
-      ...requestImage(ref),
-      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
-    })).store
-    const files = fileStoreOf(() => Promise.reject(new Error('unused')))
-    files.ensureUploaded
-      .mockResolvedValueOnce(fileReference('file-api-partial'))
-      .mockRejectedValueOnce(new LlmError('Files unavailable', 'TRANSPORT'))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: imageRef },
-          { type: 'image', attachment: secondRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    const body = server.requests[0] as { messages: Array<{ content: unknown }> }
-    expect(JSON.stringify(body.messages[0]?.content).match(/"type":"image_url"/g)).toHaveLength(2)
-    expect(JSON.stringify(body)).not.toContain('file-api-partial')
-  })
-
-  it('falls back after the configured Files API deadline without aborting chat', async () => {
-    vi.useFakeTimers()
-    const started = Promise.withResolvers<undefined>()
-    const files = fileStoreOf((_version, _connection, _policy, signal) => new Promise((_resolve, reject) => {
-      started.resolve(undefined)
-      signal?.addEventListener('abort', () => {
-        const reason: unknown = signal.reason
-        reject(reason instanceof Error ? reason : new Error('files operation aborted'))
-      }, { once: true })
-    }))
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(successfulSseResponse())
-    const adapter = adapterOf({
-      baseURL: 'https://deepseek.invalid',
-      filesApiTimeoutMs: 50,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    const pending = drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-    await started.promise
-    await vi.advanceTimersByTimeAsync(50)
-    await pending
-
-    expect(fetchSpy).toHaveBeenCalledTimes(1)
-    expect(fetchSpy.mock.calls[0]?.[1]?.body).toEqual(expect.stringContaining('image_url'))
-    fetchSpy.mockRestore()
-  })
-
-  it('does not turn caller cancellation during file resolution into base64 fallback', async () => {
-    const started = Promise.withResolvers<undefined>()
-    const files = fileStoreOf((_version, _connection, _policy, signal) => new Promise((_resolve, reject) => {
-      started.resolve(undefined)
-      signal?.addEventListener('abort', () => { reject(new Error('cancelled')) }, { once: true })
-    }))
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const fetchSpy = vi.spyOn(globalThis, 'fetch')
-    const controller = new AbortController()
-    const adapter = adapterOf({
-      baseURL: 'https://deepseek.invalid',
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    const pending = drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      signal: controller.signal,
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-    await started.promise
-    controller.abort()
-
-    await expect(pending).rejects.toMatchObject({ code: 'ABORTED' })
-    expect(fetchSpy).not.toHaveBeenCalled()
-    fetchSpy.mockRestore()
-  })
-
-  it('does not retry a generic chat failure through base64 fallback', async () => {
-    const server = await mockServer([{
-      kind: 'http-error',
-      status: 503,
-      body: JSON.stringify({ error: { message: 'chat unavailable' } }),
-    }])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const files = fileStoreOf(() => Promise.resolve(fileReference('file-api-ready')))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))).rejects.toMatchObject({ code: 'SERVER', message: 'chat unavailable' })
-
-    expect(server.requests).toHaveLength(1)
-    expect(JSON.stringify(server.requests[0])).toContain('file-api-ready')
-    expect(JSON.stringify(server.requests[0])).not.toContain('image_url')
-  })
-
-  it('does not prepare a surface-offloaded image and sends its placeholder instead', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const old = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`), bytes: 3 }
-    const recent = { ...imageRef, attachmentId: AttachmentId(`sha256:${'d'.repeat(64)}`), bytes: 3 }
-    const attachmentMocks = attachmentStoreOf((ref) => {
-      if (ref.attachmentId === old.attachmentId) throw new Error('old image must not be read')
-      return Promise.resolve(requestImage(ref))
-    })
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachmentMocks.store)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: old, offloaded: true },
-          { type: 'image', attachment: recent },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    expect(attachmentMocks.readImageRequest).toHaveBeenCalledWith(
-      recent,
-      { width: 1, height: 1, maxBytes: 2 * 1024 * 1024 },
-      expect.any(AbortSignal),
-    )
-    const body = server.requests[0] as { messages: unknown[] }
-    expect(body.messages[0]).toMatchObject({
-      role: 'user',
-      content: [
-        { type: 'text', text: expect.stringContaining(`image omitted to fit request image limits; ${old.attachmentId}`) as string },
-        { type: 'text', text: expect.stringContaining(String(recent.attachmentId)) as string },
-        { type: 'file', file_id: 'file-api-1' },
-      ],
-    })
-  })
-
-  it('projects nested tool-result images with route-owned request budgets', async () => {
-    const server = await mockServer([
-      { kind: 'sse', events: textEvents },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachmentMocks = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [
-        {
-          id: 'vision-low',
-          inputModalities: ['text', 'image'],
-          imagePixelBudget: 'low',
-          imageMaxBytes: 512_000,
-        },
-        {
-          id: 'vision-custom',
-          inputModalities: ['text', 'image'],
-          imagePixelBudget: 320_000,
-        },
-      ],
-    }, attachmentMocks.store)
-    const nested = createToolResultMessage({
-      callId: ToolCallId('image-result'),
-      content: [{ type: 'image', attachment: imageRef }],
-      isError: false,
-    })
-
-    await drain(adapter.stream({ provider: 'deepseek-official', model: 'vision-low', messages: [nested] }))
-    await drain(adapter.stream({ provider: 'deepseek-official', model: 'vision-custom', messages: [nested] }))
-
-    expect(attachmentMocks.readImageRequest).toHaveBeenNthCalledWith(
-      1,
-      imageRef,
-      { width: 1, height: 1, maxBytes: 512_000 },
-      expect.any(AbortSignal),
-    )
-    expect(attachmentMocks.readImageRequest).toHaveBeenNthCalledWith(
-      2,
-      imageRef,
-      { width: 1, height: 1, maxBytes: 2 * 1024 * 1024 },
-      expect.any(AbortSignal),
-    )
-  })
-
-  it('reuses the exact request version between agent and compaction calls', async () => {
-    const server = await mockServer([
-      { kind: 'sse', events: textEvents },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-    const messages = [createUserMessage({
-      content: [{ type: 'image' as const, attachment: imageRef }],
-      source: { kind: 'test' as const },
-    })]
-
-    await drain(adapter.stream({ provider: 'deepseek-official', model: 'deepseek-v4-flash-vision-exp', messages }))
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages,
-      purpose: 'compaction',
-    }))
-
-    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(1)
-    expect(server.requests).toMatchObject([
-      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { file_id: 'file-api-1' }] }] },
-      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { file_id: 'file-api-1' }] }] },
-    ])
-    expect(server.headers[1]?.['x-deepseek-harness-compact']).toBe('1')
-  })
-
-  it('explains a provider rejection of a normalized image and retains the raw response as cause', async () => {
-    const raw = JSON.stringify({ error: { message: 'unsupported image payload for file-api-1' } })
-    const server = await mockServer([{ kind: 'http-error', status: 400, body: raw }])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    let failure: unknown
-    try {
-      await drain(adapter.stream({
-        provider: 'deepseek-official',
-        model: 'deepseek-v4-flash-vision-exp',
-        messages: [createUserMessage({
-          content: [{ type: 'image', attachment: imageRef }],
-          source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-        })],
-      }))
-    } catch (error: unknown) {
-      failure = error
-    }
-    expect(failure).toMatchObject({
-      code: 'INVALID_REQUEST',
-      message: expect.stringContaining(
-        `normalized image "${imageRef.attachmentId}" at message 1, image 1`,
-      ) as string,
-      cause: { message: raw },
-    })
-    expect((failure as Error).message).toContain('image/png, 8-bit sRGBA, 1x1')
-    expect((failure as Error).message).toContain('unsupported image payload for file-api-1')
-    expect((failure as Error).message).not.toBe(raw)
-  })
-
-  it('identifies the sole image when a normalized rejection omits its file id', async () => {
-    const raw = JSON.stringify({ error: { message: 'unsupported image payload' } })
-    const server = await mockServer([{ kind: 'http-error', status: 400, body: raw }])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))).rejects.toMatchObject({
-      message: expect.stringContaining(`normalized image "${imageRef.attachmentId}"`) as string,
-    })
-  })
-
-  it('lists every candidate when a normalized multi-image rejection names no file id', async () => {
-    const secondRef: ImageAttachmentRef = {
-      ...imageRef,
-      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
-    }
-    const raw = JSON.stringify({ error: { message: 'unsupported image payload' } })
-    const server = await mockServer([{ kind: 'http-error', status: 400, body: raw }])
-    const attachments = attachmentStoreOf((ref) => {
-      const first = ref.attachmentId === imageRef.attachmentId
-      return Promise.resolve({
-        ...requestImage(ref),
-        variantId: ImageVariantId(`sha256:${(first ? 'b' : 'd').repeat(64)}`),
-        attachment: first ? { ...ref, name: 'diagram.png' } : ref,
-        hasAlpha: false,
-      })
-    }).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: imageRef },
-          { type: 'image', attachment: secondRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))).rejects.toMatchObject({
-      code: 'INVALID_REQUEST',
-      message: expect.stringContaining('Candidate images: "diagram.png"') as string,
-      cause: { message: raw },
-    })
-  })
-
-  it.each([
-    'file-api-1 expired',
-    'file_id file-api-10 invalid; file_id file-api-1 expired',
-    'file_id file-api-1 expired',
-    'file_not_found',
-    'file_id file-api-1 deleted',
-    'invalid file_id file-api-1',
-  ])('reuploads once when chat rejects a Files API reference as %s', async (providerMessage) => {
-    const server = await mockServer([
-      {
-        kind: 'http-error',
-        status: 400,
-        body: JSON.stringify({ error: { message: providerMessage } }),
-      },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachmentMocks = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachmentMocks.store)
-    const options = {
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image' as const, attachment: imageRef }],
-        source: { kind: 'test' as const },
-      })],
-    }
-
-    await drain(adapter.stream(options))
-
-    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(2)
-    expect(server.requests).toMatchObject([
-      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { file_id: 'file-api-1' }] }] },
-      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { file_id: 'file-api-2' }] }] },
-    ])
-    expect(attachmentMocks.readImageRequest).toHaveBeenCalledTimes(1)
-  })
-
-  it('uses inline fallback when stale-id recovery cannot resolve a replacement file', async () => {
-    const server = await mockServer([
-      {
-        kind: 'http-error',
-        status: 400,
-        body: JSON.stringify({ error: { message: 'file_id file-api-stale expired' } }),
-      },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const files = fileStoreOf(() => Promise.reject(new Error('unused')))
-    files.ensureUploaded
-      .mockResolvedValueOnce(fileReference('file-api-stale'))
-      .mockRejectedValueOnce(new LlmError('Files unavailable', 'SERVER'))
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments, files.store)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    expect(files.invalidate).toHaveBeenCalledTimes(1)
-    expect(server.requests).toHaveLength(2)
-    expect(JSON.stringify(server.requests[0])).toContain('file-api-stale')
-    expect(JSON.stringify(server.requests[1])).toContain('image_url')
-  })
-
-  it('invalidates only the identified mapping when a multi-image request names one stale file id', async () => {
-    const secondRef: ImageAttachmentRef = {
-      ...imageRef,
-      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
-    }
-    const server = await mockServer([
-      {
-        kind: 'http-error',
-        status: 400,
-        body: JSON.stringify({ error: { message: 'file_id file-api-2 expired' } }),
-      },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachments = attachmentStoreOf(ref => Promise.resolve({
-      ...requestImage(ref),
-      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
-    })).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: imageRef },
-          { type: 'image', attachment: secondRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(3)
-    const retries = server.requests as Array<{ messages: Array<{ content: Array<{ type: string; file_id?: string }> }> }>
-    expect(retries[0]?.messages[0]?.content.filter(block => block.type === 'file'))
-      .toEqual([{ type: 'file', file_id: 'file-api-1' }, { type: 'file', file_id: 'file-api-2' }])
-    expect(retries[1]?.messages[0]?.content.filter(block => block.type === 'file'))
-      .toEqual([{ type: 'file', file_id: 'file-api-1' }, { type: 'file', file_id: 'file-api-3' }])
-  })
-
-  it('invalidates every listed missing file id and preserves unlisted mappings', async () => {
-    const secondRef: ImageAttachmentRef = {
-      ...imageRef,
-      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
-    }
-    const thirdRef: ImageAttachmentRef = {
-      ...imageRef,
-      attachmentId: AttachmentId(`sha256:${'e'.repeat(64)}`),
-    }
-    const server = await mockServer([
-      {
-        kind: 'http-error',
-        status: 400,
-        body: JSON.stringify({
-          error: {
-            message: 'path.to.object[index]: the following file_ids do not exist or are not created under your account: '
-              + 'file-api-1, file-api-3, file-api-unknown',
-          },
-        }),
-      },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachments = attachmentStoreOf((ref) => {
-      let digest = 'f'
-      if (ref.attachmentId === imageRef.attachmentId) digest = 'b'
-      else if (ref.attachmentId === secondRef.attachmentId) digest = 'd'
-      return Promise.resolve({
-        ...requestImage(ref),
-        variantId: ImageVariantId(`sha256:${digest.repeat(64)}`),
-      })
-    }).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: imageRef },
-          { type: 'image', attachment: secondRef },
-          { type: 'image', attachment: thirdRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(5)
-    const retries = server.requests as Array<{ messages: Array<{ content: Array<{ type: string; file_id?: string }> }> }>
-    expect(retries[0]?.messages[0]?.content.filter(block => block.type === 'file'))
-      .toEqual([
-        { type: 'file', file_id: 'file-api-1' },
-        { type: 'file', file_id: 'file-api-2' },
-        { type: 'file', file_id: 'file-api-3' },
-      ])
-    expect(retries[1]?.messages[0]?.content.filter(block => block.type === 'file'))
-      .toEqual([
-        { type: 'file', file_id: 'file-api-4' },
-        { type: 'file', file_id: 'file-api-2' },
-        { type: 'file', file_id: 'file-api-5' },
-      ])
-  })
-
-  it('invalidates every used mapping when a stale-file response does not identify one file id', async () => {
-    const secondRef: ImageAttachmentRef = {
-      ...imageRef,
-      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
-    }
-    const server = await mockServer([
-      {
-        kind: 'http-error',
-        status: 400,
-        body: JSON.stringify({ error: { message: 'file reference expired' } }),
-      },
-      { kind: 'sse', events: textEvents },
-    ])
-    const attachments = attachmentStoreOf(ref => Promise.resolve({
-      ...requestImage(ref),
-      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
-    })).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    await drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: imageRef },
-          { type: 'image', attachment: secondRef },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))
-
-    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(4)
-    const retries = server.requests as Array<{ messages: Array<{ content: Array<{ type: string; file_id?: string }> }> }>
-    expect(retries[1]?.messages[0]?.content.filter(block => block.type === 'file'))
-      .toEqual([{ type: 'file', file_id: 'file-api-3' }, { type: 'file', file_id: 'file-api-4' }])
-  })
-
-  it('returns the second stale-file rejection without a third chat attempt', async () => {
-    const stale = JSON.stringify({ error: { message: 'file_id file-api-1 expired' } })
-    const server = await mockServer([
-      { kind: 'http-error', status: 400, body: stale },
-      { kind: 'http-error', status: 400, body: stale },
-    ])
-    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
-    const adapter = adapterOf({
-      baseURL: server.url,
-      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-    }, attachments)
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))).rejects.toMatchObject({ code: 'INVALID_REQUEST', message: 'file_id file-api-1 expired' })
-    expect(server.requests).toHaveLength(2)
-    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(2)
-  })
-
-  it.each(['deepseek-v4-flash', 'unlisted-pass-through'])(
-    'rejects image input for text-only model %s before credentials, attachments, or fetch',
-    async (model) => {
-      const server = await mockServer([])
-      const resolveApiKey = vi.fn(() => Promise.resolve('k'))
-      const resolveAttachments = vi.fn(() => ({}) as AttachmentStore)
-      const adapter = new DeepSeekAdapter({
-        options: () => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }),
-        resolveApiKey,
-        resolveUserId: () => TEST_USER_ID,
-        resolveAttachments,
-        prepareExtensions: noExtensions,
-      })
-
-      await expect(drain(adapter.stream({
-        provider: 'deepseek-official',
-        model,
-        messages: [createUserMessage({
-          content: [{ type: 'image', attachment: imageRef }],
-          source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-        })],
-      }))).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-      expect(resolveApiKey).not.toHaveBeenCalled()
-      expect(resolveAttachments).not.toHaveBeenCalled()
-      expect(server.requests).toHaveLength(0)
-    },
-  )
-
-  it('rejects vision input without an attachment provider before credentials or fetch', async () => {
-    const server = await mockServer([])
-    const resolveApiKey = vi.fn(() => Promise.resolve('k'))
-    const adapter = new DeepSeekAdapter({
-      options: () => resolveAdapterOptions({
-        protocol: 'chat-completions',
-        baseURL: server.url,
-        models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
-      }),
-      resolveApiKey,
-      resolveUserId: () => TEST_USER_ID,
-      prepareExtensions: noExtensions,
-    })
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: imageRef }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }))).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-    expect(resolveApiKey).not.toHaveBeenCalled()
-    expect(server.requests).toHaveLength(0)
-  })
-
-  it('streams raw chunks through ctx.llm.stream', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents, delayMs: 2 }])
-    const ctx = await harness(server.url)
-
-    const kinds: string[] = []
-    for await (const chunk of ctx.llm.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })) {
-      kinds.push(chunk.type)
-    }
-    expect(kinds).toEqual(['block-start', 'text-delta', 'block-end', 'usage', 'finish'])
-  })
-
-  it('forwards the harness user and session ids for host-side trajectory routing', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const ctx = await harness(server.url)
-
-    await assemble(ctx, {
-      model: 'deepseek-v4-flash',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-      sessionId: SessionId('child-session'),
-    })
-
-    expect(server.headers[0]?.['x-deepseek-harness-session-id']).toBe('child-session')
-    expect(server.headers[0]?.['x-deepseek-harness-user-id']).toBe(getOrCreateAnonymousUserId())
-  })
-
-  it('marks the auxiliary compaction call on the wire', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const ctx = await harness(server.url)
-
-    await assemble(ctx, {
-      model: 'deepseek-v4-flash',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-      purpose: 'compaction',
-    })
-
-    expect(server.headers[0]?.['x-deepseek-harness-compact']).toBe('1')
-  })
-
-  it('switches dynamically from the configured low default through off to max', async () => {
-    const server = await mockServer([
-      { kind: 'sse', events: textEvents },
-      { kind: 'sse', events: textEvents },
-      { kind: 'sse', events: textEvents },
-    ])
-    const ctx = await harness(server.url, { thinking: 'enabled', reasoningEffort: 'low' })
-
-    await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })
-    await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      reasoningEffort: ReasoningEffortId('off'),
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi again' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })
-    await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      reasoningEffort: ReasoningEffortId('max'),
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'one more time' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })
-    expect(server.requests[0]).toMatchObject({
-      thinking: { type: 'enabled' },
-      reasoning_effort: 'low',
-    })
-    expect(server.requests[1]).toMatchObject({
-      thinking: { type: 'disabled' },
-    })
-    expect(server.requests[1]).not.toHaveProperty('reasoning_effort')
-    expect(server.requests[2]).toMatchObject({
-      thinking: { type: 'enabled' },
-      reasoning_effort: 'max',
-    })
-  })
-
-  it('uses the configured maxTokens default and preserves an explicit request cap', async () => {
-    const server = await mockServer([
-      { kind: 'sse', events: textEvents },
-      { kind: 'sse', events: textEvents },
-    ])
-    const ctx = await harness(server.url, { maxTokens: 32_000 })
-
-    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [], maxTokens: 8_192 })
-
-    expect(server.requests[0]).toMatchObject({ max_tokens: 32_000 })
-    expect(server.requests[1]).toMatchObject({ max_tokens: 8_192 })
-  })
-
-  it('publishes only off and omits the wire effort when thinking is disabled', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const ctx = await harness(server.url, { thinking: 'disabled' })
-
-    await assemble(ctx,{
-      model: 'deepseek-v4-flash',
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })
-    expect(server.requests[0]).toMatchObject({
-      thinking: { type: 'disabled' },
-    })
-    expect(server.requests[0]).not.toHaveProperty('reasoning_effort')
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-v4-flash'))
-      .resolves.toMatchObject({
-        reasoning: {
-          efforts: [{
-            id: ReasoningEffortId('off'),
-            name: 'Off',
-            description: 'Use for simple tasks that do not need reasoning.',
-          }],
-          defaultEffort: ReasoningEffortId('off'),
-        },
-      })
-  })
-
-  it('reports a per-request effort failure before I/O when thinking is disabled', async () => {
-    const server = await mockServer([])
-    const ctx = await harness(server.url, { thinking: 'disabled' })
-
-    const result = await assemble(ctx, {
-      model: 'deepseek-v4-flash',
-      reasoningEffort: ReasoningEffortId('high'),
-      messages: [createUserMessage({
-        content: [{ type: 'text', text: 'hi' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    })
-    expect(result.finish).toMatchObject({
-      kind: 'error',
-      failure: { code: 'UNSUPPORTED_REASONING_EFFORT' },
-    })
-    expect(server.requests).toHaveLength(0)
-  })
-
-  it.each(['high', 'max'])(
-    'rejects direct adapter effort %s before I/O when thinking is disabled',
-    async (effort) => {
-      const server = await mockServer([])
-      const adapter = adapterOf({ apiKey: 'test-key', baseURL: server.url, thinking: 'disabled' })
-
-      const stream = adapter.stream({
-        provider: 'deepseek-official',
-        model: 'deepseek-v4-flash',
-        reasoningEffort: ReasoningEffortId(effort),
-        messages: [createUserMessage({
-          content: [{ type: 'text', text: 'hi' }],
-          source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-        })],
-      })
-      await expect(async () => {
-        for await (const _chunk of stream) { /* drain */ }
-      }).rejects.toMatchObject({ code: 'UNSUPPORTED_REASONING_EFFORT' })
-      expect(server.requests).toHaveLength(0)
-    },
-  )
-
-  it.each([
-    [401, 'AUTH'],
-    [403, 'AUTH'],
-    [429, 'RATE_LIMIT'],
-    [400, 'INVALID_REQUEST'],
-    [500, 'SERVER'],
-    [503, 'SERVER'],
-  ])('maps HTTP %d to failure code %s with the body message', async (status, code) => {
-    const behavior: Behavior = {
-      kind: 'http-error',
-      status,
-      body: JSON.stringify({ error: { message: `failed with ${status}`, type: 't', code: 'c' } }),
-    }
-    const server = await mockServer([behavior])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish).toEqual({
-      kind: 'error',
-      failure: { message: `failed with ${status}`, code, status },
-    })
-  })
-
-  it('uses the HTTP status as the cause when an error response has no body', async () => {
-    const server = await mockServer([{ kind: 'http-error', status: 500, body: '' }])
-    const adapter = adapterOf({ baseURL: server.url })
-
-    await expect(drain(adapter.stream({
-      provider: 'deepseek-official',
-      model: 'deepseek-v4-flash',
-      messages: [],
-    }))).rejects.toMatchObject({
-      code: 'SERVER',
-      cause: { message: 'DeepSeek HTTP 500' },
-    })
-  })
-
-  it('classifies an HTTP context-window failure with the canonical code', async () => {
-    const server = await mockServer([{
-      kind: 'http-error',
-      status: 400,
-      body: JSON.stringify({
-        error: {
-          message: 'This model maximum context length is 128000 tokens; your input exceeds that limit.',
-          type: 'invalid_request_error',
-          code: 'context_length_exceeded',
-        },
-      }),
-    }])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish).toMatchObject({
-      kind: 'error',
-      failure: { code: CONTEXT_WINDOW_EXCEEDED_CODE },
-    })
-  })
-
-  it('retains status, Retry-After seconds, and provider request id as structured facts', async () => {
-    const server = await mockServer([{
-      kind: 'http-error',
-      status: 429,
-      body: JSON.stringify({ error: { message: 'slow down' } }),
-      headers: { 'retry-after': '2', 'x-request-id': 'req-429' },
-    }])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish).toEqual({
-      kind: 'error',
-      failure: {
-        message: 'slow down',
-        code: 'RATE_LIMIT',
-        status: 429,
-        providerRetryAfterMs: 2_000,
-        requestId: ProviderRequestId('req-429'),
-      },
-    })
-  })
-
-  it('parses a future Retry-After HTTP date and the DeepSeek request-id fallback', async () => {
-    const now = 1_800_000_000_000
-    const dateNow = vi.spyOn(Date, 'now').mockReturnValue(now)
-    try {
-      const server = await mockServer([{
-        kind: 'http-error',
-        status: 503,
-        body: JSON.stringify({ error: { message: 'come back later' } }),
-        headers: {
-          'retry-after': new Date(now + 3_000).toUTCString(),
-          'x-deepseek-request-id': 'deepseek-503',
-        },
-      }])
-      const ctx = await harness(server.url)
-      const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-      expect(result.finish).toEqual({
-        kind: 'error',
-        failure: {
-          message: 'come back later',
-          code: 'SERVER',
-          status: 503,
-          providerRetryAfterMs: 3_000,
-          requestId: ProviderRequestId('deepseek-503'),
-        },
-      })
-    } finally {
-      dateNow.mockRestore()
-    }
-  })
-
-  it('omits zero, non-finite, invalid, and past Retry-After values', async () => {
-    const values = [
-      '0',
-      '9'.repeat(400),
-      'not-a-date',
-      new Date(0).toUTCString(),
-    ]
-    for (const value of values) {
-      const server = await mockServer([{
-        kind: 'http-error',
-        status: 429,
-        body: JSON.stringify({ error: { message: 'retry later' } }),
-        headers: { 'retry-after': value },
-      }])
-      const ctx = await harness(server.url)
-      const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-      expect(result.finish).toEqual({
-        kind: 'error',
-        failure: { message: 'retry later', code: 'RATE_LIMIT', status: 429 },
-      })
-    }
-  })
-
-  it('classifies only context-capacity HTTP 400 details as context overflow', () => {
-    expect(httpErrorCode(400, { message: 'request too large for model context' }))
-      .toBe(CONTEXT_WINDOW_EXCEEDED_CODE)
-    expect(httpErrorCode(400, { message: 'invalid input: temperature exceeds maximum allowed value' }))
-      .toBe('INVALID_REQUEST')
-    expect(httpErrorCode(413, { code: 'context_length_exceeded' })).toBe('INVALID_REQUEST')
-  })
-
-  it('distinguishes terminal quota exhaustion from transient HTTP 429 throttling', () => {
-    expect(httpErrorCode(429, { code: 'insufficient_quota', message: 'account credits exhausted' }))
-      .toBe(QUOTA_EXCEEDED_CODE)
-    expect(httpErrorCode(429, { message: 'request rate limit exceeded' })).toBe('RATE_LIMIT')
-  })
-
-  it('keeps the status-line message for JSON error bodies without a message', async () => {
-    const server = await mockServer([{ kind: 'http-error', status: 500, body: '{"error":{"type":"x"}}' }])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish.kind).toBe('error')
-    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
-    expect(result.finish.failure.code).toBe('SERVER')
-    expect(result.finish.failure.message).toMatch(/HTTP 500/)
-  })
-
-  it('keeps the status-line message for non-JSON error bodies', async () => {
-    const server = await mockServer([{ kind: 'http-error', status: 502, body: 'Bad Gateway', contentType: 'text/plain' }])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish.kind).toBe('error')
-    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
-    expect(result.finish.failure.code).toBe('SERVER')
-    expect(result.finish.failure.message).toMatch(/HTTP 502/)
-  })
-
-  it('maps unusual statuses to HTTP_<status>', () => {
-    expect(httpErrorCode(418)).toBe('HTTP_418')
-  })
-
-  it('reports a transport failure with the endpoint in the message', async () => {
-    // Port 1 is reserved/unbound, so the service normalizes the fetch failure.
-    const ctx = await harness('http://127.0.0.1:1')
-    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish).toMatchObject({
-      kind: 'error',
-      failure: {
-        code: 'TRANSPORT',
-        message: 'DeepSeek API request to http://127.0.0.1:1 failed',
-      },
-    })
-  })
-
-  it('classifies an aborted request as an aborted finish', async () => {
-    const controller = new AbortController()
-    controller.abort()
-    const ctx = await harness('http://127.0.0.1:1')
-    const result = await assemble(ctx, {
-      model: 'deepseek-v4-flash',
-      messages: [],
-      signal: controller.signal,
-    })
-    expect(result.finish).toMatchObject({ kind: 'aborted', failure: { code: 'ABORTED' } })
-  })
-
-  it('throws EMPTY_RESPONSE when the response has no body', async () => {
-    const adapter = adapterOf({ baseURL: 'http://127.0.0.1:1' })
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      new Response(null, { status: 200 }),
-    )
-    try {
-      const iterate = async (): Promise<void> => {
-        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
-      }
-      await expect(iterate()).rejects.toThrow(/no response body/)
-    } finally {
-      fetchSpy.mockRestore()
-    }
-  })
-
-  it('classifies an abrupt body close as TRANSPORT', async () => {
-    const server = await mockServer([{
-      kind: 'close-early',
-      events: ['{"choices":[{"delta":{"content":"par"}}]}'],
-    }])
-    const ctx = await harness(server.url)
-    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish.kind).toBe('error')
-    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
-    expect(result.finish.failure.code).toBe('TRANSPORT')
-    expect(result.finish.failure.message).toMatch(/^DeepSeek API stream from .* failed$/)
-  })
-
-  it('aborts mid-stream via the request signal', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents, delayMs: 50 }])
-    const ctx = await harness(server.url)
-    const controller = new AbortController()
-
-    const pending = (async () => {
-      const chunks = []
-      for await (const chunk of ctx.llm.stream({
-        provider: 'deepseek-official',
-        model: 'deepseek-v4-flash',
-        messages: [],
-        signal: controller.signal,
-      })) {
-        chunks.push(chunk)
-      }
-      return chunks
-    })()
-
-    setTimeout(() => { controller.abort() }, 30)
-    const chunks = await pending
-    expect(chunks).toHaveLength(1)
-    expect(chunks[0]?.type).toBe('finish')
-    if (chunks[0]?.type !== 'finish') throw new Error('expected a finish chunk')
-    expect(chunks[0].reason.kind).toBe('aborted')
-    if (chunks[0].reason.kind !== 'aborted') throw new Error('expected an aborted finish')
-    expect(chunks[0].reason.failure.code).toBe('ABORTED')
-  })
-
-  it('maps connection failures to TRANSPORT without losing the cause', async () => {
-    const cause = new TypeError('connection refused')
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockRejectedValue(cause)
-    const adapter = adapterOf({ baseURL: 'https://example.invalid' })
-    try {
-      const drain = async (): Promise<void> => {
-        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
-      }
-      await expect(drain()).rejects.toMatchObject({ code: 'TRANSPORT', cause })
-    } finally {
-      fetchSpy.mockRestore()
-    }
-  })
-
-  it('renders a non-Error transport rejection without losing its cause', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
-      const failed = Promise.withResolvers<Response>()
-      failed.reject('offline')
-      return failed.promise
-    })
-    const adapter = adapterOf({ baseURL: 'https://example.invalid' })
-    try {
-      const drain = async (): Promise<void> => {
-        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
-      }
-      await expect(drain()).rejects.toMatchObject({
-        message: 'DeepSeek API request to https://example.invalid failed',
-        code: 'TRANSPORT',
-        cause: 'offline',
-      })
-    } finally {
-      fetchSpy.mockRestore()
-    }
-  })
-
-  it('aborts the underlying body when the stream stays idle past its watchdog', async () => {
-    vi.useFakeTimers()
-    let stopped = false
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((_input, init) => {
-      const signal = init?.signal
-      const body = new ReadableStream<Uint8Array>({
-        start(controller) {
-          signal?.addEventListener('abort', () => {
-            stopped = true
-            controller.error(signal.reason)
-          }, { once: true })
-        },
-      })
-      return Promise.resolve(new Response(body, { status: 200 }))
-    })
-    const adapter = adapterOf({
-      baseURL: 'https://example.invalid',
-      streamIdleTimeoutMs: 100,
-    })
-    try {
-      const drain = (async () => {
-        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
-      })()
-      const rejected = expect(drain).rejects.toMatchObject({ code: 'TIMEOUT' })
-      await vi.advanceTimersByTimeAsync(0)
-      await vi.advanceTimersByTimeAsync(100)
-      await rejected
-      expect(stopped).toBe(true)
-    } finally {
-      fetchSpy.mockRestore()
-    }
-  })
-
-  it('keeps an idle provider read alive through SSE comments', async () => {
-    vi.useFakeTimers()
-    const encoder = new TextEncoder()
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
-      const body = new ReadableStream<Uint8Array>({
-        start(controller) {
-          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 75)
-          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 150)
-          setTimeout(() => {
-            controller.enqueue(encoder.encode(textEvents.map(event => `data: ${event}\n\n`).join('')))
-            controller.close()
-          }, 225)
-        },
-      })
-      return Promise.resolve(new Response(body, { status: 200 }))
-    })
-    const adapter = adapterOf({
-      baseURL: 'https://example.invalid',
-      streamIdleTimeoutMs: 100,
-    })
-    try {
-      const chunks: string[] = []
-      const drain = (async () => {
-        for await (const chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) {
-          chunks.push(chunk.type)
-        }
-      })()
-      await vi.advanceTimersByTimeAsync(75)
-      await vi.advanceTimersByTimeAsync(75)
-      await vi.advanceTimersByTimeAsync(75)
-      await expect(drain).resolves.toBeUndefined()
-      expect(chunks).toEqual(['block-start', 'text-delta', 'block-end', 'usage', 'finish'])
-    } finally {
-      fetchSpy.mockRestore()
-    }
+  it('rejects a successful response with no readable body', async () => {
+    vi.stubGlobal('fetch', async () => new Response(null, { status: 200 }))
+    await expect(chunks(adapter().stream(options()))).rejects.toMatchObject({ code: 'EMPTY_RESPONSE' })
   })
 })
 
-describe('plugin registration and config', () => {
-  it('defaults to Messages and resolves the selected protocol endpoint without rewriting overrides', () => {
-    expect(resolveAdapterOptions({})).toMatchObject({ protocol: 'messages', baseURL: 'https://api.deepseek.com/anthropic' })
-    expect(resolveAdapterOptions({ protocol: 'chat-completions' })).toMatchObject({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com' })
-    expect(resolveAdapterOptions({ protocol: 'messages' })).toMatchObject({ protocol: 'messages', baseURL: 'https://api.deepseek.com/anthropic' })
-    for (const baseURL of ['https://gateway.example/custom/v1', 'https://gateway.example/v1/messages']) {
-      expect(resolveAdapterOptions({ protocol: 'messages', baseURL }).baseURL).toBe(baseURL)
-    }
-    expect(() => resolveAdapterOptions({ protocol: 'responses' } as unknown as LlmDeepSeek.Config)).toThrow(/protocol/)
-  })
-
-  it('keeps wire helpers off the package root', () => {
-    for (const helper of [
-      'httpErrorCode',
-      'serializeMessages',
-      'serializeRequest',
-      'DONE',
-      'parseSse',
-      'mapFinishReason',
-      'mapUsage',
-      'translate',
-    ]) expect(LlmDeepSeek).not.toHaveProperty(helper)
-  })
-
-  it('registers the deepseek provider and unregisters on dispose (HMR safety)', async () => {
-    const server = await mockServer([])
-    const ctx = new Context()
+describe('Cordis provider composition', () => {
+  it('resolves an attachment service loaded after the adapter and maps its read-only path', async () => {
+    const http = await endpoint()
+    const { ctx, home } = await context()
+    vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
     await ctx.plugin(LlmRuntime)
-    const fiber = await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: server.url,
+    await ctx.plugin(Messages, { baseURL: http.url })
+    const model = 'deepseek-flash'
+    const price = () => ctx.llm.imageRequestPricing('deepseek-official', model)!
+    const dummy = { attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`), width: 1, height: 1, bytes: 3, mediaType: 'image/png' as const }
+    expect(price().priceImages([{ type: 'image', attachment: dummy }])[0]?.text).toBeDefined()
+    await ctx.plugin(LocalAttachments, { dshHome: home })
+    const attachment = await ctx.attachments.saveImage({ data: await readFile(new URL('fixtures/red.png', import.meta.url)), mediaType: 'image/png' })
+    expect(price().priceImages([{ type: 'image', attachment }])[0]?.text).not.toContain('/mounted/image.png')
+    class MappedFiles extends Service {
+      constructor(context: Context) { super(context, 'fs') }
+      processPathFromHostPath(_path: string) { return '/mounted/image.png' }
+    }
+    await ctx.plugin(MappedFiles)
+    const message = user()
+    await chunks(ctx.llm.stream(options({ model, messages: [{ ...message, content: [...message.content, { type: 'image', attachment }] }] })))
+    expect(JSON.stringify(http.requests[0]?.body)).toContain('/mounted/image.png')
+    expect(price().priceImages([{ type: 'image', attachment }])[0]?.text).toContain('/mounted/image.png')
+  })
+
+  async function boot(...args: Parameters<typeof server>) {
+    const http = await endpoint(...args)
+    const { ctx, home } = await context()
+    vi.stubEnv('DEEPSEEK_API_KEY', '')
+    await writeFile(join(home, '.credentials.yaml'), 'version: 1\nrefs:\n  DEEPSEEK_API_KEY: stored-key\n', { mode: 0o600 })
+    await writeFile(join(home, 'settings.yaml'), '{}\n')
+    const template = await readFile(new URL('fixtures/cordis.yml', import.meta.url), 'utf8')
+    await writeFile(join(home, 'cordis.yml'), template.replaceAll('{{endpoint}}', JSON.stringify(http.url)).replaceAll('{{settings}}', JSON.stringify(join(home, 'settings.yaml'))).replaceAll('{{credentials}}', JSON.stringify(join(home, '.credentials.yaml'))))
+    ctx.baseUrl = pathToFileURL(home).href + '/'
+    await ctx.plugin(Loader)
+    ctx.loader.builtins.include = Include
+    const modules = new Map<string, unknown>([
+      ['@deepseek-ai/dsh-llm', LlmRuntime], ['@deepseek-ai/dsh-llm-deepseek', Messages],
+      ['@deepseek-ai/dsh-credentials-local', LocalCredentials], ['@deepseek-ai/dsh-settings-file', FileSettings],
+      ['@deepseek-ai/dsh-agent', AgentRegistry], ['@deepseek-ai/dsh-agent-loop', AgentLoop],
+      ['@deepseek-ai/dsh-session', SessionStore], ['@deepseek-ai/dsh-session-projection', SessionProjectionRegistry],
+      ['@deepseek-ai/dsh-system-prompt', SystemPrompt], ['@deepseek-ai/dsh-tools', ToolRuntime],
+    ])
+    // The importer supplies source modules while Loader still owns configuration and effects.
+    for (const name of modules.keys()) {
+      const directory = join(home, 'node_modules', name)
+      await mkdir(directory, { recursive: true })
+      await writeFile(join(directory, 'package.json'), JSON.stringify({ name, version: '0.1.3-alpha.1', type: 'module' }))
+    }
+    ctx.loader.internal = sourceModuleLoader(async (name) => {
+      if (!modules.has(name)) throw new Error(`unexpected module ${name}`)
+      return modules.get(name)
     })
-    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
-    expect(ctx.llm.listConfigurableProviders()).toEqual([{
-      provider: 'deepseek-official',
-      displayName: 'DeepSeek',
-      settingsNs: 'llm-deepseek',
-      settingsPath: [],
-    }])
+    await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(join(home, 'cordis.yml')).href } })
+    await ctx.loader.await()
+    return { ctx, http }
+  }
+
+  it.each([
+    { model: MODEL, inHistory: false },
+    { model: MODEL, inHistory: true },
+    { model: 'deepseek-flash', inHistory: true },
+  ])('updates, clears and restores prompts across continued and resumed sessions, model=$model in-history=$inHistory', async ({ model, inHistory }) => {
+    const { ctx, http } = await boot()
+    if (inHistory && model === MODEL) await ctx.settings.update(Messages.name, { models: [{ id: model, systemPromptUpdate: 'in-history' }] })
+    let prompt = 'first prompt'
+    ctx.on('system-prompt/assemble', async (_assembly, _context, next) => ({
+      ...await next(), sections: [{ name: 'test', text: prompt, order: 0 }],
+    }))
+    const agentOptions = { provider: 'deepseek-official', model }
+    const agent = await ctx.agentLoop.create(SessionId('prompt-update'), agentOptions)
+    await send(agent, 'first')
+    prompt = 'second prompt'
+    await send(agent, 'second')
+    const count = agent.session.snapshotEvents().filter(event => event.type === 'system/message').length
+    await send(agent, 'unchanged')
+    expect(agent.session.snapshotEvents().filter(event => event.type === 'system/message')).toHaveLength(count)
+    prompt = ''
+    await send(agent, 'clear')
+    const { agent: resumed } = await ctx.agents.create({ sessionId: SessionId('prompt-resume'), agentOptions,
+      seed: [...agent.session.snapshotEvents()] })
+    await send(resumed, 'resume cleared')
+    prompt = 'restored prompt'
+    await send(resumed, 'restore')
+    expect(http.requests.map(request => request.body.system)).toEqual(inHistory
+      ? ['first prompt', 'first prompt', 'first prompt', undefined, undefined, undefined]
+      : ['first prompt', 'second prompt', 'second prompt', undefined, undefined, 'restored prompt'])
+    for (const [index, request] of http.requests.entries()) {
+      const messages = request.body.messages as { role: string; content: unknown[] }[]
+      expect(messages.filter(message => message.role === 'assistant')).toHaveLength(index)
+      expect(messages.filter(message => message.role === 'system').map(message => message.content)).toEqual(
+        !inHistory ? [] : index === 1 || index === 2 ? [[{ type: 'text', text: 'second prompt' }]]
+          : index === 5 ? [[{ type: 'text', text: 'restored prompt' }]] : [],
+      )
+      expect(JSON.stringify(messages.filter(message => message.role !== 'system'))).not.toMatch(/first prompt|second prompt|restored prompt/)
+    }
+    expect(resumed.session.requestContext()?.systemPromptUpdate).toBe(inHistory ? 'in-history' : undefined)
+  })
+
+  it.each([false, true])('continues and resumes sessions after a model capability change, in-history=%s', async (inHistory) => {
+    const { ctx, http } = await boot()
+    await ctx.settings.update('llm-deepseek', { baseURL: http.url, models: [{ id: MODEL, systemPromptUpdate: 'in-history' }] })
+    let prompt = 'old prompt'
+    ctx.on('system-prompt/assemble', async (_assembly, _context, next) => ({
+      ...await next(), sections: [{ name: 'test', text: prompt, order: 0 }],
+    }))
+    const selection: ModelSelectionRef = { current: { provider: 'deepseek-official', model: MODEL }, assembled: undefined }
+    const agent = await ctx.agentLoop.create(SessionId('capability-switch'), selection.current)
+    installModelSelection(agent.ctx, selection)
+    await send(agent, 'first')
+    prompt = 'current prompt'
+    await send(agent, 'second')
+    expect((http.requests[1]?.body.messages as { role: string }[]).filter(message => message.role === 'system')).toHaveLength(1)
+    const seed = [...agent.session.snapshotEvents()]
+    const saved = JSON.stringify(seed)
+    await ctx.settings.update(Messages.name, { models: [{ id: MODEL, ...inHistory ? { systemPromptUpdate: 'in-history' } : {} }] })
+    selection.current = { provider: 'deepseek-official', model: MODEL }
+    await send(agent, 'switch')
+    const { agent: resumed } = await ctx.agents.create({ sessionId: SessionId('switch-resume'), agentOptions: selection.current, seed })
+    await send(resumed, 'resume')
+    for (const request of http.requests.slice(2)) {
+      expect(request.path).toBe('/anthropic/v1/messages')
+      expect(request.body.system).toBe(inHistory ? 'old prompt' : 'current prompt')
+      const messages = request.body.messages as { role: string }[]
+      expect(messages.filter(message => message.role === 'assistant')).toHaveLength(2)
+      expect(messages.filter(message => message.role === 'system')).toHaveLength(inHistory ? 1 : 0)
+      expect(JSON.stringify(messages.filter(message => message.role !== 'system'))).not.toMatch(/old prompt|current prompt/)
+    }
+    expect(JSON.stringify(seed)).toBe(saved)
+    expect(agent.session.deriveMessages().filter(message => message.role === 'system')).toHaveLength(inHistory ? 2 : 1)
+    expect(resumed.session.deriveMessages().filter(message => message.role === 'system')).toHaveLength(inHistory ? 2 : 1)
+  })
+
+  it('maps multiple system snapshots on direct compaction calls to the latest prompt', async () => {
+    const { ctx, http } = await boot()
+    const history = [createSystemMessage('old'), user(),
+      createAssistantMessage({ content: [{ type: 'text', text: 'OK' }], source: { provider: 'deepseek-official', model: MODEL } }),
+      createSystemMessage('current'), user('summarize')]
+    const saved = JSON.stringify(history)
+    const response = await assemble(ctx.llm.stream(options({ messages: history, purpose: 'compaction' })))
+    expect(response.assembler.finish.kind).toBe('stop')
+    expect(http.requests[0]?.body.system).toBe('current')
+    expect((http.requests[0]?.body.messages as { role: string }[]).map(message => message.role)).toEqual(['user', 'assistant', 'user'])
+    expect(JSON.stringify(history)).toBe(saved)
+  })
+
+  it('continues a recorded tool turn with a warning when its native replay version is unknown', async () => {
+    const { ctx, http } = await boot()
+    const warnings: unknown[][] = []
+    ctx.logger.exporter({ levels: { default: LoggerLevel.WARN }, export: (message) => { if (message.type === 'warn') warnings.push(message.args) } })
+    const fixture = await readFile(new URL('../../../../snapshots/session/deepseek-messages-degraded-replay/session.v2.jsonl', import.meta.url), 'utf8')
+    const records = fixture.trim().split('\n').map(line => JSON.parse(line) as { type: string; data: { message?: Message } })
+    const assistant = records.find(record => record.type === 'assistant/message')!.data.message!
+    if (assistant.source.kind === 'model') assistant.source.provider = 'deepseek-official'
+    // The released v2 row still wraps its tool result inside a user message.
+    const released = object(records.find(record => record.type === 'tool/result')!.data.message)
+    if (!Array.isArray(released.content)) throw new Error('fixture lacks released tool content')
+    const releasedBlock = object(released.content[0])
+    if (typeof releasedBlock.toolCallId !== 'string' || !Array.isArray(releasedBlock.content)) {
+      throw new Error('fixture lacks released tool result')
+    }
+    const content = releasedBlock.content.map((value) => {
+      const block = object(value)
+      if (block.type !== 'text' || typeof block.text !== 'string') throw new Error('fixture tool result must contain text')
+      return { type: 'text' as const, text: block.text }
+    })
+    const result = createToolResultMessage({
+      callId: ToolCallId(releasedBlock.toolCallId), content, isError: releasedBlock.isError === true,
+    })
+    const saved = JSON.stringify([assistant, result])
+    const response = await assemble(ctx.llm.stream(options({ messages: [user(), assistant, result] })))
+    expect(response.assembler.finish.kind).toBe('stop')
+    expect(warnings).toEqual([[`llm-deepseek: unusable Messages replay state on assistant history for route "deepseek-official/${MODEL}"; sending provider-neutral content (DeepSeek Messages replay: unsupported kind or version)`]])
+    expect(http.requests).toHaveLength(1)
+    expect(http.requests[0]?.body.messages).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      { role: 'assistant', content: [
+        { type: 'thinking', thinking: 'The user wants me to run a simple bash command and then reply with "DONE".' },
+        { type: 'tool_use', id: 'call_00_fkbBRJsUrGKd1pWVc4Gn8233', name: 'bash', input: { command: 'echo TERMINAL_OK', description: 'Echo TERMINAL_OK to verify terminal access' } },
+      ] },
+      { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'call_00_fkbBRJsUrGKd1pWVc4Gn8233', content: [{ type: 'text', text: 'TERMINAL_OK\n' }], is_error: false }] },
+    ])
+    expect(JSON.stringify([assistant, result])).toBe(saved)
+  })
+
+  it('loads one provider from YAML, rotates settings and credentials, then removes disposed registrations', async () => {
+    const { ctx, http } = await boot()
+    expect(ctx.llm.listProviders().map(provider => provider.id)).toEqual(['deepseek-official'])
+    expect((await assemble(ctx.llm.stream(options()))).assembler.finish.kind).toBe('stop')
+    expect(http.requests[0]?.headers['x-api-key']).toBe('stored-key')
+    const second = await endpoint()
+    await ctx.settings.update(Messages.name, { baseURL: second.url, maxTokens: 51, retryPolicy: { mode: 'always' } })
+    await ctx.credentials.set(credentialRef('DEEPSEEK_API_KEY'), 'rotated')
+    await chunks(ctx.llm.stream(options()))
+    expect(second.requests[0]).toMatchObject({ headers: { 'x-api-key': 'rotated' }, body: { max_tokens: 51 } })
+    await ctx.settings.update(Messages.name, { models: [{ id: 'duplicate' }, { id: 'duplicate' }], baseURL: http.url })
+    await chunks(ctx.llm.stream(options()))
+    expect(second.requests).toHaveLength(2)
+    expect(http.requests).toHaveLength(1)
+    await ctx.settings.update(Messages.name, { models: [{ id: MODEL }], baseURL: http.url })
+    await chunks(ctx.llm.stream(options()))
+    expect(http.requests).toHaveLength(2)
+    const llm = ctx.llm
+    await ctx.fiber.dispose()
+    expect(llm.listProviders()).toEqual([])
+    expect(llm.listConfigurableProviders()).toEqual([])
+  })
+
+  it('uses environment credentials and reports missing or malformed keys without network access', async () => {
+    const http = await endpoint()
+    const { ctx } = await context()
+    vi.stubEnv('DEEPSEEK_BASE_URL', http.url)
+    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
+    await ctx.plugin(LlmRuntime)
+    const fiber = ctx.plugin(Messages)
+    await fiber
+    await chunks(ctx.llm.stream(options()))
+    expect(http.requests[0]?.headers['x-api-key']).toBe('env-key')
+    vi.stubEnv('DEEPSEEK_API_KEY', '')
+    expect((await assemble(ctx.llm.stream(options()))).assembler.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
+    vi.stubEnv('DEEPSEEK_API_KEY', 'bad\nkey')
+    expect((await assemble(ctx.llm.stream(options()))).assembler.finish).toMatchObject({ kind: 'error', failure: { code: 'INVALID_CREDENTIAL' } })
     await fiber.dispose()
     expect(ctx.llm.listProviders()).toEqual([])
-    expect(ctx.llm.listConfigurableProviders()).toEqual([])
-  })
-
-  it('registers retryPolicy from the provider config', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      retryPolicy: {
-        mode: 'always',
-        backoff: { initialDelayMs: 25, maxDelayMs: 100, jitterRatio: 0.2 },
-      },
-    })
-
-    expect(ctx.llm.providerRetryPolicy('deepseek-official')).toEqual({
-      mode: 'always',
-      initialDelayMs: 25,
-      maxDelayMs: 100,
-      jitterRatio: 0.2,
-    })
-  })
-
-  it('owns the deepseek provider and advertises the default models', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: 'http://127.0.0.1:1' })
-    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
-    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
-      { provider: 'deepseek-official', id: 'deepseek-flash', name: 'DeepSeek-V41-Flash', inputModalities: ['text', 'image'] },
-      {
-        provider: 'deepseek-official',
-        id: 'deepseek-v4-pro',
-        name: 'DeepSeek-V4-Pro',
-        description: 'Stronger agentic coding, knowledge, and difficult reasoning; suited to complex or quality-critical tasks at higher cost.',
-        inputModalities: ['text'],
-      },
-    ])
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-flash'))
-      .resolves.toMatchObject({
-        provider: 'deepseek-official',
-        id: 'deepseek-flash',
-        name: 'DeepSeek-V41-Flash',
-        inputModalities: ['text', 'image'],
-        systemPromptUpdate: 'in-history',
-        context: { contextWindow: 1_000_000 },
-        defaultMaxTokens: 256_000,
-        reasoning: {
-          efforts: [
-            { id: ReasoningEffortId('off'), name: 'Off', description: 'Use for simple tasks that do not need reasoning.' },
-            { id: ReasoningEffortId('low'), name: 'Low', description: 'Prefer for routine or latency-sensitive tasks.' },
-            { id: ReasoningEffortId('high'), name: 'High', description: 'The default balance for most tasks.' },
-            { id: ReasoningEffortId('max'), name: 'Max', description: 'Reserve for the hardest quality-first tasks.' },
-          ],
-          defaultEffort: ReasoningEffortId('high'),
-        },
-      })
-  })
-
-  it('keeps deepseek-v4-pro available with its V4 capabilities', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: 'http://127.0.0.1:1' })
-    const info = await ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-v4-pro')
-    expect(info).toMatchObject({
-      id: 'deepseek-v4-pro',
-      inputModalities: ['text'],
-      context: { contextWindow: 1_000_000 },
-      defaultMaxTokens: 256_000,
-    })
-    expect(info?.systemPromptUpdate).toBeUndefined()
-  })
-
-  it.each(['off', 'low', 'max'] as const)('uses the configured %s reasoning default', async (effort) => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      reasoningEffort: effort,
-    })
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'unlisted-pass-through'))
-      .resolves.toMatchObject({
-        reasoning: {
-          efforts: [
-            { id: ReasoningEffortId('off'), name: 'Off', description: 'Use for simple tasks that do not need reasoning.' },
-            { id: ReasoningEffortId('low'), name: 'Low', description: 'Prefer for routine or latency-sensitive tasks.' },
-            { id: ReasoningEffortId('high'), name: 'High', description: 'The default balance for most tasks.' },
-            { id: ReasoningEffortId('max'), name: 'Max', description: 'Reserve for the hardest quality-first tasks.' },
-          ],
-          defaultEffort: ReasoningEffortId(effort),
-        },
-      })
-  })
-
-  it('accepts off as the default when thinking is deployment-disabled', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      thinking: 'disabled',
-      reasoningEffort: 'off',
-    })
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'unlisted-pass-through'))
-      .resolves.toMatchObject({
-        reasoning: {
-          efforts: [{
-            id: ReasoningEffortId('off'),
-            name: 'Off',
-            description: 'Use for simple tasks that do not need reasoning.',
-          }],
-          defaultEffort: ReasoningEffortId('off'),
-        },
-      })
-  })
-
-  it.each(['low', 'high', 'max'] as const)(
-    'rejects configured reasoning effort %s when thinking is disabled',
-    async (reasoningEffort) => {
-      const ctx = new Context()
-      await ctx.plugin(LlmRuntime)
-      await expect(ctx.plugin(LlmDeepSeek, {
-        protocol: 'chat-completions',
-        baseURL: 'http://127.0.0.1:1',
-        thinking: 'disabled',
-        reasoningEffort,
-      })).rejects.toThrow(/only reasoningEffort "off"/)
-      expect(ctx.llm.listProviders()).toEqual([])
-    },
-  )
-
-  it.each(['low', 'high', 'max'] as const)(
-    'rejects disabled-thinking effort %s at the resolver boundary',
-    (reasoningEffort) => {
-      expect(() => resolveAdapterOptions({ thinking: 'disabled', reasoningEffort }))
-        .toThrow(/only reasoningEffort "off"/)
-    },
-  )
-
-  it('accepts disabled thinking with off at the resolver boundary', async () => {
-    const adapter = adapterOf({ thinking: 'disabled', reasoningEffort: 'off' })
-    await expect(adapter.resolveModel('deepseek-official', 'pass-through')).resolves.toMatchObject({
-      reasoning: {
-        efforts: [{
-          id: ReasoningEffortId('off'),
-          name: 'Off',
-          description: 'Use for simple tasks that do not need reasoning.',
-        }],
-        defaultEffort: ReasoningEffortId('off'),
-      },
-    })
-  })
-
-  it('uses the default model catalog when apply is called directly', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    LlmDeepSeek.apply(ctx, { baseURL: 'http://127.0.0.1:1' })
-    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
-      { provider: 'deepseek-official', id: 'deepseek-flash', name: 'DeepSeek-V41-Flash', inputModalities: ['text', 'image'] },
-      {
-        provider: 'deepseek-official',
-        id: 'deepseek-v4-pro',
-        name: 'DeepSeek-V4-Pro',
-        description: 'Stronger agentic coding, knowledge, and difficult reasoning; suited to complex or quality-critical tasks at higher cost.',
-        inputModalities: ['text'],
-      },
-    ])
-  })
-
-  it('defaults an adapter-supplied catalog entry to text input', async () => {
-    const connection = resolveAdapterOptions({ models: [] })
-    const adapter = new DeepSeekAdapter({
-      options: () => ({ ...connection, models: [{ id: 'adapter-model' }] }),
-      resolveApiKey: () => Promise.resolve('k'),
-      resolveUserId: () => TEST_USER_ID,
-      prepareExtensions: noExtensions,
-    })
-    await expect(adapter.listModels('deepseek-official')).resolves.toEqual([{
-      provider: 'deepseek-official',
-      id: 'adapter-model',
-      name: 'adapter-model',
-      inputModalities: ['text'],
-    }])
-  })
-
-  it('advertises configured models without restricting arbitrary request ids', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      models: [
-        { id: 'private-fast', contextWindow: 32_000 },
-        {
-          id: 'private-reasoner',
-          name: 'Private Reasoner',
-          description: 'Higher reasoning budget',
-          contextWindow: 64_000,
-          inputModalities: ['text', 'image'],
-        },
-      ],
-    })
-    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
-      { provider: 'deepseek-official', id: 'private-fast', name: 'private-fast', inputModalities: ['text'] },
-      { provider: 'deepseek-official', id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget', inputModalities: ['text', 'image'] },
-    ])
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'private-fast'))
-      .resolves.toMatchObject({ context: { contextWindow: 32_000 } })
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'private-reasoner'))
-      .resolves.toMatchObject({
-        name: 'Private Reasoner',
-        description: 'Higher reasoning budget',
-        inputModalities: ['text', 'image'],
-      })
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'arbitrary-unlisted'))
-      .resolves.toMatchObject({
-        context: { contextWindow: 1_000_000 },
-        defaultMaxTokens: 256_000,
-      })
-  })
-
-  it('uses exact model capacity before the adapter-wide default', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      defaultContextWindow: 256_000,
-      models: [
-        { id: 'inherits-default' },
-        { id: 'exact-override', contextWindow: 64_000 },
-      ],
-    })
-
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'inherits-default'))
-      .resolves.toMatchObject({ context: { contextWindow: 256_000 } })
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'exact-override'))
-      .resolves.toMatchObject({ context: { contextWindow: 64_000 } })
-    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'unlisted-pass-through'))
-      .resolves.toMatchObject({ context: { contextWindow: 256_000 } })
-  })
-
-  it('allows an explicit empty model catalog', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      models: [],
-    })
-    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([])
-  })
-
-  const invalidModels: Array<[LlmDeepSeek.DeepSeekCatalogModel[], RegExp]> = [
-    [[{ id: '' }], /ids must be non-empty/],
-    [[{ id: 'm', name: '' }], /empty name/],
-    [[{ id: 'm', contextWindow: 0 }], /contextWindow/],
-    [[{ id: 'm', contextWindow: 1.5 }], /contextWindow/],
-    [[{ id: 'm', inputModalities: [] }], /inputModalities/],
-    [[{ id: 'm', inputModalities: ['text', 'text'] }], /inputModalities must not contain duplicates/],
-    [[{
-      id: 'm',
-      inputModalities: ['audio'] as unknown as NonNullable<LlmDeepSeek.DeepSeekCatalogModel['inputModalities']>,
-    }], /expected "text" \| "image"/],
-    [[{ id: 'm' }, { id: 'm' }], /duplicate catalog model/],
-  ]
-
-  it.each(invalidModels)('rejects invalid advisory model config', async (models, message) => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      models: [...models],
-    })).rejects.toThrow(message)
-    expect(ctx.llm.listProviders()).toEqual([])
-  })
-
-  const invalidProgrammaticModalities: Array<[LlmDeepSeek.DeepSeekCatalogModel[], RegExp]> = [
-    [[{ id: 'm', inputModalities: [] }], /inputModalities must not be empty/],
-    [[{
-      id: 'm',
-      inputModalities: ['audio'] as unknown as NonNullable<LlmDeepSeek.DeepSeekCatalogModel['inputModalities']>,
-    }], /inputModalities must contain only "text" and "image"/],
-  ]
-
-  it.each(invalidProgrammaticModalities)('rejects programmatic modality config that bypasses the schema', (models, message) => {
-    expect(() => resolveAdapterOptions({ models: [...models] })).toThrow(message)
-  })
-
-  it('rejects the removed imageDetail model setting through schema and direct construction', async () => {
-    const legacyModel = { id: 'vision', inputModalities: ['image'], imageDetail: 'low' } as unknown as
-      LlmDeepSeek.DeepSeekCatalogModel
-    expect(() => resolveAdapterOptions({ models: [legacyModel] })).toThrow(/imageDetail is no longer supported/)
-
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      models: [legacyModel],
-    })).rejects.toThrow(/imageDetail is no longer supported/)
-    expect(ctx.llm.listProviders()).toEqual([])
-  })
-
-  it.each([0, 1.5])('rejects a per-model output cap of %s', (maxTokens) => {
-    expect(() => resolveAdapterOptions({ models: [{ id: 'bad-cap', maxTokens }] }))
-      .toThrow(/maxTokens must be a positive integer/)
-  })
-
-  it('surfaces a catalog model\'s in-history system prompt update mode and rejects any other mode', async () => {
-    const adapter = adapterOf({ models: [
-      { id: 'capable', systemPromptUpdate: 'in-history' },
-      { id: 'plain' },
-    ] })
-    await expect(adapter.resolveModel('deepseek-official', 'capable'))
-      .resolves.toMatchObject({ systemPromptUpdate: 'in-history' })
-    await expect(adapter.resolveModel('deepseek-official', 'plain'))
-      .resolves.not.toHaveProperty('systemPromptUpdate')
-    await expect(adapter.resolveModel('deepseek-official', 'not-in-catalog'))
-      .resolves.not.toHaveProperty('systemPromptUpdate')
-    expect(() => resolveAdapterOptions({
-      models: [{ id: 'bogus', systemPromptUpdate: 'leading' as unknown as 'in-history' }],
-    })).toThrow(/systemPromptUpdate must be "in-history" when present/)
-  })
-
-  it('rejects image request limits on a text-only catalog model', () => {
-    expect(() => resolveAdapterOptions({
-      models: [{ id: 'text-only', inputModalities: ['text'], imagePixelBudget: 1 }],
-    })).toThrow(/text-only catalog model .* cannot declare image request limits/)
-  })
-
-  it.each([
-    ['imagePixelBudget', 0, /imagePixelBudget must be "low" or a positive safe integer/],
-    ['imagePixelBudget', Number.MAX_SAFE_INTEGER + 1, /imagePixelBudget must be "low" or a positive safe integer/],
-    ['imagePixelBudget', 'auto', /imagePixelBudget must be "low" or a positive safe integer/],
-    ['imageMaxBytes', 0, /imageMaxBytes must be a positive safe integer/],
-    ['imageMaxBytes', 1.5, /imageMaxBytes must be a positive safe integer/],
-  ] as const)('rejects per-model %s=%s', (field, value, message) => {
-    expect(() => resolveAdapterOptions({
-      models: [{ id: 'vision', inputModalities: ['image'], [field]: value }],
-    })).toThrow(message)
-  })
-
-  it('prefers a model\'s own output cap over the profile default', async () => {
-    // The profile default stays what an unlisted or uncapped model resolves
-    // to, so adding a per-model cap changes one model rather than the route.
-    const adapter = adapterOf({ maxTokens: 4096, models: [
-      { id: 'capped', maxTokens: 512 },
-      { id: 'uncapped' },
-    ] })
-    await expect(adapter.resolveModel('deepseek-official', 'capped'))
-      .resolves.toMatchObject({ defaultMaxTokens: 512 })
-    await expect(adapter.resolveModel('deepseek-official', 'uncapped'))
-      .resolves.toMatchObject({ defaultMaxTokens: 4096 })
-    await expect(adapter.resolveModel('deepseek-official', 'not-in-catalog'))
-      .resolves.toMatchObject({ defaultMaxTokens: 4096 })
-  })
-
-  it('rejects invalid context capacity when apply is called directly', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    expect(() => {
-      LlmDeepSeek.apply(ctx, {
-        baseURL: 'http://127.0.0.1:1',
-        models: [{ id: 'invalid-context', contextWindow: 0 }],
-      })
-    }).toThrow(/contextWindow must be a positive integer/)
-    expect(ctx.llm.listProviders()).toEqual([])
-  })
-
-  it.each([0, 1.5])(
-    'rejects invalid adapter-wide default context capacity %s',
-    async (defaultContextWindow) => {
-      expect(() => resolveAdapterOptions({ defaultContextWindow }))
-        .toThrow(/defaultContextWindow must be a positive integer/)
-
-      const ctx = new Context()
-      await ctx.plugin(LlmRuntime)
-      await expect(ctx.plugin(LlmDeepSeek, {
-        protocol: 'chat-completions',
-        baseURL: 'http://127.0.0.1:1',
-        defaultContextWindow,
-      })).rejects.toThrow(/defaultContextWindow/)
-      expect(ctx.llm.listProviders()).toEqual([])
-    },
-  )
-
-  it.each([0, 1.5, Number.MAX_SAFE_INTEGER + 1])(
-    'rejects invalid adapter-wide maxTokens %s',
-    async (maxTokens) => {
-      expect(() => resolveAdapterOptions({ maxTokens }))
-        .toThrow(/maxTokens must be a positive safe integer/)
-
-      const ctx = new Context()
-      await ctx.plugin(LlmRuntime)
-      await expect(ctx.plugin(LlmDeepSeek, {
-        protocol: 'chat-completions',
-        baseURL: 'http://127.0.0.1:1',
-        maxTokens,
-      })).rejects.toThrow(/maxTokens/)
-      expect(ctx.llm.listProviders()).toEqual([])
-    },
-  )
-
-  it('rejects offload quanta larger than their request bounds', () => {
-    expect(() => resolveAdapterOptions({
-      maxRequestFilesBytes: 10,
-      imageOffloadByteQuantum: 11,
-    })).toThrow(/imageOffloadByteQuantum must not exceed maxRequestFilesBytes/)
-    expect(() => resolveAdapterOptions({
-      maxInlineRequestImageBytes: 10,
-      inlineImageOffloadByteQuantum: 11,
-    })).toThrow(/inlineImageOffloadByteQuantum must not exceed maxInlineRequestImageBytes/)
-    expect(() => resolveAdapterOptions({
-      maxImagesPerRequest: 10,
-      imageOffloadCountQuantum: 11,
-    })).toThrow(/imageOffloadCountQuantum must not exceed maxImagesPerRequest/)
-  })
-
-  it.each([
-    ['maxImagesPerRequest', 0, /maxImagesPerRequest must be a positive safe integer/],
-    ['maxImagesPerRequest', 1.5, /maxImagesPerRequest must be a positive safe integer/],
-    ['imageOffloadByteQuantum', 0, /imageOffloadByteQuantum must be a positive safe integer/],
-    ['imageOffloadByteQuantum', Number.MAX_SAFE_INTEGER + 1, /imageOffloadByteQuantum must be a positive safe integer/],
-    ['inlineImageOffloadByteQuantum', 0, /inlineImageOffloadByteQuantum must be a positive safe integer/],
-    ['inlineImageOffloadByteQuantum', Number.MAX_SAFE_INTEGER + 1, /inlineImageOffloadByteQuantum must be a positive safe integer/],
-    ['imageOffloadCountQuantum', 0, /imageOffloadCountQuantum must be a positive safe integer/],
-    ['imageOffloadCountQuantum', 1.5, /imageOffloadCountQuantum must be a positive safe integer/],
-    ['fileExpiresAfterSeconds', 3_599, /fileExpiresAfterSeconds must be an integer from 3600 through 2592000/],
-    ['fileExpiresAfterSeconds', 2_592_001, /fileExpiresAfterSeconds must be an integer from 3600 through 2592000/],
-    ['fileRefreshMarginSeconds', -1, /fileRefreshMarginSeconds must be a non-negative integer/],
-    ['fileRefreshMarginSeconds', 604_800, /fileRefreshMarginSeconds must be a non-negative integer/],
-    ['fileQuotaCleanupBatch', 0, /fileQuotaCleanupBatch must be an integer from 1 through 1000/],
-    ['fileQuotaCleanupBatch', 1_001, /fileQuotaCleanupBatch must be an integer from 1 through 1000/],
-  ] as const)('rejects %s=%s', (field, value, message) => {
-    expect(() => resolveAdapterOptions({ [field]: value })).toThrow(message)
-  })
-
-  it.each([0, 1.5, Number.MAX_SAFE_INTEGER + 1])(
-    'rejects invalid request file bound %s',
-    async (maxRequestFilesBytes) => {
-      expect(() => resolveAdapterOptions({ maxRequestFilesBytes }))
-        .toThrow(/maxRequestFilesBytes must be a positive safe integer/)
-
-      const ctx = new Context()
-      await ctx.plugin(LlmRuntime)
-      await expect(ctx.plugin(LlmDeepSeek, {
-        protocol: 'chat-completions',
-        baseURL: 'http://127.0.0.1:1',
-        maxRequestFilesBytes,
-      })).rejects.toThrow(/maxRequestFilesBytes/)
-      expect(ctx.llm.listProviders()).toEqual([])
-    },
-  )
-
-  it.each([0, 1.5, Number.MAX_SAFE_INTEGER + 1])(
-    'rejects invalid inline request image bound %s',
-    async (maxInlineRequestImageBytes) => {
-      expect(() => resolveAdapterOptions({ maxInlineRequestImageBytes }))
-        .toThrow(/maxInlineRequestImageBytes must be a positive safe integer/)
-
-      const ctx = new Context()
-      await ctx.plugin(LlmRuntime)
-      await expect(ctx.plugin(LlmDeepSeek, {
-        protocol: 'chat-completions',
-        baseURL: 'http://127.0.0.1:1',
-        maxInlineRequestImageBytes,
-      })).rejects.toThrow(/maxInlineRequestImageBytes/)
-      expect(ctx.llm.listProviders()).toEqual([])
-    },
-  )
-
-  it('falls back to DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL env vars', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
-    vi.stubEnv('DEEPSEEK_BASE_URL', 'http://127.0.0.1:1')
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions' })
-    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
-  })
-
-  it('loads keyless, keeps the catalog browsable, and fails the request actionably', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: 'http://127.0.0.1:1' })
-    // First-boot onboarding: the route registers so models stay discoverable;
-    // only the request itself needs a key.
-    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
-    await expect(ctx.llm.listModels('deepseek-official')).resolves.toHaveLength(2)
-    const first = await assemble(ctx, { model: 'deepseek-flash', messages: [] })
-    expect(first.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
-    // The guidance leads with the managed credential store.
-    const second = await assemble(ctx, { model: 'deepseek-flash', messages: [] })
-    expect(second.finish.kind).toBe('error')
-    if (second.finish.kind !== 'error') throw new Error('expected an error finish')
-    // The guidance names both places a credential can come from, and nothing
-    // else: configuration carries the reference, never a literal key.
-    expect(second.finish.failure.message)
-      .toMatch(/store DEEPSEEK_API_KEY through the credentials service.*export DEEPSEEK_API_KEY/s)
-  })
-
-  it('reads the ambient variable when no credentials seam is mounted', async () => {
-    // The plain cordis.yml composition: no credential provider, the key in
-    // the launching environment.
-    vi.stubEnv('DEEPSEEK_API_KEY', 'ambient-key')
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: server.url })
-    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(server.headers[0]?.authorization).toBe('Bearer ambient-key')
-  })
-
-  it('treats an empty ambient variable as no key when no credentials seam is mounted', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: 'http://127.0.0.1:1' })
-    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(result.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
-  })
-
-  it('prefers explicit config over env for key and base URL', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
-    vi.stubEnv('DEEPSEEK_BASE_URL', 'http://env-host:1')
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const ctx = await harness(server.url) // harness passes explicit config
-    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(server.requests).toHaveLength(1) // hit the explicit URL, not env
-  })
-
-  it('uses DEEPSEEK_BASE_URL when config omits baseURL', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    vi.stubEnv('DEEPSEEK_BASE_URL', server.url)
-    vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions' })
-    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-    expect(server.requests).toHaveLength(1)
-  })
-
-
-  it('takes DEEPSEEK_BASE_URL from any environment layer, with explicit config still on top', () => {
-    const trusted = createLaunchEnvironmentSnapshot([
-      { source: 'user-env', path: '/home/.dsh/.env', values: { DEEPSEEK_BASE_URL: 'https://user.example' } },
-    ])
-    expect(resolveAdapterOptions({}, trusted).baseURL).toBe('https://user.example')
-    // The product trusts the project it is launched in, so a checkout can
-    // point its own agent at the gateway that checkout is meant to use.
-    const project = createLaunchEnvironmentSnapshot([
-      { source: 'project-env', path: '/work/.env', values: { DEEPSEEK_BASE_URL: 'https://project.example' } },
-    ])
-    expect(resolveAdapterOptions({}, project).baseURL).toBe('https://project.example')
-    // An explicitly configured endpoint outranks every environment layer, so a
-    // stale shell value cannot rewrite a deployment's own gateway.
-    const shell = createLaunchEnvironmentSnapshot([
-      { source: 'process', values: { DEEPSEEK_BASE_URL: 'https://stale.example' } },
-    ])
-    expect(resolveAdapterOptions({ baseURL: 'https://gateway.internal' }, shell).baseURL).toBe('https://gateway.internal')
-  })
-  it('uses the public Chat base URL when selected without an endpoint override', async () => {
-    vi.stubEnv('DEEPSEEK_API_KEY', 'k')
-    vi.stubEnv('DEEPSEEK_BASE_URL', undefined)
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    // Registration succeeds; no call is made (would hit api.deepseek.com).
-    await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions' })
-    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
-  })
-
-  it('adapter is constructible directly for embedding over the shared resolver', async () => {
-    const adapter = adapterOf()
-    expect(adapter).toBeInstanceOf(DeepSeekAdapter)
-    // Direct embedding shares the plugin's one resolve step, so it advertises
-    // the same default catalog instead of a divergent empty one.
-    await expect(adapter.listModels('deepseek-official')).resolves.toHaveLength(2)
-  })
-
-  it('resolves connection facts and the credential exactly once per stream call', async () => {
-    const server = await mockServer([{ kind: 'sse', events: textEvents }])
-    const options = vi.fn(() => resolveAdapterOptions({ protocol: 'chat-completions', baseURL: server.url }))
-    const resolveApiKey = vi.fn(() => Promise.resolve('per-request-key'))
-    const resolveUserId = vi.fn(() => TEST_USER_ID)
-    const adapter = new DeepSeekAdapter({ options, resolveApiKey, resolveUserId, prepareExtensions: noExtensions })
-
-    for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
-
-    expect(options).toHaveBeenCalledTimes(1)
-    expect(resolveApiKey).toHaveBeenCalledTimes(1)
-    expect(resolveUserId).toHaveBeenCalledTimes(1)
-    expect(server.headers[0]?.authorization).toBe('Bearer per-request-key')
-  })
-
-  it('rejects invalid idle watchdog bounds for direct and plugin composition', async () => {
-    expect(() => resolveAdapterOptions({ streamIdleTimeoutMs: Number.POSITIVE_INFINITY }))
-      .toThrow(/streamIdleTimeoutMs.*positive finite/)
-    expect(() => resolveAdapterOptions({ streamIdleTimeoutMs: MAX_TIMER_DELAY_MS + 1 }))
-      .toThrow(/streamIdleTimeoutMs.*no greater/)
-
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      streamIdleTimeoutMs: 0,
-    })).rejects.toThrow(/streamIdleTimeoutMs/)
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      streamIdleTimeoutMs: MAX_TIMER_DELAY_MS + 1,
-    })).rejects.toThrow(/streamIdleTimeoutMs/)
-  })
-
-  it('validates Files API timeout bounds independently of the stream idle deadline', async () => {
-    expect(() => resolveAdapterOptions({ filesApiTimeoutMs: Number.POSITIVE_INFINITY }))
-      .toThrow(/filesApiTimeoutMs.*positive finite/)
-    expect(() => resolveAdapterOptions({ filesApiTimeoutMs: MAX_TIMER_DELAY_MS + 1 }))
-      .toThrow(/filesApiTimeoutMs.*no greater/)
-
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      filesApiTimeoutMs: 0,
-    })).rejects.toThrow(/filesApiTimeoutMs/)
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      filesApiTimeoutMs: MAX_TIMER_DELAY_MS + 1,
-    })).rejects.toThrow(/filesApiTimeoutMs/)
-    expect(resolveAdapterOptions({ filesApiTimeoutMs: 100, streamIdleTimeoutMs: 100 }))
-      .toMatchObject({ filesApiTimeoutMs: 100, streamIdleTimeoutMs: 100 })
-  })
-
-  it('rejects invalid nested retryPolicy before registering the provider', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmRuntime)
-
-    await expect(ctx.plugin(LlmDeepSeek, {
-      protocol: 'chat-completions',
-      baseURL: 'http://127.0.0.1:1',
-      retryPolicy: { mode: 'normal', maxRetries: -1 },
-    })).rejects.toThrow(/retryPolicy/)
-    expect(ctx.llm.listProviders()).toEqual([])
   })
 })
diff --git a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
index 7288bb9bfb..9872b90f89 100644
--- a/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-deepseek/tests/dynamic-config.spec.ts
@@ -131,7 +131,7 @@ async function boot(dir: string, config: object): Promise<Harness> {
   const settingsFiber = ctx.plugin(FileSettingsProvider, { path: join(dir, 'settings.yaml'), watch: false })
   await settingsFiber
   await ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
-  await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', ...config })
+  await ctx.plugin(LlmDeepSeek, { ...config })
   return { ctx, settingsFiber }
 }
 
@@ -149,7 +149,7 @@ describe('request-level dynamic configuration', () => {
     const { ctx } = await boot(dir, { baseURL: serverA.url })
 
     await prompt(ctx)
-    expect(serverA.headers[0]?.authorization).toBe('Bearer first-key')
+    expect(serverA.headers[0]?.['x-api-key']).toBe('first-key')
 
     await ctx.settings.update(NS, { baseURL: serverB.url })
     await ctx.credentials.set(KEY_REF, 'second-key')
@@ -157,7 +157,7 @@ describe('request-level dynamic configuration', () => {
     await prompt(ctx)
     // No restart, no re-registration: the next request resolved both facts.
     expect(serverA.requests).toHaveLength(1)
-    expect(serverB.headers[0]?.authorization).toBe('Bearer second-key')
+    expect(serverB.headers[0]?.['x-api-key']).toBe('second-key')
   })
 
   it('starts keyless and serves the next request once the key arrives', async () => {
@@ -171,7 +171,7 @@ describe('request-level dynamic configuration', () => {
     await expect(access(join(dir, '.anonymous-user-id'))).rejects.toMatchObject({ code: 'ENOENT' })
     await ctx.credentials.set(KEY_REF, 'sk-arrived')
     await prompt(ctx)
-    expect(server.headers[0]?.authorization).toBe('Bearer sk-arrived')
+    expect(server.headers[0]?.['x-api-key']).toBe('sk-arrived')
     await expect(access(join(dir, '.anonymous-user-id'))).resolves.toBeUndefined()
   })
 
@@ -246,10 +246,10 @@ describe('request-level dynamic configuration', () => {
     const first = (server.requests[0] as { messages: Array<{ content: unknown }> }).messages[0]?.content
     const second = (server.requests[1] as { messages: Array<{ content: unknown }> }).messages[0]?.content
     expect(server.requests).toHaveLength(2)
-    expect(JSON.stringify(first).match(/"type":"file"/g)).toHaveLength(2)
+    expect(JSON.stringify(first).match(/"type":"image"/g)).toHaveLength(2)
     expect(JSON.stringify(second)).toContain('[image omitted to fit request image limits')
     expect(JSON.stringify(second)).toContain(MODEL_IMAGE_PATH)
-    expect(JSON.stringify(second).match(/"type":"file"/g)).toHaveLength(1)
+    expect(JSON.stringify(second).match(/"type":"image"/g)).toHaveLength(1)
   })
   it('re-registers the route in place when the captured retry policy changes, without an empty-registry window', async () => {
     const dir = await home()
@@ -309,7 +309,29 @@ describe('request-level dynamic configuration', () => {
     // regression this pins — not its key either.
     expect(rejected.requests).toHaveLength(0)
     expect(good.requests).toHaveLength(1)
-    expect(good.headers[0]?.authorization).toBe('Bearer good-key')
+    expect(good.headers[0]?.['x-api-key']).toBe('good-key')
+  })
+
+  it.each(['messages', 'chat-completions'])('rejects a persisted protocol=%s section and recovers after removing the field', async (protocol) => {
+    const dir = await home()
+    const composition = await mockServer([{ kind: 'sse', events: textEvents }])
+    const repaired = await mockServer([{ kind: 'sse', events: textEvents }])
+    vi.stubEnv('DEEPSEEK_API_KEY', 'composition-key')
+    vi.stubEnv('REPAIRED_DEEPSEEK_KEY', 'repaired-key')
+    const section = { baseURL: repaired.url, apiKeyEnv: 'REPAIRED_DEEPSEEK_KEY' }
+    await writeFile(join(dir, 'settings.yaml'), JSON.stringify({ [NS]: { ...section, protocol } }))
+    const { ctx } = await boot(dir, { baseURL: composition.url })
+
+    await prompt(ctx)
+    expect(composition.requests).toHaveLength(1)
+    expect(composition.headers[0]?.['x-api-key']).toBe('composition-key')
+    expect(repaired.requests).toHaveLength(0)
+
+    await ctx.settings.replace(NS, section)
+    await prompt(ctx)
+    expect(repaired.requests).toHaveLength(1)
+    expect(repaired.headers[0]?.['x-api-key']).toBe('repaired-key')
+    expect(ctx.settings.get(NS)).not.toHaveProperty('protocol')
   })
 
   it('falls back to the composition entry when settings detach', async () => {
@@ -327,6 +349,6 @@ describe('request-level dynamic configuration', () => {
     await settingsFiber.dispose()
     await prompt(ctx)
     expect(serverA.requests).toHaveLength(1)
-    expect(serverA.headers[0]?.authorization).toBe('Bearer steady-key')
+    expect(serverA.headers[0]?.['x-api-key']).toBe('steady-key')
   })
 })
diff --git a/packages/llm/llm-deepseek/tests/egress.spec.ts b/packages/llm/llm-deepseek/tests/egress.spec.ts
index 61629ef425..3a74a50cb8 100644
--- a/packages/llm/llm-deepseek/tests/egress.spec.ts
+++ b/packages/llm/llm-deepseek/tests/egress.spec.ts
@@ -51,19 +51,19 @@ afterAll(() => {
   rmSync(home, { recursive: true, force: true })
 })
 
-/** Drive the shipping adapter's chat-completions request at an unresolvable endpoint. */
+/** Drive the shipping adapter's Messages request at an unresolvable endpoint. */
 async function streamOnce(): Promise<void> {
   const ctx = new Context()
   await ctx.plugin(LlmRuntime)
   await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
-  await ctx.plugin(LlmDeepSeek, { protocol: 'chat-completions', baseURL: 'http://deepseek-probe.invalid/v1', models: [{ id: 'm' }] })
+  await ctx.plugin(LlmDeepSeek, { baseURL: 'http://deepseek-probe.invalid/v1', models: [{ id: 'm' }] })
   for await (const _chunk of ctx.llm.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) {
     // The endpoint never answers; the proxy record is the assertion.
   }
 }
 
 describe('llm-deepseek egress', () => {
-  it('sends the chat-completions request through the proxy', async () => {
+  it('sends the Messages request through the proxy', async () => {
     const observed = await observe(streamOnce)
     expect(observed.join('|')).toContain('deepseek-probe.invalid')
   })
diff --git a/packages/llm/llm-deepseek/tests/messages/expected/degraded-replay.json b/packages/llm/llm-deepseek/tests/expected/degraded-replay.json
similarity index 100%
rename from packages/llm/llm-deepseek/tests/messages/expected/degraded-replay.json
rename to packages/llm/llm-deepseek/tests/expected/degraded-replay.json
diff --git a/packages/llm/llm-deepseek/tests/messages/extensions.spec.ts b/packages/llm/llm-deepseek/tests/extensions.spec.ts
similarity index 99%
rename from packages/llm/llm-deepseek/tests/messages/extensions.spec.ts
rename to packages/llm/llm-deepseek/tests/extensions.spec.ts
index 29c2ce10c0..66256ce5df 100644
--- a/packages/llm/llm-deepseek/tests/messages/extensions.spec.ts
+++ b/packages/llm/llm-deepseek/tests/extensions.spec.ts
@@ -8,7 +8,7 @@ import LlmRuntime from '@deepseek-ai/dsh-llm'
 import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
 import type { DeepSeekLlmApiExtensionRequest } from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import * as DeepSeek from '../../src/index.ts'
+import * as DeepSeek from '../src/index.ts'
 import { assemble, options, sse, textEvents } from './helpers.ts'
 
 declare module '@deepseek-ai/dsh-deepseek-llm-api-extensions' {
diff --git a/packages/llm/llm-deepseek/tests/file-store.spec.ts b/packages/llm/llm-deepseek/tests/file-store.spec.ts
index 10af67203a..a671607788 100644
--- a/packages/llm/llm-deepseek/tests/file-store.spec.ts
+++ b/packages/llm/llm-deepseek/tests/file-store.spec.ts
@@ -4,9 +4,9 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
 import type { ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import { DeepSeekFileStore, MAX_IMAGE_BYTES } from '../src/common/file-store.ts'
-import { DeepSeekFileId } from '../src/common/file-id.ts'
-import { deepSeekFileScope, DeepSeekUploadIndex } from '../src/common/upload-index.ts'
+import { DeepSeekFileStore, MAX_IMAGE_BYTES } from '../src/file-store.ts'
+import { DeepSeekFileId } from '../src/file-id.ts'
+import { deepSeekFileScope, DeepSeekUploadIndex } from '../src/upload-index.ts'
 
 const REF: ImageAttachmentRef = {
   attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`),
@@ -27,7 +27,7 @@ const VERSION: RequestImageAttachment = {
   space: 'srgb',
   hasAlpha: true,
 }
-const CONNECTION = { protocol: 'chat-completions' as const, baseURL: 'https://api.deepseek.com', apiKey: 'key' }
+const CONNECTION = { baseURL: 'https://api.deepseek.com', apiKey: 'key' }
 const POLICY = { expiresAfterSeconds: 604_800, refreshMarginSeconds: 3_600, quotaCleanupBatch: 100 }
 const NOW = 1_700_000_000_000
 
@@ -50,17 +50,16 @@ function uploadFetch(now: () => number = () => NOW) {
       const createdAt = now() / 1_000
       return new Response(JSON.stringify({
         id: `file-api-${uploads}`,
-        object: 'file',
-        bytes: 3,
-        created_at: createdAt,
+        type: 'file',
+        size_bytes: 3,
+        created_at: new Date(createdAt * 1_000).toISOString(),
         filename: `dsh-${'a'.repeat(16)}-${'b'.repeat(8)}.png`,
-        purpose: 'user_data',
-        expires_at: createdAt + POLICY.expiresAfterSeconds,
+        mime_type: 'image/png',
       }), { status: 200 })
     }
     if (init?.method === 'DELETE') {
       const id = requestUrl(_url).split('/').at(-1)
-      return new Response(JSON.stringify({ id, object: 'file', deleted: true }), { status: 200 })
+      return new Response(JSON.stringify({ id, type: 'file_deleted' }), { status: 200 })
     }
     throw new Error('unexpected Files API request')
   }) as typeof fetch
@@ -68,42 +67,34 @@ function uploadFetch(now: () => number = () => NOW) {
 }
 
 describe('DeepSeekFileStore', () => {
-  it('separates native Files reuse, invalidation, and expiry from the chat namespace', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'dsh-native-file-store-'))
+  it('reuses equivalent API roots and isolates other endpoints across invalidation and expiry', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-file-scope-'))
     roots.push(dir)
     let now = NOW
-    let uploads = 0
-    const fetchImpl: typeof fetch = async (input, init) => {
-      if (init?.method !== 'POST') throw new Error('only uploads expected')
-      uploads++
-      const common = { id: `file-${uploads}`, filename: 'dsh-image.png' }
-      return new Response(JSON.stringify(requestUrl(input).includes('/v1/files')
-        ? { ...common, type: 'file', size_bytes: VERSION.bytes, created_at: new Date(now).toISOString(), mime_type: VERSION.mediaType }
-        : { ...common, object: 'file', bytes: VERSION.bytes, created_at: now / 1_000, expires_at: now / 1_000 + POLICY.expiresAfterSeconds, purpose: 'user_data' }))
-    }
+    const remote = uploadFetch(() => now)
     const index = new DeepSeekUploadIndex(join(dir, 'index.json'))
-    const store = new DeepSeekFileStore({ index, fetch: fetchImpl, now: () => now })
-    const native = { ...CONNECTION, protocol: 'messages' as const }
-    const chat = await store.ensureUploaded(VERSION, CONNECTION, POLICY)
-    const first = await store.ensureUploaded(VERSION, native, POLICY)
+    const store = new DeepSeekFileStore({ index, fetch: remote.fetchImpl, now: () => now })
+    const alternate = { ...CONNECTION, baseURL: 'https://other.example' }
+    const other = await store.ensureUploaded(VERSION, alternate, POLICY)
+    const first = await store.ensureUploaded(VERSION, CONNECTION, POLICY)
     expect(first.record.scope).toBe(deepSeekFileScope(`${CONNECTION.baseURL}/v1`, CONNECTION.apiKey))
-    expect(first.record.scope).not.toBe(chat.record.scope)
-    expect((await store.ensureUploaded(VERSION, { ...native, baseURL: `${native.baseURL}/v1/` }, POLICY)).record).toEqual(first.record)
-    const reopened = new DeepSeekFileStore({ index, fetch: fetchImpl, now: () => now })
-    expect((await reopened.ensureUploaded(VERSION, native, POLICY)).record).toEqual(first.record)
-    await reopened.invalidate(VERSION, chat.record.fileId, native)
-    expect((await reopened.ensureUploaded(VERSION, native, POLICY)).record).toEqual(first.record)
-    expect(uploads).toBe(2)
-    await reopened.invalidate(VERSION, first.record.fileId, native)
-    const replacement = await reopened.ensureUploaded(VERSION, native, POLICY)
+    expect(first.record.scope).not.toBe(other.record.scope)
+    expect((await store.ensureUploaded(VERSION, { ...CONNECTION, baseURL: `${CONNECTION.baseURL}/v1/` }, POLICY)).record).toEqual(first.record)
+    const reopened = new DeepSeekFileStore({ index, fetch: remote.fetchImpl, now: () => now })
+    expect((await reopened.ensureUploaded(VERSION, CONNECTION, POLICY)).record).toEqual(first.record)
+    await reopened.invalidate(VERSION, other.record.fileId, CONNECTION)
+    expect((await reopened.ensureUploaded(VERSION, CONNECTION, POLICY)).record).toEqual(first.record)
+    expect(remote.uploads()).toBe(2)
+    await reopened.invalidate(VERSION, first.record.fileId, CONNECTION)
+    const replacement = await reopened.ensureUploaded(VERSION, CONNECTION, POLICY)
     expect(replacement.record.fileId).not.toBe(first.record.fileId)
-    expect((await reopened.ensureUploaded(VERSION, CONNECTION, POLICY)).record).toEqual(chat.record)
-    expect(uploads).toBe(3)
+    expect((await reopened.ensureUploaded(VERSION, alternate, POLICY)).record).toEqual(other.record)
+    expect(remote.uploads()).toBe(3)
     now = replacement.record.expiresAt - POLICY.refreshMarginSeconds * 1_000
-    const refreshed = await reopened.ensureUploaded(VERSION, native, POLICY)
+    const refreshed = await reopened.ensureUploaded(VERSION, CONNECTION, POLICY)
     expect(refreshed.record.fileId).not.toBe(replacement.record.fileId)
     expect(refreshed.record.expiresAt).toBe(now + POLICY.expiresAfterSeconds * 1_000)
-    expect(uploads).toBe(4)
+    expect(remote.uploads()).toBe(4)
   })
 
   it('reclaims the oldest owned native file across descending pages before retrying an upload', async () => {
@@ -135,7 +126,7 @@ describe('DeepSeekFileStore', () => {
         : { data: [file('oldest-owned', 3_000), file('foreign', 4_000, 'user-file.png')], has_more: false }))
     }
     const store = new DeepSeekFileStore({ index: new DeepSeekUploadIndex(join(dir, 'index.json')), fetch: fetchImpl, now: () => NOW })
-    await expect(store.ensureUploaded(VERSION, { ...CONNECTION, protocol: 'messages' }, { ...POLICY, quotaCleanupBatch: 1 })).resolves.toMatchObject({ record: { fileId: 'file-uploaded' } })
+    await expect(store.ensureUploaded(VERSION, CONNECTION, { ...POLICY, quotaCleanupBatch: 1 })).resolves.toMatchObject({ record: { fileId: 'file-uploaded' } })
     expect(cursors).toEqual([null, 'middle'])
     expect(deleted).toEqual(['oldest-owned'])
     expect(uploads).toBe(2)
@@ -192,12 +183,11 @@ describe('DeepSeekFileStore', () => {
     expect(uploadSignal?.aborted).toBe(false)
     complete?.(new Response(JSON.stringify({
       id: 'file-api-shared',
-      object: 'file',
-      bytes: 3,
-      created_at: NOW / 1_000,
+      type: 'file',
+      size_bytes: 3,
+      created_at: new Date(NOW).toISOString(),
       filename: `dsh-${'a'.repeat(16)}-${'b'.repeat(8)}.png`,
-      purpose: 'user_data',
-      expires_at: NOW / 1_000 + POLICY.expiresAfterSeconds,
+      mime_type: 'image/png',
     }), { status: 200 }))
     await expect(completed).resolves.toMatchObject({ record: { fileId: 'file-api-shared' } })
   })
@@ -273,9 +263,8 @@ describe('DeepSeekFileStore', () => {
         })
       }
       return Promise.resolve(new Response(JSON.stringify({
-        id: 'file-api-retry', object: 'file', bytes: 3, created_at: NOW / 1_000,
-        filename: 'dsh-retry.png', purpose: 'user_data',
-        expires_at: NOW / 1_000 + POLICY.expiresAfterSeconds,
+        id: 'file-api-retry', type: 'file', size_bytes: 3, created_at: new Date(NOW).toISOString(),
+        filename: 'dsh-retry.png', mime_type: 'image/png',
       }), { status: 200 }))
     }) as typeof fetch
     const store = new DeepSeekFileStore({
@@ -295,11 +284,11 @@ describe('DeepSeekFileStore', () => {
     await expect(retried).resolves.toMatchObject({ record: { fileId: 'file-api-retry' } })
   })
 
-  it.each(['chat-completions', 'messages'] as const)('rejects a request version above the %s per-image limit before transport', async (protocol) => {
+  it('rejects a request version above the per-image limit before transport', async () => {
     const fetchImpl = vi.fn() as typeof fetch
     const store = new DeepSeekFileStore({ now: () => NOW, fetch: fetchImpl })
     const oversized = { ...VERSION, bytes: MAX_IMAGE_BYTES + 1 }
-    await expect(store.ensureUploaded(oversized, { ...CONNECTION, protocol }, POLICY))
+    await expect(store.ensureUploaded(oversized, CONNECTION, POLICY))
       .rejects.toMatchObject({ code: 'INVALID_REQUEST', message: 'DeepSeek image exceeds the 32 MiB per-image limit.' })
     expect(fetchImpl).not.toHaveBeenCalled()
   })
@@ -329,9 +318,8 @@ describe('DeepSeekFileStore', () => {
     const dir = await mkdtemp(join(tmpdir(), 'dsh-file-store-'))
     roots.push(dir)
     const fetchImpl = vi.fn(() => Promise.resolve(new Response(JSON.stringify({
-      id: 'file-api-wrong-size', object: 'file', bytes: 2, created_at: NOW / 1_000,
-      filename: 'dsh-wrong.png', purpose: 'user_data',
-      expires_at: NOW / 1_000 + POLICY.expiresAfterSeconds,
+      id: 'file-api-wrong-size', type: 'file', size_bytes: 2, created_at: new Date(NOW).toISOString(),
+      filename: 'dsh-wrong.png', mime_type: 'image/png',
     }), { status: 200 }))) as typeof fetch
     const store = new DeepSeekFileStore({
       index: new DeepSeekUploadIndex(join(dir, 'index.json')),
@@ -377,7 +365,7 @@ describe('DeepSeekFileStore', () => {
     })
   })
 
-  it('reuses local expires_at above the refresh margin and uploads again at the margin', async () => {
+  it('reuses the local expiry above the refresh margin and uploads again at the margin', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'dsh-file-store-'))
     roots.push(dir)
     const index = new DeepSeekUploadIndex(join(dir, 'index.json'))
@@ -418,7 +406,7 @@ describe('DeepSeekFileStore', () => {
     vi.spyOn(index, 'commit').mockResolvedValue({
       accepted: false,
       record: {
-        scope: deepSeekFileScope(CONNECTION.baseURL, CONNECTION.apiKey),
+        scope: deepSeekFileScope(`${CONNECTION.baseURL}/v1`, CONNECTION.apiKey),
         attachmentId: VERSION.attachment.attachmentId,
         variantId: VERSION.variantId,
         fileId: DeepSeekFileId('file-api-winner'),
@@ -452,22 +440,20 @@ describe('DeepSeekFileStore', () => {
           error: { message: 'stored file quota exceeded', code: 'file_quota' },
         }), { status: 400 }))
         return Promise.resolve(new Response(JSON.stringify({
-          id: 'file-api-recovered', object: 'file', bytes: 3, created_at: NOW / 1_000,
-          filename: 'dsh-recovered.png', purpose: 'user_data',
-          expires_at: NOW / 1_000 + POLICY.expiresAfterSeconds,
+          id: 'file-api-recovered', type: 'file', size_bytes: 3, created_at: new Date(NOW).toISOString(),
+          filename: 'dsh-recovered.png', mime_type: 'image/png',
         }), { status: 200 }))
       }
       if (init?.method === 'DELETE') {
         return Promise.resolve(new Response(JSON.stringify({
-          id: 'file-api-old', object: 'file', deleted: true,
+          id: 'file-api-old', type: 'file_deleted',
         }), { status: 200 }))
       }
-      expect(new URL(requestUrl(input)).pathname).toBe('/files')
+      expect(new URL(requestUrl(input)).pathname).toBe('/v1/files')
       return Promise.resolve(new Response(JSON.stringify({
-        object: 'list',
         data: [{
-          id: 'file-api-old', object: 'file', bytes: 3, created_at: NOW / 1_000,
-          filename: 'dsh-old.png', purpose: 'user_data',
+          id: 'file-api-old', type: 'file', size_bytes: 3, created_at: new Date(NOW).toISOString(),
+          filename: 'dsh-old.png', mime_type: 'image/png',
         }],
         first_id: 'file-api-old', last_id: 'file-api-old', has_more: false,
       }), { status: 200 }))
@@ -492,10 +478,9 @@ describe('DeepSeekFileStore', () => {
         error: { message: 'file count quota exceeded', code: 'file_quota' },
       }), { status: 400 }))
       return Promise.resolve(new Response(JSON.stringify({
-        object: 'list',
         data: [{
-          id: 'file-api-foreign', object: 'file', bytes: 3, created_at: NOW / 1_000,
-          filename: 'foreign.png', purpose: 'user_data',
+          id: 'file-api-foreign', type: 'file', size_bytes: 3, created_at: new Date(NOW).toISOString(),
+          filename: 'foreign.png', mime_type: 'image/png',
         }],
         has_more: false,
       }), { status: 200 }))
@@ -518,20 +503,19 @@ describe('DeepSeekFileStore', () => {
       if (init?.method === 'DELETE') {
         const id = target.pathname.split('/').at(-1) ?? ''
         deleted.add(id)
-        return new Response(JSON.stringify({ id, object: 'file', deleted: true }), { status: 200 })
+        return new Response(JSON.stringify({ id, type: 'file_deleted' }), { status: 200 })
       }
-      const after = target.searchParams.get('after')
+      const after = target.searchParams.get('after_id')
       if (after !== null && deleted.has(after)) throw new Error('deleted cursor cannot be reused')
       const id = after === null ? 'file-api-oldest' : 'file-api-next'
       return new Response(JSON.stringify({
-        object: 'list',
         data: [{
           id,
-          object: 'file',
-          bytes: 3,
-          created_at: NOW / 1_000,
+          type: 'file',
+          size_bytes: 3,
+          created_at: new Date(NOW).toISOString(),
           filename: `dsh-${id}.png`,
-          purpose: 'user_data',
+          mime_type: 'image/png',
         }],
         first_id: id,
         last_id: id,
@@ -556,12 +540,12 @@ describe('DeepSeekFileStore', () => {
       const fetchImpl = vi.fn((input: string | URL | Request, init?: RequestInit) => {
         if (init?.method === 'DELETE') {
           const id = requestUrl(input).split('/').at(-1)
-          return Promise.resolve(new Response(JSON.stringify({ id, object: 'file', deleted: true }), { status: 200 }))
+          return Promise.resolve(new Response(JSON.stringify({ id, type: 'file_deleted' }), { status: 200 }))
         }
         page += 1
         const lastId = mode === 'missing' ? undefined : 'file-api-same'
         return Promise.resolve(new Response(JSON.stringify({
-          object: 'list', data: [], has_more: true,
+          data: [], has_more: true,
           ...lastId === undefined ? {} : { last_id: lastId },
         }), { status: 200 }))
       }) as typeof fetch
diff --git a/packages/llm/llm-deepseek/tests/files-api.spec.ts b/packages/llm/llm-deepseek/tests/files-api.spec.ts
index a23664c85c..daed0ebedf 100644
--- a/packages/llm/llm-deepseek/tests/files-api.spec.ts
+++ b/packages/llm/llm-deepseek/tests/files-api.spec.ts
@@ -2,13 +2,13 @@ import { once } from 'node:events'
 import { createServer } from 'node:http'
 import { describe, expect, it, vi } from 'vitest'
 import { LlmError, userAgent } from '@deepseek-ai/dsh-llm'
-import { DeepSeekFileId } from '../src/common/file-id.ts'
+import { DeepSeekFileId } from '../src/file-id.ts'
 import {
   DeepSeekFilesClient,
   DeepSeekFilesError,
   isFilesQuotaError,
   MAX_FILE_UPLOAD_BYTES,
-} from '../src/common/files-api.ts'
+} from '../src/files-api.ts'
 
 function requestUrl(input: string | URL | Request): string {
   if (typeof input === 'string') return input
@@ -17,28 +17,19 @@ function requestUrl(input: string | URL | Request): string {
 
 function file(overrides: Record<string, unknown> = {}) {
   return {
-    id: 'file-api-one',
-    object: 'file',
-    bytes: 3,
-    created_at: 1_700_000_000,
-    filename: 'image.png',
-    purpose: 'user_data',
-    expires_at: 1_700_604_800,
+    id: 'file-api-one', type: 'file', size_bytes: 3,
+    created_at: '2023-11-14T22:13:20.000Z', filename: 'image.png', mime_type: 'image/png',
     ...overrides,
   }
 }
 
 describe('DeepSeekFilesClient', () => {
-  function messagesFile(overrides: Record<string, unknown> = {}) {
-    return { id: 'file-api-one', type: 'file', size_bytes: 3, created_at: '2026-09-12T13:02:46.677853363+00:00', filename: 'image.png', mime_type: 'image/png', ...overrides }
-  }
-
-  describe.each(['messages', 'chat-completions'] as const)('%s successful response JSON', (protocol) => {
+  describe('successful response JSON', () => {
     it.each((['upload', 'list', 'retrieve', 'delete'] as const).flatMap(operation =>
       ['', '{"id":'].map(body => ({ operation, body })),
     ))('rejects malformed JSON with operation and HTTP status: %j', async ({ operation, body }) => {
       const fetchImpl = vi.fn<typeof fetch>(async () => new Response(body, { status: 200 }))
-      const client = new DeepSeekFilesClient({ protocol, baseURL: 'https://files.example', apiKey: 'test-key', fetch: fetchImpl })
+      const client = new DeepSeekFilesClient({ baseURL: 'https://files.example', apiKey: 'test-key', fetch: fetchImpl })
       const operations = {
         upload: () => client.upload({ data: Uint8Array.of(1), mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds: 3_600 }),
         list: () => client.list(),
@@ -59,7 +50,7 @@ describe('DeepSeekFilesClient', () => {
 
     it.each([new TypeError('body transport failed'), new DOMException('body aborted', 'AbortError')])(
       'preserves a non-JSON body-read failure: %s', async (failure) => {
-        const client = new DeepSeekFilesClient({ protocol, baseURL: 'https://files.example', apiKey: 'test-key',
+        const client = new DeepSeekFilesClient({ baseURL: 'https://files.example', apiKey: 'test-key',
           fetch: async () => new Response(new ReadableStream({ start(controller) { controller.error(failure) } })),
         })
         await expect(client.retrieve(DeepSeekFileId('file-api-one'))).rejects.toBe(failure)
@@ -79,20 +70,20 @@ describe('DeepSeekFilesClient', () => {
       expect(form.get('purpose')).toBeNull()
       expect(form.get('expires_after[anchor]')).toBe('created_at')
       expect(form.get('expires_after[seconds]')).toBe('3600')
-      return new Response(JSON.stringify(messagesFile()))
+      return new Response(JSON.stringify(file()))
     }) as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL: 'https://gateway.example/custom/route///', apiKey: 'key', fetch: fetchImpl })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://gateway.example/custom/route///', apiKey: 'key', fetch: fetchImpl })
     const uploaded = await client.upload({ data: Uint8Array.of(1, 2, 3), mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds: 3_600 })
-    const createdAt = Math.floor(Date.parse('2026-09-12T13:02:46.677Z') / 1_000)
-    expect(uploaded).toEqual({ id: 'file-api-one', bytes: 3, createdAt, filename: 'image.png', purpose: 'user_data', expiresAt: createdAt + 3_600 })
+    const createdAt = Math.floor(Date.parse('2023-11-14T22:13:20.000Z') / 1_000)
+    expect(uploaded).toEqual({ id: 'file-api-one', bytes: 3, createdAt, filename: 'image.png', expiresAt: createdAt + 3_600 })
   })
 
   it.each([
     ['https://provider.example/anthropic/v1', 'https://provider.example/anthropic/v1/files'],
     ['https://provider.example/v1beta/', 'https://provider.example/v1beta/v1/files'],
   ])('resolves the Messages Files endpoint from %s', async (baseURL, expected) => {
-    const fetchImpl = vi.fn<typeof fetch>(async () => new Response(JSON.stringify(messagesFile())))
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL, apiKey: 'key', fetch: fetchImpl })
+    const fetchImpl = vi.fn<typeof fetch>(async () => new Response(JSON.stringify(file())))
+    const client = new DeepSeekFilesClient({ baseURL, apiKey: 'key', fetch: fetchImpl })
 
     await client.upload({
       data: Uint8Array.of(1, 2, 3), mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds: 3_600,
@@ -102,42 +93,42 @@ describe('DeepSeekFilesClient', () => {
     expect(requestUrl(fetchImpl.mock.calls[0]![0])).toBe(expected)
   })
 
-  it('maps Messages list cursors, file metadata and deletion without OpenAI-only fields', async () => {
+  it('maps Messages list cursors, file metadata and deletion with native metadata', async () => {
     const fetchImpl = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
       const url = new URL(requestUrl(input))
       if (url.search) {
         expect(Object.fromEntries(url.searchParams)).toEqual({ after_id: 'file-before', limit: '1000' })
-        return new Response(JSON.stringify({ data: [messagesFile()], first_id: 'file-api-one', last_id: 'file-api-one', has_more: false }))
+        return new Response(JSON.stringify({ data: [file()], first_id: 'file-api-one', last_id: 'file-api-one', has_more: false }))
       }
       expect(url.pathname).toBe('/anthropic/v1/files/file-api-one')
-      return new Response(JSON.stringify(init?.method === 'DELETE' ? { id: 'file-api-one', type: 'file_deleted' } : messagesFile()))
+      return new Response(JSON.stringify(init?.method === 'DELETE' ? { id: 'file-api-one', type: 'file_deleted' } : file()))
     }) as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL: 'https://api.deepseek.com/anthropic', apiKey: 'key', fetch: fetchImpl })
-    await expect(client.list({ after: DeepSeekFileId('file-before'), limit: 1_000, order: 'asc' })).resolves.toMatchObject({ data: [{ bytes: 3 }], hasMore: false })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com/anthropic', apiKey: 'key', fetch: fetchImpl })
+    await expect(client.list({ after: DeepSeekFileId('file-before'), limit: 1_000 })).resolves.toMatchObject({ data: [{ bytes: 3 }], hasMore: false })
     await expect(client.retrieve(DeepSeekFileId('file-api-one'))).resolves.toMatchObject({ id: 'file-api-one', bytes: 3 })
     await expect(client.delete(DeepSeekFileId('file-api-one'))).resolves.toBeUndefined()
   })
 
   it('accepts an empty Messages list with null cursors', async () => {
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL: 'https://gateway.example', apiKey: 'key',
+    const client = new DeepSeekFilesClient({ baseURL: 'https://gateway.example', apiKey: 'key',
       fetch: async () => new Response(JSON.stringify({ data: [], first_id: null, last_id: null, has_more: false })),
     })
     await expect(client.list()).resolves.toEqual({ data: [], hasMore: false })
   })
 
   it.each(['first_id', 'last_id'])('rejects a Messages list with a numeric %s', async (cursor) => {
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL: 'https://gateway.example', apiKey: 'key',
+    const client = new DeepSeekFilesClient({ baseURL: 'https://gateway.example', apiKey: 'key',
       fetch: async () => new Response(JSON.stringify({ data: [], first_id: null, last_id: null, has_more: false, [cursor]: 1 })),
     })
     await expect(client.list()).rejects.toMatchObject({ code: 'INVALID_RESPONSE' })
   })
 
-  it.for(['messages', 'chat-completions'] as const)('refuses a redirected %s Files request before contacting another origin', async (protocol, { onTestFinished }) => {
+  it('refuses a redirected Files request before contacting another origin', async ({ onTestFinished }) => {
     const forwarded: string[] = []
     const origins: string[] = []
     const destination = createServer((request, response) => {
       forwarded.push(String(request.headers['x-api-key'] ?? request.headers.authorization))
-      response.end(JSON.stringify(protocol === 'messages' ? messagesFile() : file()))
+      response.end(JSON.stringify(file()))
     })
     const source = createServer((_request, response) => {
       response.writeHead(307, { location: `${origins[0]}/file-api-one` })
@@ -159,37 +150,37 @@ describe('DeepSeekFilesClient', () => {
       if (address === null || typeof address === 'string') throw new Error('expected a TCP server address')
       origins.push(`http://127.0.0.1:${address.port}`)
     }
-    const client = new DeepSeekFilesClient({ protocol, baseURL: origins[1]!, apiKey: 'redirect-test-key' })
+    const client = new DeepSeekFilesClient({ baseURL: origins[1]!, apiKey: 'redirect-test-key' })
     const error = await client.retrieve(DeepSeekFileId('file-api-one')).catch((cause: unknown) => cause)
     expect(forwarded).toEqual([])
     expect(error).toMatchObject({ code: 'TRANSPORT' })
   })
 
   it.each([null, [], { type: 'wrong' }, { mime_type: null }, { created_at: 'invalid' }, { created_at: 123 }, { size_bytes: -1 }])('rejects malformed Messages file metadata %#', async (value) => {
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL: 'https://gateway.example', apiKey: 'key',
-      fetch: async () => new Response(JSON.stringify(value === null || Array.isArray(value) ? value : messagesFile(value))),
+    const client = new DeepSeekFilesClient({ baseURL: 'https://gateway.example', apiKey: 'key',
+      fetch: async () => new Response(JSON.stringify(value === null || Array.isArray(value) ? value : file(value))),
     })
     await expect(client.retrieve(DeepSeekFileId('file-api-one'))).rejects.toMatchObject({ code: 'INVALID_RESPONSE' })
   })
 
   it('rejects a Messages deletion that returns a different file identity', async () => {
-    const client = new DeepSeekFilesClient({ protocol: 'messages', baseURL: 'https://gateway.example', apiKey: 'key',
+    const client = new DeepSeekFilesClient({ baseURL: 'https://gateway.example', apiKey: 'key',
       fetch: async () => new Response(JSON.stringify({ id: 'wrong', type: 'file_deleted' })),
     })
     await expect(client.delete(DeepSeekFileId('file-api-one'))).rejects.toMatchObject({ code: 'INVALID_RESPONSE' })
   })
 
-  it('uploads multipart bytes with the required purpose and explicit expiry', async () => {
+  it('uploads multipart bytes with attribution and explicit expiry', async () => {
     const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
-      expect(requestUrl(url)).toBe('https://api.deepseek.com/files')
+      expect(requestUrl(url)).toBe('https://api.deepseek.com/v1/files')
       expect(init?.method).toBe('POST')
       const headers = new Headers(init?.headers)
-      expect(headers.get('authorization')).toBe('Bearer key')
+      expect(headers.get('x-api-key')).toBe('key')
       expect(headers.get('user-agent')).toBe(userAgent())
       const form = init?.body
       expect(form).toBeInstanceOf(FormData)
       if (!(form instanceof FormData)) throw new Error('expected multipart body')
-      expect(form.get('purpose')).toBe('user_data')
+      expect(form.get('purpose')).toBeNull()
       expect(form.get('expires_after[anchor]')).toBe('created_at')
       expect(form.get('expires_after[seconds]')).toBe('604800')
       const blob = form.get('file')
@@ -197,7 +188,7 @@ describe('DeepSeekFilesClient', () => {
       expect((blob as Blob).size).toBe(3)
       return new Response(JSON.stringify(file()), { status: 200 })
     }) as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com/', apiKey: 'key', fetch: fetchImpl })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com/', apiKey: 'key', fetch: fetchImpl })
 
     await expect(client.upload({
       data: Uint8Array.of(1, 2, 3),
@@ -209,7 +200,6 @@ describe('DeepSeekFilesClient', () => {
       bytes: 3,
       createdAt: 1_700_000_000,
       filename: 'image.png',
-      purpose: 'user_data',
       expiresAt: 1_700_604_800,
     })
   })
@@ -219,40 +209,28 @@ describe('DeepSeekFilesClient', () => {
       const target = requestUrl(url)
       if (target.includes('?')) {
         return new Response(JSON.stringify({
-          object: 'list', data: [file()], first_id: 'file-api-one', last_id: 'file-api-one', has_more: false,
+          data: [file()], first_id: 'file-api-one', last_id: 'file-api-one', has_more: false,
         }), { status: 200 })
       }
       if (init?.method === 'DELETE') {
-        return new Response(JSON.stringify({ id: 'file-api-one', object: 'file', deleted: true }), { status: 200 })
+        return new Response(JSON.stringify({ id: 'file-api-one', type: 'file_deleted' }), { status: 200 })
       }
       return new Response(JSON.stringify(file()), { status: 200 })
     }) as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
 
-    await expect(client.list({ after: DeepSeekFileId('file-api-before'), limit: 20, order: 'desc' })).resolves.toMatchObject({
+    await expect(client.list({ after: DeepSeekFileId('file-api-before'), limit: 20 })).resolves.toMatchObject({
       data: [{ id: 'file-api-one' }], firstId: 'file-api-one', lastId: 'file-api-one', hasMore: false,
     })
     await expect(client.retrieve(DeepSeekFileId('file-api-one'))).resolves.toMatchObject({ id: 'file-api-one' })
     await expect(client.delete(DeepSeekFileId('file-api-one'))).resolves.toBeUndefined()
   })
 
-  it('refuses an upload response that omits the requested expiry', async () => {
-    const fetchImpl = vi.fn(() => Promise.resolve(new Response(
-      JSON.stringify(file({ expires_at: undefined })),
-      { status: 200 },
-    ))) as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
-
-    await expect(client.upload({
-      data: Uint8Array.of(1), mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds: 3_600,
-    })).rejects.toMatchObject({ code: 'INVALID_RESPONSE' })
-  })
-
   it('retains quota error detail for the one cleanup retry policy', async () => {
     const fetchImpl = vi.fn(() => Promise.resolve(new Response(JSON.stringify({
       error: { message: 'user storage quota exceeded', type: 'invalid_request_error', code: 'file_quota' },
     }), { status: 400 }))) as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
 
     const error = await client.upload({
       data: Uint8Array.of(1), mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds: 3_600,
@@ -269,7 +247,6 @@ describe('DeepSeekFilesClient', () => {
     [400, 'FILES_API'],
   ] as const)('classifies HTTP %i Files failures as %s', async (status, code) => {
     const client = new DeepSeekFilesClient({
-      protocol: 'chat-completions',
       baseURL: 'https://api.deepseek.com',
       apiKey: 'key',
       fetch: vi.fn(() => Promise.resolve(new Response('not-json', { status }))),
@@ -290,7 +267,6 @@ describe('DeepSeekFilesClient', () => {
     { error: { message: 1, type: 2, code: 3 } },
   ])('falls back to the HTTP status for an unstructured provider error %#', async (body) => {
     const client = new DeepSeekFilesClient({
-      protocol: 'chat-completions',
       baseURL: 'https://api.deepseek.com',
       apiKey: 'key',
       fetch: vi.fn(() => Promise.resolve(new Response(JSON.stringify(body), { status: 400 }))),
@@ -303,7 +279,6 @@ describe('DeepSeekFilesClient', () => {
   it('wraps transport failures but preserves an aborted request reason', async () => {
     const transport = new Error('socket closed')
     const client = new DeepSeekFilesClient({
-      protocol: 'chat-completions',
       baseURL: 'https://api.deepseek.com',
       apiKey: 'key',
       fetch: vi.fn(() => Promise.reject(transport)),
@@ -324,19 +299,15 @@ describe('DeepSeekFilesClient', () => {
     [],
     file({ id: 1 }),
     file({ id: '' }),
-    file({ object: 'wrong' }),
-    file({ bytes: 1.5 }),
-    file({ bytes: -1 }),
+    file({ type: 'wrong' }),
+    file({ size_bytes: 1.5 }),
+    file({ size_bytes: -1 }),
     file({ created_at: 1.5 }),
     file({ created_at: -1 }),
     file({ filename: 1 }),
     file({ filename: '' }),
-    file({ purpose: 'assistants' }),
-    file({ expires_at: 1.5 }),
-    file({ expires_at: -1 }),
   ])('rejects an invalid file object %#', async (body) => {
     const client = new DeepSeekFilesClient({
-      protocol: 'chat-completions',
       baseURL: 'https://api.deepseek.com',
       apiKey: 'key',
       fetch: vi.fn(() => Promise.resolve(new Response(JSON.stringify(body), { status: 200 }))),
@@ -350,7 +321,7 @@ describe('DeepSeekFilesClient', () => {
     3_600.5,
   ])('refuses invalid file expiry %s before transport', async (expiresAfterSeconds) => {
     const fetchImpl = vi.fn() as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
     await expect(client.upload({
       data: Uint8Array.of(1), mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds,
     })).rejects.toMatchObject({ code: 'INVALID_REQUEST' })
@@ -359,7 +330,7 @@ describe('DeepSeekFilesClient', () => {
 
   it('refuses a file larger than the upload limit before transport', async () => {
     const fetchImpl = vi.fn() as typeof fetch
-    const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
+    const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com', apiKey: 'key', fetch: fetchImpl })
     const data = { byteLength: MAX_FILE_UPLOAD_BYTES + 1 } as Uint8Array
     await expect(client.upload({
       data, mediaType: 'image/png', filename: 'image.png', expiresAfterSeconds: 3_600,
@@ -371,14 +342,12 @@ describe('DeepSeekFilesClient', () => {
     null,
     [],
     {},
-    { object: 'wrong', data: [], has_more: false },
-    { object: 'list', data: null, has_more: false },
-    { object: 'list', data: [], has_more: 0 },
-    { object: 'list', data: [], has_more: false, first_id: 1 },
-    { object: 'list', data: [], has_more: false, last_id: 1 },
+    { data: null, has_more: false },
+    { data: [], has_more: 0 },
+    { data: [], has_more: false, first_id: 1 },
+    { data: [], has_more: false, last_id: 1 },
   ])('rejects an invalid list response %#', async (body) => {
     const client = new DeepSeekFilesClient({
-      protocol: 'chat-completions',
       baseURL: 'https://api.deepseek.com',
       apiKey: 'key',
       fetch: vi.fn(() => Promise.resolve(new Response(JSON.stringify(body), { status: 200 }))),
@@ -388,11 +357,11 @@ describe('DeepSeekFilesClient', () => {
 
   it('accepts a list without cursors and uses the global fetch default', async () => {
     const fetchImpl = vi.fn(() => Promise.resolve(new Response(JSON.stringify({
-      object: 'list', data: [], has_more: false,
+      data: [], has_more: false,
     }), { status: 200 })))
     vi.stubGlobal('fetch', fetchImpl)
     try {
-      const client = new DeepSeekFilesClient({ protocol: 'chat-completions', baseURL: 'https://api.deepseek.com///', apiKey: 'key' })
+      const client = new DeepSeekFilesClient({ baseURL: 'https://api.deepseek.com///', apiKey: 'key' })
       await expect(client.list()).resolves.toEqual({ data: [], hasMore: false })
     } finally {
       vi.unstubAllGlobals()
@@ -403,12 +372,10 @@ describe('DeepSeekFilesClient', () => {
     null,
     [],
     {},
-    { id: 'wrong', object: 'file', deleted: true },
-    { id: 'file-api-one', object: 'wrong', deleted: true },
-    { id: 'file-api-one', object: 'file', deleted: false },
+    { id: 'wrong', type: 'file_deleted' },
+    { id: 'file-api-one', type: 'wrong' },
   ])('rejects an invalid delete response %#', async (body) => {
     const client = new DeepSeekFilesClient({
-      protocol: 'chat-completions',
       baseURL: 'https://api.deepseek.com',
       apiKey: 'key',
       fetch: vi.fn(() => Promise.resolve(new Response(JSON.stringify(body), { status: 200 }))),
diff --git a/packages/llm/llm-deepseek/tests/messages/files.spec.ts b/packages/llm/llm-deepseek/tests/files.spec.ts
similarity index 91%
rename from packages/llm/llm-deepseek/tests/messages/files.spec.ts
rename to packages/llm/llm-deepseek/tests/files.spec.ts
index e4f1a9060e..aee62c111b 100644
--- a/packages/llm/llm-deepseek/tests/messages/files.spec.ts
+++ b/packages/llm/llm-deepseek/tests/files.spec.ts
@@ -1,16 +1,17 @@
 /** Messages file-reference admission, bounded recovery and request-wide inline fallback. */
+import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
-import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
+import type { ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
 import { createAssistantMessage, createToolResultMessage, LlmError, ToolCallId } from '@deepseek-ai/dsh-llm'
-import { DeepSeekFileId } from '../../src/common/file-id.ts'
-import type { DeepSeekFileStore } from '../../src/common/file-store.ts'
-import { resolveAdapterOptions } from '../../src/config.ts'
-import type { Config } from '../../src/config.ts'
-import { DeepSeekMessagesAdapter } from '../../src/protocols/messages/adapter.ts'
-import { prepareImages } from '../../src/protocols/messages/images.ts'
-import { providerErrorDetail } from '../../src/protocols/messages/transport.ts'
-import { chunks, options, prepareExtensions, sse, textEvents, user } from './helpers.ts'
+import { DeepSeekFileId } from '../src/file-id.ts'
+import { DeepSeekFileStore } from '../src/file-store.ts'
+import { resolveAdapterOptions } from '../src/config.ts'
+import type { Config } from '../src/config.ts'
+import { DeepSeekAdapter } from '../src/adapter.ts'
+import { prepareImages } from '../src/images.ts'
+import { providerErrorDetail } from '../src/transport.ts'
+import { chunks, options, prepareExtensions, sse, textEvents, user, requestImageStore } from './helpers.ts'
 
 const model = 'deepseek-flash'
 const ref: ImageAttachmentRef = { attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`), width: 1, height: 1, mediaType: 'image/png', bytes: 3 }
@@ -31,15 +32,15 @@ function harness(config: Config = {}) {
     record: { fileId: DeepSeekFileId(image.attachment.attachmentId === ref.attachmentId ? 'file-a' : 'file-b') }, uploaded: false,
   } as Awaited<ReturnType<DeepSeekFileStore['ensureUploaded']>>))
   const invalidate = vi.fn<DeepSeekFileStore['invalidate']>(async () => {})
-  const files = { ensureUploaded, invalidate } as unknown as DeepSeekFileStore
+  const files = Object.assign(new DeepSeekFileStore(), { ensureUploaded, invalidate })
   const readImageRequest = vi.fn(async (attachment: ImageAttachmentRef) => version(attachment))
   // The codec and remote upload are the expensive boundaries; request projection and recovery stay real.
-  const attachments = { readImageRequest } as unknown as AttachmentStore
+  const attachments = requestImageStore(readImageRequest)
   const prepare = vi.fn(prepareExtensions)
-  const adapter = new DeepSeekMessagesAdapter({
-    connection: () => resolveAdapterOptions(Object.assign({ baseURL: 'https://gateway.example/custom' }, config)),
-    apiKey: async () => 'test-key', userId: () => 'test-user', attachments: () => attachments,
-    imageAccess: () => ({ readonlyPath: '/workspace/image.png' }), files: () => files, prepareExtensions: prepare,
+  const adapter = new DeepSeekAdapter({
+    options: () => resolveAdapterOptions(Object.assign({ baseURL: 'https://gateway.example/custom' }, config)),
+    resolveApiKey: async () => 'test-key', resolveUserId: () => 'test-user' as AnonymousUserId, resolveAttachments: () => attachments,
+    resolveImageAccess: () => ({ readonlyPath: '/workspace/image.png' }), resolveFiles: () => files, prepareExtensions: prepare,
   })
   return { adapter, ensureUploaded, invalidate, readImageRequest, prepare }
 }
@@ -55,7 +56,7 @@ describe('Messages Files requests', () => {
       createToolResultMessage({ callId, isError: false, content: [{ type: 'image', attachment: ref }, { type: 'image', attachment: ref }] })]
     await chunks(h.adapter.stream(options({ model, messages })))
     expect(h.readImageRequest).toHaveBeenCalledTimes(1)
-    expect(h.ensureUploaded).toHaveBeenCalledWith(expect.anything(), { baseURL: 'https://gateway.example/custom', apiKey: 'test-key', protocol: 'messages' }, expect.anything(), expect.any(AbortSignal))
+    expect(h.ensureUploaded).toHaveBeenCalledWith(expect.anything(), { baseURL: 'https://gateway.example/custom', apiKey: 'test-key' }, expect.anything(), expect.any(AbortSignal))
     const [url, init] = fetchImpl.mock.calls[0]!
     expect(url).toBe('https://gateway.example/custom/v1/messages')
     expect(new Headers(init?.headers).get('anthropic-beta')).toBe('files-api-2025-04-14')
@@ -72,7 +73,7 @@ describe('Messages Files requests', () => {
     vi.stubGlobal('fetch', fetchImpl)
     const h = harness()
     await chunks(h.adapter.stream(request([ref, second])))
-    expect(h.invalidate).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ attachment: ref }), 'file-a', expect.objectContaining({ protocol: 'messages' }))
+    expect(h.invalidate).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ attachment: ref }), 'file-a', expect.objectContaining({}))
     expect(fetchImpl).toHaveBeenCalledTimes(2)
     expect(h.prepare).toHaveBeenCalledTimes(2)
     expect(h.ensureUploaded).toHaveBeenCalledTimes(4)
diff --git a/packages/llm/llm-deepseek/tests/messages/fixtures/cordis.yml b/packages/llm/llm-deepseek/tests/fixtures/cordis.yml
similarity index 100%
rename from packages/llm/llm-deepseek/tests/messages/fixtures/cordis.yml
rename to packages/llm/llm-deepseek/tests/fixtures/cordis.yml
diff --git a/packages/llm/llm-deepseek/tests/messages/fixtures/history.ts b/packages/llm/llm-deepseek/tests/fixtures/history.ts
similarity index 77%
rename from packages/llm/llm-deepseek/tests/messages/fixtures/history.ts
rename to packages/llm/llm-deepseek/tests/fixtures/history.ts
index 4c5b78c6d1..0a02332dfc 100644
--- a/packages/llm/llm-deepseek/tests/messages/fixtures/history.ts
+++ b/packages/llm/llm-deepseek/tests/fixtures/history.ts
@@ -1,7 +1,7 @@
 /** Exercise Messages request conversion with recorded responses from another protocol. */
 import type { Context } from '@deepseek-ai/cordis'
-import { resolveAdapterOptions } from '../../../src/config.ts'
-import { serialize } from '../../../src/protocols/messages/serialize.ts'
+import { resolveAdapterOptions } from '../../src/config.ts'
+import { serialize } from '../../src/serialize.ts'
 
 export const name = 'messages-history-snapshot'
 export const inject = ['llm']
diff --git a/packages/llm/llm-deepseek/tests/messages/fixtures/input-history.ts b/packages/llm/llm-deepseek/tests/fixtures/input-history.ts
similarity index 93%
rename from packages/llm/llm-deepseek/tests/messages/fixtures/input-history.ts
rename to packages/llm/llm-deepseek/tests/fixtures/input-history.ts
index ce98439370..33f45f6291 100644
--- a/packages/llm/llm-deepseek/tests/messages/fixtures/input-history.ts
+++ b/packages/llm/llm-deepseek/tests/fixtures/input-history.ts
@@ -3,8 +3,8 @@ import assert from 'node:assert/strict'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-agent'
 import { createUserMessage, ToolCallId } from '@deepseek-ai/dsh-llm'
-import { resolveAdapterOptions } from '../../../src/config.ts'
-import { serialize } from '../../../src/protocols/messages/serialize.ts'
+import { resolveAdapterOptions } from '../../src/config.ts'
+import { serialize } from '../../src/serialize.ts'
 
 declare module '@deepseek-ai/dsh-llm' {
   interface MessageSourceMap {
diff --git a/packages/llm/llm-deepseek/tests/messages/helpers.ts b/packages/llm/llm-deepseek/tests/helpers.ts
similarity index 63%
rename from packages/llm/llm-deepseek/tests/messages/helpers.ts
rename to packages/llm/llm-deepseek/tests/helpers.ts
index 1aff3c74f6..d5f8e780d7 100644
--- a/packages/llm/llm-deepseek/tests/messages/helpers.ts
+++ b/packages/llm/llm-deepseek/tests/helpers.ts
@@ -1,14 +1,18 @@
 /** Deterministic Messages fixtures and loopback transport with explicit teardown. */
+import { Context } from '@deepseek-ai/cordis'
+import AttachmentStore from '@deepseek-ai/dsh-attachment'
+import type { ModuleLoaderV2 } from '@deepseek-ai/cordis-plugin-loader'
+import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
 import { createServer } from 'node:http'
 import type { IncomingHttpHeaders, ServerResponse } from 'node:http'
 import { once } from 'node:events'
-import { object } from '../../src/protocols/messages/replay.ts'
+import { object } from '../src/replay.ts'
 import { BlockAssembler, createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
-import { resolveAdapterOptions } from '../../src/index.ts'
-import { DeepSeekMessagesAdapter } from '../../src/protocols/messages/adapter.ts'
-import type { Config } from '../../src/config.ts'
-import { DeepSeekFileStore } from '../../src/common/file-store.ts'
+import { resolveAdapterOptions } from '../src/index.ts'
+import { DeepSeekAdapter } from '../src/adapter.ts'
+import type { Config } from '../src/config.ts'
+import { DeepSeekFileStore } from '../src/file-store.ts'
 
 export const prepareExtensions = async () => ({ fields: {}, accept: async () => {} })
 
@@ -40,7 +44,7 @@ export async function assemble(stream: AsyncIterable<StreamChunk>, model = MODEL
 }
 export function adapter(config: Config = {}) {
   const files = new DeepSeekFileStore()
-  return new DeepSeekMessagesAdapter({ connection: () => resolveAdapterOptions(config), apiKey: () => Promise.resolve('test-key'), userId: () => 'test-user', attachments: () => undefined, imageAccess: () => undefined, files: () => files, prepareExtensions })
+  return new DeepSeekAdapter({ options: () => resolveAdapterOptions(config), resolveApiKey: () => Promise.resolve('test-key'), resolveUserId: () => 'test-user' as AnonymousUserId, resolveAttachments: () => undefined, resolveImageAccess: () => undefined, resolveFiles: () => files, prepareExtensions })
 }
 export async function server(reply: (response: ServerResponse, count: number) => void = response => response.end(sse(textEvents))) {
   const requests: { path: string; headers: IncomingHttpHeaders; body: Record<string, unknown> }[] = []
@@ -70,3 +74,28 @@ export async function server(reply: (response: ServerResponse, count: number) =>
     },
   }
 }
+
+/** Supply only the image projection operation; any unexpected storage work fails. */
+export function requestImageStore(readImageRequest: AttachmentStore['readImageRequest']): AttachmentStore {
+  class ProjectedAttachments extends AttachmentStore {
+    get imageLimits(): never { throw new Error('unexpected image policy read') }
+    validateImage(): never { throw new Error('unexpected image validation') }
+    saveImage(): never { throw new Error('unexpected image save') }
+    readImage(): never { throw new Error('unexpected original image read') }
+    override readImageRequest = readImageRequest
+  }
+  return new ProjectedAttachments(new Context())
+}
+
+/** Import mapped source modules without claiming support for Node's HMR internals. */
+export function sourceModuleLoader(importModule: (specifier: string) => Promise<unknown>): ModuleLoaderV2 {
+  return {
+    version: 'v2',
+    import: importModule,
+    get loadCache(): never { throw new Error('unexpected module cache access') },
+    register(): never { throw new Error('unexpected module hook registration') },
+    getOrCreateModuleJob(): never { throw new Error('unexpected module job creation') },
+    resolveSync(): never { throw new Error('unexpected synchronous module resolution') },
+    load(): never { throw new Error('unexpected module load') },
+  }
+}
diff --git a/packages/llm/llm-deepseek/tests/image-tokens.spec.ts b/packages/llm/llm-deepseek/tests/image-tokens.spec.ts
index 5825de033e..0796e3d113 100644
--- a/packages/llm/llm-deepseek/tests/image-tokens.spec.ts
+++ b/packages/llm/llm-deepseek/tests/image-tokens.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { deepSeekImageTokens, deepSeekRequestImageDimensions } from '../src/common/image-tokens.ts'
+import { deepSeekImageTokens, deepSeekRequestImageDimensions } from '../src/image-tokens.ts'
 
 describe('DeepSeek image tokens', () => {
   // Reference values from the provider's published image token calculator
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index 146fd111d4..0626186629 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -29,14 +29,13 @@ import * as DeepSeekPluginPackageInventory from '@deepseek-ai/dsh-plugin-package
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { assemble } from './assemble.ts'
 import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
-import { server as messagesServer } from './messages/helpers.ts'
+import { sourceModuleLoader } from './helpers.ts'
 
 const NS = 'llm-deepseek'
 const KEY_REF = credentialRef('DEEPSEEK_API_KEY')
 
 let root: string | undefined
 let context: Context | undefined
-const closeMessagesServers: (() => Promise<void>)[] = []
 
 afterEach(async () => {
   await context?.fiber.dispose()
@@ -44,12 +43,11 @@ afterEach(async () => {
   if (root !== undefined) await rm(root, { recursive: true, force: true })
   root = undefined
   await closeMockServers()
-  while (closeMessagesServers.length) await closeMessagesServers.pop()!()
   vi.unstubAllEnvs()
 })
 
 async function loadComposition(
-  options: { withDynamic: boolean; baseURL: string; reuseRoot?: string; enableSessionLog?: boolean; protocol?: 'chat-completions' | 'messages' },
+  options: { withDynamic: boolean; baseURL: string; reuseRoot?: string; enableSessionLog?: boolean },
 ): Promise<{ ctx: Context; settingsPath: string; credentialsPath: string }> {
   // A reused root is the restart case: the same harness home, its documents
   // exactly as the previous process left them.
@@ -97,7 +95,6 @@ async function loadComposition(
     '- id: llm-deepseek',
     "  name: '@deepseek-ai/dsh-llm-deepseek'",
     '  config:',
-    `    protocol: ${options.protocol ?? 'chat-completions'}`,
     `    baseURL: ${JSON.stringify(options.baseURL)}`,
     '',
   ].join('\n'))
@@ -129,13 +126,10 @@ async function loadComposition(
       type: 'module',
     })}\n`)
   }))
-  ctx.loader.internal = {
-    version: 'v2',
-    async import(specifier: string) {
-      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
-      return modules.get(specifier)
-    },
-  } as unknown as NonNullable<typeof ctx.loader.internal>
+  ctx.loader.internal = sourceModuleLoader(async (specifier) => {
+    if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+    return modules.get(specifier)
+  })
   await ctx.loader.create({
     name: 'cordis:include',
     config: { path: pathToFileURL(configPath).href },
@@ -144,18 +138,12 @@ async function loadComposition(
   return { ctx, settingsPath, credentialsPath }
 }
 
-async function extensionServer(protocol: 'chat-completions' | 'messages') {
-  if (protocol === 'chat-completions') return mockServer([{ kind: 'sse', events: textEvents }])
-  const server = await messagesServer()
-  closeMessagesServers.push(() => server.close())
-  return { url: server.url, get requests() { return server.requests.map(request => request.body) } }
-}
 
 describe('llm-deepseek real dynamic composition', () => {
-  it.each(['chat-completions', 'messages'] as const)('keeps package inventory on when the %s Loader composition disables session upload', async (protocol) => {
+  it('keeps package inventory on when the Loader composition disables session upload', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'entry-key')
-    const server = await extensionServer(protocol)
-    const { ctx } = await loadComposition({ withDynamic: false, baseURL: server.url, protocol, enableSessionLog: false })
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const { ctx } = await loadComposition({ withDynamic: false, baseURL: server.url, enableSessionLog: false })
     const session = ctx.sessions.create(SessionId('extension-composition'))
     session.append('turn/start', { turn: 1 })
 
@@ -171,13 +159,12 @@ describe('llm-deepseek real dynamic composition', () => {
     expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(-1)
   })
 
-  it.each(['chat-completions', 'messages'] as const)('sends the canonical session suffix by default through %s Loader composition', async (protocol) => {
+  it('sends the canonical session suffix by default through Loader composition', async () => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'entry-key')
-    const server = await extensionServer(protocol)
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
     const { ctx } = await loadComposition({
       withDynamic: false,
       baseURL: server.url,
-      protocol,
     })
     const session = ctx.sessions.create(SessionId('extension-composition-enabled'))
     session.append('turn/start', { turn: 1 })
@@ -210,7 +197,7 @@ describe('llm-deepseek real dynamic composition', () => {
 
     expect(ctx.get('settings')!.describe().map(entry => entry.ns)).toEqual([NS])
     await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(serverA.headers[0]?.authorization).toBe('Bearer boot-key')
+    expect(serverA.headers[0]?.['x-api-key']).toBe('boot-key')
     expect(serverA.headers[0]?.['x-deepseek-harness-user-id']).toBe(getOrCreateAnonymousUserId())
 
     // External edits, exactly as a user or the web UI would leave them on disk.
@@ -225,7 +212,7 @@ describe('llm-deepseek real dynamic composition', () => {
 
     await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
     expect(serverA.requests).toHaveLength(1)
-    expect(serverB.headers[0]?.authorization).toBe('Bearer rotated-key')
+    expect(serverB.headers[0]?.['x-api-key']).toBe('rotated-key')
   })
 
   it('keeps a stored key writable and rotatable across a real restart', async () => {
@@ -240,7 +227,7 @@ describe('llm-deepseek real dynamic composition', () => {
     expect(await boot.ctx.get('credentials')!.describe(KEY_REF))
       .toEqual({ configured: true, source: 'file', writable: true })
     await assemble(boot.ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(first.headers[0]?.authorization).toBe('Bearer stored-by-ui')
+    expect(first.headers[0]?.['x-api-key']).toBe('stored-by-ui')
     await boot.ctx.fiber.dispose()
     context = undefined
 
@@ -254,7 +241,7 @@ describe('llm-deepseek real dynamic composition', () => {
     // Rotation still works after the restart, and the next request uses it.
     await credentials.set(KEY_REF, 'rotated-after-restart')
     await assemble(restarted.ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(second.headers[0]?.authorization).toBe('Bearer rotated-after-restart')
+    expect(second.headers[0]?.['x-api-key']).toBe('rotated-after-restart')
   })
 
   it('boots the same adapter on entry config alone, resolving the reference from the environment', async () => {
@@ -267,6 +254,6 @@ describe('llm-deepseek real dynamic composition', () => {
     expect(ctx.get('settings')).toBeUndefined()
     expect(ctx.get('credentials')).toBeUndefined()
     await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
-    expect(server.headers[0]?.authorization).toBe('Bearer entry-key')
+    expect(server.headers[0]?.['x-api-key']).toBe('entry-key')
   })
 })
diff --git a/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts
deleted file mode 100644
index aeb6ebe3e8..0000000000
--- a/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts
+++ /dev/null
@@ -1,281 +0,0 @@
-/**
- * Real Messages round trips use the official root and require credentials.
- * System-update checks additionally require DEEPSEEK_IN_HISTORY_MODEL.
- */
-import { randomUUID } from 'node:crypto'
-import { mkdtemp, readFile, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { Context, LoggerLevel } from '@deepseek-ai/cordis'
-import Loader from '@deepseek-ai/cordis-plugin-loader'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
-import LocalAttachments from '@deepseek-ai/dsh-attachment-local'
-import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
-import LlmRuntime, { BlockAssembler, createAssistantMessage, createSystemMessage, createToolResultMessage, ReasoningEffortId, ToolCallId } from '@deepseek-ai/dsh-llm'
-import type { Message } from '@deepseek-ai/dsh-llm'
-import * as PluginPackageInventoryDeepSeek from '@deepseek-ai/dsh-plugin-package-inventory-deepseek'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import * as SessionLogDeepSeek from '@deepseek-ai/dsh-session-log-deepseek'
-import * as Messages from '../../src/index.ts'
-import { DeepSeekFilesClient } from '../../src/common/files-api.ts'
-import { MESSAGES_FILES_BETA } from '../../src/common/messages-api.ts'
-import { assemble, options, user } from './helpers.ts'
-
-const IN_HISTORY_MODEL = process.env.DEEPSEEK_IN_HISTORY_MODEL
-const cleanups: (() => Promise<unknown>)[] = []
-afterEach(async () => {
-  while (cleanups.length) await cleanups.pop()!()
-  vi.unstubAllEnvs()
-  vi.unstubAllGlobals()
-})
-async function boot(models?: Messages.Config['models']) {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-messages-e2e-'))
-  cleanups.push(() => rm(home, { recursive: true, force: true }))
-  vi.stubEnv('DSH_HOME', home)
-  const ctx = new Context()
-  cleanups.push(() => ctx.fiber.dispose())
-  await ctx.plugin(LlmRuntime)
-  await ctx.plugin(Messages, {
-    baseURL: Messages.MESSAGES_BASE_URL,
-    maxTokens: 4096,
-    ...models === undefined ? {} : { models },
-  })
-  return ctx
-}
-const tool = { name: 'lookup_value', description: 'Read the requested value. Always call this tool to obtain a value.', parameters: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] } }
-
-describe.skipIf(!process.env.DEEPSEEK_API_KEY)('DeepSeek Messages real API', () => {
-  it.skipIf(!IN_HISTORY_MODEL).each([false, true])('updates system instructions during a conversation, in-history=%s', async (inHistory) => {
-    const model = IN_HISTORY_MODEL as string
-    // Each case owns the capability, even for a model with an in-history catalog default.
-    const ctx = await boot([{ id: model, ...inHistory ? { systemPromptUpdate: 'in-history' as const } : {} }])
-    const history: Message[] = [createSystemMessage('Reply to every user message with exactly PROMPT_FIRST.'), user('Answer now.')]
-    const reply = async (expected: string) => {
-      const saved = JSON.stringify(history)
-      const response = await assemble(ctx.llm.stream(options({ model, messages: history, reasoningEffort: ReasoningEffortId('high') })), model)
-      expect(response.assembler.finish.kind).toBe('stop')
-      expect(response.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain(expected)
-      expect(JSON.stringify(history)).toBe(saved)
-      history.push(response.message)
-    }
-    await reply('PROMPT_FIRST')
-    history.push(createSystemMessage('Reply to every user message with exactly PROMPT_SECOND.'), user('Answer again.'))
-    await reply('PROMPT_SECOND')
-    const withoutSystem = history.filter(message => message.role !== 'system')
-    history.splice(0, history.length, createSystemMessage(''), ...withoutSystem, user('Reply with exactly PROMPT_CLEARED.'))
-    await reply('PROMPT_CLEARED')
-  })
-
-  it('uploads, lists, retrieves, reuses, and replaces a deleted Files image across Messages requests', async () => {
-    const ctx = await boot()
-    await ctx.plugin(LocalAttachments)
-    const fetchImpl = globalThis.fetch
-    const uploads: string[] = []
-    const bodies: string[] = []
-    const files = new DeepSeekFilesClient({ baseURL: Messages.MESSAGES_BASE_URL, protocol: 'messages', apiKey: process.env.DEEPSEEK_API_KEY as string, fetch: fetchImpl })
-    const ownedFiles = new Set<ReturnType<typeof Messages.DeepSeekFileId>>()
-    cleanups.push(async () => {
-      for (const id of ownedFiles) await files.delete(id)
-    })
-    vi.stubGlobal('fetch', async (input: string | URL | Request, init?: RequestInit) => {
-      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
-      const response = await fetchImpl(input, init)
-      if (url === `${Messages.MESSAGES_BASE_URL}/v1/files` && init?.method === 'POST' && response.ok) {
-        const file = await response.clone().json() as { id: string }
-        uploads.push(file.id)
-        ownedFiles.add(Messages.DeepSeekFileId(file.id))
-      }
-      if (url === `${Messages.MESSAGES_BASE_URL}/v1/messages`) {
-        expect(new Headers(init?.headers).get('anthropic-beta')).toBe(MESSAGES_FILES_BETA)
-        if (typeof init?.body !== 'string') throw new Error('expected a JSON Messages request')
-        bodies.push(init.body)
-      }
-      return response
-    })
-    const attachment = await ctx.attachments.saveImage({ data: await readFile(new URL('fixtures/red.png', import.meta.url)), mediaType: 'image/png' })
-    const message = user('What is the dominant color of this image? Reply with one English color word.')
-    const request = options({
-      model: 'deepseek-flash', reasoningEffort: ReasoningEffortId('off'),
-      messages: [{ ...message, content: [...message.content, { type: 'image', attachment }] }],
-    })
-    for (let run = 0; run < 2; run++) {
-      const result = await assemble(ctx.llm.stream(request), request.model)
-      expect(result.assembler.finish.kind).toBe('stop')
-      expect(result.message.content.filter(block => block.type === 'text').map(block => block.text).join('').toLowerCase()).toContain('red')
-    }
-    expect(uploads).toHaveLength(1)
-    expect(bodies).toHaveLength(2)
-    expect(bodies.every(body => body.includes(`"file_id":"${uploads[0]}"`) && !body.includes('"type":"base64"'))).toBe(true)
-    const fileId = Messages.DeepSeekFileId(uploads[0]!)
-    const retrieved = await files.retrieve(fileId)
-    expect(retrieved).toMatchObject({ id: fileId, bytes: attachment.bytes, purpose: 'user_data' })
-    expect(retrieved.expiresAt).toBeUndefined()
-    let page = await files.list({ limit: 1_000 })
-    const cursors = new Set<string>()
-    while (!page.data.some(file => file.id === fileId) && page.hasMore) {
-      expect(page.lastId).toBeDefined()
-      const after = page.lastId!
-      expect(cursors.has(after)).toBe(false)
-      cursors.add(after)
-      page = await files.list({ after, limit: 1_000 })
-    }
-    expect(page.data).toContainEqual(retrieved)
-    await files.delete(fileId)
-    ownedFiles.delete(fileId)
-    const recovered = await assemble(ctx.llm.stream(request), request.model)
-    expect(recovered.assembler.finish.kind).toBe('stop')
-    expect(recovered.message.content.filter(block => block.type === 'text').map(block => block.text).join('').toLowerCase()).toContain('red')
-    expect(uploads).toHaveLength(2)
-    expect(uploads[1]).not.toBe(fileId)
-    expect(bodies).toHaveLength(4)
-    expect(bodies[2]).toContain(`"file_id":"${fileId}"`)
-    expect(bodies[3]).toContain(`"file_id":"${uploads[1]}"`)
-    expect(bodies[3]).not.toContain('"type":"base64"')
-  })
-
-  it.each([false, true])('submits Loader package inventory and records HTTP acceptance with session-log enabled=%s', async (enabled) => {
-    const ctx = await boot()
-    await ctx.plugin(Loader)
-    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
-    await ctx.plugin(SessionLogDeepSeek, enabled ? {} : { enabled: false })
-    ctx.baseUrl = import.meta.url
-    // Select the source module while Loader owns its active package entry.
-    ctx.loader.internal = {
-      version: 'v2',
-      async import(specifier: string) {
-        if (specifier !== '@deepseek-ai/dsh-plugin-package-inventory-deepseek') throw new Error(`unexpected Loader import: ${specifier}`)
-        return PluginPackageInventoryDeepSeek
-      },
-    } as unknown as NonNullable<typeof ctx.loader.internal>
-    await ctx.loader.create({ name: '@deepseek-ai/dsh-plugin-package-inventory-deepseek' })
-    await ctx.loader.await()
-    const packageIdentity = JSON.parse(await readFile(new URL('../../../plugin-package-inventory-deepseek/package.json', import.meta.url), 'utf8')) as { name: string; version: string }
-    const session = ctx.sessions.create(SessionId(`real-messages-extensions-${randomUUID()}`))
-    session.append('turn/start', { turn: 1 })
-    const fetchImpl = globalThis.fetch
-    let afterSeq: number = -1
-    let throughSeq = 0
-    let requests = 0
-    vi.stubGlobal('fetch', async (input: string | URL | Request, init?: RequestInit) => {
-      const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
-      if (url !== `${Messages.MESSAGES_BASE_URL}/v1/messages`) return fetchImpl(input, init)
-      if (typeof init?.body !== 'string') throw new Error('expected a JSON Messages request')
-      const body = JSON.parse(init.body) as Record<string, unknown>
-      expect(body).toMatchObject({ dsh_plugin_packages: {
-        version: 1, packages: [{ name: packageIdentity.name, version: packageIdentity.version }],
-      } })
-      if (enabled) {
-        expect(body).toMatchObject({ dsh_session_log: {
-          version: 1, sessionFormatVersion: session.header.version, session: { id: session.id },
-          afterSeq, throughSeq,
-          events: Array.from({ length: throughSeq - afterSeq }, (_, index) => ({ seq: afterSeq + index + 1 })),
-        } })
-      } else expect(body).not.toHaveProperty('dsh_session_log')
-      expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(afterSeq)
-      const response = await fetchImpl(input, init)
-      expect(response.ok).toBe(true)
-      expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(afterSeq)
-      requests += 1
-      return response
-    })
-    for (let run = 0; run < 2; run++) {
-      afterSeq = SessionLogDeepSeek.acceptedThrough(session)
-      throughSeq = Number(session.seq) - 1
-      const assembler = new BlockAssembler()
-      for await (const chunk of ctx.llm.stream(options({ sessionId: session.id, reasoningEffort: ReasoningEffortId('off'), messages: [user('Reply with exactly PONG.')] }))) {
-        expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(enabled ? throughSeq : -1)
-        assembler.push(chunk)
-      }
-      expect(assembler.finish.kind).toBe('stop')
-      expect(assembler.blocks().filter(block => block.type === 'text').map(block => block.text).join('')).toContain('PONG')
-      expect(requests).toBe(run + 1)
-      if (run === 0) session.append('step/start', { turn: 1, step: 1 })
-    }
-    expect(session.snapshotEvents().filter(event => event.type === 'session-log-deepseek/delivery-accepted')).toHaveLength(enabled ? 2 : 0)
-  })
-
-  it.each(['off', 'low', 'high', 'max'])('streams text with %s effort', async (effort) => {
-    const ctx = await boot()
-    const result = await assemble(ctx.llm.stream(options({ reasoningEffort: ReasoningEffortId(effort), temperature: 0, messages: [user('Reply with exactly PONG.')] })))
-    expect(result.assembler.finish).toEqual({ kind: 'stop' })
-    expect(result.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('PONG')
-    expect(result.assembler.usage?.outputTokens).toBeGreaterThan(0)
-    expect(result.message.source.replayState).toBeDefined()
-  })
-
-  it('replays a JSON-persisted thinking/tool turn and an error result before continuing', async () => {
-    const ctx = await boot()
-    const history: Message[] = [user('Use lookup_value with key secret. If the tool returns an error, report its exact error text and stop.')]
-    const request = options({ messages: history, tools: [tool], reasoningEffort: ReasoningEffortId('high') })
-    const first = await assemble(ctx.llm.stream(request))
-    expect(first.assembler.finish.kind).toBe('tool-calls')
-    const calls = first.message.content.filter(block => block.type === 'tool-call')
-    expect(calls).toHaveLength(1)
-    const restored = JSON.parse(JSON.stringify(first.message)) as Message
-    history.push(restored)
-    for (const call of calls) history.push(createToolResultMessage({ callId: call.id, content: [{ type: 'text', text: 'LOOKUP_DENIED_731' }], isError: true }))
-    const second = await assemble(ctx.llm.stream({ ...request, messages: history }))
-    expect(second.assembler.finish.kind).toBe('stop')
-    expect(second.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('LOOKUP_DENIED_731')
-    history.push(second.message, user('Reply with exactly DONE.'))
-    const third = await assemble(ctx.llm.stream({ ...request, messages: history }))
-    expect(third.assembler.finish.kind).toBe('stop')
-  })
-
-  it('continues persisted foreign history containing malformed tool arguments', async () => {
-    const ctx = await boot()
-    const callId = ToolCallId('historical_lookup')
-    const history = [
-      user('Look up the secret value.'),
-      createAssistantMessage({ source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' }, content: [
-        { type: 'tool-call', id: callId, name: 'lookup_value', arguments: '{"key":"the "secret""}' },
-      ] }),
-      createToolResultMessage({ callId, content: [{ type: 'text', text: 'Invalid arguments: expected an object' }], isError: true }),
-      user('Do not retry the lookup. Reply with exactly HISTORY_RECOVERED_731.'),
-    ]
-    const saved = JSON.stringify(history)
-    const restored = JSON.parse(saved) as Message[]
-    const response = await assemble(ctx.llm.stream(options({ messages: restored, tools: [tool], reasoningEffort: ReasoningEffortId('off') })))
-    expect(response.assembler.finish.kind).toBe('stop')
-    expect(response.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('HISTORY_RECOVERED_731')
-    expect(JSON.stringify(restored)).toBe(saved)
-  })
-
-  it('cancels an active stream without committing a successful response', async () => {
-    const ctx = await boot()
-    const controller = new AbortController()
-    const stream = ctx.llm.stream(options({ signal: controller.signal, messages: [user('List the integers from one to one thousand, one per line.')] }))
-    let cancelled = false
-    let finish: unknown
-    for await (const chunk of stream) {
-      if (!cancelled && (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta')) { cancelled = true; controller.abort() }
-      if (chunk.type === 'finish') finish = chunk.reason
-    }
-    expect(cancelled).toBe(true)
-    expect(finish).toMatchObject({ kind: 'aborted' })
-  })
-
-  it('continues a thinking/tool turn after degrading unusable persisted replay metadata', async () => {
-    const ctx = await boot()
-    const warnings: unknown[][] = []
-    ctx.logger.exporter({ levels: { default: LoggerLevel.WARN }, export: (message) => { if (message.type === 'warn') warnings.push(message.args) } })
-    const history: Message[] = [user('Use lookup_value with key secret. Then reply with the exact tool result and stop.')]
-    const request = options({ messages: history, tools: [tool], reasoningEffort: ReasoningEffortId('high') })
-    const first = await assemble(ctx.llm.stream(request))
-    expect(first.assembler.finish.kind).toBe('tool-calls')
-    const calls = first.message.content.filter(block => block.type === 'tool-call')
-    expect(calls).toHaveLength(1)
-    const restored = JSON.parse(JSON.stringify(first.message)) as typeof first.message
-    restored.source.replayState = { response: { kind: 'deepseek-messages', version: 2 }, blocks: [] }
-    const saved = JSON.stringify(restored)
-    history.push(restored, ...calls.map(call => createToolResultMessage({ callId: call.id, content: [{ type: 'text', text: 'REPLAY_RECOVERED_731' }], isError: false })))
-    const second = await assemble(ctx.llm.stream({ ...request, messages: history }))
-    expect(second.assembler.finish.kind).toBe('stop')
-    expect(second.message.content.filter(block => block.type === 'text').map(block => block.text).join('')).toContain('REPLAY_RECOVERED_731')
-    expect(warnings).toEqual([[expect.stringContaining('unsupported kind or version')]])
-    expect(JSON.stringify(restored)).toBe(saved)
-  })
-})
diff --git a/packages/llm/llm-deepseek/tests/messages/adapter.spec.ts b/packages/llm/llm-deepseek/tests/messages/adapter.spec.ts
deleted file mode 100644
index 6a9fa25af6..0000000000
--- a/packages/llm/llm-deepseek/tests/messages/adapter.spec.ts
+++ /dev/null
@@ -1,450 +0,0 @@
-/** HTTP lifecycle, routing and optional Cordis services under real composition. */
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { Context, LoggerLevel, Service } from '@deepseek-ai/cordis'
-import LocalAttachments from '@deepseek-ai/dsh-attachment-local'
-import AgentRegistry, { installModelSelection } from '@deepseek-ai/dsh-agent'
-import type { Agent, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
-import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRuntime from '@deepseek-ai/dsh-tools'
-import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
-import { AttachmentId } from '@deepseek-ai/dsh-attachment'
-import Loader from '@deepseek-ai/cordis-plugin-loader'
-import Include from '@deepseek-ai/cordis-plugin-include'
-import LlmRuntime, { createAssistantMessage, createSystemMessage, createToolResultMessage, createUserMessage, ToolCallId } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
-import { credentialRef } from '@deepseek-ai/dsh-credentials'
-import LocalCredentials from '@deepseek-ai/dsh-credentials-local'
-import FileSettings from '@deepseek-ai/dsh-settings-file'
-import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import { DeepSeekMessagesAdapter } from '../../src/protocols/messages/adapter.ts'
-import { DeepSeekFileStore } from '../../src/common/file-store.ts'
-import * as Messages from '../../src/index.ts'
-import { adapter, assemble, chunks, MODEL, options, prepareExtensions, server, sse, textEvents, user } from './helpers.ts'
-
-const cleanup: (() => Promise<unknown>)[] = []
-afterEach(async () => {
-  while (cleanup.length) await cleanup.pop()!()
-  vi.unstubAllEnvs()
-  vi.unstubAllGlobals()
-})
-async function endpoint(...args: Parameters<typeof server>) {
-  const instance = await server(...args)
-  cleanup.push(() => instance.close())
-  return instance
-}
-async function context() {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-messages-test-'))
-  cleanup.push(() => rm(home, { recursive: true, force: true }))
-  vi.stubEnv('DSH_HOME', home)
-  const ctx = new Context()
-  cleanup.push(() => ctx.fiber.dispose())
-  return { ctx, home }
-}
-
-async function send(agent: Agent, text: string) {
-  agent.followup(user(text))
-  await agent.whenIdle()
-  expect(agent.session.snapshotEvents().at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'completed' } } })
-}
-
-declare module '@deepseek-ai/dsh-llm' {
-  interface MessageSourceMap {
-    'saved-notice': { kind: 'saved-notice' }
-  }
-}
-
-describe('direct Messages HTTP', () => {
-  it('continues through Messages with assistant blocks in saved user history', async () => {
-    const http = await endpoint()
-    const notice = createUserMessage({ source: { kind: 'saved-notice' }, content: [
-      { type: 'text', text: 'Background subagent finished.' },
-      { type: 'reasoning', text: 'child reasoning' },
-      { type: 'tool-call', id: ToolCallId('child-call'), name: 'read', arguments: '{}' },
-      { type: 'text', text: 'Its closing message: answer.' },
-    ] })
-    const empty = createUserMessage({ source: { kind: 'user' }, content: [{ type: 'reasoning', text: 'no closing text' }] })
-    const history = [notice, empty]
-    const saved = JSON.stringify(history)
-    const llm = adapter({ baseURL: http.url })
-    const first = await assemble(llm.stream(options({ messages: history })))
-    const second = await assemble(llm.stream(options({ messages: [...history, first.message, user('continue')] })))
-
-    expect(first.assembler.finish.kind).toBe('stop')
-    expect(second.assembler.finish.kind).toBe('stop')
-    expect(http.requests).toHaveLength(2)
-    const wireNotice = { role: 'user', content: [
-      { type: 'text', text: 'Background subagent finished.' },
-      { type: 'text', text: 'Its closing message: answer.' },
-    ] }
-    expect(http.requests[0]?.body.messages).toEqual([wireNotice])
-    expect(http.requests[1]?.body.messages).toEqual([
-      wireNotice,
-      { role: 'assistant', content: [{ type: 'text', text: 'Hello 世界' }] },
-      { role: 'user', content: [{ type: 'text', text: 'continue' }] },
-    ])
-    expect(JSON.stringify(history)).toBe(saved)
-  })
-
-  it('continues without a diagnostic callback when replay metadata is unusable', async () => {
-    const http = await endpoint()
-    const message = createAssistantMessage({ content: [{ type: 'text', text: 'Remember 731.' }], source: {
-      provider: 'deepseek-official', model: MODEL, replayState: { response: {}, blocks: [] },
-    } })
-    const response = await assemble(adapter({ baseURL: http.url }).stream(options({ messages: [user(), message, user()] })))
-    expect(response.assembler.finish.kind).toBe('stop')
-    expect(http.requests[0]?.body.messages).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-      { role: 'assistant', content: [{ type: 'text', text: 'Remember 731.' }] },
-      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-    ])
-  })
-
-  it('uses the Messages endpoint, authentication, attribution and final usage', async () => {
-    const http = await endpoint()
-    const llm = adapter({ baseURL: http.url })
-    const response = await assemble(llm.stream(options({ model: 'deepseek-flash', sessionId: SessionId('session-test'), purpose: 'compaction' })), 'deepseek-flash')
-    expect(response.message.content).toEqual([{ type: 'text', text: 'Hello 世界' }])
-    expect(response.message.source).toMatchObject({
-      model: 'deepseek-flash', replayState: { response: { model: 'deepseek-flash' } },
-    })
-    expect(http.requests[0]).toMatchObject({ path: '/anthropic/v1/messages', headers: {
-      'x-api-key': 'test-key', 'anthropic-version': '2023-06-01',
-      'user-agent': expect.stringContaining('deepseek-harness/') as string, 'x-deepseek-harness-user-id': 'test-user',
-      'x-deepseek-harness-session-id': 'session-test', 'x-deepseek-harness-compact': '1',
-    }, body: { thinking: { type: 'enabled' }, output_config: { effort: 'high' } } })
-    expect(llm.providerInfo('deepseek-official')).toEqual({ id: 'deepseek-official', name: 'DeepSeek' })
-    expect((await llm.listModels('deepseek-official')).map(model => model.id)).toEqual([
-      'deepseek-flash', 'deepseek-v4-pro',
-    ])
-    expect(await llm.resolveModel('deepseek-official', 'deepseek-flash')).toMatchObject({
-      name: 'DeepSeek-V41-Flash', inputModalities: ['text', 'image'], systemPromptUpdate: 'in-history',
-    })
-    expect(await llm.resolveModel('deepseek-official', MODEL)).toMatchObject({ id: MODEL })
-    expect(llm.imageRequestPricing('deepseek-official', MODEL)).toBeDefined()
-  })
-
-  it.each([
-    ['https://provider.example', 'https://provider.example/v1/messages'],
-    ['https://provider.example/v1/', 'https://provider.example/v1/messages'],
-    ['https://provider.example/v1beta', 'https://provider.example/v1beta/v1/messages'],
-    ['https://provider.example/v2', 'https://provider.example/v2/v1/messages'],
-    ['https://provider.example/anthropic', 'https://provider.example/anthropic/v1/messages'],
-    ['https://v1.provider.example', 'https://v1.provider.example/v1/messages'],
-  ])('resolves the Messages endpoint from %s', async (baseURL, expected) => {
-    const fetchImpl = vi.fn<typeof fetch>(async () => new Response(sse(textEvents), {
-      headers: { 'content-type': 'text/event-stream' },
-    }))
-    vi.stubGlobal('fetch', fetchImpl)
-
-    await chunks(adapter({ baseURL }).stream(options()))
-
-    expect(fetchImpl.mock.calls[0]?.[0]).toBe(expected)
-  })
-
-  it.each([true, false])('maps non-2xx responses (JSON=%s)', async (json) => {
-    const http = await endpoint((response) => { response.statusCode = 429; response.setHeader('retry-after', '3'); response.end(json ? JSON.stringify({ error: { type: 'rate_limit_error', message: 'slow down' } }) : '<html>busy</html>') })
-    await expect(chunks(adapter({ baseURL: http.url }).stream(options()))).rejects.toMatchObject({ code: 'RATE_LIMIT', failure: { status: 429, providerRetryAfterMs: 3000 } })
-  })
-
-  it('refuses redirects before credentials reach another origin or request extensions are accepted', async () => {
-    const destination = await endpoint()
-    const source = await endpoint((response) => {
-      response.writeHead(307, { location: `${destination.url}/v1/messages` })
-      response.end()
-    })
-    const accept = vi.fn(async () => {})
-    const prepare = vi.fn(async () => ({ fields: {}, accept }))
-    const files = new DeepSeekFileStore()
-    const llm = new DeepSeekMessagesAdapter({
-      connection: () => Messages.resolveAdapterOptions({ baseURL: source.url }),
-      apiKey: () => Promise.resolve('test-key'), userId: () => 'test-user',
-      attachments: () => undefined, imageAccess: () => undefined, files: () => files,
-      prepareExtensions: prepare,
-    })
-    const error = await chunks(llm.stream(options())).catch((cause: unknown) => cause)
-    expect(source.requests).toHaveLength(1)
-    expect(source.requests[0]?.headers['x-api-key']).toBe('test-key')
-    expect(destination.requests).toEqual([])
-    expect(error).toMatchObject({ code: 'TRANSPORT' })
-    expect(prepare).toHaveBeenCalledOnce()
-    expect(accept).not.toHaveBeenCalled()
-  })
-
-  it('freezes endpoint and defaults for a prepared call while the next call sees new settings', async () => {
-    const first = await endpoint(), second = await endpoint()
-    let config = Messages.resolveAdapterOptions({ baseURL: first.url, maxTokens: 10, models: [{ id: MODEL, systemPromptUpdate: 'in-history' }] })
-    const files = new DeepSeekFileStore()
-    const llm = new DeepSeekMessagesAdapter({ connection: () => config, apiKey: snapshot => Promise.resolve(snapshot.maxTokens === 10 ? 'first' : 'second'), userId: () => 'user', attachments: () => undefined, imageAccess: () => undefined, files: () => files, prepareExtensions })
-    const prepared = await llm.prepareCall('deepseek-official', MODEL)
-    config = Messages.resolveAdapterOptions({ baseURL: second.url, maxTokens: 20 })
-    expect(prepared.model.systemPromptUpdate).toBe('in-history')
-    expect((await llm.resolveModel('deepseek-official', MODEL)).systemPromptUpdate).toBeUndefined()
-    await chunks(prepared.stream(options()))
-    await chunks(llm.stream(options()))
-    expect(first.requests[0]).toMatchObject({ headers: { 'x-api-key': 'first' }, body: { max_tokens: 10 } })
-    expect(second.requests[0]).toMatchObject({ headers: { 'x-api-key': 'second' }, body: { max_tokens: 20 } })
-  })
-
-  it('aborts an open provider response when its consumer stops', async () => {
-    let closed!: () => void
-    const stopped = new Promise<void>((resolve) => { closed = resolve })
-    const http = await endpoint((response) => {
-      response.once('close', closed)
-      response.write(sse(textEvents.slice(0, 3)))
-    })
-    const stream = adapter({ baseURL: http.url }).stream(options())[Symbol.asyncIterator]()
-    expect((await stream.next()).value).toMatchObject({ type: 'block-start' })
-    await stream.return!()
-    await stopped
-  })
-
-  it('distinguishes caller cancellation from idle timeout and transport failure', async () => {
-    const http = await endpoint((response) =>{  response.flushHeaders() })
-    await expect(chunks(adapter({ baseURL: http.url, streamIdleTimeoutMs: 30 }).stream(options()))).rejects.toMatchObject({ code: 'TIMEOUT' })
-    const controller = new AbortController(); controller.abort()
-    await expect(chunks(adapter({ baseURL: http.url }).stream(options({ signal: controller.signal })))).rejects.toMatchObject({ code: 'ABORTED' })
-    vi.stubGlobal('fetch', async () => { throw new TypeError('network down') })
-    await expect(chunks(adapter().stream(options()))).rejects.toMatchObject({ code: 'TRANSPORT' })
-  })
-
-  it('rejects a successful response with no readable body', async () => {
-    vi.stubGlobal('fetch', async () => new Response(null, { status: 200 }))
-    await expect(chunks(adapter().stream(options()))).rejects.toMatchObject({ code: 'EMPTY_RESPONSE' })
-  })
-})
-
-describe('Cordis provider composition', () => {
-  it('resolves an attachment service loaded after the adapter and maps its read-only path', async () => {
-    const http = await endpoint()
-    const { ctx, home } = await context()
-    vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
-    await ctx.plugin(LlmRuntime)
-    await ctx.plugin(Messages, { baseURL: http.url })
-    const model = 'deepseek-flash'
-    const price = () => ctx.llm.imageRequestPricing('deepseek-official', model)!
-    const dummy = { attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`), width: 1, height: 1, bytes: 3, mediaType: 'image/png' as const }
-    expect(price().priceImages([{ type: 'image', attachment: dummy }])[0]?.text).toBeDefined()
-    await ctx.plugin(LocalAttachments, { dshHome: home })
-    const attachment = await ctx.attachments.saveImage({ data: await readFile(new URL('fixtures/red.png', import.meta.url)), mediaType: 'image/png' })
-    expect(price().priceImages([{ type: 'image', attachment }])[0]?.text).not.toContain('/mounted/image.png')
-    class MappedFiles extends Service {
-      constructor(context: Context) { super(context, 'fs') }
-      processPathFromHostPath(_path: string) { return '/mounted/image.png' }
-    }
-    await ctx.plugin(MappedFiles)
-    const message = user()
-    await chunks(ctx.llm.stream(options({ model, messages: [{ ...message, content: [...message.content, { type: 'image', attachment }] }] })))
-    expect(JSON.stringify(http.requests[0]?.body)).toContain('/mounted/image.png')
-    expect(price().priceImages([{ type: 'image', attachment }])[0]?.text).toContain('/mounted/image.png')
-  })
-
-  async function boot(...args: Parameters<typeof server>) {
-    const http = await endpoint(...args)
-    const { ctx, home } = await context()
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
-    await writeFile(join(home, '.credentials.yaml'), 'version: 1\nrefs:\n  DEEPSEEK_API_KEY: stored-key\n', { mode: 0o600 })
-    await writeFile(join(home, 'settings.yaml'), '{}\n')
-    const template = await readFile(new URL('fixtures/cordis.yml', import.meta.url), 'utf8')
-    await writeFile(join(home, 'cordis.yml'), template.replaceAll('{{endpoint}}', JSON.stringify(http.url)).replaceAll('{{settings}}', JSON.stringify(join(home, 'settings.yaml'))).replaceAll('{{credentials}}', JSON.stringify(join(home, '.credentials.yaml'))))
-    ctx.baseUrl = pathToFileURL(home).href + '/'
-    await ctx.plugin(Loader)
-    ctx.loader.builtins.include = Include
-    const modules = new Map<string, unknown>([
-      ['@deepseek-ai/dsh-llm', LlmRuntime], ['@deepseek-ai/dsh-llm-deepseek', Messages],
-      ['@deepseek-ai/dsh-credentials-local', LocalCredentials], ['@deepseek-ai/dsh-settings-file', FileSettings],
-      ['@deepseek-ai/dsh-agent', AgentRegistry], ['@deepseek-ai/dsh-agent-loop', AgentLoop],
-      ['@deepseek-ai/dsh-session', SessionStore], ['@deepseek-ai/dsh-session-projection', SessionProjectionRegistry],
-      ['@deepseek-ai/dsh-system-prompt', SystemPrompt], ['@deepseek-ai/dsh-tools', ToolRuntime],
-    ])
-    // The importer supplies source modules while Loader still owns configuration and effects.
-    for (const name of modules.keys()) {
-      const directory = join(home, 'node_modules', name)
-      await mkdir(directory, { recursive: true })
-      await writeFile(join(directory, 'package.json'), JSON.stringify({ name, version: '0.1.3-alpha.1', type: 'module' }))
-    }
-    ctx.loader.internal = { version: 'v2', async import(name: string) {
-      if (!modules.has(name)) throw new Error(`unexpected module ${name}`)
-      return modules.get(name)
-    } } as unknown as NonNullable<typeof ctx.loader.internal>
-    await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(join(home, 'cordis.yml')).href } })
-    await ctx.loader.await()
-    return { ctx, http }
-  }
-
-  it.each([
-    { model: MODEL, inHistory: false },
-    { model: MODEL, inHistory: true },
-    { model: 'deepseek-flash', inHistory: true },
-  ])('updates, clears and restores prompts across continued and resumed sessions, model=$model in-history=$inHistory', async ({ model, inHistory }) => {
-    const { ctx, http } = await boot()
-    if (inHistory && model === MODEL) await ctx.settings.update(Messages.name, { models: [{ id: model, systemPromptUpdate: 'in-history' }] })
-    let prompt = 'first prompt'
-    ctx.on('system-prompt/assemble', async (_assembly, _context, next) => ({
-      ...await next(), sections: [{ name: 'test', text: prompt, order: 0 }],
-    }))
-    const agentOptions = { provider: 'deepseek-official', model }
-    const agent = await ctx.agentLoop.create(SessionId('prompt-update'), agentOptions)
-    await send(agent, 'first')
-    prompt = 'second prompt'
-    await send(agent, 'second')
-    const count = agent.session.snapshotEvents().filter(event => event.type === 'system/message').length
-    await send(agent, 'unchanged')
-    expect(agent.session.snapshotEvents().filter(event => event.type === 'system/message')).toHaveLength(count)
-    prompt = ''
-    await send(agent, 'clear')
-    const { agent: resumed } = await ctx.agents.create({ sessionId: SessionId('prompt-resume'), agentOptions,
-      seed: [...agent.session.snapshotEvents()] })
-    await send(resumed, 'resume cleared')
-    prompt = 'restored prompt'
-    await send(resumed, 'restore')
-    expect(http.requests.map(request => request.body.system)).toEqual(inHistory
-      ? ['first prompt', 'first prompt', 'first prompt', undefined, undefined, undefined]
-      : ['first prompt', 'second prompt', 'second prompt', undefined, undefined, 'restored prompt'])
-    for (const [index, request] of http.requests.entries()) {
-      const messages = request.body.messages as { role: string; content: unknown[] }[]
-      expect(messages.filter(message => message.role === 'assistant')).toHaveLength(index)
-      expect(messages.filter(message => message.role === 'system').map(message => message.content)).toEqual(
-        !inHistory ? [] : index === 1 || index === 2 ? [[{ type: 'text', text: 'second prompt' }]]
-          : index === 5 ? [[{ type: 'text', text: 'restored prompt' }]] : [],
-      )
-      expect(JSON.stringify(messages.filter(message => message.role !== 'system'))).not.toMatch(/first prompt|second prompt|restored prompt/)
-    }
-    expect(resumed.session.requestContext()?.systemPromptUpdate).toBe(inHistory ? 'in-history' : undefined)
-  })
-
-  it.each([false, true])('continues and resumes Chat Completions sessions through Messages, in-history=%s', async (inHistory) => {
-    let messagesProtocol = false
-    const { ctx, http } = await boot(response => response.end(messagesProtocol ? sse(textEvents) : [
-      'data: {"choices":[{"delta":{"content":"OK"}}]}\n\n',
-      'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\n',
-      'data: [DONE]\n\n',
-    ].join('')))
-    await ctx.settings.update('llm-deepseek', { protocol: 'chat-completions', baseURL: http.url, models: [{ id: MODEL, systemPromptUpdate: 'in-history' }] })
-    let prompt = 'old prompt'
-    ctx.on('system-prompt/assemble', async (_assembly, _context, next) => ({
-      ...await next(), sections: [{ name: 'test', text: prompt, order: 0 }],
-    }))
-    const selection: ModelSelectionRef = { current: { provider: 'deepseek-official', model: MODEL }, assembled: undefined }
-    const agent = await ctx.agentLoop.create(SessionId('protocol-switch'), selection.current)
-    installModelSelection(agent.ctx, selection)
-    await send(agent, 'first')
-    prompt = 'current prompt'
-    await send(agent, 'second')
-    expect((http.requests[1]?.body.messages as { role: string }[]).filter(message => message.role === 'system')).toHaveLength(2)
-    const seed = [...agent.session.snapshotEvents()]
-    const saved = JSON.stringify(seed)
-    messagesProtocol = true
-    await ctx.settings.update(Messages.name, { protocol: 'messages', models: [{ id: MODEL, ...inHistory ? { systemPromptUpdate: 'in-history' } : {} }] })
-    selection.current = { provider: 'deepseek-official', model: MODEL }
-    await send(agent, 'switch')
-    const { agent: resumed } = await ctx.agents.create({ sessionId: SessionId('switch-resume'), agentOptions: selection.current, seed })
-    await send(resumed, 'resume')
-    for (const request of http.requests.slice(2)) {
-      expect(request.path).toBe('/anthropic/v1/messages')
-      expect(request.body.system).toBe(inHistory ? 'old prompt' : 'current prompt')
-      const messages = request.body.messages as { role: string }[]
-      expect(messages.filter(message => message.role === 'assistant')).toHaveLength(2)
-      expect(messages.filter(message => message.role === 'system')).toHaveLength(inHistory ? 1 : 0)
-      expect(JSON.stringify(messages.filter(message => message.role !== 'system'))).not.toMatch(/old prompt|current prompt/)
-    }
-    expect(JSON.stringify(seed)).toBe(saved)
-    expect(agent.session.deriveMessages().filter(message => message.role === 'system')).toHaveLength(inHistory ? 2 : 1)
-    expect(resumed.session.deriveMessages().filter(message => message.role === 'system')).toHaveLength(inHistory ? 2 : 1)
-  })
-
-  it('maps multiple system snapshots on direct compaction calls to the latest prompt', async () => {
-    const { ctx, http } = await boot()
-    const history = [createSystemMessage('old'), user(),
-      createAssistantMessage({ content: [{ type: 'text', text: 'OK' }], source: { provider: 'deepseek-official', model: MODEL } }),
-      createSystemMessage('current'), user('summarize')]
-    const saved = JSON.stringify(history)
-    const response = await assemble(ctx.llm.stream(options({ messages: history, purpose: 'compaction' })))
-    expect(response.assembler.finish.kind).toBe('stop')
-    expect(http.requests[0]?.body.system).toBe('current')
-    expect((http.requests[0]?.body.messages as { role: string }[]).map(message => message.role)).toEqual(['user', 'assistant', 'user'])
-    expect(JSON.stringify(history)).toBe(saved)
-  })
-
-  it('continues a recorded tool turn with a warning when its native replay version is unknown', async () => {
-    const { ctx, http } = await boot()
-    const warnings: unknown[][] = []
-    ctx.logger.exporter({ levels: { default: LoggerLevel.WARN }, export: (message) => { if (message.type === 'warn') warnings.push(message.args) } })
-    const fixture = await readFile(new URL('../../../../../snapshots/session/deepseek-messages-degraded-replay/session.v2.jsonl', import.meta.url), 'utf8')
-    const records = fixture.trim().split('\n').map(line => JSON.parse(line) as { type: string; data: { message?: Message } })
-    const assistant = records.find(record => record.type === 'assistant/message')!.data.message!
-    if (assistant.source.kind === 'model') assistant.source.provider = 'deepseek-official'
-    // The released v2 row still wraps its tool result inside a user message.
-    const released = records.find(record => record.type === 'tool/result')!.data.message! as unknown as {
-      readonly content: readonly {
-        readonly type: string
-        readonly toolCallId: ToolCallId
-        readonly content: readonly ContentBlock[]
-        readonly isError?: boolean
-      }[]
-    }
-    const releasedBlock = released.content[0]!
-    const result = createToolResultMessage({
-      callId: releasedBlock.toolCallId, content: [...releasedBlock.content], isError: releasedBlock.isError === true,
-    })
-    const saved = JSON.stringify([assistant, result])
-    const response = await assemble(ctx.llm.stream(options({ messages: [user(), assistant, result] })))
-    expect(response.assembler.finish.kind).toBe('stop')
-    expect(warnings).toEqual([[`llm-deepseek: unusable Messages replay state on assistant history for route "deepseek-official/${MODEL}"; sending provider-neutral content (DeepSeek Messages replay: unsupported kind or version)`]])
-    expect(http.requests).toHaveLength(1)
-    expect(http.requests[0]?.body.messages).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-      { role: 'assistant', content: [
-        { type: 'thinking', thinking: 'The user wants me to run a simple bash command and then reply with "DONE".' },
-        { type: 'tool_use', id: 'call_00_fkbBRJsUrGKd1pWVc4Gn8233', name: 'bash', input: { command: 'echo TERMINAL_OK', description: 'Echo TERMINAL_OK to verify terminal access' } },
-      ] },
-      { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'call_00_fkbBRJsUrGKd1pWVc4Gn8233', content: [{ type: 'text', text: 'TERMINAL_OK\n' }], is_error: false }] },
-    ])
-    expect(JSON.stringify([assistant, result])).toBe(saved)
-  })
-
-  it('loads one provider from YAML, rotates settings and credentials, then removes disposed registrations', async () => {
-    const { ctx, http } = await boot()
-    expect(ctx.llm.listProviders().map(provider => provider.id)).toEqual(['deepseek-official'])
-    expect((await assemble(ctx.llm.stream(options()))).assembler.finish.kind).toBe('stop')
-    expect(http.requests[0]?.headers['x-api-key']).toBe('stored-key')
-    const second = await endpoint()
-    await ctx.settings.update(Messages.name, { baseURL: second.url, maxTokens: 51, retryPolicy: { mode: 'always' } })
-    await ctx.credentials.set(credentialRef('DEEPSEEK_API_KEY'), 'rotated')
-    await chunks(ctx.llm.stream(options()))
-    expect(second.requests[0]).toMatchObject({ headers: { 'x-api-key': 'rotated' }, body: { max_tokens: 51 } })
-    await ctx.settings.update(Messages.name, { models: [{ id: 'duplicate' }, { id: 'duplicate' }], baseURL: http.url })
-    await chunks(ctx.llm.stream(options()))
-    expect(second.requests).toHaveLength(2)
-    expect(http.requests).toHaveLength(1)
-    await ctx.settings.update(Messages.name, { models: [{ id: MODEL }], baseURL: http.url })
-    await chunks(ctx.llm.stream(options()))
-    expect(http.requests).toHaveLength(2)
-    const llm = ctx.llm
-    await ctx.fiber.dispose()
-    expect(llm.listProviders()).toEqual([])
-    expect(llm.listConfigurableProviders()).toEqual([])
-  })
-
-  it('uses environment credentials and reports missing or malformed keys without network access', async () => {
-    const http = await endpoint()
-    const { ctx } = await context()
-    vi.stubEnv('DEEPSEEK_BASE_URL', http.url)
-    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
-    await ctx.plugin(LlmRuntime)
-    const fiber = ctx.plugin(Messages)
-    await fiber
-    await chunks(ctx.llm.stream(options()))
-    expect(http.requests[0]?.headers['x-api-key']).toBe('env-key')
-    vi.stubEnv('DEEPSEEK_API_KEY', '')
-    expect((await assemble(ctx.llm.stream(options()))).assembler.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
-    vi.stubEnv('DEEPSEEK_API_KEY', 'bad\nkey')
-    expect((await assemble(ctx.llm.stream(options()))).assembler.finish).toMatchObject({ kind: 'error', failure: { code: 'INVALID_CREDENTIAL' } })
-    await fiber.dispose()
-    expect(ctx.llm.listProviders()).toEqual([])
-  })
-})
diff --git a/packages/llm/llm-deepseek/tests/messages/fixtures/red.png b/packages/llm/llm-deepseek/tests/messages/fixtures/red.png
deleted file mode 100644
index 62a5f8f47f..0000000000
Binary files a/packages/llm/llm-deepseek/tests/messages/fixtures/red.png and /dev/null differ
diff --git a/packages/llm/llm-deepseek/tests/messages/serialize.spec.ts b/packages/llm/llm-deepseek/tests/messages/serialize.spec.ts
deleted file mode 100644
index dbb1424056..0000000000
--- a/packages/llm/llm-deepseek/tests/messages/serialize.spec.ts
+++ /dev/null
@@ -1,454 +0,0 @@
-/** Request conversion and durable replay validation. */
-import { describe, expect, it, vi } from 'vitest'
-import { createDeveloperMessage, createUserMessage, createAssistantMessage, createMessage, createSystemMessage, createToolResultMessage, ReasoningEffortId, ToolCallId } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, GenerateOptions, ImageBlock, Message, RequestMessage, RequestUserInput } from '@deepseek-ai/dsh-llm'
-import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
-import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import { resolveAdapterOptions } from '../../src/config.ts'
-import { modelInfo } from '../../src/common/model-info.ts'
-import type { Config } from '../../src/config.ts'
-import { imagePricing, inlineImages, prepareImages } from '../../src/protocols/messages/images.ts'
-import { readReplay, replayState } from '../../src/protocols/messages/replay.ts'
-import { serialize } from '../../src/protocols/messages/serialize.ts'
-import { MODEL, options, user } from './helpers.ts'
-
-const connection = resolveAdapterOptions({})
-const call = (id = 'a'): ContentBlock => ({ type: 'tool-call', id: ToolCallId(id), name: 'read', arguments: '{"path":"a"}' })
-const assistant = (content: ContentBlock[]) => createAssistantMessage({ content, source: { provider: 'deepseek-official', model: MODEL } })
-const result = (id = 'a', content: ContentBlock[] = [{ type: 'text', text: 'result' }]) => createToolResultMessage({ callId: ToolCallId(id), content, isError: false })
-const body = (messages: RequestMessage[] = [user()], overrides: Partial<GenerateOptions> = {}) => serialize(
-  options({ messages, ...overrides }), connection, messages, new Map(), () => undefined,
-)
-const capable = resolveAdapterOptions({ models: [{ id: MODEL, systemPromptUpdate: 'in-history' }] })
-const nativeBody = (messages: Message[]) => serialize(options({ messages }), capable, messages, new Map(), () => undefined)
-
-describe('Messages request conversion', () => {
-  it('rejects unknown plugin content without interpreting its payload', () => {
-    expect(() => body([createUserMessage({ source: { kind: 'user' }, content: [
-      { type: 'plugin:text', text: 'opaque' } as never,
-    ] })])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
-  })
-  it.each(['user', 'system', 'assistant', 'tool'] as const)('rejects tool-change blocks in %s history', (role) => {
-    for (const type of ['tool-addition', 'tool-removal'] as const) {
-      const message = { id: 'invalid', role, source: { kind: 'test' }, content: [{ type, toolName: 'search' }] } as unknown as Message
-      expect(() => body([message])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
-    }
-  })
-
-  it('rejects deferred tool definitions until provider loading is implemented', () => {
-    expect(() => body([], { tools: [{ name: 'search', description: '', parameters: {}, deferLoading: true }] }))
-      .toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
-  })
-
-  it('preserves the exact request with request-only text after durable tool results', () => {
-    const prefix = [user(), assistant([call()]), result()]
-    const input: RequestUserInput = { role: 'user', content: [{ type: 'text', text: 'review or summarize this input' }] }
-    const durable = createUserMessage({ content: input.content, source: { kind: 'user' } })
-    expect(body([...prefix, input], { system: 'policy' })).toEqual(body([...prefix, durable], { system: 'policy' }))
-  })
-
-  it('preserves request-only image content through image preparation and wire conversion', async () => {
-    const attachment: ImageAttachmentRef = {
-      attachmentId: AttachmentId(`sha256:${'e'.repeat(64)}`), mediaType: 'image/png', bytes: 3, width: 1, height: 1,
-    }
-    const version: RequestImageAttachment = {
-      variantId: ImageVariantId(`sha256:${'f'.repeat(64)}`), attachment, data: Uint8Array.of(1, 2, 3),
-      mediaType: 'image/png', bytes: 3, width: 1, height: 1, depth: 'uchar', space: 'srgb', hasAlpha: true,
-    }
-    const input: RequestUserInput = { role: 'user', content: [
-      { type: 'text', text: 'before' }, { type: 'image', attachment }, { type: 'text', text: 'after' },
-    ] }
-    const store = { readImageRequest: async () => version } as unknown as AttachmentStore
-    const vision = resolveAdapterOptions({ models: [{ id: MODEL, inputModalities: ['text', 'image'] }] })
-    const durable = createUserMessage({ content: input.content, source: { kind: 'user' } })
-    const actual = await prepareImages([input], vision, MODEL, store, () => undefined, new AbortController().signal)
-    const expected = await prepareImages([durable], vision, MODEL, store, () => undefined, new AbortController().signal)
-    expect(serialize(options({ messages: [input] }), vision, actual.messages, actual.versions, () => undefined))
-      .toEqual(serialize(options({ messages: [durable] }), vision, expected.messages, expected.versions, () => undefined))
-    expect(actual.messages[0]).toBe(input)
-    expect(input).not.toHaveProperty('id')
-    expect(input).not.toHaveProperty('source')
-  })
-
-  it('rejects developer history while provider serialization is unsupported', () => {
-    const message = createDeveloperMessage({ content: [{ type: 'tool-addition', toolName: 'search' }], source: { kind: 'tool-registry' } })
-    expect(() => body([message])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
-  })
-
-  it('keeps the original top-level prompt and cached prefix while appending native system updates', () => {
-    const head = createSystemMessage('original')
-    const first = [head, user('first')]
-    const update = createSystemMessage('updated')
-    const second = [...first, assistant([{ type: 'text', text: 'one' }]), update, user('second')]
-    const saved = JSON.stringify(second)
-    const before = nativeBody(first)
-    const after = nativeBody(second)
-    expect(after.system).toBe(before.system)
-    expect(after.messages.slice(0, before.messages.length)).toEqual(before.messages)
-    expect(after.messages.slice(-2)).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'second' }] },
-      { role: 'system', content: [{ type: 'text', text: 'updated' }] },
-    ])
-    const third = nativeBody([...second, assistant([{ type: 'text', text: 'two' }]), user('third')])
-    expect(third.messages.slice(0, after.messages.length)).toEqual(after.messages)
-    expect(JSON.stringify(second)).toBe(saved)
-  })
-
-  it('places system updates after all parallel tool results and before the next assistant', () => {
-    const history = [createSystemMessage('original'), user(), assistant([call(), call('b')]),
-      createSystemMessage('first update'), result(), createSystemMessage('second update'), result('b'),
-      user('more input'), assistant([{ type: 'text', text: 'done' }])]
-    const request = nativeBody(history)
-    expect(request.messages.map(message => message.role)).toEqual(['user', 'assistant', 'user', 'system', 'system', 'assistant'])
-    expect(request.messages[2]?.content.map(block => block.type)).toEqual(['tool_result', 'tool_result', 'text'])
-    expect(request.messages.slice(3, 5).map(message => message.content)).toEqual([
-      [{ type: 'text', text: 'first update' }], [{ type: 'text', text: 'second update' }],
-    ])
-  })
-
-  it('accepts native trailing updates without a top-level prompt and rejects unrepresentable positions', () => {
-    const update = createSystemMessage('update')
-    expect(nativeBody([user(), update])).toMatchObject({ messages: [
-      { role: 'user' }, { role: 'system', content: [{ type: 'text', text: 'update' }] },
-    ] })
-    expect(nativeBody([user(), update]).system).toBeUndefined()
-    expect(() => nativeBody([user(), assistant([{ type: 'text', text: 'done' }]), update])).toThrow(/preceding user/)
-    expect(() => nativeBody([user(), createSystemMessage('')])).toThrow(/empty in-history/)
-    expect(() => nativeBody([user(), assistant([call(), call('b')]), update, result()])).toThrow(/immediate results/)
-  })
-
-  it.each([[], [{ type: 'reasoning', text: 'child reasoning' }], [call('child-call')]] satisfies ContentBlock[][])(
-    'rejects native system updates when their user input is omitted %#', (...content) => {
-      const empty = createMessage({ role: 'user', source: { kind: 'user' }, content })
-      const history = [user(), assistant([{ type: 'text', text: 'answer' }]), createSystemMessage('updated'), empty]
-      const saved = JSON.stringify(history)
-      for (const messages of [history, [...history, assistant([{ type: 'text', text: 'next answer' }])]]) {
-        expect(() => nativeBody(messages)).toThrow(expect.objectContaining({
-          code: 'UNSUPPORTED_CONTENT',
-          message: 'DeepSeek Messages cannot represent system update without a preceding user or tool-result turn',
-        }))
-      }
-      expect(JSON.stringify(history)).toBe(saved)
-    },
-  )
-
-  it('keeps native system updates after retained text or tool results beside omitted user input', () => {
-    const reasoning: ContentBlock = { type: 'reasoning', text: 'child reasoning' }
-    const empty = createMessage({ role: 'user', source: { kind: 'user' }, content: [reasoning] })
-    const update = createSystemMessage('updated')
-    for (const [previous, retained, expected] of [
-      [assistant([{ type: 'text', text: 'answer' }]), user('continue'), [{ type: 'text', text: 'continue' }]],
-      [assistant([call()]), result('a', [reasoning]), [{ type: 'tool_result', tool_use_id: 'a', content: [], is_error: false }]],
-    ] as const) {
-      const history = [user(), previous, update, empty, retained, assistant([{ type: 'text', text: 'done' }])]
-      const saved = JSON.stringify(history)
-      const request = nativeBody(history)
-      expect(request.messages.map(message => message.role)).toEqual(['user', 'assistant', 'user', 'system', 'assistant'])
-      expect(request.messages[2]?.content).toEqual(expected)
-      expect(request.messages[3]?.content).toEqual([{ type: 'text', text: 'updated' }])
-      expect(JSON.stringify(history)).toBe(saved)
-    }
-  })
-
-  it('groups parallel results before ordinary text and keeps tool failure content', () => {
-    const messages = [user(), assistant([call(), call('b')]), user('follow-up'), result(), createToolResultMessage({ callId: ToolCallId('b'), content: [{ type: 'text', text: 'permission denied' }], isError: true })]
-    expect(body(messages).messages).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-      { role: 'assistant', content: ['a', 'b'].map(id => ({ type: 'tool_use', id, name: 'read', input: { path: 'a' } })) },
-      { role: 'user', content: [
-        { type: 'tool_result', tool_use_id: 'a', content: [{ type: 'text', text: 'result' }], is_error: false },
-        { type: 'tool_result', tool_use_id: 'b', content: [{ type: 'text', text: 'permission denied' }], is_error: true },
-        { type: 'text', text: 'follow-up' },
-      ] },
-    ])
-    expect(messages[2]?.content).toEqual([{ type: 'text', text: 'follow-up' }])
-  })
-
-  it('preserves empty results without inventing model-visible output', () => {
-    const response = body([user(), assistant([call()]), result('a', [])])
-    expect(response.messages[2]?.content[0]).toMatchObject({ content: [] })
-    const { isError: _isError, ...minimal } = createToolResultMessage({ callId: ToolCallId('a'), content: [{ type: 'text', text: '' }], isError: false })
-    expect(body([assistant([call()]), minimal]).messages[1]?.content[0]).toEqual({ type: 'tool_result', tool_use_id: 'a', content: [] })
-  })
-
-  it('omits assistant-only blocks from user input while preserving text and durable content', () => {
-    const history = [createMessage({ role: 'user', source: { kind: 'user' }, content: [
-      { type: 'text', text: 'Background subagent finished.\n' },
-      { type: 'reasoning', text: 'child reasoning' },
-      call('child-call'),
-      { type: 'text', text: '  child answer  ' },
-    ] })]
-    const saved = JSON.stringify(history)
-
-    expect(body(history).messages).toEqual([{ role: 'user', content: [
-      { type: 'text', text: 'Background subagent finished.\n' },
-      { type: 'text', text: '  child answer  ' },
-    ] }])
-    expect(JSON.stringify(history)).toBe(saved)
-  })
-
-  it('omits assistant-only blocks inside tool results while retaining calls, errors and empty results', () => {
-    const reasoning: ContentBlock = { type: 'reasoning', text: 'tool reasoning' }
-    const history = [assistant([reasoning, call(), call('b')]),
-      createToolResultMessage({ callId: ToolCallId('a'), content: [reasoning, call('nested-call'), { type: 'text', text: '  result\n' }], isError: true }),
-      result('b', [reasoning, call('another-nested-call')]),
-    ]
-    const saved = JSON.stringify(history)
-
-    expect(body(history).messages).toEqual([
-      { role: 'assistant', content: [
-        { type: 'thinking', thinking: 'tool reasoning' },
-        ...['a', 'b'].map(id => ({ type: 'tool_use', id, name: 'read', input: { path: 'a' } })),
-      ] },
-      { role: 'user', content: [
-        { type: 'tool_result', tool_use_id: 'a', content: [{ type: 'text', text: '  result\n' }], is_error: true },
-        { type: 'tool_result', tool_use_id: 'b', content: [], is_error: false },
-      ] },
-    ])
-    expect(JSON.stringify(history)).toBe(saved)
-  })
-
-  it.each([
-    [], [{ type: 'reasoning', text: 'child reasoning' }], [call('child-call')],
-  ] satisfies ContentBlock[][])('omits empty user input after conversion %#', (...content) => {
-    const empty = createMessage({ role: 'user', source: { kind: 'user' }, content })
-    expect(body([empty, user(), assistant([{ type: 'text', text: 'answer' }]), empty]).messages).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-      { role: 'assistant', content: [{ type: 'text', text: 'answer' }] },
-    ])
-  })
-
-  it('collects leading system text and maps tools, stop sequences and explicit output cap', () => {
-    const system = createMessage({ role: 'system', source: { kind: 'system-prompt' }, content: [{ type: 'text', text: 'instructions' }] })
-    expect(body([system, user()], { system: 'top', maxTokens: 123, stop: ['END'], tools: [{ name: 'read', description: 'Read a file', parameters: { type: 'object' } }] })).toMatchObject({
-      system: 'top\n\ninstructions', max_tokens: 123, stop_sequences: ['END'], tools: [{ name: 'read', description: 'Read a file', input_schema: { type: 'object' } }],
-    })
-    expect(body([user(), system]).system).toBe('instructions')
-  })
-
-  it('uses the latest complete system snapshot without changing tool history or durable messages', () => {
-    const conversation = [user(), assistant([call()]), result(), assistant([{ type: 'text', text: 'done' }]), user('continue')]
-    const history = [createSystemMessage('obsolete'), ...conversation.slice(0, 2),
-      createSystemMessage('intermediate'), ...conversation.slice(2, 4),
-      createSystemMessage('current'), conversation[4]!]
-    const saved = JSON.stringify(history)
-    expect(body(history)).toEqual({ ...body(conversation), system: 'current' })
-    expect(body(history, { system: 'one-shot prefix' }).system).toBe('one-shot prefix\n\ncurrent')
-    expect(JSON.stringify(history)).toBe(saved)
-  })
-
-  it('replaces adjacent system snapshots and joins blocks only within the current snapshot', () => {
-    const latest = createMessage({ role: 'system', source: { kind: 'system-prompt' },
-      content: [{ type: 'text', text: 'part one' }, { type: 'text', text: ' and part two' }] })
-    expect(body([createSystemMessage('old'), latest, user()]).system).toBe('part one and part two')
-  })
-
-  it.each([[], [{ type: 'text' as const, text: '' }]].map(content => ({ content })))('clears earlier prompt snapshots with empty content %#', ({ content }) => {
-    const cleared = createMessage({ role: 'system', source: { kind: 'system-prompt' }, content })
-    const history = [createSystemMessage('old'), user(), cleared]
-    expect(body(history).system).toBeUndefined()
-    expect(body(history, { system: 'one-shot prefix' }).system).toBe('one-shot prefix')
-    expect(body(history, { system: '' }).system).toBeUndefined()
-  })
-
-  it('rejects non-text system content even when a later snapshot supersedes it', () => {
-    const invalid = createMessage({ role: 'system', source: { kind: 'system-prompt' }, content: [{ type: 'reasoning', text: 'bad' }] })
-    expect(() => body([invalid, user(), createSystemMessage('current')])).toThrow(/non-text system/)
-  })
-
-  it.each(['off', 'low', 'high', 'max'])('maps reasoning effort %s', (effort) => {
-    const request = body([user()], { reasoningEffort: ReasoningEffortId(effort) })
-    expect(request.thinking.type).toBe(effort === 'off' ? 'disabled' : 'enabled')
-    expect(request.output_config).toEqual(effort === 'off' ? undefined : { effort })
-  })
-
-  it('disables thinking for titles, passes temperature with thinking and refuses unsupported effort', () => {
-    expect(body([user()], { purpose: 'session-title', temperature: 0 })).toMatchObject({ thinking: { type: 'disabled' }, temperature: 0 })
-    expect(body([user()], { temperature: 0 })).toMatchObject({ thinking: { type: 'enabled' }, temperature: 0 })
-    expect(() => body([user()], { reasoningEffort: ReasoningEffortId('medium') })).toThrow(/effort/)
-    const disabled = resolveAdapterOptions({ thinking: 'disabled' })
-    expect(serialize(options(), disabled, [user()], new Map(), () => undefined).thinking).toEqual({ type: 'disabled' })
-    expect(() => serialize(options({ reasoningEffort: ReasoningEffortId('high') }), disabled, [user()], new Map(), () => undefined)).toThrow(/effort/)
-    const capped = resolveAdapterOptions({ models: [{ id: MODEL, maxTokens: 321 }] })
-    expect(serialize(options(), capped, [user()], new Map(), () => undefined).max_tokens).toBe(321)
-  })
-
-  it.each([
-    [result()], [assistant([call()])], [assistant([call()]), user()],
-    [assistant([call(), call()]), result()],
-    [assistant([call()]), result(), result()],
-  ])('rejects unmatched or duplicated tool history %#', (...messages) => {
-    expect(() => body(messages)).toThrow(/tool/)
-  })
-
-  it.each(['{', '', '[]', 'null', '42', 'true', '"text"', '{"description":"最快，但"某个说法"没有证据。"}'])('uses empty input for malformed or non-object historical tool arguments %s', (arguments_) => {
-    const message = assistant([{ type: 'tool-call', id: ToolCallId('a'), name: 'read', arguments: arguments_ }])
-    const history = [user(), message, createToolResultMessage({ callId: ToolCallId('a'), content: [{ type: 'text', text: 'Invalid arguments' }], isError: true }), user('Continue')]
-    const saved = JSON.stringify(history)
-    const restored = JSON.parse(saved) as Message[]
-    expect(body(restored).messages).toEqual([
-      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-      { role: 'assistant', content: [{ type: 'tool_use', id: 'a', name: 'read', input: {} }] },
-      { role: 'user', content: [
-        { type: 'tool_result', tool_use_id: 'a', content: [{ type: 'text', text: 'Invalid arguments' }], is_error: true },
-        { type: 'text', text: 'Continue' },
-      ] },
-    ])
-    expect(JSON.stringify(restored)).toBe(saved)
-  })
-
-  it('preserves own signed thinking, omits absent signatures and validates durable metadata', () => {
-    const content: ContentBlock[] = [{ type: 'reasoning', text: '' }, { type: 'text', text: 'answer' }]
-    const source = { provider: 'deepseek-official', model: MODEL, replayState: replayState(MODEL, [{ type: 'reasoning', signature: 'signed' }, { type: 'text' }]) }
-    const message = createAssistantMessage({ content, source })
-    expect(body([user(), message, user()]).messages[1]?.content).toEqual([{ type: 'thinking', thinking: '', signature: 'signed' }, { type: 'text', text: 'answer' }])
-    expect(body([assistant([{ type: 'reasoning', text: 'foreign thought' }])]).messages[0]?.content).toEqual([{ type: 'thinking', thinking: 'foreign thought' }])
-    expect(readReplay(message, 'different-model')).toBeUndefined()
-    expect(readReplay(user(), MODEL)).toBeUndefined()
-  })
-
-  it.each([
-    null,
-    [],
-    { response: null, blocks: [] },
-    { response: { kind: 'other', version: 1 }, blocks: [] },
-    { response: { kind: 'deepseek-messages', version: 2 }, blocks: [] },
-    { response: { kind: 'deepseek-messages', version: 1, model: 'wrong' }, blocks: [] },
-    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [] },
-    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: null },
-    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [null] },
-    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [{ type: 'tool-call' }] },
-    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [{ type: 'reasoning', signature: 3 }] },
-  ].map(state => ({ state })))('degrades unusable replay state with a diagnostic %#', ({ state }) => {
-    const message = createAssistantMessage({ content: [{ type: 'reasoning', text: 'think' }], source: { provider: 'deepseek-official', model: MODEL, replayState: state } })
-    const onDegrade = vi.fn()
-    expect(readReplay(message, MODEL, onDegrade)).toBeUndefined()
-    expect(onDegrade).toHaveBeenCalledExactlyOnceWith(expect.any(String))
-    expect(body([message]).messages[0]?.content).toEqual([{ type: 'thinking', thinking: 'think' }])
-  })
-
-  it.each([MODEL, 'different-model'])('keeps durable content when replay degrades for %s', async (model) => {
-    const message = createAssistantMessage({
-      content: [{ type: 'reasoning', text: 'Read the file.' }, { type: 'text', text: 'Checking a.' }, call()],
-      source: { provider: 'deepseek-official', model: MODEL, replayState: replayState(MODEL, [
-        { type: 'reasoning', signature: 'do-not-send' }, { type: 'text', signature: 'invalid-for-text' }, { type: 'tool-call' },
-      ]) },
-    })
-    const saved = JSON.stringify(message)
-    const restored = JSON.parse(saved) as Message
-    const messages = [user(), restored, result()]
-    const onDegrade = vi.fn()
-    const request = serialize(options({ model }), connection, messages, new Map(), () => undefined, onDegrade)
-    expect(onDegrade).toHaveBeenCalledExactlyOnceWith('DeepSeek Messages replay: invalid signature')
-    await expect(JSON.stringify(request.messages, null, 2) + '\n').toMatchFileSnapshot('expected/degraded-replay.json')
-    expect(JSON.stringify(restored)).toBe(saved)
-  })
-
-  it('keeps valid cross-model and foreign history quiet and propagates diagnostic failures', () => {
-    const onDegrade = vi.fn()
-    const message = createAssistantMessage({ content: [{ type: 'reasoning', text: 'think' }], source: {
-      provider: 'deepseek-official', model: MODEL, replayState: replayState(MODEL, [{ type: 'reasoning', signature: '' }]),
-    } })
-    expect(readReplay(message, MODEL, onDegrade)).toEqual([{ type: 'reasoning', signature: '' }])
-    expect(readReplay(message, 'different-model', onDegrade)).toBeUndefined()
-    expect(readReplay(assistant([{ type: 'text', text: 'foreign' }]), MODEL, onDegrade)).toBeUndefined()
-    expect(onDegrade).not.toHaveBeenCalled()
-    const damaged = { ...message, source: { ...message.source, replayState: { response: {}, blocks: [] } } }
-    const failure = new Error('diagnostic failed')
-    expect(() => readReplay(damaged, MODEL, () => { throw failure })).toThrow(failure)
-  })
-
-  it.each([1, 2])('uses empty historical tool input with replay version %s', (version) => {
-    const message = createAssistantMessage({ content: [{ type: 'tool-call', id: ToolCallId('a'), name: 'read', arguments: '{' }], source: {
-      provider: 'deepseek-official', model: MODEL, replayState: { response: { kind: 'deepseek-messages', version, model: MODEL }, blocks: [{ type: 'tool-call' }] },
-    } })
-    const saved = JSON.stringify(message)
-    const onDegrade = vi.fn()
-    const request = serialize(options(), connection, [message, result()], new Map(), () => undefined, onDegrade)
-    expect(request.messages[0]?.content).toEqual([{ type: 'tool_use', id: 'a', name: 'read', input: {} }])
-    expect(onDegrade).toHaveBeenCalledTimes(version === 1 ? 0 : 1)
-    expect(JSON.stringify(message)).toBe(saved)
-  })
-})
-
-describe('validated configuration', () => {
-  it('advertises exact model metadata and allows unlisted text models', () => {
-    expect(modelInfo(connection, 'deepseek-official', MODEL)).toMatchObject({ context: { contextWindow: 1_000_000 }, defaultMaxTokens: 256_000, reasoning: { defaultEffort: 'high' } })
-    expect(modelInfo(connection, 'deepseek-official', 'custom').inputModalities).toEqual(['text'])
-    expect(modelInfo(connection, 'deepseek-official', MODEL).systemPromptUpdate).toBeUndefined()
-    expect(modelInfo(connection, 'deepseek-official', 'custom').systemPromptUpdate).toBeUndefined()
-    expect(modelInfo(capable, 'deepseek-official', MODEL).systemPromptUpdate).toBe('in-history')
-    expect(modelInfo(capable, 'deepseek-official', 'custom').systemPromptUpdate).toBeUndefined()
-    expect(modelInfo(resolveAdapterOptions({ thinking: 'disabled' }), 'deepseek-official', MODEL).reasoning?.efforts).toMatchObject([{ id: 'off', name: 'Off' }])
-    expect(resolveAdapterOptions({ baseURL: 'https://example.com/anthropic///' }).baseURL).toBe('https://example.com/anthropic///')
-  })
-  it.each([
-    { thinking: 'disabled', reasoningEffort: 'high' }, { models: [{ id: '' }] },
-    { models: [{ id: 'a' }, { id: 'a' }] }, { models: [{ id: 'a', name: '' }] },
-    { maxInlineRequestImageBytes: 1 }, { maxImagesPerRequest: 1 },
-    { baseURL: 'ftp://example.com' }, { baseURL: 'https://user:pass@example.com' },
-    { baseURL: 'https://example.com/?key=x' }, { baseURL: 'https://example.com/#x' },
-    { maxTokens: 0 }, { streamIdleTimeoutMs: 0 },
-    { models: [{ id: MODEL, systemPromptUpdate: 'unsupported' }] },
-  ])('rejects invalid composition input %#', (value) => {
-    expect(() => resolveAdapterOptions(value as Config)).toThrow()
-  })
-})
-
-describe('Messages images', () => {
-  const ref: ImageAttachmentRef = { attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`), mediaType: 'image/png', width: 1, height: 1, bytes: 3 }
-  const image: ImageBlock = { type: 'image', attachment: ref }
-  const version: RequestImageAttachment = { attachment: ref, variantId: ImageVariantId(`sha256:${'b'.repeat(64)}`), mediaType: 'image/png', bytes: 3, data: Uint8Array.of(1, 2, 3), width: 1, height: 1, depth: 'uchar', space: 'srgb', hasAlpha: false }
-  const access = () => ({ readonlyPath: '/workspace/image.png' })
-  const model = 'deepseek-flash'
-  // Only the read operation is consumed by image preparation; the transport is mocked, not durable content.
-  const attachments = { readImageRequest: async () => version } as unknown as AttachmentStore
-  const signal = new AbortController().signal
-  it('keeps image bytes inside tool results and deduplicates normalization', async () => {
-    const history = [assistant([call()]), result('a', [image, image])]
-    const prepared = await prepareImages(history, connection, model, attachments, access, signal)
-    expect(prepared.versions.size).toBe(1)
-    const request = serialize(options({ model }), connection, prepared.messages, prepared.versions, access)
-    expect(request.messages[1]?.content[0]).toMatchObject({ type: 'tool_result', content: [
-      { type: 'text', text: expect.stringContaining('/workspace/image.png') as string }, { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'AQID' } },
-      { type: 'text' }, { type: 'image' },
-    ] })
-    expect(imagePricing(connection, model, access).priceImages([image])[0]?.visualTokens).toBeGreaterThan(0)
-    expect(imagePricing(connection, MODEL, access).priceImages([image])[0]?.visualTokens).toBe(0)
-  })
-  it('requires logged offload at exact encoded bytes and preserves durable references', async () => {
-    const config = resolveAdapterOptions({
-      maxInlineRequestImageBytes: 4, inlineImageOffloadByteQuantum: 1, maxImagesPerRequest: 2, imageOffloadCountQuantum: 1,
-    })
-    const history = [result('a', [image, image])]
-    const prepared = await prepareImages(history, config, model, attachments, access, signal)
-    expect(prepared.messages[0]?.content).toMatchObject([image, image])
-    expect(() => inlineImages(prepared.messages, prepared.versions, config)).toThrow(expect.objectContaining({
-      failure: expect.objectContaining({ code: 'IMAGE_OFFLOAD_REQUIRED', offloadImages: 1 }) as unknown,
-    }))
-    const offloaded: ImageBlock = { ...image, offloaded: true }
-    const retry = await prepareImages([result('a', [offloaded, image])], config, model, attachments, access, signal)
-    expect(inlineImages(retry.messages, retry.versions, config)[0]?.content).toMatchObject([{ type: 'text' }, { type: 'image' }])
-    expect(history[0]?.content).toMatchObject([image, image])
-    expect(imagePricing(config, model, access).priceImages([image, image]).map(entry => entry.visualTokens))
-      .toEqual([expect.any(Number), expect.any(Number)])
-    const large = { readImageRequest: async () => ({ ...version, bytes: 30, data: new Uint8Array(30) }) } as unknown as AttachmentStore
-    const exact = await prepareImages([result('a', [image])], config, model, large, access, signal)
-    expect(() => inlineImages(exact.messages, exact.versions, config)).toThrow(expect.objectContaining({
-      failure: expect.objectContaining({ code: 'IMAGE_OFFLOAD_REQUIRED', offloadImages: 1 }) as unknown,
-    }))
-  })
-  it('rejects unsupported roles and unavailable image capabilities before HTTP', async () => {
-    const history = [result('a', [image])]
-    await expect(prepareImages(history, connection, MODEL, attachments, access, signal)).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-    await expect(prepareImages(history, connection, model, undefined, access, signal)).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-    await expect(prepareImages([assistant([image])], connection, model, attachments, access, signal)).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-    expect(() => body([result('a', [image])])).toThrow(/image/)
-    expect(() => body([assistant([image])])).toThrow(/assistant/)
-    // @ts-expect-error -- malformed provider input can carry a retired nested result block.
-    expect(() => body([result('a', [{ type: 'tool-result', toolCallId: ToolCallId('nested'), content: [] }])]))
-      .toThrow(/user\/tool-result content tool-result/)
-    expect(() => serialize(options({ model }), connection, [result('a', [image])], new Map([[ref.attachmentId, version]]), access, undefined, new Map()))
-      .toThrow(/request file id is missing/)
-  })
-})
diff --git a/packages/llm/llm-deepseek/tests/mock-server.ts b/packages/llm/llm-deepseek/tests/mock-server.ts
index 819a945e93..45402bdc1b 100644
--- a/packages/llm/llm-deepseek/tests/mock-server.ts
+++ b/packages/llm/llm-deepseek/tests/mock-server.ts
@@ -13,7 +13,7 @@ export interface MockServer {
   requests: unknown[]
   /** Header bags of received requests, in order (parallel to `requests`). */
   headers: IncomingMessage['headers'][]
-  /** Parsed Files API operations, excluded from chat request ordering. */
+  /** Parsed Files API operations, excluded from model request ordering. */
   fileRequests: Array<{ method: string; path: string; filename?: string; bytes?: number }>
   script: Behavior[]
   close(): Promise<void>
@@ -28,18 +28,20 @@ export async function closeMockServers(): Promise<void> {
 
 /** A minimal complete text generation, reused by request-shape assertions. */
 export const textEvents = [
-  '{"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":""}}]}',
-  '{"choices":[{"delta":{"content":"hello"}}]}',
-  '{"choices":[{"delta":{"content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
-  '[DONE]',
-]
+  { type: 'message_start', message: { id: 'msg_1', model: 'deepseek-v4-flash', usage: { input_tokens: 3, output_tokens: 0 } } },
+  { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+  { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'hello' } },
+  { type: 'content_block_stop', index: 0 },
+  { type: 'message_delta', delta: { stop_reason: 'end_turn' }, usage: { output_tokens: 1 } },
+  { type: 'message_stop' },
+].map(event => JSON.stringify(event))
 
-/** Local chat-completions stand-in: replays scripted behaviors per request. */
+/** Local Messages stand-in: replays scripted behaviors per request. */
 export async function mockServer(script: Behavior[]): Promise<MockServer> {
   const requests: unknown[] = []
   const headers: IncomingMessage['headers'][] = []
   const fileRequests: MockServer['fileRequests'] = []
-  const files = new Map<string, { id: string; object: 'file'; bytes: number; created_at: number; filename: string; purpose: 'user_data'; expires_at: number }>()
+  const files = new Map<string, { id: string; type: 'file'; size_bytes: number; created_at: string; filename: string; mime_type: string }>()
   let nextFile = 1
   const server = createServer((request: IncomingMessage, response: ServerResponse) => {
     const chunks: Buffer[] = []
@@ -48,12 +50,12 @@ export async function mockServer(script: Behavior[]): Promise<MockServer> {
       void (async () => {
         const url = new URL(request.url ?? '/', 'http://localhost')
         const body = Buffer.concat(chunks)
-        if (url.pathname === '/files' && request.method === 'POST') {
+        if (url.pathname === '/v1/files' && request.method === 'POST') {
           const headers = new Headers()
           for (const [name, value] of Object.entries(request.headers)) {
             if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(', ') : value)
           }
-          const form = await new Request('http://localhost/files', {
+          const form = await new Request('http://localhost/v1/files', {
             method: 'POST',
             headers,
             body,
@@ -62,28 +64,25 @@ export async function mockServer(script: Behavior[]): Promise<MockServer> {
           if (!(blob instanceof Blob)) throw new Error('mock upload omitted file')
           const name = 'name' in blob && typeof blob.name === 'string' ? blob.name : 'uploaded_file'
           const id = `file-api-${nextFile}`
-          const createdAt = Math.floor(Date.now() / 1_000)
+          const createdAt = new Date().toISOString()
           nextFile += 1
-          const expiresSeconds = Number(form.get('expires_after[seconds]'))
           const file = {
             id,
-            object: 'file' as const,
-            bytes: blob.size,
+            type: 'file' as const,
+            size_bytes: blob.size,
             created_at: createdAt,
             filename: name,
-            purpose: 'user_data' as const,
-            expires_at: createdAt + expiresSeconds,
+            mime_type: blob.type,
           }
           files.set(id, file)
           fileRequests.push({ method: 'POST', path: url.pathname, filename: name, bytes: blob.size })
           response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(file))
           return
         }
-        if (url.pathname === '/files' && request.method === 'GET') {
+        if (url.pathname === '/v1/files' && request.method === 'GET') {
           fileRequests.push({ method: 'GET', path: `${url.pathname}${url.search}` })
           const data = [...files.values()]
           response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({
-            object: 'list',
             data,
             first_id: data[0]?.id,
             last_id: data.at(-1)?.id,
@@ -91,17 +90,17 @@ export async function mockServer(script: Behavior[]): Promise<MockServer> {
           }))
           return
         }
-        if (url.pathname.startsWith('/files/') && request.method === 'DELETE') {
-          const id = decodeURIComponent(url.pathname.slice('/files/'.length))
+        if (url.pathname.startsWith('/v1/files/') && request.method === 'DELETE') {
+          const id = decodeURIComponent(url.pathname.slice('/v1/files/'.length))
           files.delete(id)
           fileRequests.push({ method: 'DELETE', path: url.pathname })
           response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({
-            id, object: 'file', deleted: true,
+            id, type: 'file_deleted',
           }))
           return
         }
-        if (url.pathname.startsWith('/files/') && request.method === 'GET') {
-          const id = decodeURIComponent(url.pathname.slice('/files/'.length))
+        if (url.pathname.startsWith('/v1/files/') && request.method === 'GET') {
+          const id = decodeURIComponent(url.pathname.slice('/v1/files/'.length))
           fileRequests.push({ method: 'GET', path: url.pathname })
           const file = files.get(id)
           if (file === undefined) {
diff --git a/packages/llm/llm-deepseek/tests/prepared-call.spec.ts b/packages/llm/llm-deepseek/tests/prepared-call.spec.ts
new file mode 100644
index 0000000000..68e38db8ee
--- /dev/null
+++ b/packages/llm/llm-deepseek/tests/prepared-call.spec.ts
@@ -0,0 +1,58 @@
+/** Prepared calls retain their endpoint and credential generation. */
+import { afterEach, expect, it } from 'vitest'
+import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
+import { Config, DeepSeekAdapter, resolveAdapterOptions } from '../src/index.ts'
+import type { DeepSeekConnectionOptions } from '../src/index.ts'
+import { assemble, chunks, MODEL, options, server } from './helpers.ts'
+
+const close: (() => Promise<void>)[] = []
+afterEach(async () => {
+  while (close.length) await close.pop()!()
+})
+async function endpoint(...args: Parameters<typeof server>) {
+  const instance = await server(...args)
+  close.push(() => instance.close())
+  return instance
+}
+function adapter(connection: () => DeepSeekConnectionOptions) {
+  return new DeepSeekAdapter({
+    options: connection,
+    resolveApiKey: snapshot => Promise.resolve(`key-for-${snapshot.apiKeyEnv}`),
+    resolveUserId: () => '00000000-0000-4000-8000-000000000001' as AnonymousUserId,
+    prepareExtensions: () => Promise.resolve({ fields: {}, accept: () => Promise.resolve() }),
+  })
+}
+
+it.each([false, true])('uses Messages, schema=%s', async (schema) => {
+  const http = await endpoint()
+  const raw = { baseURL: http.url }
+  const connection = resolveAdapterOptions(schema ? Config(raw) : raw)
+  const response = await assemble(adapter(() => connection).stream(options()))
+
+  expect(response.message.content).toEqual([{ type: 'text', text: 'Hello 世界' }])
+  expect(http.requests).toHaveLength(1)
+  expect(http.requests[0]).toMatchObject({
+    path: '/anthropic/v1/messages',
+    headers: { 'x-api-key': 'key-for-DEEPSEEK_API_KEY', 'anthropic-version': '2023-06-01' },
+    body: { model: MODEL, messages: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }] },
+  })
+})
+
+it('keeps the prepared credential reference and endpoint after configuration changes', async () => {
+  const first = await endpoint(), second = await endpoint()
+  let connection = resolveAdapterOptions({ baseURL: first.url, apiKeyEnv: 'FIRST_KEY', maxTokens: 12 })
+  const llm = adapter(() => connection)
+  const prepared = await llm.prepareCall('deepseek-official', MODEL)
+  connection = resolveAdapterOptions({ baseURL: second.url, apiKeyEnv: 'SECOND_KEY', maxTokens: 24 })
+  await chunks(prepared.stream(options()))
+  await chunks(prepared.stream(options()))
+  expect(prepared.model.defaultMaxTokens).toBe(12)
+  expect((await llm.resolveModel('deepseek-official', MODEL)).defaultMaxTokens).toBe(24)
+  await chunks(llm.stream(options()))
+  expect(first.requests).toHaveLength(2)
+  for (const request of first.requests) expect(request).toMatchObject({
+    path: '/anthropic/v1/messages', headers: { 'x-api-key': 'key-for-FIRST_KEY' }, body: { max_tokens: 12 },
+  })
+  expect(second.requests).toHaveLength(1)
+  expect(second.requests[0]).toMatchObject({ path: '/anthropic/v1/messages', headers: { 'x-api-key': 'key-for-SECOND_KEY' } })
+})
diff --git a/packages/llm/llm-deepseek/tests/protocol.spec.ts b/packages/llm/llm-deepseek/tests/protocol.spec.ts
deleted file mode 100644
index 788df7982f..0000000000
--- a/packages/llm/llm-deepseek/tests/protocol.spec.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-/** Same-provider protocol changes retain prepared requests and durable conversation content. */
-import { afterEach, expect, it } from 'vitest'
-import type { Message } from '@deepseek-ai/dsh-llm'
-import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
-import { Config, DeepSeekAdapter, resolveAdapterOptions } from '../src/index.ts'
-import type { DeepSeekConnectionOptions } from '../src/index.ts'
-import { assemble, chunks, end, MODEL, options, server, sse, start, textEvents, user } from './messages/helpers.ts'
-
-const close: (() => Promise<void>)[] = []
-afterEach(async () => {
-  while (close.length) await close.pop()!()
-})
-async function endpoint(...args: Parameters<typeof server>) {
-  const instance = await server(...args)
-  close.push(() => instance.close())
-  return instance
-}
-const chat = 'data: {"choices":[{"delta":{"content":"Chat answer"}}]}\n\n'
-  + 'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n'
-function adapter(connection: () => DeepSeekConnectionOptions) {
-  return new DeepSeekAdapter({
-    options: connection,
-    resolveApiKey: snapshot => Promise.resolve(`key-for-${snapshot.apiKeyEnv}`),
-    resolveUserId: () => '00000000-0000-4000-8000-000000000001' as AnonymousUserId,
-    prepareExtensions: () => Promise.resolve({ fields: {}, accept: () => Promise.resolve() }),
-  })
-}
-
-it.each([false, true])('uses Messages when protocol is omitted, schema=%s', async (schema) => {
-  const http = await endpoint()
-  const raw = { baseURL: http.url }
-  const connection = resolveAdapterOptions(schema ? Config(raw) : raw)
-  const response = await assemble(adapter(() => connection).stream(options()))
-
-  expect(response.message.content).toEqual([{ type: 'text', text: 'Hello 世界' }])
-  expect(http.requests).toHaveLength(1)
-  expect(http.requests[0]).toMatchObject({
-    path: '/anthropic/v1/messages',
-    headers: { 'x-api-key': 'key-for-DEEPSEEK_API_KEY', 'anthropic-version': '2023-06-01' },
-    body: { model: MODEL, messages: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }] },
-  })
-})
-
-it('keeps the prepared Messages protocol, credential reference and endpoint after switching to Chat', async () => {
-  const first = await endpoint(), second = await endpoint(response => response.end(chat))
-  let connection = resolveAdapterOptions({ protocol: 'messages', baseURL: first.url, apiKeyEnv: 'MESSAGES_KEY', maxTokens: 12 })
-  const llm = adapter(() => connection)
-  const prepared = await llm.prepareCall('deepseek-official', MODEL)
-  connection = resolveAdapterOptions({ protocol: 'chat-completions', baseURL: second.url, apiKeyEnv: 'CHAT_KEY', maxTokens: 24 })
-  await chunks(prepared.stream(options()))
-  await chunks(prepared.stream(options()))
-  expect(prepared.model.defaultMaxTokens).toBe(12)
-  expect((await llm.resolveModel('deepseek-official', MODEL)).defaultMaxTokens).toBe(24)
-  await chunks(llm.stream(options()))
-  expect(first.requests).toHaveLength(2)
-  for (const request of first.requests) expect(request).toMatchObject({
-    path: '/anthropic/v1/messages', headers: { 'x-api-key': 'key-for-MESSAGES_KEY' }, body: { max_tokens: 12 },
-  })
-  expect(second.requests).toHaveLength(1)
-  expect(second.requests[0]).toMatchObject({ path: '/anthropic/chat/completions', headers: { authorization: 'Bearer key-for-CHAT_KEY' } })
-})
-
-it('continues Messages → Chat → Messages with the same provider and without leaking native signatures to Chat', async () => {
-  const signed = [start,
-    { type: 'content_block_start', index: 0, content_block: { type: 'thinking', thinking: 'Reasoning', signature: 'native-signature' } },
-    { type: 'content_block_stop', index: 0 },
-    { type: 'content_block_start', index: 1, content_block: { type: 'text', text: 'Messages answer' } },
-    { type: 'content_block_stop', index: 1 }, ...end(),
-  ]
-  const http = await endpoint((response, count) => response.end(count === 1 ? sse(signed) : count === 2 ? chat : sse(textEvents)))
-  let connection = resolveAdapterOptions({ protocol: 'messages', baseURL: http.url })
-  const llm = adapter(() => connection)
-  const history: Message[] = [user()]
-  const first = await assemble(llm.stream(options({ messages: history })))
-  history.push(first.message, user('continue with Chat'))
-  const saved = JSON.stringify(history)
-  connection = resolveAdapterOptions({ protocol: 'chat-completions', baseURL: http.url })
-  const second = await assemble(llm.stream(options({ messages: history })))
-  expect(JSON.stringify(http.requests[1]?.body)).not.toContain('signature')
-  expect(http.requests[1]?.body.messages).toContainEqual({ role: 'assistant', content: 'Messages answer', reasoning_content: 'Reasoning' })
-  expect(JSON.stringify(history)).toBe(saved)
-  expect(second.message.source.replayState).toBeUndefined()
-  history.push(second.message, user('continue with Messages'))
-  connection = resolveAdapterOptions({ protocol: 'messages', baseURL: http.url })
-  const third = await assemble(llm.stream(options({ messages: history })))
-  expect(third.assembler.finish.kind).toBe('stop')
-  const messages = http.requests[2]?.body.messages as { role: string; content: unknown[] }[]
-  expect(messages.filter(message => message.role === 'assistant')).toEqual([
-    { role: 'assistant', content: [{ type: 'thinking', thinking: 'Reasoning', signature: 'native-signature' }, { type: 'text', text: 'Messages answer' }] },
-    { role: 'assistant', content: [{ type: 'text', text: 'Chat answer' }] },
-  ])
-})
diff --git a/packages/llm/llm-deepseek/tests/request-pricing.spec.ts b/packages/llm/llm-deepseek/tests/request-pricing.spec.ts
index bf2216d6c8..cb4b31d3c6 100644
--- a/packages/llm/llm-deepseek/tests/request-pricing.spec.ts
+++ b/packages/llm/llm-deepseek/tests/request-pricing.spec.ts
@@ -3,7 +3,7 @@ import { offloadedImageText, requestImageHandleText, textOnlyImageText } from '@
 import type { ImageBlock } from '@deepseek-ai/dsh-llm'
 import { AttachmentId } from '@deepseek-ai/dsh-attachment'
 import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
-import { deepSeekImageRequestPricing } from '../src/common/request-pricing.ts'
+import { deepSeekImageRequestPricing } from '../src/request-pricing.ts'
 import { resolveAdapterOptions } from '../src/index.ts'
 import type { Config } from '../src/index.ts'
 
diff --git a/packages/llm/llm-deepseek/tests/runtime.e2e.ts b/packages/llm/llm-deepseek/tests/runtime.e2e.ts
new file mode 100644
index 0000000000..e2634f8d64
--- /dev/null
+++ b/packages/llm/llm-deepseek/tests/runtime.e2e.ts
@@ -0,0 +1,462 @@
+import { readFileSync } from 'node:fs'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import LlmRuntime, { createToolResultMessage, createUserMessage, ToolCallId, ReasoningEffortId, createMessage, createSystemMessage } from '@deepseek-ai/dsh-llm'
+import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
+import AttachmentStore, { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
+import LocalAttachments from '@deepseek-ai/dsh-attachment-local'
+import type {
+  ImageAttachmentLimits,
+  ImageAttachmentRef,
+  ImageRequestTarget,
+  RequestImageAttachment,
+  SaveImageAttachment,
+  StoredImageAttachment,
+} from '@deepseek-ai/dsh-attachment'
+import { LocalCredentialProvider } from '@deepseek-ai/dsh-credentials-local'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
+import * as PluginPackageInventoryDeepSeek from '@deepseek-ai/dsh-plugin-package-inventory-deepseek'
+import * as SessionLogDeepSeek from '@deepseek-ai/dsh-session-log-deepseek'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import type { Config } from '@deepseek-ai/dsh-llm-deepseek'
+import type { WireRequest } from '../src/wire-types.ts'
+import { assemble, type AssembledResult } from './assemble.ts'
+
+/**
+ * Real-API e2e for the direct-fetch adapter: V4 Flash across thinking modes
+ * and a max-effort tool round trip with reasoning passback. The suite skips
+ * entirely without $DEEPSEEK_API_KEY; the pre-release vision smoke additionally
+ * requires $DEEPSEEK_VISION_E2E=1, and the Flash image/system-update smoke
+ * requires $DEEPSEEK_FLASH_E2E=1.
+ */
+
+const FLASH = 'deepseek-v4-flash'
+const VISION = 'deepseek-v4-flash-vision-exp'
+const VISION_E2E_ENABLED = process.env.DEEPSEEK_VISION_E2E === '1'
+/** A model whose endpoint reads the latest `system` message at any position; unset skips the in-history smoke. */
+const IN_HISTORY_MODEL = process.env.DEEPSEEK_IN_HISTORY_MODEL
+const TEST_PNG = Uint8Array.from(readFileSync(
+  new URL('../../llm-pi-ai/tests/fixtures/qr-code.png', import.meta.url),
+))
+const contexts: Context[] = []
+let identityHome: string
+
+class E2eAttachmentStore extends AttachmentStore {
+  readonly imageLimits: ImageAttachmentLimits = {
+    maxImageBytes: TEST_PNG.byteLength,
+    maxImagesPerMessage: 1,
+    maxMessageImageBytes: TEST_PNG.byteLength,
+    maxImagePixels: 256 * 256,
+    maxImageDimension: 256,
+    mediaTypes: ['image/png'],
+  }
+  readonly ref: ImageAttachmentRef = {
+    attachmentId: AttachmentId(`sha256:${randomBytes(32).toString('hex')}`),
+    mediaType: 'image/png',
+    bytes: TEST_PNG.byteLength,
+    width: 256,
+    height: 256,
+    name: 'files-api-e2e.png',
+  }
+  readonly version: RequestImageAttachment = {
+    variantId: ImageVariantId(`sha256:${randomBytes(32).toString('hex')}`),
+    attachment: this.ref,
+    data: TEST_PNG,
+    mediaType: 'image/png',
+    bytes: TEST_PNG.byteLength,
+    width: 256,
+    height: 256,
+    depth: 'uchar',
+    space: 'srgb',
+    hasAlpha: false,
+  }
+
+  validateImage(_input: SaveImageAttachment): Promise<void> {
+    return Promise.resolve()
+  }
+
+  saveImage(_input: SaveImageAttachment): Promise<ImageAttachmentRef> {
+    return Promise.resolve(this.ref)
+  }
+
+  readImage(ref: ImageAttachmentRef, _signal?: AbortSignal): Promise<StoredImageAttachment> {
+    return Promise.resolve({ ref, data: TEST_PNG })
+  }
+
+  override readImageRequest(
+    _ref: ImageAttachmentRef,
+    _target: ImageRequestTarget,
+    _signal?: AbortSignal,
+  ): Promise<RequestImageAttachment> {
+    return Promise.resolve(this.version)
+  }
+}
+
+beforeEach(async () => {
+  identityHome = await mkdtemp(join(tmpdir(), 'dsh-e2e-user-id-'))
+  vi.stubEnv('DSH_HOME', identityHome)
+})
+
+async function harness(model: string, config: Partial<Config> = {}) {
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(LlmRuntime)
+  await ctx.plugin(E2eAttachmentStore)
+  await ctx.plugin(LlmDeepSeek, {
+    baseURL: LlmDeepSeek.PUBLIC_BASE_URL,
+    ...model === VISION ? { models: [{ id: VISION, inputModalities: ['text', 'image'] }] } : {},
+    ...config,
+  })
+  return ctx
+}
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  vi.unstubAllGlobals()
+  vi.unstubAllEnvs()
+  await rm(identityHome, { recursive: true, force: true })
+})
+
+function ask(text: string): Message[] {
+  return [createUserMessage({
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  })]
+}
+
+function textOf(result: AssembledResult): string {
+  return result.message.content
+    .filter(block => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+const weatherTool: ToolSchema = {
+  name: 'get_weather',
+  description: 'Get the current weather for a city.',
+  parameters: {
+    type: 'object',
+    properties: { city: { type: 'string', description: 'City name' } },
+    required: ['city'],
+  },
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', () => {
+  it.skipIf(process.env.DEEPSEEK_FLASH_E2E !== '1')('deepseek-flash accepts images and retains system updates', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LocalAttachments)
+    await ctx.plugin(LlmDeepSeek, { baseURL: LlmDeepSeek.PUBLIC_BASE_URL, maxTokens: 4096 })
+    const model = 'deepseek-flash'
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', model)).resolves.toMatchObject({
+      inputModalities: ['text', 'image'], systemPromptUpdate: 'in-history',
+    })
+    const attachment = await ctx.attachments.saveImage({ data: readFileSync(new URL('fixtures/red.png', import.meta.url)), mediaType: 'image/png' })
+    const message = ask('What is the dominant color of this image?')[0]!
+    const history: Message[] = [
+      createSystemMessage('Answer with one English color word.'),
+      { ...message, content: [...message.content, { type: 'image', attachment }] },
+    ]
+    const reply = async () => {
+      const response = await assemble(ctx, { model, messages: history, reasoningEffort: ReasoningEffortId('high') })
+      expect(response.finish.kind, JSON.stringify(response.finish)).toBe('stop')
+      history.push(response.message)
+      return textOf(response).trim().toLowerCase()
+    }
+    expect(await reply()).toMatch(/^red[.!]?$/)
+    history.push(createSystemMessage('Reply to every user message with exactly banana.'), ...ask('Answer now.'))
+    expect(await reply()).toBe('banana')
+    history.push(...ask('Answer again.'))
+    expect(await reply()).toBe('banana')
+  })
+
+  it.skipIf(!VISION_E2E_ENABLED)('uses the built-in official route to upload, reference, and delete one image', async () => {
+    const key = process.env.DEEPSEEK_API_KEY
+    if (key === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
+    const baseURL = LlmDeepSeek.PUBLIC_BASE_URL
+    const ctx = await harness(VISION, { baseURL })
+    await ctx.plugin(E2eAttachmentStore)
+    const attachments = ctx.attachments as E2eAttachmentStore
+    let uploadedFile: LlmDeepSeek.DeepSeekFileIdType | undefined
+    const nativeFetch = globalThis.fetch
+    const observedFetch: typeof fetch = async (input, init) => {
+      const response = await nativeFetch(input, init)
+      const url = new URL(input instanceof Request ? input.url : input)
+      const method = init?.method ?? (input instanceof Request ? input.method : 'GET')
+      if (method === 'POST' && url.pathname.endsWith('/files') && response.ok) {
+        const value = await response.clone().json() as { id?: unknown }
+        if (typeof value.id === 'string') uploadedFile = LlmDeepSeek.DeepSeekFileId(value.id)
+      }
+      return response
+    }
+    vi.stubGlobal('fetch', observedFetch)
+    const files = new LlmDeepSeek.DeepSeekFilesClient({ baseURL, apiKey: key })
+
+    try {
+      const result = await assemble(ctx, {
+        model: VISION,
+        messages: [createUserMessage({
+          content: [
+            { type: 'text', text: 'Briefly describe this image.' },
+            { type: 'image', attachment: attachments.ref },
+          ],
+          source: { kind: 'user' },
+        })],
+        maxTokens: 100,
+      })
+      expect(
+        result.finish.kind,
+        `DeepSeek vision result: ${JSON.stringify(result.finish)}`,
+      ).toBe('stop')
+      expect(textOf(result).trim().length).toBeGreaterThan(0)
+      expect(uploadedFile).toMatch(/^file-api-/u)
+    } finally {
+      if (uploadedFile !== undefined) await files.delete(uploadedFile)
+    }
+  })
+
+  it('accepts the session-log and plugin-package request extension fields', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(Loader)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
+    await ctx.plugin(SessionLogDeepSeek, { enabled: true })
+    await ctx.plugin(PluginPackageInventoryDeepSeek)
+    await ctx.plugin(LlmDeepSeek, { baseURL: LlmDeepSeek.PUBLIC_BASE_URL, thinking: 'disabled' })
+    const session = ctx.sessions.create(SessionId('real-extension-fields'))
+    session.append('turn/start', { turn: 1 })
+
+    const result = await assemble(ctx, {
+      model: FLASH,
+      messages: ask('Reply with exactly the word: pong'),
+      maxTokens: 50,
+      sessionId: session.id,
+    })
+    expect(result.finish.kind).toBe('stop')
+    expect(textOf(result).toLowerCase()).toContain('pong')
+    expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(0)
+  })
+
+  it('serves a real request with the key held only by a credentials-local document', async () => {
+    const key = process.env.DEEPSEEK_API_KEY
+    if (key === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-e2e-credentials-'))
+    try {
+      // JSON.stringify quotes the value: YAML is a JSON superset, so a real
+      // key survives whatever characters it happens to carry.
+      await writeFile(join(dir, '.credentials.yaml'), `version: 1\nrefs:\n  DEEPSEEK_API_KEY: ${JSON.stringify(key)}\n`, { mode: 0o600 })
+      // Scrub the ambient variable so only the credential seam can supply the
+      // key: this request proves the per-request resolution path end to end.
+      vi.stubEnv('DEEPSEEK_API_KEY', '')
+      const ctx = new Context()
+      contexts.push(ctx)
+      await ctx.plugin(LlmRuntime)
+      await ctx.plugin(LocalCredentialProvider, { path: join(dir, '.credentials.yaml'), watch: false })
+      await ctx.plugin(LlmDeepSeek, { baseURL: LlmDeepSeek.PUBLIC_BASE_URL })
+
+      const result = await assemble(ctx, {
+        model: FLASH,
+        messages: ask('Reply with exactly the word: pong'),
+        maxTokens: 50,
+      })
+      expect(result.finish.kind).toBe('stop')
+      expect(textOf(result).toLowerCase()).toContain('pong')
+    } finally {
+      vi.unstubAllEnvs()
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('flash dynamically switches from off to low', async () => {
+    const ctx = await harness(FLASH, { reasoningEffort: 'off' })
+    const withoutThinking = await assemble(ctx,{
+      model: FLASH,
+      messages: ask('Reply with exactly the word: pong'),
+      maxTokens: 50,
+    })
+    expect(withoutThinking.finish.kind).toBe('stop')
+    expect(textOf(withoutThinking).toLowerCase()).toContain('pong')
+    expect(withoutThinking.message.content.some(block => block.type === 'reasoning')).toBe(false)
+    expect(withoutThinking.usage?.inputTokens).toBeGreaterThan(0)
+    expect(withoutThinking.usage?.outputTokens).toBeGreaterThan(0)
+
+    const withThinking = await assemble(ctx,{
+      model: FLASH,
+      reasoningEffort: ReasoningEffortId('low'),
+      messages: ask('Which is larger, 9.11 or 9.8? Answer with just the number.'),
+      maxTokens: 2000,
+    })
+    expect(withThinking.finish.kind).toBe('stop')
+    expect(withThinking.message.content.some(block => block.type === 'reasoning' && block.text.trim().length > 0)).toBe(true)
+    expect(textOf(withThinking)).toContain('9.8')
+    expect(withThinking.usage?.outputTokens).toBeGreaterThan(0)
+  })
+
+  it(
+    'flash + thinking enabled (effort max): tool-call round trip with reasoning passback',
+    async () => {
+      const ctx = await harness(FLASH, { thinking: 'enabled' })
+
+      // Turn 1: the model must call the tool (and think before it).
+      const first = await assemble(ctx,{
+        model: FLASH,
+        reasoningEffort: ReasoningEffortId('max'),
+        messages: ask('What is the weather in Paris right now? Use the get_weather tool.'),
+        tools: [weatherTool],
+        maxTokens: 2000,
+      })
+      expect(
+        first.finish.kind,
+        `DeepSeek Flash tool-call turn finished as ${JSON.stringify(first.finish)}`,
+      ).toBe('tool-calls')
+      const call = first.message.content.find(block => block.type === 'tool-call')
+      expect(call).toBeDefined()
+      expect(call!.name).toBe('get_weather')
+      expect(JSON.parse(call!.arguments)).toMatchObject({ city: expect.stringMatching(/paris/i) as string })
+
+      // Turn 2: send the tool result back WITH the assistant's reasoning
+      // block in history (the official thinking+tools passback rule).
+      const second = await assemble(ctx,{
+        model: FLASH,
+        reasoningEffort: ReasoningEffortId('max'),
+        messages: [
+          ...ask('What is the weather in Paris right now? Use the get_weather tool.'),
+          createMessage({
+            role: 'assistant', content: first.message.content,
+            source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+          }),
+          createToolResultMessage({
+            callId: ToolCallId(call!.id),
+            content: [{ type: 'text', text: 'Sunny, 22°C' }],
+            isError: false,
+          }),
+        ],
+        tools: [weatherTool],
+        maxTokens: 2000,
+      })
+      expect(
+        second.finish.kind,
+        `DeepSeek Flash tool-result turn finished as ${JSON.stringify(second.finish)}`,
+      ).toBe('stop')
+      expect(textOf(second).toLowerCase()).toMatch(/sunny|22/)
+    },
+  )
+
+  it.skipIf(IN_HISTORY_MODEL === undefined)(
+    'an in-history model follows a mid-history system message and keeps the cached prefix',
+    async () => {
+      const model = IN_HISTORY_MODEL as string
+      const ctx = await harness(model, {
+        thinking: 'disabled',
+        models: [{ id: model, systemPromptUpdate: 'in-history' }],
+      })
+      await expect(ctx.llm.resolveModelInfo('deepseek-official', model))
+        .resolves.toMatchObject({ systemPromptUpdate: 'in-history' })
+      const system = (text: string) => createSystemMessage(text)
+      // A nonce before the padding isolates the provider cache across runs and retries.
+      const nonce = randomBytes(16).toString('hex')
+      const padding = Array.from({ length: 40 }, (_, index) => `Rule ${String(index + 1)}: keep every answer short and factual.`).join('\n')
+      // Both update strategies use identical prompt bytes, with the changed instruction near the head.
+      const prompt = (word: string) => `Test ${nonce}. When the user says ping, reply with exactly the word: ${word}\n${padding}`
+      const initial = prompt('pong')
+      const latest = prompt('banana')
+      const history = [system(initial), ...ask('ping')]
+      const wireRequests: WireRequest[] = []
+      const nativeFetch = globalThis.fetch
+      const observedFetch: typeof fetch = async (input, init) => {
+        if (init?.method !== 'POST' || typeof init.body !== 'string') return nativeFetch(input, init)
+        const body = JSON.parse(init.body) as WireRequest
+        if (body.model === model) {
+          wireRequests.push(body)
+          if (wireRequests.length === 1) {
+            expect(body.system).toBe(initial)
+            expect(body.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'ping' }] }])
+          } else if (wireRequests.length === 2) {
+            expect(body).toEqual(wireRequests[0])
+          } else if (wireRequests.length === 3) {
+            expect(body.system).toBe(initial)
+            expect(body.messages[0]).toEqual(wireRequests[0]!.messages[0])
+            expect(body.messages.at(-1)).toEqual({ role: 'system', content: [{ type: 'text', text: latest }] })
+          } else if (wireRequests.length === 4) {
+            expect(body.system).toBe(latest)
+            expect(body.messages).toEqual(wireRequests[2]!.messages.filter(message => message.role !== 'system'))
+          }
+        }
+        return nativeFetch(input, init)
+      }
+      vi.stubGlobal('fetch', observedFetch)
+      try {
+        const first = await assemble(ctx, { model, messages: history, maxTokens: 50 })
+        expect(first.finish.kind).toBe('stop')
+        expect(textOf(first).trim()).toBe('pong')
+        const initialTokens = first.usage?.inputTokens ?? 0
+        expect(initialTokens).toBeGreaterThan(0)
+
+        // Measure reusable tokens rather than assuming a provider cache-block size.
+        const warm = await assemble(ctx, { model, messages: history, maxTokens: 50 })
+        expect(warm.finish.kind).toBe('stop')
+        expect(textOf(warm).trim()).toBe('pong')
+        const reusableTokens = warm.usage?.cacheReadTokens ?? 0
+        expect(reusableTokens).toBeLessThanOrEqual(initialTokens)
+        expect(reusableTokens).toBeGreaterThan(0)
+        const assistant = createMessage({
+          role: 'assistant', content: first.message.content, source: first.message.source,
+        })
+
+        const updated = await assemble(ctx, {
+          model,
+          messages: [...history, assistant, system(latest), ...ask('ping')],
+          maxTokens: 50,
+        })
+        expect(updated.finish.kind).toBe('stop')
+        expect(textOf(updated).trim()).toBe('banana')
+
+        const replaced = await assemble(ctx, {
+          model,
+          messages: [system(latest), ...ask('ping'), assistant, ...ask('ping')],
+          maxTokens: 50,
+        })
+        expect(replaced.finish.kind).toBe('stop')
+        expect(textOf(replaced).trim()).toBe('banana')
+        expect(wireRequests).toHaveLength(4)
+
+        const cached = updated.usage?.cacheReadTokens ?? 0
+        expect(replaced.usage?.cacheReadTokens).toBeDefined()
+        const baselineCached = replaced.usage?.cacheReadTokens ?? 0
+        expect(cached).toBeGreaterThanOrEqual(reusableTokens)
+        expect(cached).toBeGreaterThan(baselineCached)
+      } finally {
+        vi.stubGlobal('fetch', nativeFetch)
+      }
+    },
+  )
+
+  it('streams raw chunks in protocol order', async () => {
+    const ctx = await harness(FLASH, { thinking: 'disabled' })
+    const kinds: string[] = []
+    for await (const chunk of ctx.llm.stream({
+      provider: 'deepseek-official',
+      model: FLASH,
+      messages: ask('Count from 1 to 5, digits only.'),
+      maxTokens: 50,
+    })) {
+      kinds.push(chunk.type)
+    }
+    expect(kinds[0]).toBe('block-start')
+    expect(kinds.at(-1)).toBe('finish')
+    expect(kinds.filter(kind => kind === 'finish')).toHaveLength(1)
+    // usage precedes finish (deferred-emit contract)
+    expect(kinds.indexOf('usage')).toBeLessThan(kinds.indexOf('finish'))
+  })
+})
diff --git a/packages/llm/llm-deepseek/tests/runtime.spec.ts b/packages/llm/llm-deepseek/tests/runtime.spec.ts
new file mode 100644
index 0000000000..55ab3acb4f
--- /dev/null
+++ b/packages/llm/llm-deepseek/tests/runtime.spec.ts
@@ -0,0 +1,2340 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
+import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
+import { createLaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment'
+import LlmRuntime, { ToolCallId, createUserMessage,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  createToolResultMessage,
+  createAssistantMessage,
+  LlmError,
+  ProviderRequestId,
+  QUOTA_EXCEEDED_CODE,
+  ReasoningEffortId,
+  userAgent,
+} from '@deepseek-ai/dsh-llm'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { getOrCreateAnonymousUserId, type AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
+import type { PreparedDeepSeekLlmApiExtensions } from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import { DeepSeekAdapter, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+import type { ContextFormed } from '@deepseek-ai/dsh-llm'
+import { providerError } from '../src/transport.ts'
+import { resolveRequestImageTarget } from '../src/request-pricing.ts'
+import { assemble } from './assemble.ts'
+import { closeMockServers, mockServer, textEvents } from './mock-server.ts'
+import type { Behavior } from './mock-server.ts'
+import { requestImageStore } from './helpers.ts'
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'test': { kind: 'test' } & ContextFormed
+  }
+}
+
+const TEST_USER_ID = '00000000-0000-4000-8000-000000000001' as AnonymousUserId
+let testHome: string
+
+beforeEach(() => {
+  testHome = mkdtempSync(join(tmpdir(), 'dsh-llm-deepseek-'))
+  vi.stubEnv('DSH_HOME', testHome)
+})
+
+afterEach(async () => {
+  await closeMockServers()
+  vi.unstubAllEnvs()
+  vi.useRealTimers()
+  rmSync(testHome, { recursive: true, force: true })
+})
+
+async function harness(baseURL: string, config: object = {}) {
+  // Configuration carries only the reference; the key comes from the
+  // environment, which is the whole credential plane without a mounted seam.
+  vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
+  const ctx = new Context()
+  await ctx.plugin(LlmRuntime)
+  await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
+  await ctx.plugin(LlmDeepSeek, { baseURL, ...config })
+  return ctx
+}
+
+/** Direct adapter over the plugin's real resolve step, with a static key. */
+function noExtensions(): Promise<PreparedDeepSeekLlmApiExtensions> {
+  return Promise.resolve({ fields: {}, accept: () => Promise.resolve() })
+}
+
+/** Direct adapter over the plugin's real resolve step, with a static key. */
+function adapterOf(
+  config: Partial<LlmDeepSeek.Config> & { apiKey?: string } = {},
+  attachments?: AttachmentStore,
+  files?: LlmDeepSeek.DeepSeekFileStore,
+): DeepSeekAdapter {
+  const { apiKey, ...rest } = config
+  return new DeepSeekAdapter({
+    options: () => resolveAdapterOptions({ ...rest }),
+    resolveApiKey: () => Promise.resolve(apiKey ?? 'k'),
+    resolveUserId: () => TEST_USER_ID,
+    resolveAttachments: () => attachments,
+    ...files === undefined ? {} : { resolveFiles: () => files },
+    prepareExtensions: noExtensions,
+  })
+}
+
+async function drain(stream: AsyncIterable<unknown>): Promise<void> {
+  for await (const _chunk of stream) { /* drain */ }
+}
+
+const imageRef: ImageAttachmentRef = {
+  attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`),
+  mediaType: 'image/png',
+  bytes: 3,
+  width: 1,
+  height: 1,
+}
+
+function requestImage(ref = imageRef): RequestImageAttachment {
+  return {
+    variantId: ImageVariantId(`sha256:${'b'.repeat(64)}`),
+    attachment: ref,
+    data: Uint8Array.of(1, 2, 3),
+    mediaType: 'image/png',
+    bytes: 3,
+    width: 1,
+    height: 1,
+    depth: 'uchar',
+    space: 'srgb',
+    hasAlpha: true,
+  }
+}
+
+function attachmentStoreOf(
+  project: (ref: ImageAttachmentRef, policy: unknown, signal?: AbortSignal) => Promise<RequestImageAttachment>,
+): {
+  store: AttachmentStore
+  readImageRequest: ReturnType<typeof vi.fn<typeof project>>
+} {
+  const readImageRequest = vi.fn(project)
+  return {
+    store: requestImageStore(readImageRequest),
+    readImageRequest,
+  }
+}
+
+function fileStoreOf(
+  implementation: (...args: Parameters<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>) => ReturnType<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>,
+) {
+  const ensureUploaded = vi.fn(implementation)
+  const invalidate = vi.fn(() => Promise.resolve())
+  return {
+    store: Object.assign(new LlmDeepSeek.DeepSeekFileStore(), { ensureUploaded, invalidate }),
+    ensureUploaded,
+    invalidate,
+  }
+}
+
+function fileReference(fileId: string): Awaited<ReturnType<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>> {
+  return {
+    record: { fileId: LlmDeepSeek.DeepSeekFileId(fileId) },
+    uploaded: true,
+  } as Awaited<ReturnType<LlmDeepSeek.DeepSeekFileStore['ensureUploaded']>>
+}
+
+function successfulSseResponse(): Response {
+  return new Response(textEvents.map(event => `data: ${event}\n\n`).join(''), {
+    status: 200,
+    headers: { 'content-type': 'text/event-stream' },
+  })
+}
+
+describe('request image target', () => {
+  it.each([
+    [
+      { id: 'default' },
+      { width: 1302, height: 1302, maxBytes: 2 * 1024 * 1024 },
+    ],
+    [
+      { id: 'low', imagePixelBudget: 'low' as const },
+      { width: 512, height: 512, maxBytes: 2 * 1024 * 1024 },
+    ],
+    [
+      { id: 'custom', imagePixelBudget: 320_000, imageMaxBytes: 512_000 },
+      { width: 565, height: 565, maxBytes: 512_000 },
+    ],
+  ])('resolves route-owned defaults and overrides for %s on a 4096x4096 source', (model, expected) => {
+    expect(resolveRequestImageTarget(model, { width: 4096, height: 4096 })).toEqual(expected)
+  })
+
+  it('caps every request image at the provider per-side limit', () => {
+    expect(resolveRequestImageTarget({ id: 'default' }, { width: 8192, height: 78 }))
+      .toEqual({ width: 4096, height: 39, maxBytes: 2 * 1024 * 1024 })
+    expect(resolveRequestImageTarget({ id: 'custom', imagePixelBudget: 640_000 }, { width: 10_000, height: 100 }))
+      .toEqual({ width: 4096, height: 41, maxBytes: 2 * 1024 * 1024 })
+  })
+
+  it('answers image request pricing from the current connection snapshot', () => {
+    const adapter = adapterOf({
+      models: [{ id: 'vision', inputModalities: ['text', 'image'] }],
+    })
+    const priced = adapter.imageRequestPricing('deepseek-official', 'vision')?.priceImages([{ type: 'image', attachment: imageRef }])
+    expect(priced).toHaveLength(1)
+    expect(priced?.[0]!.visualTokens).toBeGreaterThan(0)
+    const textOnly = adapter.imageRequestPricing('deepseek-official', 'unlisted')?.priceImages([{ type: 'image', attachment: imageRef }])
+    expect(textOnly?.[0]!.visualTokens).toBe(0)
+  })
+
+  it('prices descriptor text through the serializer\'s access resolution', () => {
+    const attachments = {} as AttachmentStore
+    const adapter = new DeepSeekAdapter({
+      options: () => resolveAdapterOptions({ models: [{ id: 'vision', inputModalities: ['text', 'image'] }] }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+      resolveAttachments: () => attachments,
+      resolveImageAccess: (store, ref) => (store === attachments && ref === imageRef
+        ? { readonlyPath: '/world/img.png' }
+        : undefined),
+      prepareExtensions: noExtensions,
+    })
+    const priced = adapter.imageRequestPricing('deepseek-official', 'vision')?.priceImages([{ type: 'image', attachment: imageRef }])
+    expect(priced?.[0]?.text).toContain('/world/img.png')
+  })
+})
+
+describe('DeepSeekAdapter against a mock server', () => {
+  it('merges prepared extension fields and accepts them once after HTTP 2xx', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const accept = vi.fn()
+    const prepareExtensions = vi.fn(async () => ({
+      fields: { dsh_test: { version: 1 } },
+      accept: async () => { accept() },
+    }))
+    const adapter = new DeepSeekAdapter({
+      options: () => resolveAdapterOptions({ baseURL: server.url }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+      prepareExtensions: prepareExtensions as never,
+    })
+
+    await drain(adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [], sessionId: SessionId('s') }))
+    expect(server.requests[0]).toMatchObject({ dsh_test: { version: 1 } })
+    expect(prepareExtensions).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 's' }))
+    expect(accept).toHaveBeenCalledOnce()
+  })
+
+  it('fails before fetch on extension preparation or base-field collision', async () => {
+    const server = await mockServer([])
+    const base = {
+      options: () => resolveAdapterOptions({ baseURL: server.url }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+    }
+    const failed = new DeepSeekAdapter({
+      ...base,
+      prepareExtensions: () => Promise.reject(new Error('metadata unavailable')),
+    })
+    await expect(drain(failed.stream({ provider: 'deepseek-official', model: 'm', messages: [] })))
+      .rejects.toMatchObject({ code: 'REQUEST_EXTENSION' })
+
+    const collision = new DeepSeekAdapter({
+      ...base,
+      prepareExtensions: (() => Promise.resolve({ fields: { model: 'replacement' }, accept: () => Promise.resolve() })) as never,
+    })
+    await expect(drain(collision.stream({ provider: 'deepseek-official', model: 'm', messages: [] })))
+      .rejects.toMatchObject({ code: 'REQUEST_EXTENSION' })
+    expect(server.requests).toHaveLength(0)
+  })
+
+  it('passes cancellation into extension preparation and aborts before fetch', async () => {
+    const server = await mockServer([])
+    const controller = new AbortController()
+    const started = Promise.withResolvers<undefined>()
+    let signalSeen: AbortSignal | undefined
+    const adapter = new DeepSeekAdapter({
+      options: () => resolveAdapterOptions({ baseURL: server.url }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+      prepareExtensions: ((request: { signal: AbortSignal }) => {
+        signalSeen = request.signal
+        started.resolve(undefined)
+        if (request.signal === undefined) return new Promise(() => {})
+        return new Promise((_resolve, reject) => {
+          request.signal.addEventListener('abort', () => {
+            const reason: unknown = request.signal.reason
+            reject(reason instanceof Error ? reason : new Error('extension preparation aborted', { cause: reason }))
+          }, { once: true })
+        })
+      }) as never,
+    })
+
+    const pending = drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'm',
+      messages: [],
+      signal: controller.signal,
+    }))
+    await started.promise
+    expect(signalSeen).toBeInstanceOf(AbortSignal)
+    controller.abort()
+    await expect(pending).rejects.toMatchObject({ code: 'ABORTED' })
+    expect(server.requests).toHaveLength(0)
+  })
+
+  it('passes cancellation through an outstanding fetch', async () => {
+    const controller = new AbortController()
+    const started = Promise.withResolvers<undefined>()
+    const fetch = vi.spyOn(globalThis, 'fetch').mockImplementation((_input, init) => {
+      const signal = init?.signal
+      return new Promise<Response>((_resolve, reject) => {
+        started.resolve(undefined)
+        signal?.addEventListener('abort', () => {
+          const reason: unknown = signal.reason
+          reject(reason instanceof Error ? reason : new Error('fetch aborted', { cause: reason }))
+        }, { once: true })
+      })
+    })
+    try {
+      const adapter = adapterOf({ baseURL: 'https://provider.invalid' })
+      const pending = drain(adapter.stream({
+        provider: 'deepseek-official',
+        model: 'm',
+        messages: [],
+        signal: controller.signal,
+      }))
+      await started.promise
+      controller.abort()
+      await expect(pending).rejects.toMatchObject({ code: 'ABORTED' })
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+
+  it('does not accept extensions on non-2xx and does accept before a later stream failure', async () => {
+    const server = await mockServer([
+      { kind: 'http-error', status: 500, body: '{}' },
+      { kind: 'close-early', events: textEvents.slice(0, 3) },
+    ])
+    const accept = vi.fn()
+    const adapter = new DeepSeekAdapter({
+      options: () => resolveAdapterOptions({ baseURL: server.url }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+      prepareExtensions: () => Promise.resolve({ fields: { dsh_test: 1 }, accept: async () => { accept() } }) as never,
+    })
+    const request = { provider: 'deepseek-official', model: 'm', messages: [] }
+
+    await expect(drain(adapter.stream(request))).rejects.toMatchObject({ code: 'SERVER' })
+    expect(accept).not.toHaveBeenCalled()
+    await expect(drain(adapter.stream(request))).rejects.toBeDefined()
+    expect(accept).toHaveBeenCalledOnce()
+  })
+
+  it('reports a post-2xx extension acceptance failure without relabelling it as transport', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const failure = new Error('watermark append failed')
+    const adapter = new DeepSeekAdapter({
+      options: () => resolveAdapterOptions({ baseURL: server.url }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+      prepareExtensions: () => Promise.resolve({
+        fields: { dsh_test: 1 },
+        accept: () => Promise.reject(failure),
+      }) as never,
+    })
+
+    await expect(drain(adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })))
+      .rejects.toMatchObject({ code: 'REQUEST_EXTENSION', cause: failure })
+    expect(server.requests).toHaveLength(1)
+  })
+
+  it('streams a text generation end to end through the assembler', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const ctx = await harness(server.url)
+
+    const result = await assemble(ctx, {
+      model: 'deepseek-v4-pro',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })
+    expect(result.message.content).toEqual([{ type: 'text', text: 'hello' }])
+    expect(result.finish).toEqual({ kind: 'stop' })
+    expect(result.usage).toEqual({ inputTokens: 3, outputTokens: 1, totalTokens: 4 })
+
+    // The wire request carried the auth header contents we configured.
+    expect(server.requests[0]).toMatchObject({
+      model: 'deepseek-v4-pro',
+      max_tokens: 256_000,
+      output_config: { effort: 'high' },
+      stream: true,
+    })
+    // App attribution and DeepSeek request identity are independent wire facts.
+    expect(server.headers[0]?.['user-agent']).toBe(userAgent())
+    expect(server.headers[0]?.['x-deepseek-harness-user-id']).toBe(getOrCreateAnonymousUserId())
+    expect(server.headers[0]).not.toHaveProperty('x-deepseek-harness-session-id')
+    expect(server.headers[0]).not.toHaveProperty('http-referer')
+    expect(server.headers[0]).not.toHaveProperty('x-openrouter-title')
+    expect(server.headers[0]).not.toHaveProperty('x-openrouter-categories')
+    expect(server.headers[0]).not.toHaveProperty('x-deepseek-harness-compact')
+  })
+
+  it('uploads a durable image once and sends only its Files API id to the vision model', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const signalSeen: (AbortSignal | undefined)[] = []
+    const policies: unknown[] = []
+    const attachmentMocks = attachmentStoreOf((ref, policy, signal) => {
+      signalSeen.push(signal)
+      policies.push(policy)
+      return Promise.resolve(requestImage(ref))
+    })
+    const adapter = adapterOf({ baseURL: server.url }, attachmentMocks.store)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-flash',
+      messages: [createUserMessage({
+        content: [
+          { type: 'text', text: 'describe ' },
+          { type: 'image', attachment: imageRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    expect(server.requests[0]).toMatchObject({
+      model: 'deepseek-flash',
+      messages: [{
+        role: 'user',
+        content: [
+          { type: 'text', text: 'describe ' },
+          { type: 'text', text: expect.stringContaining(`Image ${imageRef.attachmentId}; request preview 1x1px.`) as string },
+          { type: 'image', source: { type: 'file', file_id: 'file-api-1' } },
+        ],
+      }],
+    })
+    expect(server.fileRequests).toEqual([{
+      method: 'POST',
+      path: '/v1/files',
+      filename: `dsh-${'a'.repeat(16)}-${'b'.repeat(8)}.png`,
+      bytes: 3,
+    }])
+    expect(signalSeen[0]).toBeInstanceOf(AbortSignal)
+    expect(policies).toEqual([{ width: 1, height: 1, maxBytes: 2 * 1024 * 1024 }])
+  })
+
+  it('rejects unknown plugin content without preparing nested images', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const attachmentMocks = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
+    const adapter = adapterOf({ baseURL: server.url }, attachmentMocks.store)
+    await expect(drain(adapter.stream({ provider: 'deepseek-official', model: 'deepseek-v4-pro', messages: [
+      createUserMessage({ source: { kind: 'user' }, content: [
+        { type: 'plugin:message',
+          message: { role: 'tool', toolCallId: 'foreign', content: [{ type: 'image', attachment: { ...imageRef } }] },
+        } as never,
+        { type: 'text', text: 'context' },
+      ] }),
+    ] }))).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
+    expect(attachmentMocks.readImageRequest).not.toHaveBeenCalled()
+    expect(server.fileRequests).toHaveLength(0)
+    expect(server.requests).toHaveLength(0)
+  })
+
+  it('falls back to one all-base64 request when Files API resolution fails', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const secondRef = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`) }
+    const attachments = attachmentStoreOf(ref => Promise.resolve({
+      ...requestImage(ref),
+      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
+    })).store
+    const files = fileStoreOf(() => Promise.reject(new LlmError('Files unavailable', 'SERVER')))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: imageRef },
+          { type: 'image', attachment: secondRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    const body = server.requests[0] as { messages: Array<{ content: unknown }> }
+    expect(JSON.stringify(body.messages[0]?.content).match(/"type":"image"/g)).toHaveLength(2)
+    expect(JSON.stringify(body)).not.toContain('file_id')
+    expect(files.ensureUploaded).toHaveBeenCalledTimes(1)
+  })
+
+  it('fails a base64 fallback whose retained images exceed the inline bound with the count to offload', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const files = fileStoreOf(() => Promise.reject(new LlmError('Files unavailable', 'SERVER')))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      maxInlineRequestImageBytes: 80,
+      inlineImageOffloadByteQuantum: 40,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: Array.from({ length: 21 }, () => ({ type: 'image' as const, attachment: imageRef })),
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))).rejects.toMatchObject({ code: 'IMAGE_OFFLOAD_REQUIRED', message: expect.stringContaining('11 more') as string })
+    expect(server.requests).toHaveLength(0)
+  })
+  it('discards partially resolved file ids and falls back with every retained image inline', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const secondRef = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`) }
+    const attachments = attachmentStoreOf(ref => Promise.resolve({
+      ...requestImage(ref),
+      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
+    })).store
+    const files = fileStoreOf(() => Promise.reject(new Error('unused')))
+    files.ensureUploaded
+      .mockResolvedValueOnce(fileReference('file-api-partial'))
+      .mockRejectedValueOnce(new LlmError('Files unavailable', 'TRANSPORT'))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: imageRef },
+          { type: 'image', attachment: secondRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    const body = server.requests[0] as { messages: Array<{ content: unknown }> }
+    expect(JSON.stringify(body.messages[0]?.content).match(/"type":"image"/g)).toHaveLength(2)
+    expect(JSON.stringify(body)).not.toContain('file-api-partial')
+  })
+
+  it('falls back after the configured Files API deadline without aborting the model request', async () => {
+    vi.useFakeTimers()
+    const started = Promise.withResolvers<undefined>()
+    const files = fileStoreOf((_version, _connection, _policy, signal) => new Promise((_resolve, reject) => {
+      started.resolve(undefined)
+      signal?.addEventListener('abort', () => {
+        const reason: unknown = signal.reason
+        reject(reason instanceof Error ? reason : new Error('files operation aborted'))
+      }, { once: true })
+    }))
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(successfulSseResponse())
+    const adapter = adapterOf({
+      baseURL: 'https://deepseek.invalid',
+      filesApiTimeoutMs: 50,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    const pending = drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+    await started.promise
+    await vi.advanceTimersByTimeAsync(50)
+    await pending
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    expect(fetchSpy.mock.calls[0]?.[1]?.body).toEqual(expect.stringContaining('base64'))
+    fetchSpy.mockRestore()
+  })
+
+  it('does not turn caller cancellation during file resolution into base64 fallback', async () => {
+    const started = Promise.withResolvers<undefined>()
+    const files = fileStoreOf((_version, _connection, _policy, signal) => new Promise((_resolve, reject) => {
+      started.resolve(undefined)
+      signal?.addEventListener('abort', () => { reject(new Error('cancelled')) }, { once: true })
+    }))
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const fetchSpy = vi.spyOn(globalThis, 'fetch')
+    const controller = new AbortController()
+    const adapter = adapterOf({
+      baseURL: 'https://deepseek.invalid',
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    const pending = drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      signal: controller.signal,
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+    await started.promise
+    controller.abort()
+
+    await expect(pending).rejects.toMatchObject({ code: 'ABORTED' })
+    expect(fetchSpy).not.toHaveBeenCalled()
+    fetchSpy.mockRestore()
+  })
+
+  it('does not retry a generic Messages failure through base64 fallback', async () => {
+    const server = await mockServer([{
+      kind: 'http-error',
+      status: 503,
+      body: JSON.stringify({ error: { message: 'chat unavailable' } }),
+    }])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const files = fileStoreOf(() => Promise.resolve(fileReference('file-api-ready')))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))).rejects.toMatchObject({ code: 'SERVER', message: 'chat unavailable' })
+
+    expect(server.requests).toHaveLength(1)
+    expect(JSON.stringify(server.requests[0])).toContain('file-api-ready')
+    expect(JSON.stringify(server.requests[0])).not.toContain('base64')
+  })
+
+  it('does not prepare a surface-offloaded image and sends its placeholder instead', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const old = { ...imageRef, attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`), bytes: 3 }
+    const recent = { ...imageRef, attachmentId: AttachmentId(`sha256:${'d'.repeat(64)}`), bytes: 3 }
+    const attachmentMocks = attachmentStoreOf((ref) => {
+      if (ref.attachmentId === old.attachmentId) throw new Error('old image must not be read')
+      return Promise.resolve(requestImage(ref))
+    })
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachmentMocks.store)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: old, offloaded: true },
+          { type: 'image', attachment: recent },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    expect(attachmentMocks.readImageRequest).toHaveBeenCalledWith(
+      recent,
+      { width: 1, height: 1, maxBytes: 2 * 1024 * 1024 },
+      expect.any(AbortSignal),
+    )
+    const body = server.requests[0] as { messages: unknown[] }
+    expect(body.messages[0]).toMatchObject({
+      role: 'user',
+      content: [
+        { type: 'text', text: expect.stringContaining(`image omitted to fit request image limits; ${old.attachmentId}`) as string },
+        { type: 'text', text: expect.stringContaining(String(recent.attachmentId)) as string },
+        { type: 'image', source: { type: 'file', file_id: 'file-api-1' } },
+      ],
+    })
+  })
+
+  it('projects nested tool-result images with route-owned request budgets', async () => {
+    const server = await mockServer([
+      { kind: 'sse', events: textEvents },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachmentMocks = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [
+        {
+          id: 'vision-low',
+          inputModalities: ['text', 'image'],
+          imagePixelBudget: 'low',
+          imageMaxBytes: 512_000,
+        },
+        {
+          id: 'vision-custom',
+          inputModalities: ['text', 'image'],
+          imagePixelBudget: 320_000,
+        },
+      ],
+    }, attachmentMocks.store)
+    const nested = createToolResultMessage({
+      callId: ToolCallId('image-result'),
+      content: [{ type: 'image', attachment: imageRef }],
+      isError: false,
+    })
+
+    const call = createAssistantMessage({
+      source: { provider: 'deepseek-official', model: 'vision-low' },
+      content: [{ type: 'tool-call', id: nested.toolCallId, name: 'read_image', arguments: '{}' }],
+    })
+    await drain(adapter.stream({ provider: 'deepseek-official', model: 'vision-low', messages: [call, nested] }))
+    await drain(adapter.stream({ provider: 'deepseek-official', model: 'vision-custom', messages: [call, nested] }))
+
+    expect(attachmentMocks.readImageRequest).toHaveBeenNthCalledWith(
+      1,
+      imageRef,
+      { width: 1, height: 1, maxBytes: 512_000 },
+      expect.any(AbortSignal),
+    )
+    expect(attachmentMocks.readImageRequest).toHaveBeenNthCalledWith(
+      2,
+      imageRef,
+      { width: 1, height: 1, maxBytes: 2 * 1024 * 1024 },
+      expect.any(AbortSignal),
+    )
+  })
+
+  it('reuses the exact request version between agent and compaction calls', async () => {
+    const server = await mockServer([
+      { kind: 'sse', events: textEvents },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+    const messages = [createUserMessage({
+      content: [{ type: 'image' as const, attachment: imageRef }],
+      source: { kind: 'test' as const },
+    })]
+
+    await drain(adapter.stream({ provider: 'deepseek-official', model: 'deepseek-v4-flash-vision-exp', messages }))
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages,
+      purpose: 'compaction',
+    }))
+
+    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(1)
+    expect(server.requests).toMatchObject([
+      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { type: 'image', source: { type: 'file', file_id: 'file-api-1' } }] }] },
+      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { type: 'image', source: { type: 'file', file_id: 'file-api-1' } }] }] },
+    ])
+    expect(server.headers[1]?.['x-deepseek-harness-compact']).toBe('1')
+  })
+
+  it('explains a provider rejection of a normalized image and retains the raw response as cause', async () => {
+    const raw = JSON.stringify({ error: { message: 'unsupported image payload for file-api-1' } })
+    const server = await mockServer([{ kind: 'http-error', status: 400, body: raw }])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    let failure: unknown
+    try {
+      await drain(adapter.stream({
+        provider: 'deepseek-official',
+        model: 'deepseek-v4-flash-vision-exp',
+        messages: [createUserMessage({
+          content: [{ type: 'image', attachment: imageRef }],
+          source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        })],
+      }))
+    } catch (error: unknown) {
+      failure = error
+    }
+    expect(failure).toMatchObject({
+      code: 'INVALID_REQUEST',
+      message: expect.stringContaining(
+        `normalized image "${imageRef.attachmentId}" at message 1, image 1`,
+      ) as string,
+      cause: { message: raw },
+    })
+    expect((failure as Error).message).toContain('image/png, 8-bit sRGBA, 1x1')
+    expect((failure as Error).message).toContain('unsupported image payload for file-api-1')
+    expect((failure as Error).message).not.toBe(raw)
+  })
+
+  it('identifies the sole image when a normalized rejection omits its file id', async () => {
+    const raw = JSON.stringify({ error: { message: 'unsupported image payload' } })
+    const server = await mockServer([{ kind: 'http-error', status: 400, body: raw }])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))).rejects.toMatchObject({
+      message: expect.stringContaining(`normalized image "${imageRef.attachmentId}"`) as string,
+    })
+  })
+
+  it('lists every candidate when a normalized multi-image rejection names no file id', async () => {
+    const secondRef: ImageAttachmentRef = {
+      ...imageRef,
+      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
+    }
+    const raw = JSON.stringify({ error: { message: 'unsupported image payload' } })
+    const server = await mockServer([{ kind: 'http-error', status: 400, body: raw }])
+    const attachments = attachmentStoreOf((ref) => {
+      const first = ref.attachmentId === imageRef.attachmentId
+      return Promise.resolve({
+        ...requestImage(ref),
+        variantId: ImageVariantId(`sha256:${(first ? 'b' : 'd').repeat(64)}`),
+        attachment: first ? { ...ref, name: 'diagram.png' } : ref,
+        hasAlpha: false,
+      })
+    }).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: imageRef },
+          { type: 'image', attachment: secondRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))).rejects.toMatchObject({
+      code: 'INVALID_REQUEST',
+      message: expect.stringContaining('Candidate images: "diagram.png"') as string,
+      cause: { message: raw },
+    })
+  })
+
+  it.each([
+    'file-api-1 expired',
+    'file_id file-api-10 invalid; file_id file-api-1 expired',
+    'file_id file-api-1 expired',
+    'file_not_found',
+    'file_id file-api-1 deleted',
+    'invalid file_id file-api-1',
+  ])('reuploads once when Messages rejects a Files API reference as %s', async (providerMessage) => {
+    const server = await mockServer([
+      {
+        kind: 'http-error',
+        status: 400,
+        body: JSON.stringify({ error: { message: providerMessage } }),
+      },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachmentMocks = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachmentMocks.store)
+    const options = {
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image' as const, attachment: imageRef }],
+        source: { kind: 'test' as const },
+      })],
+    }
+
+    await drain(adapter.stream(options))
+
+    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(2)
+    expect(server.requests).toMatchObject([
+      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { type: 'image', source: { type: 'file', file_id: 'file-api-1' } }] }] },
+      { messages: [{ content: [expect.objectContaining({ type: 'text' }), { type: 'image', source: { type: 'file', file_id: 'file-api-2' } }] }] },
+    ])
+    expect(attachmentMocks.readImageRequest).toHaveBeenCalledTimes(1)
+  })
+
+  it('uses inline fallback when stale-id recovery cannot resolve a replacement file', async () => {
+    const server = await mockServer([
+      {
+        kind: 'http-error',
+        status: 400,
+        body: JSON.stringify({ error: { message: 'file_id file-api-stale expired' } }),
+      },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const files = fileStoreOf(() => Promise.reject(new Error('unused')))
+    files.ensureUploaded
+      .mockResolvedValueOnce(fileReference('file-api-stale'))
+      .mockRejectedValueOnce(new LlmError('Files unavailable', 'SERVER'))
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments, files.store)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    expect(files.invalidate).toHaveBeenCalledTimes(1)
+    expect(server.requests).toHaveLength(2)
+    expect(JSON.stringify(server.requests[0])).toContain('file-api-stale')
+    expect(JSON.stringify(server.requests[1])).toContain('base64')
+  })
+
+  it('invalidates only the identified mapping when a multi-image request names one stale file id', async () => {
+    const secondRef: ImageAttachmentRef = {
+      ...imageRef,
+      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
+    }
+    const server = await mockServer([
+      {
+        kind: 'http-error',
+        status: 400,
+        body: JSON.stringify({ error: { message: 'file_id file-api-2 expired' } }),
+      },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachments = attachmentStoreOf(ref => Promise.resolve({
+      ...requestImage(ref),
+      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
+    })).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: imageRef },
+          { type: 'image', attachment: secondRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(3)
+    const retries = server.requests as Array<{ messages: Array<{ content: Array<{ type: string; file_id?: string }> }> }>
+    expect(retries[0]?.messages[0]?.content.filter(block => block.type === 'image'))
+      .toEqual([{ type: 'image', source: { type: 'file', file_id: 'file-api-1' } }, { type: 'image', source: { type: 'file', file_id: 'file-api-2' } }])
+    expect(retries[1]?.messages[0]?.content.filter(block => block.type === 'image'))
+      .toEqual([{ type: 'image', source: { type: 'file', file_id: 'file-api-1' } }, { type: 'image', source: { type: 'file', file_id: 'file-api-3' } }])
+  })
+
+  it('invalidates every listed missing file id and preserves unlisted mappings', async () => {
+    const secondRef: ImageAttachmentRef = {
+      ...imageRef,
+      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
+    }
+    const thirdRef: ImageAttachmentRef = {
+      ...imageRef,
+      attachmentId: AttachmentId(`sha256:${'e'.repeat(64)}`),
+    }
+    const server = await mockServer([
+      {
+        kind: 'http-error',
+        status: 400,
+        body: JSON.stringify({
+          error: {
+            message: 'path.to.object[index]: the following file_ids do not exist or are not created under your account: '
+              + 'file-api-1, file-api-3, file-api-unknown',
+          },
+        }),
+      },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachments = attachmentStoreOf((ref) => {
+      let digest = 'f'
+      if (ref.attachmentId === imageRef.attachmentId) digest = 'b'
+      else if (ref.attachmentId === secondRef.attachmentId) digest = 'd'
+      return Promise.resolve({
+        ...requestImage(ref),
+        variantId: ImageVariantId(`sha256:${digest.repeat(64)}`),
+      })
+    }).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: imageRef },
+          { type: 'image', attachment: secondRef },
+          { type: 'image', attachment: thirdRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(5)
+    const retries = server.requests as Array<{ messages: Array<{ content: Array<{ type: string; file_id?: string }> }> }>
+    expect(retries[0]?.messages[0]?.content.filter(block => block.type === 'image'))
+      .toEqual([
+        { type: 'image', source: { type: 'file', file_id: 'file-api-1' } },
+        { type: 'image', source: { type: 'file', file_id: 'file-api-2' } },
+        { type: 'image', source: { type: 'file', file_id: 'file-api-3' } },
+      ])
+    expect(retries[1]?.messages[0]?.content.filter(block => block.type === 'image'))
+      .toEqual([
+        { type: 'image', source: { type: 'file', file_id: 'file-api-4' } },
+        { type: 'image', source: { type: 'file', file_id: 'file-api-2' } },
+        { type: 'image', source: { type: 'file', file_id: 'file-api-5' } },
+      ])
+  })
+
+  it('invalidates every used mapping when a stale-file response does not identify one file id', async () => {
+    const secondRef: ImageAttachmentRef = {
+      ...imageRef,
+      attachmentId: AttachmentId(`sha256:${'c'.repeat(64)}`),
+    }
+    const server = await mockServer([
+      {
+        kind: 'http-error',
+        status: 400,
+        body: JSON.stringify({ error: { message: 'file reference expired' } }),
+      },
+      { kind: 'sse', events: textEvents },
+    ])
+    const attachments = attachmentStoreOf(ref => Promise.resolve({
+      ...requestImage(ref),
+      variantId: ImageVariantId(`sha256:${(ref.attachmentId === imageRef.attachmentId ? 'b' : 'd').repeat(64)}`),
+    })).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    await drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [
+          { type: 'image', attachment: imageRef },
+          { type: 'image', attachment: secondRef },
+        ],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))
+
+    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(4)
+    const retries = server.requests as Array<{ messages: Array<{ content: Array<{ type: string; file_id?: string }> }> }>
+    expect(retries[1]?.messages[0]?.content.filter(block => block.type === 'image'))
+      .toEqual([{ type: 'image', source: { type: 'file', file_id: 'file-api-3' } }, { type: 'image', source: { type: 'file', file_id: 'file-api-4' } }])
+  })
+
+  it('returns the second stale-file rejection without a third model attempt', async () => {
+    const stale = JSON.stringify({ error: { message: 'file_id file-api-1 expired' } })
+    const server = await mockServer([
+      { kind: 'http-error', status: 400, body: stale },
+      { kind: 'http-error', status: 400, body: stale },
+    ])
+    const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref))).store
+    const adapter = adapterOf({
+      baseURL: server.url,
+      models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+    }, attachments)
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))).rejects.toMatchObject({ code: 'INVALID_REQUEST', message: 'file_id file-api-1 expired' })
+    expect(server.requests).toHaveLength(2)
+    expect(server.fileRequests.filter(request => request.method === 'POST')).toHaveLength(2)
+  })
+
+  it.each(['deepseek-v4-flash', 'unlisted-pass-through'])(
+    'rejects image input for text-only model %s before credentials, image reads, or fetch',
+    async (model) => {
+      const server = await mockServer([])
+      const resolveApiKey = vi.fn(() => Promise.resolve('k'))
+      const attachments = attachmentStoreOf(ref => Promise.resolve(requestImage(ref)))
+      const resolveAttachments = vi.fn(() => attachments.store)
+      const adapter = new DeepSeekAdapter({
+        options: () => resolveAdapterOptions({ baseURL: server.url }),
+        resolveApiKey,
+        resolveUserId: () => TEST_USER_ID,
+        resolveAttachments,
+        prepareExtensions: noExtensions,
+      })
+
+      await expect(drain(adapter.stream({
+        provider: 'deepseek-official',
+        model,
+        messages: [createUserMessage({
+          content: [{ type: 'image', attachment: imageRef }],
+          source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        })],
+      }))).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
+      expect(resolveApiKey).not.toHaveBeenCalled()
+      expect(attachments.readImageRequest).not.toHaveBeenCalled()
+      expect(server.requests).toHaveLength(0)
+    },
+  )
+
+  it('rejects vision input without an attachment provider before credentials or fetch', async () => {
+    const server = await mockServer([])
+    const resolveApiKey = vi.fn(() => Promise.resolve('k'))
+    const adapter = new DeepSeekAdapter({
+      options: () => resolveAdapterOptions({
+        baseURL: server.url,
+        models: [{ id: 'deepseek-v4-flash-vision-exp', inputModalities: ['text', 'image'] }],
+      }),
+      resolveApiKey,
+      resolveUserId: () => TEST_USER_ID,
+      prepareExtensions: noExtensions,
+    })
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash-vision-exp',
+      messages: [createUserMessage({
+        content: [{ type: 'image', attachment: imageRef }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    }))).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
+    expect(resolveApiKey).not.toHaveBeenCalled()
+    expect(server.requests).toHaveLength(0)
+  })
+
+  it('streams raw chunks through ctx.llm.stream', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents, delayMs: 2 }])
+    const ctx = await harness(server.url)
+
+    const kinds: string[] = []
+    for await (const chunk of ctx.llm.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })) {
+      kinds.push(chunk.type)
+    }
+    expect(kinds).toEqual(['block-start', 'text-delta', 'block-end', 'usage', 'finish'])
+  })
+
+  it('forwards the harness user and session ids for host-side trajectory routing', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const ctx = await harness(server.url)
+
+    await assemble(ctx, {
+      model: 'deepseek-v4-flash',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+      sessionId: SessionId('child-session'),
+    })
+
+    expect(server.headers[0]?.['x-deepseek-harness-session-id']).toBe('child-session')
+    expect(server.headers[0]?.['x-deepseek-harness-user-id']).toBe(getOrCreateAnonymousUserId())
+  })
+
+  it('marks the auxiliary compaction call on the wire', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const ctx = await harness(server.url)
+
+    await assemble(ctx, {
+      model: 'deepseek-v4-flash',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+      purpose: 'compaction',
+    })
+
+    expect(server.headers[0]?.['x-deepseek-harness-compact']).toBe('1')
+  })
+
+  it('switches dynamically from the configured low default through off to max', async () => {
+    const server = await mockServer([
+      { kind: 'sse', events: textEvents },
+      { kind: 'sse', events: textEvents },
+      { kind: 'sse', events: textEvents },
+    ])
+    const ctx = await harness(server.url, { thinking: 'enabled', reasoningEffort: 'low' })
+
+    await assemble(ctx,{
+      model: 'deepseek-v4-flash',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })
+    await assemble(ctx,{
+      model: 'deepseek-v4-flash',
+      reasoningEffort: ReasoningEffortId('off'),
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi again' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })
+    await assemble(ctx,{
+      model: 'deepseek-v4-flash',
+      reasoningEffort: ReasoningEffortId('max'),
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'one more time' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })
+    expect(server.requests[0]).toMatchObject({
+      thinking: { type: 'enabled' },
+      output_config: { effort: 'low' },
+    })
+    expect(server.requests[1]).toMatchObject({
+      thinking: { type: 'disabled' },
+    })
+    expect(server.requests[1]).not.toHaveProperty('output_config')
+    expect(server.requests[2]).toMatchObject({
+      thinking: { type: 'enabled' },
+      output_config: { effort: 'max' },
+    })
+  })
+
+  it('uses the configured maxTokens default and preserves an explicit request cap', async () => {
+    const server = await mockServer([
+      { kind: 'sse', events: textEvents },
+      { kind: 'sse', events: textEvents },
+    ])
+    const ctx = await harness(server.url, { maxTokens: 32_000 })
+
+    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [], maxTokens: 8_192 })
+
+    expect(server.requests[0]).toMatchObject({ max_tokens: 32_000 })
+    expect(server.requests[1]).toMatchObject({ max_tokens: 8_192 })
+  })
+
+  it('publishes only off and omits the wire effort when thinking is disabled', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const ctx = await harness(server.url, { thinking: 'disabled' })
+
+    await assemble(ctx,{
+      model: 'deepseek-v4-flash',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })
+    expect(server.requests[0]).toMatchObject({
+      thinking: { type: 'disabled' },
+    })
+    expect(server.requests[0]).not.toHaveProperty('output_config')
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-v4-flash'))
+      .resolves.toMatchObject({
+        reasoning: {
+          efforts: [{
+            id: ReasoningEffortId('off'),
+            name: 'Off',
+            description: 'Use for simple tasks that do not need reasoning.',
+          }],
+          defaultEffort: ReasoningEffortId('off'),
+        },
+      })
+  })
+
+  it('reports a per-request effort failure before I/O when thinking is disabled', async () => {
+    const server = await mockServer([])
+    const ctx = await harness(server.url, { thinking: 'disabled' })
+
+    const result = await assemble(ctx, {
+      model: 'deepseek-v4-flash',
+      reasoningEffort: ReasoningEffortId('high'),
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'hi' }],
+        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })],
+    })
+    expect(result.finish).toMatchObject({
+      kind: 'error',
+      failure: { code: 'UNSUPPORTED_REASONING_EFFORT' },
+    })
+    expect(server.requests).toHaveLength(0)
+  })
+
+  it.each(['high', 'max'])(
+    'rejects direct adapter effort %s before I/O when thinking is disabled',
+    async (effort) => {
+      const server = await mockServer([])
+      const adapter = adapterOf({ apiKey: 'test-key', baseURL: server.url, thinking: 'disabled' })
+
+      const stream = adapter.stream({
+        provider: 'deepseek-official',
+        model: 'deepseek-v4-flash',
+        reasoningEffort: ReasoningEffortId(effort),
+        messages: [createUserMessage({
+          content: [{ type: 'text', text: 'hi' }],
+          source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        })],
+      })
+      await expect(async () => {
+        for await (const _chunk of stream) { /* drain */ }
+      }).rejects.toMatchObject({ code: 'UNSUPPORTED_REASONING_EFFORT' })
+      expect(server.requests).toHaveLength(0)
+    },
+  )
+
+  it.each([
+    [401, 'AUTH'],
+    [403, 'AUTH'],
+    [429, 'RATE_LIMIT'],
+    [400, 'INVALID_REQUEST'],
+    [500, 'SERVER'],
+    [503, 'SERVER'],
+  ])('maps HTTP %d to failure code %s with the body message', async (status, code) => {
+    const behavior: Behavior = {
+      kind: 'http-error',
+      status,
+      body: JSON.stringify({ error: { message: `failed with ${status}`, type: 't', code: 'c' } }),
+    }
+    const server = await mockServer([behavior])
+    const ctx = await harness(server.url)
+    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish).toEqual({
+      kind: 'error',
+      failure: { message: `failed with ${status}`, code, status },
+    })
+  })
+
+  it('retains the HTTP status when an error response has no body', async () => {
+    const server = await mockServer([{ kind: 'http-error', status: 500, body: '' }])
+    const adapter = adapterOf({ baseURL: server.url })
+
+    await expect(drain(adapter.stream({
+      provider: 'deepseek-official',
+      model: 'deepseek-v4-flash',
+      messages: [],
+    }))).rejects.toMatchObject({
+      failure: { code: 'SERVER', status: 500 },
+      message: 'DeepSeek Messages request failed (500)',
+    })
+  })
+
+  it('classifies an HTTP context-window failure with the canonical code', async () => {
+    const server = await mockServer([{
+      kind: 'http-error',
+      status: 400,
+      body: JSON.stringify({
+        error: {
+          message: 'This model maximum context length is 128000 tokens; your input exceeds that limit.',
+          type: 'invalid_request_error',
+          code: 'context_length_exceeded',
+        },
+      }),
+    }])
+    const ctx = await harness(server.url)
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish).toMatchObject({
+      kind: 'error',
+      failure: { code: CONTEXT_WINDOW_EXCEEDED_CODE },
+    })
+  })
+
+  it('retains status, Retry-After seconds, and provider request id as structured facts', async () => {
+    const server = await mockServer([{
+      kind: 'http-error',
+      status: 429,
+      body: JSON.stringify({ error: { message: 'slow down' } }),
+      headers: { 'retry-after': '2', 'x-request-id': 'req-429' },
+    }])
+    const ctx = await harness(server.url)
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish).toEqual({
+      kind: 'error',
+      failure: {
+        message: 'slow down',
+        code: 'RATE_LIMIT',
+        status: 429,
+        providerRetryAfterMs: 2_000,
+        requestId: ProviderRequestId('req-429'),
+      },
+    })
+  })
+
+  it('parses a future Retry-After HTTP date and the DeepSeek request-id fallback', async () => {
+    const now = 1_800_000_000_000
+    const dateNow = vi.spyOn(Date, 'now').mockReturnValue(now)
+    try {
+      const server = await mockServer([{
+        kind: 'http-error',
+        status: 503,
+        body: JSON.stringify({ error: { message: 'come back later' } }),
+        headers: {
+          'retry-after': new Date(now + 3_000).toUTCString(),
+          'x-deepseek-request-id': 'deepseek-503',
+        },
+      }])
+      const ctx = await harness(server.url)
+      const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+      expect(result.finish).toEqual({
+        kind: 'error',
+        failure: {
+          message: 'come back later',
+          code: 'SERVER',
+          status: 503,
+          providerRetryAfterMs: 3_000,
+          requestId: ProviderRequestId('deepseek-503'),
+        },
+      })
+    } finally {
+      dateNow.mockRestore()
+    }
+  })
+
+  it('omits zero, non-finite, invalid, and past Retry-After values', async () => {
+    const values = [
+      '0',
+      '9'.repeat(400),
+      'not-a-date',
+      new Date(0).toUTCString(),
+    ]
+    for (const value of values) {
+      const server = await mockServer([{
+        kind: 'http-error',
+        status: 429,
+        body: JSON.stringify({ error: { message: 'retry later' } }),
+        headers: { 'retry-after': value },
+      }])
+      const ctx = await harness(server.url)
+      const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+      expect(result.finish).toEqual({
+        kind: 'error',
+        failure: { message: 'retry later', code: 'RATE_LIMIT', status: 429 },
+      })
+    }
+  })
+
+  it('recognizes context-capacity details independently of the HTTP status', () => {
+    expect(providerError({ error: { message: 'request too large for model context' } }, 400).code)
+      .toBe(CONTEXT_WINDOW_EXCEEDED_CODE)
+    expect(providerError({ error: { message: 'invalid input: temperature exceeds maximum allowed value' } }, 400).code)
+      .toBe('INVALID_REQUEST')
+    expect(providerError({ error: { code: 'context_length_exceeded' } }, 413).code).toBe('CONTEXT_WINDOW_EXCEEDED')
+  })
+
+  it('distinguishes terminal quota exhaustion from transient HTTP 429 throttling', () => {
+    expect(providerError({ error: { code: 'insufficient_quota', message: 'account credits exhausted' } }, 429).code)
+      .toBe(QUOTA_EXCEEDED_CODE)
+    expect(providerError({ error: { message: 'request rate limit exceeded' } }, 429).code).toBe('RATE_LIMIT')
+  })
+
+  it('includes the status for JSON error bodies without a message', async () => {
+    const server = await mockServer([{ kind: 'http-error', status: 500, body: '{"error":{"type":"x"}}' }])
+    const ctx = await harness(server.url)
+    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish.kind).toBe('error')
+    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
+    expect(result.finish.failure.code).toBe('SERVER')
+    expect(result.finish.failure.message).toBe('DeepSeek Messages request failed (500)')
+  })
+
+  it('includes the status for non-JSON error bodies', async () => {
+    const server = await mockServer([{ kind: 'http-error', status: 502, body: 'Bad Gateway', contentType: 'text/plain' }])
+    const ctx = await harness(server.url)
+    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish.kind).toBe('error')
+    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
+    expect(result.finish.failure.code).toBe('SERVER')
+    expect(result.finish.failure.message).toBe('DeepSeek Messages request failed (502)')
+  })
+
+  it('maps unusual statuses to HTTP_<status>', () => {
+    expect(providerError({}, 418).code).toBe('HTTP_418')
+  })
+
+  it('reports a failed endpoint connection as a transport failure', async () => {
+    // Port 1 is reserved/unbound, so the service normalizes the fetch failure.
+    const ctx = await harness('http://127.0.0.1:1')
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish).toMatchObject({
+      kind: 'error',
+      failure: {
+        code: 'TRANSPORT',
+        message: 'DeepSeek Messages transport failed',
+      },
+    })
+  })
+
+  it('classifies an aborted request as an aborted finish', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const ctx = await harness('http://127.0.0.1:1')
+    const result = await assemble(ctx, {
+      model: 'deepseek-v4-flash',
+      messages: [],
+      signal: controller.signal,
+    })
+    expect(result.finish).toMatchObject({ kind: 'aborted', failure: { code: 'ABORTED' } })
+  })
+
+  it('throws EMPTY_RESPONSE when the response has no body', async () => {
+    const adapter = adapterOf({ baseURL: 'http://127.0.0.1:1' })
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(null, { status: 200 }),
+    )
+    try {
+      const iterate = async (): Promise<void> => {
+        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
+      }
+      await expect(iterate()).rejects.toThrow(/no response body/)
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  it('classifies an abrupt body close as TRANSPORT', async () => {
+    const server = await mockServer([{
+      kind: 'close-early',
+      events: textEvents.slice(0, 3),
+    }])
+    const ctx = await harness(server.url)
+    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish.kind).toBe('error')
+    if (result.finish.kind !== 'error') throw new Error('expected an error finish')
+    expect(result.finish.failure.code).toBe('TRANSPORT')
+    expect(result.finish.failure.message).toBe('DeepSeek Messages transport failed')
+  })
+
+  it('aborts mid-stream via the request signal', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents, delayMs: 50 }])
+    const ctx = await harness(server.url)
+    const controller = new AbortController()
+
+    const pending = (async () => {
+      const chunks = []
+      for await (const chunk of ctx.llm.stream({
+        provider: 'deepseek-official',
+        model: 'deepseek-v4-flash',
+        messages: [],
+        signal: controller.signal,
+      })) {
+        chunks.push(chunk)
+      }
+      return chunks
+    })()
+
+    setTimeout(() => { controller.abort() }, 30)
+    const chunks = await pending
+    expect(chunks).toHaveLength(1)
+    expect(chunks[0]?.type).toBe('finish')
+    if (chunks[0]?.type !== 'finish') throw new Error('expected a finish chunk')
+    expect(chunks[0].reason.kind).toBe('aborted')
+    if (chunks[0].reason.kind !== 'aborted') throw new Error('expected an aborted finish')
+    expect(chunks[0].reason.failure.code).toBe('ABORTED')
+  })
+
+  it('maps connection failures to TRANSPORT without losing the cause', async () => {
+    const cause = new TypeError('connection refused')
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockRejectedValue(cause)
+    const adapter = adapterOf({ baseURL: 'https://example.invalid' })
+    try {
+      const drain = async (): Promise<void> => {
+        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
+      }
+      await expect(drain()).rejects.toMatchObject({ code: 'TRANSPORT', cause })
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  it('renders a non-Error transport rejection without losing its cause', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
+      const failed = Promise.withResolvers<Response>()
+      failed.reject('offline')
+      return failed.promise
+    })
+    const adapter = adapterOf({ baseURL: 'https://example.invalid' })
+    try {
+      const drain = async (): Promise<void> => {
+        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
+      }
+      await expect(drain()).rejects.toMatchObject({
+        message: 'DeepSeek Messages transport failed',
+        code: 'TRANSPORT',
+        cause: 'offline',
+      })
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  it('aborts the underlying body when the stream stays idle past its watchdog', async () => {
+    vi.useFakeTimers()
+    let stopped = false
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((_input, init) => {
+      const signal = init?.signal
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          signal?.addEventListener('abort', () => {
+            stopped = true
+            controller.error(signal.reason)
+          }, { once: true })
+        },
+      })
+      return Promise.resolve(new Response(body, { status: 200 }))
+    })
+    const adapter = adapterOf({
+      baseURL: 'https://example.invalid',
+      streamIdleTimeoutMs: 100,
+    })
+    try {
+      const drain = (async () => {
+        for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
+      })()
+      const rejected = expect(drain).rejects.toMatchObject({ code: 'TIMEOUT' })
+      await vi.advanceTimersByTimeAsync(0)
+      await vi.advanceTimersByTimeAsync(100)
+      await rejected
+      expect(stopped).toBe(true)
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  it('keeps an idle provider read alive through SSE comments', async () => {
+    vi.useFakeTimers()
+    const encoder = new TextEncoder()
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 75)
+          setTimeout(() => { controller.enqueue(encoder.encode(': keep-alive\n\n')) }, 150)
+          setTimeout(() => {
+            controller.enqueue(encoder.encode(textEvents.map(event => `data: ${event}\n\n`).join('')))
+            controller.close()
+          }, 225)
+        },
+      })
+      return Promise.resolve(new Response(body, { status: 200 }))
+    })
+    const adapter = adapterOf({
+      baseURL: 'https://example.invalid',
+      streamIdleTimeoutMs: 100,
+    })
+    try {
+      const chunks: string[] = []
+      const drain = (async () => {
+        for await (const chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) {
+          chunks.push(chunk.type)
+        }
+      })()
+      await vi.advanceTimersByTimeAsync(75)
+      await vi.advanceTimersByTimeAsync(75)
+      await vi.advanceTimersByTimeAsync(75)
+      await expect(drain).resolves.toBeUndefined()
+      expect(chunks).toEqual(['block-start', 'text-delta', 'block-end', 'usage', 'finish'])
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+})
+
+describe('plugin registration and config', () => {
+  it('resolves the Messages endpoint without rewriting overrides', () => {
+    expect(resolveAdapterOptions({}).baseURL).toBe('https://api.deepseek.com/anthropic')
+    for (const baseURL of ['https://example.com', 'https://example.com/custom']) {
+      expect(resolveAdapterOptions({ baseURL }).baseURL).toBe(baseURL)
+    }
+    const retired = { protocol: 'messages', baseURL: 'https://gateway.example' }
+    expect(() => resolveAdapterOptions(retired)).toThrow(/protocol/)
+  })
+
+  it('keeps wire helpers off the package root', () => {
+    for (const helper of [
+      'httpErrorCode',
+      'serializeMessages',
+      'serializeRequest',
+      'DONE',
+      'parseSse',
+      'mapFinishReason',
+      'mapUsage',
+      'translate',
+    ]) expect(LlmDeepSeek).not.toHaveProperty(helper)
+  })
+
+  it('registers the deepseek provider and unregisters on dispose (HMR safety)', async () => {
+    const server = await mockServer([])
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    const fiber = await ctx.plugin(LlmDeepSeek, {
+      baseURL: server.url,
+    })
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
+    expect(ctx.llm.listConfigurableProviders()).toEqual([{
+      provider: 'deepseek-official',
+      displayName: 'DeepSeek',
+      settingsNs: 'llm-deepseek',
+      settingsPath: [],
+    }])
+    await fiber.dispose()
+    expect(ctx.llm.listProviders()).toEqual([])
+    expect(ctx.llm.listConfigurableProviders()).toEqual([])
+  })
+
+  it('registers retryPolicy from the provider config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      retryPolicy: {
+        mode: 'always',
+        backoff: { initialDelayMs: 25, maxDelayMs: 100, jitterRatio: 0.2 },
+      },
+    })
+
+    expect(ctx.llm.providerRetryPolicy('deepseek-official')).toEqual({
+      mode: 'always',
+      initialDelayMs: 25,
+      maxDelayMs: 100,
+      jitterRatio: 0.2,
+    })
+  })
+
+  it('owns the deepseek provider and advertises the default models', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, { baseURL: 'http://127.0.0.1:1' })
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
+    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
+      { provider: 'deepseek-official', id: 'deepseek-flash', name: 'DeepSeek-V41-Flash', inputModalities: ['text', 'image'] },
+      {
+        provider: 'deepseek-official',
+        id: 'deepseek-v4-pro',
+        name: 'DeepSeek-V4-Pro',
+        description: 'Stronger agentic coding, knowledge, and difficult reasoning; suited to complex or quality-critical tasks at higher cost.',
+        inputModalities: ['text'],
+      },
+    ])
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-flash'))
+      .resolves.toMatchObject({
+        provider: 'deepseek-official',
+        id: 'deepseek-flash',
+        name: 'DeepSeek-V41-Flash',
+        inputModalities: ['text', 'image'],
+        systemPromptUpdate: 'in-history',
+        context: { contextWindow: 1_000_000 },
+        defaultMaxTokens: 256_000,
+        reasoning: {
+          efforts: [
+            { id: ReasoningEffortId('off'), name: 'Off', description: 'Use for simple tasks that do not need reasoning.' },
+            { id: ReasoningEffortId('low'), name: 'Low', description: 'Prefer for routine or latency-sensitive tasks.' },
+            { id: ReasoningEffortId('high'), name: 'High', description: 'The default balance for most tasks.' },
+            { id: ReasoningEffortId('max'), name: 'Max', description: 'Reserve for the hardest quality-first tasks.' },
+          ],
+          defaultEffort: ReasoningEffortId('high'),
+        },
+      })
+  })
+
+  it('keeps deepseek-v4-pro available with its V4 capabilities', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, { baseURL: 'http://127.0.0.1:1' })
+    const info = await ctx.llm.resolveModelInfo('deepseek-official', 'deepseek-v4-pro')
+    expect(info).toMatchObject({
+      id: 'deepseek-v4-pro',
+      inputModalities: ['text'],
+      context: { contextWindow: 1_000_000 },
+      defaultMaxTokens: 256_000,
+    })
+    expect(info?.systemPromptUpdate).toBeUndefined()
+  })
+
+  it.each(['off', 'low', 'max'] as const)('uses the configured %s reasoning default', async (effort) => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      reasoningEffort: effort,
+    })
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'unlisted-pass-through'))
+      .resolves.toMatchObject({
+        reasoning: {
+          efforts: [
+            { id: ReasoningEffortId('off'), name: 'Off', description: 'Use for simple tasks that do not need reasoning.' },
+            { id: ReasoningEffortId('low'), name: 'Low', description: 'Prefer for routine or latency-sensitive tasks.' },
+            { id: ReasoningEffortId('high'), name: 'High', description: 'The default balance for most tasks.' },
+            { id: ReasoningEffortId('max'), name: 'Max', description: 'Reserve for the hardest quality-first tasks.' },
+          ],
+          defaultEffort: ReasoningEffortId(effort),
+        },
+      })
+  })
+
+  it('accepts off as the default when thinking is deployment-disabled', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      thinking: 'disabled',
+      reasoningEffort: 'off',
+    })
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'unlisted-pass-through'))
+      .resolves.toMatchObject({
+        reasoning: {
+          efforts: [{
+            id: ReasoningEffortId('off'),
+            name: 'Off',
+            description: 'Use for simple tasks that do not need reasoning.',
+          }],
+          defaultEffort: ReasoningEffortId('off'),
+        },
+      })
+  })
+
+  it.each(['low', 'high', 'max'] as const)(
+    'rejects configured reasoning effort %s when thinking is disabled',
+    async (reasoningEffort) => {
+      const ctx = new Context()
+      await ctx.plugin(LlmRuntime)
+      await expect(ctx.plugin(LlmDeepSeek, {
+        baseURL: 'http://127.0.0.1:1',
+        thinking: 'disabled',
+        reasoningEffort,
+      })).rejects.toThrow(/only reasoningEffort "off"/)
+      expect(ctx.llm.listProviders()).toEqual([])
+    },
+  )
+
+  it.each(['low', 'high', 'max'] as const)(
+    'rejects disabled-thinking effort %s at the resolver boundary',
+    (reasoningEffort) => {
+      expect(() => resolveAdapterOptions({ thinking: 'disabled', reasoningEffort }))
+        .toThrow(/only reasoningEffort "off"/)
+    },
+  )
+
+  it('accepts disabled thinking with off at the resolver boundary', async () => {
+    const adapter = adapterOf({ thinking: 'disabled', reasoningEffort: 'off' })
+    await expect(adapter.resolveModel('deepseek-official', 'pass-through')).resolves.toMatchObject({
+      reasoning: {
+        efforts: [{
+          id: ReasoningEffortId('off'),
+          name: 'Off',
+          description: 'Use for simple tasks that do not need reasoning.',
+        }],
+        defaultEffort: ReasoningEffortId('off'),
+      },
+    })
+  })
+
+  it('uses the default model catalog when apply is called directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    LlmDeepSeek.apply(ctx, { baseURL: 'http://127.0.0.1:1' })
+    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
+      { provider: 'deepseek-official', id: 'deepseek-flash', name: 'DeepSeek-V41-Flash', inputModalities: ['text', 'image'] },
+      {
+        provider: 'deepseek-official',
+        id: 'deepseek-v4-pro',
+        name: 'DeepSeek-V4-Pro',
+        description: 'Stronger agentic coding, knowledge, and difficult reasoning; suited to complex or quality-critical tasks at higher cost.',
+        inputModalities: ['text'],
+      },
+    ])
+  })
+
+  it('defaults an adapter-supplied catalog entry to text input', async () => {
+    const connection = resolveAdapterOptions({ models: [] })
+    const adapter = new DeepSeekAdapter({
+      options: () => ({ ...connection, models: [{ id: 'adapter-model' }] }),
+      resolveApiKey: () => Promise.resolve('k'),
+      resolveUserId: () => TEST_USER_ID,
+      prepareExtensions: noExtensions,
+    })
+    await expect(adapter.listModels('deepseek-official')).resolves.toEqual([{
+      provider: 'deepseek-official',
+      id: 'adapter-model',
+      name: 'adapter-model',
+      inputModalities: ['text'],
+    }])
+  })
+
+  it('advertises configured models without restricting arbitrary request ids', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      models: [
+        { id: 'private-fast', contextWindow: 32_000 },
+        {
+          id: 'private-reasoner',
+          name: 'Private Reasoner',
+          description: 'Higher reasoning budget',
+          contextWindow: 64_000,
+          inputModalities: ['text', 'image'],
+        },
+      ],
+    })
+    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([
+      { provider: 'deepseek-official', id: 'private-fast', name: 'private-fast', inputModalities: ['text'] },
+      { provider: 'deepseek-official', id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget', inputModalities: ['text', 'image'] },
+    ])
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'private-fast'))
+      .resolves.toMatchObject({ context: { contextWindow: 32_000 } })
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'private-reasoner'))
+      .resolves.toMatchObject({
+        name: 'Private Reasoner',
+        description: 'Higher reasoning budget',
+        inputModalities: ['text', 'image'],
+      })
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'arbitrary-unlisted'))
+      .resolves.toMatchObject({
+        context: { contextWindow: 1_000_000 },
+        defaultMaxTokens: 256_000,
+      })
+  })
+
+  it('uses exact model capacity before the adapter-wide default', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      defaultContextWindow: 256_000,
+      models: [
+        { id: 'inherits-default' },
+        { id: 'exact-override', contextWindow: 64_000 },
+      ],
+    })
+
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'inherits-default'))
+      .resolves.toMatchObject({ context: { contextWindow: 256_000 } })
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'exact-override'))
+      .resolves.toMatchObject({ context: { contextWindow: 64_000 } })
+    await expect(ctx.llm.resolveModelInfo('deepseek-official', 'unlisted-pass-through'))
+      .resolves.toMatchObject({ context: { contextWindow: 256_000 } })
+  })
+
+  it('allows an explicit empty model catalog', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      models: [],
+    })
+    await expect(ctx.llm.listModels('deepseek-official')).resolves.toEqual([])
+  })
+
+  const invalidModels: Array<[object[], RegExp]> = [
+    [[{ id: '' }], /ids must be non-empty/],
+    [[{ id: 'm', name: '' }], /empty name/],
+    [[{ id: 'm', contextWindow: 0 }], /contextWindow/],
+    [[{ id: 'm', contextWindow: 1.5 }], /contextWindow/],
+    [[{ id: 'm', inputModalities: [] }], /inputModalities/],
+    [[{ id: 'm', inputModalities: ['text', 'text'] }], /inputModalities must not contain duplicates/],
+    [[{
+      id: 'm',
+      inputModalities: ['audio'],
+    }], /expected "text" \| "image"/],
+    [[{ id: 'm' }, { id: 'm' }], /duplicate catalog model/],
+  ]
+
+  it.each(invalidModels)('rejects invalid advisory model config', async (models, message) => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await expect(Reflect.apply(ctx.plugin.bind(ctx), undefined, [LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1', models: [...models],
+    }])).rejects.toThrow(message)
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
+  const invalidProgrammaticModalities: Array<[object[], RegExp]> = [
+    [[{ id: 'm', inputModalities: [] }], /inputModalities must not be empty/],
+    [[{
+      id: 'm',
+      inputModalities: ['audio'],
+    }], /inputModalities must contain only "text" and "image"/],
+  ]
+
+  it.each(invalidProgrammaticModalities)('rejects programmatic modality config that bypasses the schema', (models, message) => {
+    expect(() => { Reflect.apply(resolveAdapterOptions, undefined, [{ models: [...models] }]) }).toThrow(message)
+  })
+
+  it('rejects the removed imageDetail model setting through schema and direct construction', async () => {
+    const legacyModel = { id: 'vision', inputModalities: ['image' as const], imageDetail: 'low' }
+    expect(() => resolveAdapterOptions({ models: [legacyModel] })).toThrow(/imageDetail is no longer supported/)
+
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      models: [legacyModel],
+    })).rejects.toThrow(/imageDetail is no longer supported/)
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
+  it.each([0, 1.5])('rejects a per-model output cap of %s', (maxTokens) => {
+    expect(() => resolveAdapterOptions({ models: [{ id: 'bad-cap', maxTokens }] }))
+      .toThrow(/maxTokens must be a positive integer/)
+  })
+
+  it('surfaces a catalog model\'s in-history system prompt update mode and rejects any other mode', async () => {
+    const adapter = adapterOf({ models: [
+      { id: 'capable', systemPromptUpdate: 'in-history' },
+      { id: 'plain' },
+    ] })
+    await expect(adapter.resolveModel('deepseek-official', 'capable'))
+      .resolves.toMatchObject({ systemPromptUpdate: 'in-history' })
+    await expect(adapter.resolveModel('deepseek-official', 'plain'))
+      .resolves.not.toHaveProperty('systemPromptUpdate')
+    await expect(adapter.resolveModel('deepseek-official', 'not-in-catalog'))
+      .resolves.not.toHaveProperty('systemPromptUpdate')
+    expect(() => { Reflect.apply(resolveAdapterOptions, undefined, [{
+      models: [{ id: 'bogus', systemPromptUpdate: 'leading' }],
+    }]) }).toThrow(/systemPromptUpdate must be "in-history" when present/)
+  })
+
+  it('rejects image request limits on a text-only catalog model', () => {
+    expect(() => resolveAdapterOptions({
+      models: [{ id: 'text-only', inputModalities: ['text'], imagePixelBudget: 1 }],
+    })).toThrow(/text-only catalog model .* cannot declare image request limits/)
+  })
+
+  it.each([
+    ['imagePixelBudget', 0, /imagePixelBudget must be "low" or a positive safe integer/],
+    ['imagePixelBudget', Number.MAX_SAFE_INTEGER + 1, /imagePixelBudget must be "low" or a positive safe integer/],
+    ['imagePixelBudget', 'auto', /imagePixelBudget must be "low" or a positive safe integer/],
+    ['imageMaxBytes', 0, /imageMaxBytes must be a positive safe integer/],
+    ['imageMaxBytes', 1.5, /imageMaxBytes must be a positive safe integer/],
+  ] as const)('rejects per-model %s=%s', (field, value, message) => {
+    expect(() => resolveAdapterOptions({
+      models: [{ id: 'vision', inputModalities: ['image'], [field]: value }],
+    })).toThrow(message)
+  })
+
+  it('prefers a model\'s own output cap over the profile default', async () => {
+    // The profile default stays what an unlisted or uncapped model resolves
+    // to, so adding a per-model cap changes one model rather than the route.
+    const adapter = adapterOf({ maxTokens: 4096, models: [
+      { id: 'capped', maxTokens: 512 },
+      { id: 'uncapped' },
+    ] })
+    await expect(adapter.resolveModel('deepseek-official', 'capped'))
+      .resolves.toMatchObject({ defaultMaxTokens: 512 })
+    await expect(adapter.resolveModel('deepseek-official', 'uncapped'))
+      .resolves.toMatchObject({ defaultMaxTokens: 4096 })
+    await expect(adapter.resolveModel('deepseek-official', 'not-in-catalog'))
+      .resolves.toMatchObject({ defaultMaxTokens: 4096 })
+  })
+
+  it('rejects invalid context capacity when apply is called directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    expect(() => {
+      LlmDeepSeek.apply(ctx, {
+        baseURL: 'http://127.0.0.1:1',
+        models: [{ id: 'invalid-context', contextWindow: 0 }],
+      })
+    }).toThrow(/contextWindow must be a positive integer/)
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+
+  it.each([0, 1.5])(
+    'rejects invalid adapter-wide default context capacity %s',
+    async (defaultContextWindow) => {
+      expect(() => resolveAdapterOptions({ defaultContextWindow }))
+        .toThrow(/defaultContextWindow must be a positive integer/)
+
+      const ctx = new Context()
+      await ctx.plugin(LlmRuntime)
+      await expect(ctx.plugin(LlmDeepSeek, {
+        baseURL: 'http://127.0.0.1:1',
+        defaultContextWindow,
+      })).rejects.toThrow(/defaultContextWindow/)
+      expect(ctx.llm.listProviders()).toEqual([])
+    },
+  )
+
+  it.each([0, 1.5, Number.MAX_SAFE_INTEGER + 1])(
+    'rejects invalid adapter-wide maxTokens %s',
+    async (maxTokens) => {
+      expect(() => resolveAdapterOptions({ maxTokens }))
+        .toThrow(/maxTokens must be a positive safe integer/)
+
+      const ctx = new Context()
+      await ctx.plugin(LlmRuntime)
+      await expect(ctx.plugin(LlmDeepSeek, {
+        baseURL: 'http://127.0.0.1:1',
+        maxTokens,
+      })).rejects.toThrow(/maxTokens/)
+      expect(ctx.llm.listProviders()).toEqual([])
+    },
+  )
+
+  it('rejects offload quanta larger than their request bounds', () => {
+    expect(() => resolveAdapterOptions({
+      maxRequestFilesBytes: 10,
+      imageOffloadByteQuantum: 11,
+    })).toThrow(/imageOffloadByteQuantum must not exceed maxRequestFilesBytes/)
+    expect(() => resolveAdapterOptions({
+      maxInlineRequestImageBytes: 10,
+      inlineImageOffloadByteQuantum: 11,
+    })).toThrow(/inlineImageOffloadByteQuantum must not exceed maxInlineRequestImageBytes/)
+    expect(() => resolveAdapterOptions({
+      maxImagesPerRequest: 10,
+      imageOffloadCountQuantum: 11,
+    })).toThrow(/imageOffloadCountQuantum must not exceed maxImagesPerRequest/)
+  })
+
+  it.each([
+    ['maxImagesPerRequest', 0, /maxImagesPerRequest must be a positive safe integer/],
+    ['maxImagesPerRequest', 1.5, /maxImagesPerRequest must be a positive safe integer/],
+    ['imageOffloadByteQuantum', 0, /imageOffloadByteQuantum must be a positive safe integer/],
+    ['imageOffloadByteQuantum', Number.MAX_SAFE_INTEGER + 1, /imageOffloadByteQuantum must be a positive safe integer/],
+    ['inlineImageOffloadByteQuantum', 0, /inlineImageOffloadByteQuantum must be a positive safe integer/],
+    ['inlineImageOffloadByteQuantum', Number.MAX_SAFE_INTEGER + 1, /inlineImageOffloadByteQuantum must be a positive safe integer/],
+    ['imageOffloadCountQuantum', 0, /imageOffloadCountQuantum must be a positive safe integer/],
+    ['imageOffloadCountQuantum', 1.5, /imageOffloadCountQuantum must be a positive safe integer/],
+    ['fileExpiresAfterSeconds', 3_599, /fileExpiresAfterSeconds must be an integer from 3600 through 2592000/],
+    ['fileExpiresAfterSeconds', 2_592_001, /fileExpiresAfterSeconds must be an integer from 3600 through 2592000/],
+    ['fileRefreshMarginSeconds', -1, /fileRefreshMarginSeconds must be a non-negative integer/],
+    ['fileRefreshMarginSeconds', 604_800, /fileRefreshMarginSeconds must be a non-negative integer/],
+    ['fileQuotaCleanupBatch', 0, /fileQuotaCleanupBatch must be an integer from 1 through 1000/],
+    ['fileQuotaCleanupBatch', 1_001, /fileQuotaCleanupBatch must be an integer from 1 through 1000/],
+  ] as const)('rejects %s=%s', (field, value, message) => {
+    expect(() => resolveAdapterOptions({ [field]: value })).toThrow(message)
+  })
+
+  it.each([0, 1.5, Number.MAX_SAFE_INTEGER + 1])(
+    'rejects invalid request file bound %s',
+    async (maxRequestFilesBytes) => {
+      expect(() => resolveAdapterOptions({ maxRequestFilesBytes }))
+        .toThrow(/maxRequestFilesBytes must be a positive safe integer/)
+
+      const ctx = new Context()
+      await ctx.plugin(LlmRuntime)
+      await expect(ctx.plugin(LlmDeepSeek, {
+        baseURL: 'http://127.0.0.1:1',
+        maxRequestFilesBytes,
+      })).rejects.toThrow(/maxRequestFilesBytes/)
+      expect(ctx.llm.listProviders()).toEqual([])
+    },
+  )
+
+  it.each([0, 1.5, Number.MAX_SAFE_INTEGER + 1])(
+    'rejects invalid inline request image bound %s',
+    async (maxInlineRequestImageBytes) => {
+      expect(() => resolveAdapterOptions({ maxInlineRequestImageBytes }))
+        .toThrow(/maxInlineRequestImageBytes must be a positive safe integer/)
+
+      const ctx = new Context()
+      await ctx.plugin(LlmRuntime)
+      await expect(ctx.plugin(LlmDeepSeek, {
+        baseURL: 'http://127.0.0.1:1',
+        maxInlineRequestImageBytes,
+      })).rejects.toThrow(/maxInlineRequestImageBytes/)
+      expect(ctx.llm.listProviders()).toEqual([])
+    },
+  )
+
+  it('falls back to DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL env vars', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
+    vi.stubEnv('DEEPSEEK_BASE_URL', 'http://127.0.0.1:1')
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {})
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
+  })
+
+  it('loads keyless, keeps the catalog browsable, and fails the request actionably', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', '')
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, { baseURL: 'http://127.0.0.1:1' })
+    // First-boot onboarding: the route registers so models stay discoverable;
+    // only the request itself needs a key.
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
+    await expect(ctx.llm.listModels('deepseek-official')).resolves.toHaveLength(2)
+    const first = await assemble(ctx, { model: 'deepseek-flash', messages: [] })
+    expect(first.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
+    // The guidance leads with the managed credential store.
+    const second = await assemble(ctx, { model: 'deepseek-flash', messages: [] })
+    expect(second.finish.kind).toBe('error')
+    if (second.finish.kind !== 'error') throw new Error('expected an error finish')
+    // The guidance names both places a credential can come from, and nothing
+    // else: configuration carries the reference, never a literal key.
+    expect(second.finish.failure.message)
+      .toMatch(/store DEEPSEEK_API_KEY through the credentials service.*export DEEPSEEK_API_KEY/s)
+  })
+
+  it('reads the ambient variable when no credentials seam is mounted', async () => {
+    // The plain cordis.yml composition: no credential provider, the key in
+    // the launching environment.
+    vi.stubEnv('DEEPSEEK_API_KEY', 'ambient-key')
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, { baseURL: server.url })
+    await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(server.headers[0]?.['x-api-key']).toBe('ambient-key')
+  })
+
+  it('treats an empty ambient variable as no key when no credentials seam is mounted', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', '')
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, { baseURL: 'http://127.0.0.1:1' })
+    const result = await assemble(ctx, { model: 'deepseek-v4-flash', messages: [] })
+    expect(result.finish).toMatchObject({ kind: 'error', failure: { code: 'MISSING_CREDENTIAL' } })
+  })
+
+  it('prefers explicit config over env for key and base URL', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
+    vi.stubEnv('DEEPSEEK_BASE_URL', 'http://env-host:1')
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const ctx = await harness(server.url) // harness passes explicit config
+    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    expect(server.requests).toHaveLength(1) // hit the explicit URL, not env
+  })
+
+  it('uses DEEPSEEK_BASE_URL when config omits baseURL', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    vi.stubEnv('DEEPSEEK_BASE_URL', server.url)
+    vi.stubEnv('DEEPSEEK_API_KEY', 'test-key')
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await ctx.plugin(LlmDeepSeek, {})
+    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+    expect(server.requests).toHaveLength(1)
+  })
+
+
+  it('takes DEEPSEEK_BASE_URL from any environment layer, with explicit config still on top', () => {
+    const trusted = createLaunchEnvironmentSnapshot([
+      { source: 'user-env', path: '/home/.dsh/.env', values: { DEEPSEEK_BASE_URL: 'https://user.example' } },
+    ])
+    expect(resolveAdapterOptions({}, trusted).baseURL).toBe('https://user.example')
+    // The product trusts the project it is launched in, so a checkout can
+    // point its own agent at the gateway that checkout is meant to use.
+    const project = createLaunchEnvironmentSnapshot([
+      { source: 'project-env', path: '/work/.env', values: { DEEPSEEK_BASE_URL: 'https://project.example' } },
+    ])
+    expect(resolveAdapterOptions({}, project).baseURL).toBe('https://project.example')
+    // An explicitly configured endpoint outranks every environment layer, so a
+    // stale shell value cannot rewrite a deployment's own gateway.
+    const shell = createLaunchEnvironmentSnapshot([
+      { source: 'process', values: { DEEPSEEK_BASE_URL: 'https://stale.example' } },
+    ])
+    expect(resolveAdapterOptions({ baseURL: 'https://gateway.internal' }, shell).baseURL).toBe('https://gateway.internal')
+  })
+  it('uses the public Messages base URL without an endpoint override', async () => {
+    vi.stubEnv('DEEPSEEK_API_KEY', 'k')
+    vi.stubEnv('DEEPSEEK_BASE_URL', undefined)
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    // Registration succeeds; no call is made (would hit api.deepseek.com).
+    await ctx.plugin(LlmDeepSeek, {})
+    expect(ctx.llm.listProviders()).toEqual([{ id: 'deepseek-official', name: 'DeepSeek' }])
+  })
+
+  it('adapter is constructible directly for embedding over the shared resolver', async () => {
+    const adapter = adapterOf()
+    expect(adapter).toBeInstanceOf(DeepSeekAdapter)
+    // Direct embedding shares the plugin's one resolve step, so it advertises
+    // the same default catalog instead of a divergent empty one.
+    await expect(adapter.listModels('deepseek-official')).resolves.toHaveLength(2)
+  })
+
+  it('resolves connection facts and the credential exactly once per stream call', async () => {
+    const server = await mockServer([{ kind: 'sse', events: textEvents }])
+    const options = vi.fn(() => resolveAdapterOptions({ baseURL: server.url }))
+    const resolveApiKey = vi.fn(() => Promise.resolve('per-request-key'))
+    const resolveUserId = vi.fn(() => TEST_USER_ID)
+    const adapter = new DeepSeekAdapter({ options, resolveApiKey, resolveUserId, prepareExtensions: noExtensions })
+
+    for await (const _chunk of adapter.stream({ provider: 'deepseek-official', model: 'm', messages: [] })) { /* drain */ }
+
+    expect(options).toHaveBeenCalledTimes(1)
+    expect(resolveApiKey).toHaveBeenCalledTimes(1)
+    expect(resolveUserId).toHaveBeenCalledTimes(1)
+    expect(server.headers[0]?.['x-api-key']).toBe('per-request-key')
+  })
+
+  it('rejects invalid idle watchdog bounds for direct and plugin composition', async () => {
+    expect(() => resolveAdapterOptions({ streamIdleTimeoutMs: Number.POSITIVE_INFINITY }))
+      .toThrow(/streamIdleTimeoutMs.*positive finite/)
+    expect(() => resolveAdapterOptions({ streamIdleTimeoutMs: MAX_TIMER_DELAY_MS + 1 }))
+      .toThrow(/streamIdleTimeoutMs.*no greater/)
+
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      streamIdleTimeoutMs: 0,
+    })).rejects.toThrow(/streamIdleTimeoutMs/)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      streamIdleTimeoutMs: MAX_TIMER_DELAY_MS + 1,
+    })).rejects.toThrow(/streamIdleTimeoutMs/)
+  })
+
+  it('validates Files API timeout bounds independently of the stream idle deadline', async () => {
+    expect(() => resolveAdapterOptions({ filesApiTimeoutMs: Number.POSITIVE_INFINITY }))
+      .toThrow(/filesApiTimeoutMs.*positive finite/)
+    expect(() => resolveAdapterOptions({ filesApiTimeoutMs: MAX_TIMER_DELAY_MS + 1 }))
+      .toThrow(/filesApiTimeoutMs.*no greater/)
+
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      filesApiTimeoutMs: 0,
+    })).rejects.toThrow(/filesApiTimeoutMs/)
+    await expect(ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      filesApiTimeoutMs: MAX_TIMER_DELAY_MS + 1,
+    })).rejects.toThrow(/filesApiTimeoutMs/)
+    expect(resolveAdapterOptions({ filesApiTimeoutMs: 100, streamIdleTimeoutMs: 100 }))
+      .toMatchObject({ filesApiTimeoutMs: 100, streamIdleTimeoutMs: 100 })
+  })
+
+  it('rejects invalid nested retryPolicy before registering the provider', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmRuntime)
+
+    await expect(ctx.plugin(LlmDeepSeek, {
+      baseURL: 'http://127.0.0.1:1',
+      retryPolicy: { mode: 'normal', maxRetries: -1 },
+    })).rejects.toThrow(/retryPolicy/)
+    expect(ctx.llm.listProviders()).toEqual([])
+  })
+})
diff --git a/packages/llm/llm-deepseek/tests/serialize.spec.ts b/packages/llm/llm-deepseek/tests/serialize.spec.ts
index 804536fe3b..de32f4680f 100644
--- a/packages/llm/llm-deepseek/tests/serialize.spec.ts
+++ b/packages/llm/llm-deepseek/tests/serialize.spec.ts
@@ -1,832 +1,458 @@
+/** Request conversion and durable replay validation. */
 import { describe, expect, it, vi } from 'vitest'
+import { createDeveloperMessage, createUserMessage, createAssistantMessage, createMessage, createSystemMessage, createToolResultMessage, ReasoningEffortId, ToolCallId } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, ImageBlock, Message, RequestMessage, RequestUserInput } from '@deepseek-ai/dsh-llm'
 import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
-import type { ImageAttachmentRef, ImageMediaType, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
-import { createDeveloperMessage, createToolResultMessage, createUserMessage, ToolCallId, ReasoningEffortId, createMessage } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, GenerateOptions, Message, RequestUserInput } from '@deepseek-ai/dsh-llm'
-import type { ContextFormed } from '@deepseek-ai/dsh-llm'
-import {
-  serializeMessages,
-  serializeMessagesWithImages,
-  serializeRequest,
-  serializeRequestWithImages,
-} from '../src/protocols/chat-completions/serialize.ts'
-import type { ImageSerializationOptions } from '../src/protocols/chat-completions/serialize.ts'
+import type { ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment'
+import { resolveAdapterOptions } from '../src/config.ts'
+import { modelInfo } from '../src/model-info.ts'
+import type { Config } from '../src/config.ts'
+import { imagePricing, inlineImages, prepareImages } from '../src/images.ts'
+import { readReplay, replayState } from '../src/replay.ts'
+import { serialize } from '../src/serialize.ts'
+import { MODEL, options, user, requestImageStore } from './helpers.ts'
 
-declare module '@deepseek-ai/dsh-llm' {
-  interface MessageSourceMap {
-    'test': { kind: 'test' } & ContextFormed
-  }
-}
+const connection = resolveAdapterOptions({})
+const call = (id = 'a'): ContentBlock => ({ type: 'tool-call', id: ToolCallId(id), name: 'read', arguments: '{"path":"a"}' })
+const assistant = (content: ContentBlock[]) => createAssistantMessage({ content, source: { provider: 'deepseek-official', model: MODEL } })
+const result = (id = 'a', content: ContentBlock[] = [{ type: 'text', text: 'result' }]) => createToolResultMessage({ callId: ToolCallId(id), content, isError: false })
+const body = (messages: RequestMessage[] = [user()], overrides: Partial<GenerateOptions> = {}) => serialize(
+  options({ messages, ...overrides }), connection, messages, new Map(), () => undefined,
+)
+const capable = resolveAdapterOptions({ models: [{ id: MODEL, systemPromptUpdate: 'in-history' }] })
+const nativeBody = (messages: Message[]) => serialize(options({ messages }), capable, messages, new Map(), () => undefined)
 
-type FileResolver = Extract<ImageSerializationOptions['representation'], { kind: 'file' }>['resolveFileId']
-
-function request(overrides: Partial<GenerateOptions> = {}): GenerateOptions {
-  return { provider: 'deepseek-official', model: 'deepseek-v4-flash', messages: [], ...overrides }
-}
-
-function imageRef(mediaType: ImageMediaType = 'image/png', bytes = 3): ImageAttachmentRef {
-  const digit = ({
-    'image/png': 'a',
-    'image/jpeg': 'b',
-    'image/webp': 'c',
-    'image/gif': 'd',
-  } as const)[mediaType]
-  return {
-    attachmentId: AttachmentId(`sha256:${digit.repeat(64)}`),
-    mediaType,
-    bytes,
-    width: 1,
-    height: 1,
-  }
-}
-
-function fileResolver(id = 'file-api-image') {
-  return vi.fn<FileResolver>(() => Promise.resolve(id))
-}
-
-function requestVersion(ref: ImageAttachmentRef): RequestImageAttachment {
-  const hash = String(ref.attachmentId).slice('sha256:'.length)
-  return {
-    variantId: ImageVariantId(`sha256:${hash}`),
-    attachment: ref,
-    data: new Uint8Array(ref.bytes),
-    mediaType: ref.mediaType,
-    bytes: ref.bytes,
-    width: ref.width,
-    height: ref.height,
-    depth: 'uchar',
-    space: 'srgb',
-    hasAlpha: ref.mediaType === 'image/png',
-  }
-}
-
-function imageOptions(
-  refs: readonly ImageAttachmentRef[],
-  resolveFileId: FileResolver = fileResolver(),
-  maxRequestImageBytes = 20 * 1024 * 1024,
-): ImageSerializationOptions {
-  return {
-    representation: { kind: 'file' as const, resolveFileId },
-    requestImages: new Map(refs.map(ref => [ref.attachmentId, requestVersion(ref)])),
-    maxRequestImageBytes,
-  }
-}
-
-function inlineImageOptions(
-  refs: readonly ImageAttachmentRef[],
-  maxRequestImageBytes = 20 * 1024 * 1024,
-  byteQuantum = 10 * 1024 * 1024,
-): ImageSerializationOptions {
-  return {
-    representation: { kind: 'base64' },
-    requestImages: new Map(refs.map(ref => [ref.attachmentId, requestVersion(ref)])),
-    maxRequestImageBytes,
-    byteQuantum,
-  }
-}
-
-it.each(['user', 'system', 'assistant', 'tool'] as const)('rejects tool-change blocks in %s history', (role) => {
-  for (const type of ['tool-addition', 'tool-removal'] as const) {
-    const message = { id: 'invalid', role, source: { kind: 'test' }, content: [{ type, toolName: 'search' }] } as unknown as Message
-    expect(() => serializeMessages([message])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
-  }
-})
-
-it('rejects deferred tool definitions until provider loading is implemented', () => {
-  expect(() => serializeRequest(request({ tools: [{ name: 'search', description: '', parameters: {}, deferLoading: true }] })))
-    .toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
-})
-
-describe('request-only user input', () => {
-  it('preserves the exact text request and durable tool-result prefix', () => {
-    const prefix = [
-      createMessage({ role: 'assistant', content: [{ type: 'tool-call', id: ToolCallId('lookup'), name: 'lookup', arguments: '{}' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' } }),
-      createToolResultMessage({ callId: ToolCallId('lookup'), content: [{ type: 'text', text: 'result' }], isError: false }),
-    ]
-    const input: RequestUserInput = { role: 'user', content: [{ type: 'text', text: 'review or summarize this input' }] }
-    const durable = createUserMessage({ content: input.content, source: { kind: 'test' } })
-    expect(serializeRequest(request({ messages: [...prefix, input], system: 'policy' })))
-      .toEqual(serializeRequest(request({ messages: [...prefix, durable], system: 'policy' })))
+describe('Messages request conversion', () => {
+  it('rejects unknown plugin content without interpreting its payload', () => {
+    expect(() => body([createUserMessage({ source: { kind: 'user' }, content: [
+      { type: 'plugin:text', text: 'opaque' } as never,
+    ] })])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
+  })
+  it.each(['user', 'system', 'assistant', 'tool'] as const)('rejects tool-change blocks in %s history', (role) => {
+    for (const type of ['tool-addition', 'tool-removal'] as const) {
+      const content: ContentBlock[] = [{ type, toolName: 'search' }]
+      const message = role === 'user' ? createUserMessage({ source: { kind: 'user' }, content })
+        : role === 'system' ? createMessage({ role, source: { kind: 'system-prompt' }, content })
+          : role === 'assistant' ? assistant(content) : result('invalid', content)
+      expect(() => body([message])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
+    }
   })
 
-  it('preserves image ordering and bytes without manufacturing durable metadata', async () => {
-    const ref = imageRef()
+  it('rejects deferred tool definitions until provider loading is implemented', () => {
+    expect(() => body([], { tools: [{ name: 'search', description: '', parameters: {}, deferLoading: true }] }))
+      .toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
+  })
+
+  it('preserves the exact request with request-only text after durable tool results', () => {
+    const prefix = [user(), assistant([call()]), result()]
+    const input: RequestUserInput = { role: 'user', content: [{ type: 'text', text: 'review or summarize this input' }] }
+    const durable = createUserMessage({ content: input.content, source: { kind: 'user' } })
+    expect(body([...prefix, input], { system: 'policy' })).toEqual(body([...prefix, durable], { system: 'policy' }))
+  })
+
+  it('preserves request-only image content through image preparation and wire conversion', async () => {
+    const attachment: ImageAttachmentRef = {
+      attachmentId: AttachmentId(`sha256:${'e'.repeat(64)}`), mediaType: 'image/png', bytes: 3, width: 1, height: 1,
+    }
+    const version: RequestImageAttachment = {
+      variantId: ImageVariantId(`sha256:${'f'.repeat(64)}`), attachment, data: Uint8Array.of(1, 2, 3),
+      mediaType: 'image/png', bytes: 3, width: 1, height: 1, depth: 'uchar', space: 'srgb', hasAlpha: true,
+    }
     const input: RequestUserInput = { role: 'user', content: [
-      { type: 'text', text: 'before' }, { type: 'image', attachment: ref }, { type: 'text', text: 'after' },
+      { type: 'text', text: 'before' }, { type: 'image', attachment }, { type: 'text', text: 'after' },
     ] }
-    const durable = createUserMessage({ content: input.content, source: { kind: 'test' } })
-    const actual = await serializeRequestWithImages(request({ messages: [input] }), inlineImageOptions([ref]))
-    const expected = await serializeRequestWithImages(request({ messages: [durable] }), inlineImageOptions([ref]))
-    expect(actual).toEqual(expected)
+    const store = requestImageStore(async () => version)
+    const vision = resolveAdapterOptions({ models: [{ id: MODEL, inputModalities: ['text', 'image'] }] })
+    const durable = createUserMessage({ content: input.content, source: { kind: 'user' } })
+    const actual = await prepareImages([input], vision, MODEL, store, () => undefined, new AbortController().signal)
+    const expected = await prepareImages([durable], vision, MODEL, store, () => undefined, new AbortController().signal)
+    expect(serialize(options({ messages: [input] }), vision, actual.messages, actual.versions, () => undefined))
+      .toEqual(serialize(options({ messages: [durable] }), vision, expected.messages, expected.versions, () => undefined))
+    expect(actual.messages[0]).toBe(input)
     expect(input).not.toHaveProperty('id')
     expect(input).not.toHaveProperty('source')
   })
-})
 
-describe('serializeMessages', () => {
-  it('maps user text to string content', () => {
-    const wire = serializeMessages([
-      createUserMessage({
-        content: [{ type: 'text', text: 'hello ' }, { type: 'text', text: 'world' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      }),
-    ])
-    expect(wire).toEqual([{ role: 'user', content: 'hello world' }])
+  it('rejects developer history while provider serialization is unsupported', () => {
+    const message = createDeveloperMessage({ content: [{ type: 'tool-addition', toolName: 'search' }], source: { kind: 'tool-registry' } })
+    expect(() => body([message])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
   })
 
-  it('maps system-role messages in history', () => {
-    const wire = serializeMessages([
-      createMessage({
-        role: 'system', content: [{ type: 'text', text: 'be brief' }],
-        source: { kind: 'system-prompt' },
-      }),
+  it('keeps the original top-level prompt and cached prefix while appending native system updates', () => {
+    const head = createSystemMessage('original')
+    const first = [head, user('first')]
+    const update = createSystemMessage('updated')
+    const second = [...first, assistant([{ type: 'text', text: 'one' }]), update, user('second')]
+    const saved = JSON.stringify(second)
+    const before = nativeBody(first)
+    const after = nativeBody(second)
+    expect(after.system).toBe(before.system)
+    expect(after.messages.slice(0, before.messages.length)).toEqual(before.messages)
+    expect(after.messages.slice(-2)).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'second' }] },
+      { role: 'system', content: [{ type: 'text', text: 'updated' }] },
     ])
-    expect(wire).toEqual([{ role: 'system', content: 'be brief' }])
+    const third = nativeBody([...second, assistant([{ type: 'text', text: 'two' }]), user('third')])
+    expect(third.messages.slice(0, after.messages.length)).toEqual(after.messages)
+    expect(JSON.stringify(second)).toBe(saved)
   })
 
-  it('passes reasoning_content back on tool-call-free turns', () => {
-    const wire = serializeMessages([
-      createMessage({
-        role: 'assistant',
-        content: [
-          { type: 'reasoning', text: 'thinking…' },
-          { type: 'text', text: 'answer' },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      }),
-    ])
-    // A gateway that re-encodes the conversation for another vendor recovers
-    // the upstream thinking signature by hashing this exact text, and a turn
-    // that called no tool carries it nowhere else.
-    expect(wire).toEqual([{ role: 'assistant', content: 'answer', reasoning_content: 'thinking…' }])
-  })
-
-  it('passes reasoning_content back on tool-call turns (official passback rule)', () => {
-    const wire = serializeMessages([
-      createMessage({
-        role: 'assistant',
-        content: [
-          { type: 'reasoning', text: 'I should check the weather.' },
-          { type: 'tool-call', id: ToolCallId('call-1'), name: 'get_weather', arguments: '{"city":"Paris"}' },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      }),
-    ])
-    expect(wire).toEqual([{
-      role: 'assistant',
-      // "" (not null) on tool-call turns — mirrors the official samples'
-      // verbatim message replay; some gateways reject null.
-      content: '',
-      reasoning_content: 'I should check the weather.',
-      tool_calls: [{ id: 'call-1', type: 'function', function: { name: 'get_weather', arguments: '{"city":"Paris"}' } }],
-    }])
-  })
-
-  it('serializes parallel tool calls in order', () => {
-    const wire = serializeMessages([
-      createMessage({
-        role: 'assistant',
-        content: [
-          { type: 'tool-call', id: ToolCallId('a'), name: 'one', arguments: '{}' },
-          { type: 'tool-call', id: ToolCallId('b'), name: 'two', arguments: '{}' },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      }),
-    ])
-    const assistant = wire[0] as { tool_calls: { id: string }[] }
-    expect(assistant.tool_calls.map(call => call.id)).toEqual(['a', 'b'])
-  })
-
-  it('turns tool messages into role:tool wire messages', () => {
-    const wire = serializeMessages([
-      createToolResultMessage({
-        callId: ToolCallId('call-1'),
-        content: [{ type: 'text', text: 'Sunny 22C' }],
-        isError: false,
-      }),
-    ])
-    expect(wire).toEqual([{ role: 'tool', tool_call_id: 'call-1', content: 'Sunny 22C' }])
-  })
-
-  it('sends a sentinel for empty tool content', () => {
-    const wire = serializeMessages([
-      createToolResultMessage({ callId: ToolCallId('call-1'), content: [], isError: false }),
-    ])
-    expect(wire).toEqual([{ role: 'tool', tool_call_id: 'call-1', content: '(no output)' }])
-  })
-
-  it('keeps user text and tool messages as separate wire messages', () => {
-    const wire = serializeMessages([
-      createUserMessage({
-        content: [{ type: 'text', text: 'context note' }],
-        source: { kind: 'test' },
-      }),
-      createToolResultMessage({
-        callId: ToolCallId('call-1'),
-        content: [{ type: 'text', text: 'ok' }],
-        isError: false,
-      }),
-    ])
-    expect(wire).toEqual([
-      { role: 'user', content: 'context note' },
-      { role: 'tool', tool_call_id: 'call-1', content: 'ok' },
+  it('places system updates after all parallel tool results and before the next assistant', () => {
+    const history = [createSystemMessage('original'), user(), assistant([call(), call('b')]),
+      createSystemMessage('first update'), result(), createSystemMessage('second update'), result('b'),
+      user('more input'), assistant([{ type: 'text', text: 'done' }])]
+    const request = nativeBody(history)
+    expect(request.messages.map(message => message.role)).toEqual(['user', 'assistant', 'user', 'system', 'system', 'assistant'])
+    expect(request.messages[2]?.content.map(block => block.type)).toEqual(['tool_result', 'tool_result', 'text'])
+    expect(request.messages.slice(3, 5).map(message => message.content)).toEqual([
+      [{ type: 'text', text: 'first update' }], [{ type: 'text', text: 'second update' }],
     ])
   })
 
-  it('skips plugin-added block types (merge-extensible ContentBlockMap)', () => {
-    const wire = serializeMessages([
-      createUserMessage({
-        content: [
-          { type: 'chart', data: 'x' } as unknown as ContentBlock,
-          { type: 'text', text: 'see chart' },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      }),
+  it('accepts native trailing updates without a top-level prompt and rejects unrepresentable positions', () => {
+    const update = createSystemMessage('update')
+    expect(nativeBody([user(), update])).toMatchObject({ messages: [
+      { role: 'user' }, { role: 'system', content: [{ type: 'text', text: 'update' }] },
+    ] })
+    expect(nativeBody([user(), update]).system).toBeUndefined()
+    expect(() => nativeBody([user(), assistant([{ type: 'text', text: 'done' }]), update])).toThrow(/preceding user/)
+    expect(() => nativeBody([user(), createSystemMessage('')])).toThrow(/empty in-history/)
+    expect(() => nativeBody([user(), assistant([call(), call('b')]), update, result()])).toThrow(/immediate results/)
+  })
+
+  it.each([[], [{ type: 'reasoning', text: 'child reasoning' }], [call('child-call')]] satisfies ContentBlock[][])(
+    'rejects native system updates when their user input is omitted %#', (...content) => {
+      const empty = createMessage({ role: 'user', source: { kind: 'user' }, content })
+      const history = [user(), assistant([{ type: 'text', text: 'answer' }]), createSystemMessage('updated'), empty]
+      const saved = JSON.stringify(history)
+      for (const messages of [history, [...history, assistant([{ type: 'text', text: 'next answer' }])]]) {
+        expect(() => nativeBody(messages)).toThrow(expect.objectContaining({
+          code: 'UNSUPPORTED_CONTENT',
+          message: 'DeepSeek Messages cannot represent system update without a preceding user or tool-result turn',
+        }))
+      }
+      expect(JSON.stringify(history)).toBe(saved)
+    },
+  )
+
+  it('keeps native system updates after retained text or tool results beside omitted user input', () => {
+    const reasoning: ContentBlock = { type: 'reasoning', text: 'child reasoning' }
+    const empty = createMessage({ role: 'user', source: { kind: 'user' }, content: [reasoning] })
+    const update = createSystemMessage('updated')
+    for (const [previous, retained, expected] of [
+      [assistant([{ type: 'text', text: 'answer' }]), user('continue'), [{ type: 'text', text: 'continue' }]],
+      [assistant([call()]), result('a', [reasoning]), [{ type: 'tool_result', tool_use_id: 'a', content: [], is_error: false }]],
+    ] as const) {
+      const history = [user(), previous, update, empty, retained, assistant([{ type: 'text', text: 'done' }])]
+      const saved = JSON.stringify(history)
+      const request = nativeBody(history)
+      expect(request.messages.map(message => message.role)).toEqual(['user', 'assistant', 'user', 'system', 'assistant'])
+      expect(request.messages[2]?.content).toEqual(expected)
+      expect(request.messages[3]?.content).toEqual([{ type: 'text', text: 'updated' }])
+      expect(JSON.stringify(history)).toBe(saved)
+    }
+  })
+
+  it('groups parallel results before ordinary text and keeps tool failure content', () => {
+    const messages = [user(), assistant([call(), call('b')]), user('follow-up'), result(), createToolResultMessage({ callId: ToolCallId('b'), content: [{ type: 'text', text: 'permission denied' }], isError: true })]
+    expect(body(messages).messages).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      { role: 'assistant', content: ['a', 'b'].map(id => ({ type: 'tool_use', id, name: 'read', input: { path: 'a' } })) },
+      { role: 'user', content: [
+        { type: 'tool_result', tool_use_id: 'a', content: [{ type: 'text', text: 'result' }], is_error: false },
+        { type: 'tool_result', tool_use_id: 'b', content: [{ type: 'text', text: 'permission denied' }], is_error: true },
+        { type: 'text', text: 'follow-up' },
+      ] },
     ])
-    expect(wire).toEqual([{ role: 'user', content: 'see chart' }])
+    expect(messages[2]?.content).toEqual([{ type: 'text', text: 'follow-up' }])
   })
 
-  it('rejects image blocks instead of silently flattening them away', () => {
-    expect(() => serializeMessages([createUserMessage({
-      content: [{
-        type: 'image',
-        attachment: {
-          attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`),
-          mediaType: 'image/png', bytes: 68, width: 1, height: 1,
-        },
-      }],
-      source: { kind: 'test' },
-    })])).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_CONTENT' }))
+  it('preserves empty results without inventing model-visible output', () => {
+    const response = body([user(), assistant([call()]), result('a', [])])
+    expect(response.messages[2]?.content[0]).toMatchObject({ content: [] })
+    const { isError: _isError, ...minimal } = createToolResultMessage({ callId: ToolCallId('a'), content: [{ type: 'text', text: '' }], isError: false })
+    expect(body([assistant([call()]), minimal]).messages[1]?.content[0]).toEqual({ type: 'tool_result', tool_use_id: 'a', content: [] })
   })
 
-  it('emits an empty user message rather than dropping block-less messages', () => {
-    const wire = serializeMessages([createUserMessage({
-      content: [],
-      source: { kind: 'test' },
-    })])
-    expect(wire).toEqual([{ role: 'user', content: '' }])
+  it('omits assistant-only blocks from user input while preserving text and durable content', () => {
+    const history = [createMessage({ role: 'user', source: { kind: 'user' }, content: [
+      { type: 'text', text: 'Background subagent finished.\n' },
+      { type: 'reasoning', text: 'child reasoning' },
+      call('child-call'),
+      { type: 'text', text: '  child answer  ' },
+    ] })]
+    const saved = JSON.stringify(history)
+
+    expect(body(history).messages).toEqual([{ role: 'user', content: [
+      { type: 'text', text: 'Background subagent finished.\n' },
+      { type: 'text', text: '  child answer  ' },
+    ] }])
+    expect(JSON.stringify(history)).toBe(saved)
+  })
+
+  it('omits assistant-only blocks inside tool results while retaining calls, errors and empty results', () => {
+    const reasoning: ContentBlock = { type: 'reasoning', text: 'tool reasoning' }
+    const history = [assistant([reasoning, call(), call('b')]),
+      createToolResultMessage({ callId: ToolCallId('a'), content: [reasoning, call('nested-call'), { type: 'text', text: '  result\n' }], isError: true }),
+      result('b', [reasoning, call('another-nested-call')]),
+    ]
+    const saved = JSON.stringify(history)
+
+    expect(body(history).messages).toEqual([
+      { role: 'assistant', content: [
+        { type: 'thinking', thinking: 'tool reasoning' },
+        ...['a', 'b'].map(id => ({ type: 'tool_use', id, name: 'read', input: { path: 'a' } })),
+      ] },
+      { role: 'user', content: [
+        { type: 'tool_result', tool_use_id: 'a', content: [{ type: 'text', text: '  result\n' }], is_error: true },
+        { type: 'tool_result', tool_use_id: 'b', content: [], is_error: false },
+      ] },
+    ])
+    expect(JSON.stringify(history)).toBe(saved)
+  })
+
+  it.each([
+    [], [{ type: 'reasoning', text: 'child reasoning' }], [call('child-call')],
+  ] satisfies ContentBlock[][])('omits empty user input after conversion %#', (...content) => {
+    const empty = createMessage({ role: 'user', source: { kind: 'user' }, content })
+    expect(body([empty, user(), assistant([{ type: 'text', text: 'answer' }]), empty]).messages).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'answer' }] },
+    ])
+  })
+
+  it('collects leading system text and maps tools, stop sequences and explicit output cap', () => {
+    const system = createMessage({ role: 'system', source: { kind: 'system-prompt' }, content: [{ type: 'text', text: 'instructions' }] })
+    expect(body([system, user()], { system: 'top', maxTokens: 123, stop: ['END'], tools: [{ name: 'read', description: 'Read a file', parameters: { type: 'object' } }] })).toMatchObject({
+      system: 'top\n\ninstructions', max_tokens: 123, stop_sequences: ['END'], tools: [{ name: 'read', description: 'Read a file', input_schema: { type: 'object' } }],
+    })
+    expect(body([user(), system]).system).toBe('instructions')
+  })
+
+  it('uses the latest complete system snapshot without changing tool history or durable messages', () => {
+    const conversation = [user(), assistant([call()]), result(), assistant([{ type: 'text', text: 'done' }]), user('continue')]
+    const history = [createSystemMessage('obsolete'), ...conversation.slice(0, 2),
+      createSystemMessage('intermediate'), ...conversation.slice(2, 4),
+      createSystemMessage('current'), conversation[4]!]
+    const saved = JSON.stringify(history)
+    expect(body(history)).toEqual({ ...body(conversation), system: 'current' })
+    expect(body(history, { system: 'one-shot prefix' }).system).toBe('one-shot prefix\n\ncurrent')
+    expect(JSON.stringify(history)).toBe(saved)
+  })
+
+  it('replaces adjacent system snapshots and joins blocks only within the current snapshot', () => {
+    const latest = createMessage({ role: 'system', source: { kind: 'system-prompt' },
+      content: [{ type: 'text', text: 'part one' }, { type: 'text', text: ' and part two' }] })
+    expect(body([createSystemMessage('old'), latest, user()]).system).toBe('part one and part two')
+  })
+
+  it.each([[], [{ type: 'text' as const, text: '' }]].map(content => ({ content })))('clears earlier prompt snapshots with empty content %#', ({ content }) => {
+    const cleared = createMessage({ role: 'system', source: { kind: 'system-prompt' }, content })
+    const history = [createSystemMessage('old'), user(), cleared]
+    expect(body(history).system).toBeUndefined()
+    expect(body(history, { system: 'one-shot prefix' }).system).toBe('one-shot prefix')
+    expect(body(history, { system: '' }).system).toBeUndefined()
+  })
+
+  it('rejects non-text system content even when a later snapshot supersedes it', () => {
+    const invalid = createMessage({ role: 'system', source: { kind: 'system-prompt' }, content: [{ type: 'reasoning', text: 'bad' }] })
+    expect(() => body([invalid, user(), createSystemMessage('current')])).toThrow(/non-text system/)
+  })
+
+  it.each(['off', 'low', 'high', 'max'])('maps reasoning effort %s', (effort) => {
+    const request = body([user()], { reasoningEffort: ReasoningEffortId(effort) })
+    expect(request.thinking.type).toBe(effort === 'off' ? 'disabled' : 'enabled')
+    expect(request.output_config).toEqual(effort === 'off' ? undefined : { effort })
+  })
+
+  it('disables thinking for titles, passes temperature with thinking and refuses unsupported effort', () => {
+    expect(body([user()], { purpose: 'session-title', temperature: 0 })).toMatchObject({ thinking: { type: 'disabled' }, temperature: 0 })
+    expect(body([user()], { temperature: 0 })).toMatchObject({ thinking: { type: 'enabled' }, temperature: 0 })
+    expect(() => body([user()], { reasoningEffort: ReasoningEffortId('medium') })).toThrow(/effort/)
+    const disabled = resolveAdapterOptions({ thinking: 'disabled' })
+    expect(serialize(options(), disabled, [user()], new Map(), () => undefined).thinking).toEqual({ type: 'disabled' })
+    expect(() => serialize(options({ reasoningEffort: ReasoningEffortId('high') }), disabled, [user()], new Map(), () => undefined)).toThrow(/effort/)
+    const capped = resolveAdapterOptions({ models: [{ id: MODEL, maxTokens: 321 }] })
+    expect(serialize(options(), capped, [user()], new Map(), () => undefined).max_tokens).toBe(321)
+  })
+
+  it.each([
+    [result()], [assistant([call()])], [assistant([call()]), user()],
+    [assistant([call(), call()]), result()],
+    [assistant([call()]), result(), result()],
+  ])('rejects unmatched or duplicated tool history %#', (...messages) => {
+    expect(() => body(messages)).toThrow(/tool/)
+  })
+
+  it.each(['{', '', '[]', 'null', '42', 'true', '"text"', '{"description":"最快，但"某个说法"没有证据。"}'])('uses empty input for malformed or non-object historical tool arguments %s', (arguments_) => {
+    const message = assistant([{ type: 'tool-call', id: ToolCallId('a'), name: 'read', arguments: arguments_ }])
+    const history = [user(), message, createToolResultMessage({ callId: ToolCallId('a'), content: [{ type: 'text', text: 'Invalid arguments' }], isError: true }), user('Continue')]
+    const saved = JSON.stringify(history)
+    const restored = JSON.parse(saved) as Message[]
+    expect(body(restored).messages).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      { role: 'assistant', content: [{ type: 'tool_use', id: 'a', name: 'read', input: {} }] },
+      { role: 'user', content: [
+        { type: 'tool_result', tool_use_id: 'a', content: [{ type: 'text', text: 'Invalid arguments' }], is_error: true },
+        { type: 'text', text: 'Continue' },
+      ] },
+    ])
+    expect(JSON.stringify(restored)).toBe(saved)
+  })
+
+  it('preserves own signed thinking, omits absent signatures and validates durable metadata', () => {
+    const content: ContentBlock[] = [{ type: 'reasoning', text: '' }, { type: 'text', text: 'answer' }]
+    const source = { provider: 'deepseek-official', model: MODEL, replayState: replayState(MODEL, [{ type: 'reasoning', signature: 'signed' }, { type: 'text' }]) }
+    const message = createAssistantMessage({ content, source })
+    expect(body([user(), message, user()]).messages[1]?.content).toEqual([{ type: 'thinking', thinking: '', signature: 'signed' }, { type: 'text', text: 'answer' }])
+    expect(body([assistant([{ type: 'reasoning', text: 'foreign thought' }])]).messages[0]?.content).toEqual([{ type: 'thinking', thinking: 'foreign thought' }])
+    expect(readReplay(message, 'different-model')).toBeUndefined()
+    expect(readReplay(user(), MODEL)).toBeUndefined()
+  })
+
+  it.each([
+    null,
+    [],
+    { response: null, blocks: [] },
+    { response: { kind: 'other', version: 1 }, blocks: [] },
+    { response: { kind: 'deepseek-messages', version: 2 }, blocks: [] },
+    { response: { kind: 'deepseek-messages', version: 1, model: 'wrong' }, blocks: [] },
+    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [] },
+    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: null },
+    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [null] },
+    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [{ type: 'tool-call' }] },
+    { response: { kind: 'deepseek-messages', version: 1, model: MODEL }, blocks: [{ type: 'reasoning', signature: 3 }] },
+  ].map(state => ({ state })))('degrades unusable replay state with a diagnostic %#', ({ state }) => {
+    const message = createAssistantMessage({ content: [{ type: 'reasoning', text: 'think' }], source: { provider: 'deepseek-official', model: MODEL, replayState: state } })
+    const onDegrade = vi.fn()
+    expect(readReplay(message, MODEL, onDegrade)).toBeUndefined()
+    expect(onDegrade).toHaveBeenCalledExactlyOnceWith(expect.any(String))
+    expect(body([message]).messages[0]?.content).toEqual([{ type: 'thinking', thinking: 'think' }])
+  })
+
+  it.each([MODEL, 'different-model'])('keeps durable content when replay degrades for %s', async (model) => {
+    const message = createAssistantMessage({
+      content: [{ type: 'reasoning', text: 'Read the file.' }, { type: 'text', text: 'Checking a.' }, call()],
+      source: { provider: 'deepseek-official', model: MODEL, replayState: replayState(MODEL, [
+        { type: 'reasoning', signature: 'do-not-send' }, { type: 'text', signature: 'invalid-for-text' }, { type: 'tool-call' },
+      ]) },
+    })
+    const saved = JSON.stringify(message)
+    const restored = JSON.parse(saved) as Message
+    const messages = [user(), restored, result()]
+    const onDegrade = vi.fn()
+    const request = serialize(options({ model }), connection, messages, new Map(), () => undefined, onDegrade)
+    expect(onDegrade).toHaveBeenCalledExactlyOnceWith('DeepSeek Messages replay: invalid signature')
+    await expect(JSON.stringify(request.messages, null, 2) + '\n').toMatchFileSnapshot('expected/degraded-replay.json')
+    expect(JSON.stringify(restored)).toBe(saved)
+  })
+
+  it('keeps valid cross-model and foreign history quiet and propagates diagnostic failures', () => {
+    const onDegrade = vi.fn()
+    const message = createAssistantMessage({ content: [{ type: 'reasoning', text: 'think' }], source: {
+      provider: 'deepseek-official', model: MODEL, replayState: replayState(MODEL, [{ type: 'reasoning', signature: '' }]),
+    } })
+    expect(readReplay(message, MODEL, onDegrade)).toEqual([{ type: 'reasoning', signature: '' }])
+    expect(readReplay(message, 'different-model', onDegrade)).toBeUndefined()
+    expect(readReplay(assistant([{ type: 'text', text: 'foreign' }]), MODEL, onDegrade)).toBeUndefined()
+    expect(onDegrade).not.toHaveBeenCalled()
+    const damaged = { ...message, source: { ...message.source, replayState: { response: {}, blocks: [] } } }
+    const failure = new Error('diagnostic failed')
+    expect(() => readReplay(damaged, MODEL, () => { throw failure })).toThrow(failure)
+  })
+
+  it.each([1, 2])('uses empty historical tool input with replay version %s', (version) => {
+    const message = createAssistantMessage({ content: [{ type: 'tool-call', id: ToolCallId('a'), name: 'read', arguments: '{' }], source: {
+      provider: 'deepseek-official', model: MODEL, replayState: { response: { kind: 'deepseek-messages', version, model: MODEL }, blocks: [{ type: 'tool-call' }] },
+    } })
+    const saved = JSON.stringify(message)
+    const onDegrade = vi.fn()
+    const request = serialize(options(), connection, [message, result()], new Map(), () => undefined, onDegrade)
+    expect(request.messages[0]?.content).toEqual([{ type: 'tool_use', id: 'a', name: 'read', input: {} }])
+    expect(onDegrade).toHaveBeenCalledTimes(version === 1 ? 0 : 1)
+    expect(JSON.stringify(message)).toBe(saved)
   })
 })
 
-describe('serializeRequest', () => {
-  const history: Message[] = [createUserMessage({
-    content: [{ type: 'text', text: 'hi' }],
-    source: { kind: 'test' },
-  })]
+describe('validated configuration', () => {
+  it('advertises exact model metadata and allows unlisted text models', () => {
+    expect(modelInfo(connection, 'deepseek-official', MODEL)).toMatchObject({ context: { contextWindow: 1_000_000 }, defaultMaxTokens: 256_000, reasoning: { defaultEffort: 'high' } })
+    expect(modelInfo(connection, 'deepseek-official', 'custom').inputModalities).toEqual(['text'])
+    expect(modelInfo(connection, 'deepseek-official', MODEL).systemPromptUpdate).toBeUndefined()
+    expect(modelInfo(connection, 'deepseek-official', 'custom').systemPromptUpdate).toBeUndefined()
+    expect(modelInfo(capable, 'deepseek-official', MODEL).systemPromptUpdate).toBe('in-history')
+    expect(modelInfo(capable, 'deepseek-official', 'custom').systemPromptUpdate).toBeUndefined()
+    expect(modelInfo(resolveAdapterOptions({ thinking: 'disabled' }), 'deepseek-official', MODEL).reasoning?.efforts).toMatchObject([{ id: 'off', name: 'Off' }])
+    expect(resolveAdapterOptions({ baseURL: 'https://example.com/anthropic///' }).baseURL).toBe('https://example.com/anthropic///')
+  })
+  it.each([
+    { thinking: 'disabled', reasoningEffort: 'high' }, { models: [{ id: '' }] },
+    { models: [{ id: 'a' }, { id: 'a' }] }, { models: [{ id: 'a', name: '' }] },
+    { maxInlineRequestImageBytes: 1 }, { maxImagesPerRequest: 1 },
+    { baseURL: 'ftp://example.com' }, { baseURL: 'https://user:pass@example.com' },
+    { baseURL: 'https://example.com/?key=x' }, { baseURL: 'https://example.com/#x' },
+    { maxTokens: 0 }, { streamIdleTimeoutMs: 0 },
+    { models: [{ id: MODEL, systemPromptUpdate: 'unsupported' }] },
+  ])('rejects invalid composition input %#', (value) => {
+    expect(() => resolveAdapterOptions(value as Config)).toThrow()
+  })
+})
 
-  it('always streams with usage and maps the basics', () => {
-    const wire = serializeRequest(request({ messages: history }))
-    expect(wire).toEqual({
-      model: 'deepseek-v4-flash',
-      messages: [{ role: 'user', content: 'hi' }],
-      stream: true,
-      stream_options: { include_usage: true },
+describe('Messages images', () => {
+  const ref: ImageAttachmentRef = { attachmentId: AttachmentId(`sha256:${'a'.repeat(64)}`), mediaType: 'image/png', width: 1, height: 1, bytes: 3 }
+  const image: ImageBlock = { type: 'image', attachment: ref }
+  const version: RequestImageAttachment = { attachment: ref, variantId: ImageVariantId(`sha256:${'b'.repeat(64)}`), mediaType: 'image/png', bytes: 3, data: Uint8Array.of(1, 2, 3), width: 1, height: 1, depth: 'uchar', space: 'srgb', hasAlpha: false }
+  const access = () => ({ readonlyPath: '/workspace/image.png' })
+  const model = 'deepseek-flash'
+  // Only the read operation is consumed by image preparation; the transport is mocked, not durable content.
+  const attachments = requestImageStore(async () => version)
+  const signal = new AbortController().signal
+  it('keeps image bytes inside tool results and deduplicates normalization', async () => {
+    const history = [assistant([call()]), result('a', [image, image])]
+    const prepared = await prepareImages(history, connection, model, attachments, access, signal)
+    expect(prepared.versions.size).toBe(1)
+    const request = serialize(options({ model }), connection, prepared.messages, prepared.versions, access)
+    expect(request.messages[1]?.content[0]).toMatchObject({ type: 'tool_result', content: [
+      { type: 'text', text: expect.stringContaining('/workspace/image.png') as string }, { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'AQID' } },
+      { type: 'text' }, { type: 'image' },
+    ] })
+    expect(imagePricing(connection, model, access).priceImages([image])[0]?.visualTokens).toBeGreaterThan(0)
+    expect(imagePricing(connection, MODEL, access).priceImages([image])[0]?.visualTokens).toBe(0)
+  })
+  it('requires logged offload at exact encoded bytes and preserves durable references', async () => {
+    const config = resolveAdapterOptions({
+      maxInlineRequestImageBytes: 4, inlineImageOffloadByteQuantum: 1, maxImagesPerRequest: 2, imageOffloadCountQuantum: 1,
     })
-  })
-
-  it('prepends the system prompt', () => {
-    const wire = serializeRequest(request({ messages: history, system: 'be helpful' }))
-    expect(wire.messages[0]).toEqual({ role: 'system', content: 'be helpful' })
-    expect(wire.messages[1]).toEqual({ role: 'user', content: 'hi' })
-  })
-
-  it('serializes a leading system message byte-for-byte like the same prompt passed as options.system', async () => {
-    const systemMessage = createMessage({
-      role: 'system',
-      content: [{ type: 'text', text: 'be helpful' }],
-      source: { kind: 'system-prompt' },
-    })
-    const tools = [{ name: 'f', description: 'F', parameters: { type: 'object', properties: {} } }]
-    const fromHistory = serializeRequest(request({ messages: [systemMessage, ...history], tools }))
-    const fromOption = serializeRequest(request({ messages: history, system: 'be helpful', tools }))
-    expect(fromHistory.messages[0]).toEqual({ role: 'system', content: 'be helpful' })
-    expect(JSON.stringify(fromHistory)).toBe(JSON.stringify(fromOption))
-    const images = imageOptions([])
-    const imageHistory = await serializeRequestWithImages(request({ messages: [systemMessage, ...history], tools }), images)
-    const imageOption = await serializeRequestWithImages(request({ messages: history, system: 'be helpful', tools }), images)
-    expect(JSON.stringify(imageHistory)).toBe(JSON.stringify(imageOption))
-  })
-
-  it('maps sampling params and stop sequences', () => {
-    const wire = serializeRequest(request({ messages: history, temperature: 0.2, maxTokens: 100, stop: ['END'] }))
-    expect(wire.temperature).toBe(0.2)
-    expect(wire.max_tokens).toBe(100)
-    expect(wire.stop).toEqual(['END'])
-  })
-
-  it('maps tools to the wire function shape', () => {
-    const wire = serializeRequest(request({
-      messages: history,
-      tools: [
-        { name: 'a', description: 'A', parameters: { type: 'object', properties: {} } },
-        { name: 'b', description: 'B', parameters: { type: 'object', properties: { x: { type: 'string' } } } },
-      ],
+    const offloadFailure: unknown = expect.objectContaining({ code: 'IMAGE_OFFLOAD_REQUIRED', offloadImages: 1 })
+    const history = [result('a', [image, image])]
+    const prepared = await prepareImages(history, config, model, attachments, access, signal)
+    expect(prepared.messages[0]?.content).toMatchObject([image, image])
+    expect(() => inlineImages(prepared.messages, prepared.versions, config)).toThrow(expect.objectContaining({
+      failure: offloadFailure,
+    }))
+    const offloaded: ImageBlock = { ...image, offloaded: true }
+    const retry = await prepareImages([result('a', [offloaded, image])], config, model, attachments, access, signal)
+    expect(inlineImages(retry.messages, retry.versions, config)[0]?.content).toMatchObject([{ type: 'text' }, { type: 'image' }])
+    expect(history[0]?.content).toMatchObject([image, image])
+    expect(imagePricing(config, model, access).priceImages([image, image]).map(entry => entry.visualTokens))
+      .toEqual([expect.any(Number), expect.any(Number)])
+    const large = requestImageStore(async () => ({ ...version, bytes: 30, data: new Uint8Array(30) }))
+    const exact = await prepareImages([result('a', [image])], config, model, large, access, signal)
+    expect(() => inlineImages(exact.messages, exact.versions, config)).toThrow(expect.objectContaining({
+      failure: offloadFailure,
     }))
-    expect(wire.tools).toEqual([
-      { type: 'function', function: { name: 'a', description: 'A', parameters: { type: 'object', properties: {} } } },
-      { type: 'function', function: { name: 'b', description: 'B', parameters: { type: 'object', properties: { x: { type: 'string' } } } } },
-    ])
   })
-
-  it('omits an empty tools array', () => {
-    const wire = serializeRequest(request({ messages: history, tools: [] }))
-    expect(wire.tools).toBeUndefined()
-  })
-
-  it.each(['low', 'high', 'max'] as const)('maps adapter-default thinking and request effort %s', (effort) => {
-    const wire = serializeRequest(
-      request({ messages: history, reasoningEffort: ReasoningEffortId(effort) }),
-      { thinking: 'enabled', reasoningEffort: 'high' },
-    )
-    expect(wire.thinking).toEqual({ type: 'enabled' })
-    expect(wire.reasoning_effort).toBe(effort)
-  })
-
-  it('maps off to disabled thinking without a wire reasoning effort', () => {
-    const wire = serializeRequest(
-      request({ messages: history, reasoningEffort: ReasoningEffortId('off') }),
-      { thinking: 'enabled', reasoningEffort: 'max' },
-    )
-    expect(wire.thinking).toEqual({ type: 'disabled' })
-    expect(wire.reasoning_effort).toBeUndefined()
-  })
-
-  it('re-enables thinking when max overrides an off default', () => {
-    const wire = serializeRequest(
-      request({ messages: history, reasoningEffort: ReasoningEffortId('max') }),
-      { reasoningEffort: 'off' },
-    )
-    expect(wire.thinking).toEqual({ type: 'enabled' })
-    expect(wire.reasoning_effort).toBe('max')
-  })
-
-  it('rejects enabling thinking when the deployment is locked to disabled', () => {
-    expect(() => serializeRequest(
-      request({ messages: history, reasoningEffort: ReasoningEffortId('high') }),
-      { thinking: 'disabled' },
-    )).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_REASONING_EFFORT' }))
-  })
-
-  it('disables thinking for session-title requests without changing adapter defaults', () => {
-    const wire = serializeRequest(
-      request({
-        messages: history,
-        purpose: 'session-title',
-        reasoningEffort: ReasoningEffortId('max'),
-      }),
-      { thinking: 'enabled', reasoningEffort: 'max' },
-    )
-    expect(wire.thinking).toEqual({ type: 'disabled' })
-    expect(wire.reasoning_effort).toBeUndefined()
-  })
-
-  it('omits thinking fields when unset (provider default applies)', () => {
-    const wire = serializeRequest(request({ messages: history }))
-    expect(wire.thinking).toBeUndefined()
-    expect(wire.reasoning_effort).toBeUndefined()
-  })
-
-  it('preserves an explicit enabled default without inventing a wire effort', () => {
-    const wire = serializeRequest(request({ messages: history }), { thinking: 'enabled' })
-    expect(wire.thinking).toEqual({ type: 'enabled' })
-    expect(wire.reasoning_effort).toBeUndefined()
-  })
-
-  it('rejects an effort outside the DeepSeek capability', () => {
-    expect(() => serializeRequest(request({
-      messages: history,
-      reasoningEffort: ReasoningEffortId('medium'),
-    }))).toThrow(expect.objectContaining({ code: 'UNSUPPORTED_REASONING_EFFORT' }))
-  })
-})
-
-describe('image serialization', () => {
-  it.each([
-    'image/png',
-    'image/jpeg',
-    'image/webp',
-    'image/gif',
-  ] as const)('preserves ordered text and %s image parts', async (mediaType) => {
-    const resolveFileId = fileResolver()
-    const ref = imageRef(mediaType)
-    const wire = await serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'text', text: 'before' },
-          { type: 'image', attachment: ref },
-          { type: 'text', text: 'after' },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), imageOptions([ref], resolveFileId))
-
-    expect(wire.messages).toEqual([{
-      role: 'user',
-      content: [
-        { type: 'text', text: 'before' },
-        { type: 'text', text: expect.stringContaining(`Image ${ref.attachmentId}; request preview 1x1px`) as string },
-        { type: 'file', file_id: 'file-api-image' },
-        { type: 'text', text: 'after' },
-      ],
-    }])
-  })
-
-  it.each([
-    ['image/png', 'data:image/png;base64,AAAA'],
-    ['image/jpeg', 'data:image/jpeg;base64,AAAA'],
-    ['image/webp', 'data:image/webp;base64,AAAA'],
-    ['image/gif', 'data:image/gif;base64,AAAA'],
-  ] as const)('serializes every retained %s request version as an inline data URL', async (mediaType, url) => {
-    const ref = imageRef(mediaType)
-    const wire = await serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: ref }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), inlineImageOptions([ref]))
-
-    expect(wire.messages).toEqual([{
-      role: 'user',
-      content: [
-        { type: 'text', text: expect.stringContaining(`Image ${ref.attachmentId}; request preview 1x1px`) as string },
-        { type: 'image_url', image_url: { url } },
-      ],
-    }])
-  })
-
-  it('gives image-only input a stable handle and request dimensions', async () => {
-    const ref = imageRef()
-    const wire = await serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: ref }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), imageOptions([ref]))
-
-    expect(wire.messages).toEqual([{
-      role: 'user',
-      content: [
-        {
-          type: 'text',
-          text: `Image ${ref.attachmentId}; request preview 1x1px. It may be resized or re-encoded; source dimensions, format, and byte size may differ.`,
-        },
-        { type: 'file', file_id: 'file-api-image' },
-      ],
-    }])
-  })
-
-  it('includes provider-resolved normalized access in a retained image handle', async () => {
-    const ref = { ...imageRef(), name: 'diagram.png', width: 2048, height: 1024 }
-    const images = imageOptions([ref])
-    const version = images.requestImages.get(ref.attachmentId) as RequestImageAttachment
-    version.width = 1130
-    version.height = 565
-    images.resolveImageAccess = () => ({ readonlyPath: '/tmp/dsh/objects/aa/object' })
-    const wire = await serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: ref }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), images)
-
-    expect(wire.messages[0]).toMatchObject({
-      role: 'user',
-      content: [{
-        type: 'text',
-        text: expect.stringContaining('Image "diagram.png"') as string,
-      }, { type: 'file' }],
-    })
-    expect(JSON.stringify(wire.messages[0])).toContain('/tmp/dsh/objects/aa/object')
-    expect(JSON.stringify(wire.messages[0])).toContain('request preview 1130x565px')
-  })
-
-  it('rejects an image whose prepared request version is absent', async () => {
-    const ref = imageRef()
-    await expect(serializeMessagesWithImages([createUserMessage({
-      content: [{ type: 'image', attachment: ref }],
-      source: { kind: 'test' },
-    })], imageOptions([]))).rejects.toMatchObject({ code: 'INVALID_REQUEST' })
-  })
-
-  it('keeps tool content textual and groups consecutive tool-result images afterward', async () => {
-    const messages = [
-      createToolResultMessage({
-        callId: ToolCallId('first'),
-        content: [{ type: 'image', attachment: imageRef() }],
-        isError: false,
-      }),
-      createToolResultMessage({
-        callId: ToolCallId('second'),
-        content: [
-          { type: 'text', text: 'caption' },
-          { type: 'image', attachment: imageRef('image/jpeg') },
-        ],
-        isError: false,
-      }),
-    ]
-
-    const png = imageRef()
-    const jpeg = imageRef('image/jpeg')
-    await expect(serializeMessagesWithImages(messages, imageOptions(
-      [png, jpeg],
-      vi.fn((version: RequestImageAttachment) => Promise.resolve(`file-api-${version.mediaType}`)),
-    ))).resolves.toEqual([
-      {
-        role: 'tool',
-        tool_call_id: 'first',
-        content: expect.stringContaining(`Image ${png.attachmentId}`) as string,
-      },
-      {
-        role: 'tool',
-        tool_call_id: 'second',
-        content: expect.stringContaining(`caption\nImage ${jpeg.attachmentId}`) as string,
-      },
-      {
-        role: 'user',
-        content: [
-          { type: 'text', text: 'Attached image(s) from tool result:' },
-          { type: 'file', file_id: 'file-api-image/png' },
-          { type: 'file', file_id: 'file-api-image/jpeg' },
-        ],
-      },
-    ])
-  })
-
-  it('keeps an empty user message for ignored content beside a tool message', async () => {
-    const messages = [
-      createUserMessage({
-        content: [
-          { type: 'text', text: '' },
-          { type: 'chart', data: 'ignored' } as unknown as ContentBlock,
-        ],
-        source: { kind: 'test' },
-      }),
-      createToolResultMessage({
-        callId: ToolCallId('result'),
-        content: [{ type: 'text', text: 'ok' }],
-        isError: false,
-      }),
-    ]
-
-    await expect(serializeMessagesWithImages(messages, imageOptions([], fileResolver()))).resolves.toEqual([
-      { role: 'user', content: '' },
-      { role: 'tool', tool_call_id: 'result', content: 'ok' },
-    ])
-  })
-
-  it('converts consecutive tool messages and preserves the empty fallback', async () => {
-    const messages = [
-      createToolResultMessage({
-        callId: ToolCallId('nested'),
-        content: [{ type: 'text', text: 'inside' }],
-        isError: false,
-      }),
-      createToolResultMessage({ callId: ToolCallId('empty'), content: [], isError: false }),
-    ]
-
-    await expect(serializeMessagesWithImages(messages, imageOptions([], fileResolver()))).resolves.toEqual([
-      { role: 'tool', tool_call_id: 'nested', content: 'inside' },
-      { role: 'tool', tool_call_id: 'empty', content: '(no output)' },
-    ])
-  })
-
-  it('flushes tool-result images before system and assistant history', async () => {
-    const imageResult = (id: string) => createToolResultMessage({
-      callId: ToolCallId(id),
-      content: [{ type: 'image', attachment: imageRef() }],
-      isError: false,
-    })
-    const messages = [
-      imageResult('before-system'),
-      createMessage({
-        role: 'system',
-        content: [{ type: 'text', text: 'system history' }],
-        source: { kind: 'system-prompt' },
-      }),
-      imageResult('before-assistant'),
-      createMessage({
-        role: 'assistant',
-        content: [{ type: 'text', text: 'assistant history' }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      }),
-    ]
-
-    const wire = await serializeMessagesWithImages(messages, imageOptions([imageRef()], fileResolver()))
-    expect(wire).toEqual([
-      {
-        role: 'tool',
-        tool_call_id: 'before-system',
-        content: expect.stringContaining('request preview 1x1px') as string,
-      },
-      expect.objectContaining({ role: 'user' }),
-      { role: 'system', content: 'system history' },
-      {
-        role: 'tool',
-        tool_call_id: 'before-assistant',
-        content: expect.stringContaining('request preview 1x1px') as string,
-      },
-      expect.objectContaining({ role: 'user' }),
-      { role: 'assistant', content: 'assistant history' },
-    ])
-  })
-
-  it('projects surface-offloaded occurrences to placeholders without resolving them', async () => {
-    const resolveFileId = fileResolver()
-    const png = imageRef('image/png', 3)
-    const jpeg = imageRef('image/jpeg', 3)
-    const images = imageOptions([png, jpeg], resolveFileId, 4)
-    images.resolveImageAccess = ref => ref.mediaType === 'image/png'
-      ? { readonlyPath: '/tmp/dsh/objects/png' }
-      : undefined
-    const wire = await serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          { type: 'image', attachment: png, offloaded: true },
-          { type: 'image', attachment: jpeg },
-        ],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), images)
-
-    expect(wire.messages[0]).toMatchObject({
-      role: 'user',
-      content: [
-        {
-          type: 'text',
-          text: expect.stringContaining(`image omitted to fit request image limits; ${png.attachmentId}. Normalized copy (read-only; may be resized or re-encoded): "/tmp/dsh/objects/png"`) as string,
-        },
-        { type: 'text', text: expect.stringContaining(`Image ${jpeg.attachmentId}`) as string },
-        { type: 'file', file_id: 'file-api-image' },
-      ],
-    })
-    expect(resolveFileId).toHaveBeenCalledTimes(1)
-    expect(resolveFileId.mock.calls[0]?.[0]).toMatchObject({ attachment: { mediaType: 'image/jpeg' } })
-  })
-  it('rejects retained inline images beyond the bound with the quantized count to offload', async () => {
-    const ref = imageRef('image/png', 3)
-    // 21 retained 3-byte images encode to 84 base64 bytes against an 80-byte bound with a
-    // 40-byte quantum: the removal crosses the quantum at the eleventh oldest occurrence.
-    await expect(serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: Array.from({ length: 21 }, () => ({ type: 'image' as const, attachment: ref })),
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), inlineImageOptions([ref], 80, 40))).rejects.toMatchObject({
-      code: 'IMAGE_OFFLOAD_REQUIRED',
-      failure: { offloadImages: 11 },
-    })
-  })
-
-  it('uses the configured image-count quantum before resolving files', async () => {
-    const ref = imageRef()
-    const resolveFileId = fileResolver()
-    const messages = [createUserMessage({
-      content: Array.from({ length: 3 }, () => ({ type: 'image' as const, attachment: ref })),
-      source: { kind: 'test' },
-    })]
-    await expect(serializeRequestWithImages(request({ messages }), {
-      ...imageOptions([ref], resolveFileId), maxImagesPerRequest: 2, countQuantum: 2,
-    })).rejects.toMatchObject({ code: 'IMAGE_OFFLOAD_REQUIRED', failure: { offloadImages: 2 } })
-    expect(resolveFileId).not.toHaveBeenCalled()
-  })
-
-  it('counts only retained occurrences against the bound', async () => {
-    const ref = imageRef('image/png', 3)
-    const wire = await serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [
-          ...Array.from({ length: 11 }, () => ({ type: 'image' as const, attachment: ref, offloaded: true as const })),
-          ...Array.from({ length: 10 }, () => ({ type: 'image' as const, attachment: ref })),
-        ],
-        source: { kind: 'test' },
-      })],
-    }), inlineImageOptions([ref], 80, 40))
-    const content = wire.messages[0]?.content
-    expect(JSON.stringify(content).match(/image omitted to fit request image limits/g)).toHaveLength(11)
-    expect(JSON.stringify(content).match(/"type":"image_url"/g)).toHaveLength(10)
-  })
-  it('rejects an unprepared image while computing exact request bytes', async () => {
-    const ref = imageRef()
-    await expect(serializeRequestWithImages(request({
-      model: 'deepseek-v4-flash-vision-exp',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: ref }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), imageOptions([]))).rejects.toMatchObject({ code: 'INVALID_REQUEST' })
-  })
-
-  it.each(['system', 'assistant'] as const)('rejects an image in %s history before reading attachments', async (role) => {
-    const resolveFileId = vi.fn()
-    const content: ContentBlock[] = [{ type: 'image', attachment: imageRef() }]
-    const message = role === 'system'
-      ? createMessage({ role, content, source: { kind: 'system-prompt' } })
-      : createMessage({ role, content, source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' } })
-    await expect(serializeMessagesWithImages([message], imageOptions([imageRef()], resolveFileId)))
-      .rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-    expect(resolveFileId).not.toHaveBeenCalled()
-  })
-
-  it('rejects developer history on text and image paths before reading attachments', async () => {
-    const resolveFileId = fileResolver()
-    const message = createDeveloperMessage({
-      content: [{ type: 'tool-addition', toolName: 'search' }],
-      source: { kind: 'test' },
-    })
-    const failure = { code: 'UNSUPPORTED_CONTENT', message: 'Developer messages are not supported yet' }
-    expect(() => serializeMessages([message])).toThrow(expect.objectContaining(failure))
-    await expect(serializeMessagesWithImages([message], imageOptions([], resolveFileId)))
-      .rejects.toMatchObject(failure)
-    await expect(serializeRequestWithImages(request({ messages: [message] }), imageOptions([], resolveFileId)))
-      .rejects.toMatchObject(failure)
-    expect(resolveFileId).not.toHaveBeenCalled()
-  })
-
-  it('rejects unsupported image history before request offloading can replace it', async () => {
-    const resolveFileId = vi.fn()
-    await expect(serializeRequestWithImages(request({
-      messages: [createMessage({
-        role: 'system',
-        content: [{ type: 'image', attachment: imageRef('image/png', 300) }],
-        source: { kind: 'system-prompt' },
-      })],
-    }), imageOptions([imageRef('image/png', 300)], resolveFileId, 1)))
-      .rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
-    expect(resolveFileId).not.toHaveBeenCalled()
-  })
-
-  it('prepends the request system prompt on the image path', async () => {
-    const ref = imageRef()
-    const wire = await serializeRequestWithImages(request({
-      system: 'system prompt',
-      messages: [createUserMessage({
-        content: [{ type: 'image', attachment: ref }],
-        source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })],
-    }), imageOptions([ref]))
-    expect(wire.messages[0]).toEqual({ role: 'system', content: 'system prompt' })
-  })
-
-  it('preserves stable file-resolution failure codes', async () => {
-    const failure = new Error('Stored attachment bytes are corrupt.') as Error & { code: string }
-    failure.code = 'ATTACHMENT_CORRUPT'
-    const resolveFileId = vi.fn(() => Promise.reject(failure))
-    await expect(serializeMessagesWithImages([createUserMessage({
-      content: [{ type: 'image', attachment: imageRef() }],
-      source: { kind: 'test' },
-    })], imageOptions([imageRef()], resolveFileId)))
-      .rejects.toMatchObject({ code: 'ATTACHMENT_CORRUPT' })
-  })
-
-  it('preserves non-attachment resolver failures', async () => {
-    const failure = new Error('resolver failed')
-    const resolveFileId = vi.fn(() => Promise.reject(failure))
-    await expect(serializeMessagesWithImages([createUserMessage({
-      content: [{ type: 'image', attachment: imageRef() }],
-      source: { kind: 'test' },
-    })], imageOptions([imageRef()], resolveFileId))).rejects.toBe(failure)
-  })
-})
-
-describe('review fixes: assistant content shapes', () => {
-  it('serializes a content-less, tool-call-less assistant message as "" content, never null', () => {
-    // Aborted/empty assistant turns: no text, no calls → "". The earlier
-    // null shape was live-falsified: the API 400s a null-content assistant
-    // message without tool_calls ("content or tool_calls must be set").
-    const wire = serializeMessages([createMessage({
-      role: 'assistant', content: [],
-      source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-    })])
-    expect(wire).toEqual([{ role: 'assistant', content: '' }])
-  })
-
-  it('serializes a reasoning-ONLY assistant message as "" content beside its reasoning', () => {
-    // The model can answer entirely in the reasoning channel (a v4-flash
-    // greeting did, live). Content must still be SET — a null here poisoned
-    // the session log and bricked every later turn of that session.
-    const wire = serializeMessages([createMessage({
-      role: 'assistant', content: [{ type: 'reasoning', text: '你好！有什么我可以帮你的吗？' }],
-      source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-    })])
-    expect(wire).toEqual([{
-      role: 'assistant', content: '', reasoning_content: '你好！有什么我可以帮你的吗？',
-    }])
-  })
-
-  it('serializes tool-call turns with empty string content, not null', () => {
-    const wire = serializeMessages([createMessage({
-      role: 'assistant',
-      content: [{ type: 'tool-call', id: ToolCallId('c'), name: 'f', arguments: '{}' }],
-      source: { kind: 'model', provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-    })])
-    expect(wire[0]).toMatchObject({ content: '' })
+  it('rejects unsupported roles and unavailable image capabilities before HTTP', async () => {
+    const history = [result('a', [image])]
+    await expect(prepareImages(history, connection, MODEL, attachments, access, signal)).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
+    await expect(prepareImages(history, connection, model, undefined, access, signal)).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
+    await expect(prepareImages([assistant([image])], connection, model, attachments, access, signal)).rejects.toMatchObject({ code: 'UNSUPPORTED_CONTENT' })
+    expect(() => body([result('a', [image])])).toThrow(/image/)
+    expect(() => body([assistant([image])])).toThrow(/assistant/)
+    // @ts-expect-error -- malformed provider input can carry a retired nested result block.
+    expect(() => body([result('a', [{ type: 'tool-result', toolCallId: ToolCallId('nested'), content: [] }])]))
+      .toThrow(/user\/tool-result content tool-result/)
+    expect(() => serialize(options({ model }), connection, [result('a', [image])], new Map([[ref.attachmentId, version]]), access, undefined, new Map()))
+      .toThrow(/request file id is missing/)
   })
 })
diff --git a/packages/llm/llm-deepseek/tests/sse.spec.ts b/packages/llm/llm-deepseek/tests/sse.spec.ts
deleted file mode 100644
index bdf1508c60..0000000000
--- a/packages/llm/llm-deepseek/tests/sse.spec.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { LlmError } from '@deepseek-ai/dsh-llm'
-import { DONE, parseSse } from '../src/protocols/chat-completions/sse.ts'
-
-/**
- * DeepSeek protocol contract only: the [DONE] sentinel and STREAM_CLOSED on
- * EOF without it. SSE framing (chunk splits, CRLF, multi-data joins, comments)
- * is eventsource-parser's contract, not re-proven here.
- */
-
-/** Build an SSE byte stream from string fragments (fragments = network reads). */
-function bytes(...fragments: string[]): ReadableStream<Uint8Array<ArrayBuffer>> {
-  const encoder = new TextEncoder()
-  return new ReadableStream({
-    start(controller) {
-      for (const fragment of fragments) controller.enqueue(encoder.encode(fragment))
-      controller.close()
-    },
-  })
-}
-
-async function collect(stream: AsyncIterable<string>): Promise<string[]> {
-  const out: string[] = []
-  for await (const item of stream) out.push(item)
-  return out
-}
-
-describe('parseSse', () => {
-  it('yields event payloads and the DONE sentinel', async () => {
-    const events = await collect(parseSse(bytes('data: {"a":1}\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('reports comments out of band without yielding them', async () => {
-    const comments: string[] = []
-    const events = await collect(parseSse(
-      bytes(': keep-alive\n\ndata: {"a":1}\n\ndata: [DONE]\n\n'),
-      (comment) => { comments.push(comment) },
-    ))
-    expect(comments).toEqual(['keep-alive'])
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('stops yielding after DONE even when more data follows', async () => {
-    const events = await collect(parseSse(bytes('data: [DONE]\n\ndata: {"late":1}\n\n')))
-    expect(events).toEqual([DONE])
-  })
-
-  it('throws STREAM_CLOSED when the stream ends without DONE', async () => {
-    await expect(collect(parseSse(bytes('data: {"a":1}\n\n')))).rejects.toThrow(LlmError)
-    await expect(collect(parseSse(bytes('data: {"a":1}\n\n')))).rejects.toThrow(/without \[DONE\]/)
-  })
-
-  it('throws STREAM_CLOSED for an empty stream', async () => {
-    await expect(collect(parseSse(bytes()))).rejects.toThrow(/without \[DONE\]/)
-  })
-
-  it('throws STREAM_CLOSED for a mid-event close', async () => {
-    await expect(collect(parseSse(bytes('data: {"a"')))).rejects.toThrow(/without \[DONE\]/)
-  })
-
-  it('treats a final DONE missing its blank-line terminator as truncation', async () => {
-    // Spec-strict framing: an event dispatches only on its blank-line
-    // terminator, so an unterminated tail at EOF is STREAM_CLOSED — real
-    // providers always terminate events, so a missing terminator is truncation.
-    await expect(collect(parseSse(bytes('data: {"a":1}\n\ndata: [DONE]')))).rejects.toThrow(/without \[DONE\]/)
-  })
-})
diff --git a/packages/llm/llm-deepseek/tests/messages/stream.spec.ts b/packages/llm/llm-deepseek/tests/stream.spec.ts
similarity index 97%
rename from packages/llm/llm-deepseek/tests/messages/stream.spec.ts
rename to packages/llm/llm-deepseek/tests/stream.spec.ts
index 51d54beef0..aa86d48404 100644
--- a/packages/llm/llm-deepseek/tests/messages/stream.spec.ts
+++ b/packages/llm/llm-deepseek/tests/stream.spec.ts
@@ -1,8 +1,8 @@
 /** Protocol invariants at JSON/SSE boundaries, including partial and failed responses. */
 import { describe, expect, it } from 'vitest'
-import { translate } from '../../src/protocols/messages/translate.ts'
-import { parseSse } from '../../src/protocols/messages/sse.ts'
-import { providerError } from '../../src/protocols/messages/transport.ts'
+import { translate } from '../src/translate.ts'
+import { parseSse } from '../src/sse.ts'
+import { providerError } from '../src/transport.ts'
 import { assemble, chunks, end, events, MODEL, sse, start, textEvents } from './helpers.ts'
 
 describe('Messages stream', () => {
diff --git a/packages/llm/llm-deepseek/tests/translate.spec.ts b/packages/llm/llm-deepseek/tests/translate.spec.ts
deleted file mode 100644
index 5e19f0c94f..0000000000
--- a/packages/llm/llm-deepseek/tests/translate.spec.ts
+++ /dev/null
@@ -1,446 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { BlockAssembler, EMPTY_RESPONSE_CODE, LlmError } from '@deepseek-ai/dsh-llm'
-import type { StreamChunk } from '@deepseek-ai/dsh-llm'
-import { DONE } from '../src/protocols/chat-completions/sse.ts'
-import { mapFinishReason, mapUsage, translate } from '../src/protocols/chat-completions/translate.ts'
-
-async function* feed(...payloads: (string | object)[]): AsyncGenerator<string> {
-  for (const payload of payloads) {
-    yield typeof payload === 'string' ? payload : JSON.stringify(payload)
-  }
-}
-
-async function collect(stream: AsyncIterable<StreamChunk>): Promise<StreamChunk[]> {
-  const out: StreamChunk[] = []
-  for await (const chunk of stream) out.push(chunk)
-  return out
-}
-
-/** The live first-chunk signature: role + null content + EMPTY reasoning. */
-const firstChunk = { choices: [{ delta: { role: 'assistant', content: null, reasoning_content: '' } }] }
-
-describe('translate: text', () => {
-  it('streams a text block and defers finish to DONE', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: 'Hel' } }] },
-      { choices: [{ delta: { content: 'lo' } }] },
-      { choices: [{ delta: { content: '' }, finish_reason: 'stop' }], usage: { prompt_tokens: 5, completion_tokens: 2 } },
-      DONE,
-    )))
-    expect(chunks).toEqual([
-      { type: 'block-start', index: 0, blockType: 'text' },
-      { type: 'text-delta', index: 0, text: 'Hel' },
-      { type: 'text-delta', index: 0, text: 'lo' },
-      { type: 'block-end', index: 0, block: { type: 'text', text: 'Hello' } },
-      { type: 'usage', usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } },
-      { type: 'finish', reason: { kind: 'stop' } },
-    ])
-  })
-
-  it('assembles into the message BlockAssembler expects', async () => {
-    const assembler = new BlockAssembler()
-    for await (const chunk of translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: 'hi' } }] },
-      { choices: [{ delta: {}, finish_reason: 'stop' }] },
-      DONE,
-    ))) {
-      assembler.push(chunk)
-    }
-    const result = { message: assembler.message({ provider: 'mock', model: 'mock' }), finish: assembler.finish }
-    expect(result.message.content).toEqual([{ type: 'text', text: 'hi' }])
-    expect(result.finish).toEqual({ kind: 'stop' })
-  })
-})
-
-describe('translate: reasoning', () => {
-  it('does NOT open a reasoning block for the empty first-chunk signature', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: 'plain' } }] },
-      { choices: [{ delta: {}, finish_reason: 'stop' }] },
-      DONE,
-    )))
-    expect(chunks.some(chunk => chunk.type === 'block-start' && chunk.blockType === 'reasoning')).toBe(false)
-  })
-
-  it('streams reasoning then text as separate blocks', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: null, reasoning_content: 'think' } }] },
-      { choices: [{ delta: { content: null, reasoning_content: 'ing' } }] },
-      { choices: [{ delta: { content: 'answer', reasoning_content: null } }] },
-      { choices: [{ delta: {}, finish_reason: 'stop' }] },
-      DONE,
-    )))
-    expect(chunks).toEqual([
-      { type: 'block-start', index: 0, blockType: 'reasoning' },
-      { type: 'reasoning-delta', index: 0, text: 'think' },
-      { type: 'reasoning-delta', index: 0, text: 'ing' },
-      { type: 'block-start', index: 1, blockType: 'text' },
-      { type: 'text-delta', index: 1, text: 'answer' },
-      { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'thinking' } },
-      { type: 'block-end', index: 1, block: { type: 'text', text: 'answer' } },
-      { type: 'finish', reason: { kind: 'stop' } },
-    ])
-  })
-
-  it('treats an entirely absent reasoning_content field as non-thinking', async () => {
-    const chunks = await collect(translate(feed(
-      { choices: [{ delta: { role: 'assistant', content: 'x' } }] },
-      { choices: [{ delta: {}, finish_reason: 'stop' }] },
-      DONE,
-    )))
-    expect(chunks.filter(chunk => chunk.type === 'block-start')).toEqual([
-      { type: 'block-start', index: 0, blockType: 'text' },
-    ])
-  })
-})
-
-describe('translate: tool calls', () => {
-  it('reassembles a tool call from fragmented argument deltas (live capture shape)', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_00_x', type: 'function', function: { name: 'get_weather', arguments: '' } }] } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: '{"city"' } }] } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: ': "Paris"}' } }] } }] },
-      { choices: [{ delta: { content: '' }, finish_reason: 'tool_calls' }], usage: { prompt_tokens: 28, completion_tokens: 6 } },
-      DONE,
-    )))
-    expect(chunks).toEqual([
-      { type: 'block-start', index: 0, blockType: 'tool-call' },
-      { type: 'tool-call-delta', index: 0, id: 'call_00_x', name: 'get_weather', argumentsDelta: '' },
-      { type: 'tool-call-delta', index: 0, id: 'call_00_x', name: 'get_weather', argumentsDelta: '{"city"' },
-      { type: 'tool-call-delta', index: 0, id: 'call_00_x', name: 'get_weather', argumentsDelta: ': "Paris"}' },
-      {
-        type: 'block-end',
-        index: 0,
-        block: { type: 'tool-call', id: 'call_00_x', name: 'get_weather', arguments: '{"city": "Paris"}' },
-      },
-      { type: 'usage', usage: { inputTokens: 28, outputTokens: 6, totalTokens: 34 } },
-      { type: 'finish', reason: { kind: 'tool-calls' } },
-    ])
-  })
-
-  it('disambiguates parallel tool calls by wire index', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      {
-        choices: [{
-          delta: {
-            tool_calls: [
-              { index: 0, id: 'a', type: 'function', function: { name: 'one', arguments: '{}' } },
-              { index: 1, id: 'b', type: 'function', function: { name: 'two', arguments: '' } },
-            ],
-          },
-        }],
-      },
-      { choices: [{ delta: { tool_calls: [{ index: 1, function: { arguments: '{}' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    const ends = chunks.filter(chunk => chunk.type === 'block-end')
-    expect(ends).toEqual([
-      { type: 'block-end', index: 0, block: { type: 'tool-call', id: 'a', name: 'one', arguments: '{}' } },
-      { type: 'block-end', index: 1, block: { type: 'tool-call', id: 'b', name: 'two', arguments: '{}' } },
-    ])
-  })
-
-  it('interleaves text and tool-call blocks with distinct indices', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: 'Checking.' } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'c', type: 'function', function: { name: 'f', arguments: '{}' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    const starts = chunks.filter(chunk => chunk.type === 'block-start')
-    expect(starts).toEqual([
-      { type: 'block-start', index: 0, blockType: 'text' },
-      { type: 'block-start', index: 1, blockType: 'tool-call' },
-    ])
-  })
-})
-
-describe('translate: finish and usage handling', () => {
-  it('takes usage from a trailing usage-only chunk (docs shape)', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: 'x' } }] },
-      { choices: [{ delta: {}, finish_reason: 'stop' }], usage: null },
-      { choices: [], usage: { prompt_tokens: 9, completion_tokens: 1 } },
-      DONE,
-    )))
-    expect(chunks.at(-2)).toEqual({ type: 'usage', usage: { inputTokens: 9, outputTokens: 1, totalTokens: 10 } })
-    expect(chunks.at(-1)).toEqual({ type: 'finish', reason: { kind: 'stop' } })
-  })
-
-  it('last usage wins when both attached and trailing arrive', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: {}, finish_reason: 'stop' }], usage: { prompt_tokens: 1, completion_tokens: 1 } },
-      { choices: [], usage: { prompt_tokens: 2, completion_tokens: 2 } },
-      DONE,
-    )))
-    const usage = chunks.find(chunk => chunk.type === 'usage')
-    expect(usage).toEqual({ type: 'usage', usage: { inputTokens: 2, outputTokens: 2, totalTokens: 4 } })
-  })
-
-  it('defaults to finish stop when no finish_reason ever arrives', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: 'x' } }] },
-      DONE,
-    )))
-    expect(chunks.at(-1)).toEqual({ type: 'finish', reason: { kind: 'stop' } })
-  })
-
-  it('omits the usage chunk when none arrived', async () => {
-    const chunks = await collect(translate(feed(firstChunk, DONE)))
-    expect(chunks.some(chunk => chunk.type === 'usage')).toBe(false)
-  })
-
-  it('handles chunks with no choices at all', async () => {
-    const chunks = await collect(translate(feed({}, DONE)))
-    expect(chunks).toEqual([{
-      type: 'finish',
-      reason: {
-        kind: 'error',
-        failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE },
-      },
-    }])
-  })
-
-  it('classifies an explicit stop with no opened blocks as EMPTY_RESPONSE, after usage', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: {}, finish_reason: 'stop' }], usage: { prompt_tokens: 7, completion_tokens: 0 } },
-      DONE,
-    )))
-    expect(chunks).toEqual([
-      { type: 'usage', usage: { inputTokens: 7, outputTokens: 0, totalTokens: 7 } },
-      {
-        type: 'finish',
-        reason: {
-          kind: 'error',
-          failure: { message: 'model returned a completed response with no content', code: EMPTY_RESPONSE_CODE },
-        },
-      },
-    ])
-  })
-
-  it('keeps a reasoning-only stream a successful stop (any opened block counts)', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { content: null, reasoning_content: 'mull' } }] },
-      { choices: [{ delta: {}, finish_reason: 'stop' }] },
-      DONE,
-    )))
-    expect(chunks.at(-1)).toEqual({ type: 'finish', reason: { kind: 'stop' } })
-  })
-
-  it('leaves non-stop finishes unclassified even with no opened blocks', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: {}, finish_reason: 'length' }] },
-      DONE,
-    )))
-    expect(chunks.at(-1)).toEqual({ type: 'finish', reason: { kind: 'max-tokens' } })
-  })
-})
-
-describe('translate: errors', () => {
-  it('throws MALFORMED_RESPONSE for invalid JSON payloads', async () => {
-    await expect(collect(translate(feed('{bad json')))).rejects.toThrow(LlmError)
-    await expect(collect(translate(feed('{bad json')))).rejects.toThrow(/malformed SSE payload/)
-  })
-
-  it('throws STREAM_CLOSED when the payload source ends without DONE', async () => {
-    await expect(collect(translate(feed(firstChunk)))).rejects.toThrow(/without \[DONE\]/)
-  })
-})
-
-describe('mapFinishReason', () => {
-  it.each([
-    ['stop', { kind: 'stop' }],
-    ['tool_calls', { kind: 'tool-calls' }],
-    ['length', { kind: 'max-tokens' }],
-  ])('maps %s', (wire, expected) => {
-    expect(mapFinishReason(wire)).toEqual(expected)
-  })
-
-  it.each(['content_filter', 'insufficient_system_resource', 'mystery_reason'])(
-    'maps %s to an error kind with the wire code',
-    (wire) => {
-      expect(mapFinishReason(wire)).toEqual({
-        kind: 'error',
-        failure: { message: `model stopped: ${wire}`, code: wire.toUpperCase() },
-      })
-    },
-  )
-})
-
-describe('mapUsage', () => {
-  it('maps the full live-capture shape', () => {
-    expect(mapUsage({
-      prompt_tokens: 283,
-      completion_tokens: 69,
-      total_tokens: 352,
-      prompt_cache_hit_tokens: 256,
-      prompt_cache_miss_tokens: 27,
-      prompt_tokens_details: { cached_tokens: 256 },
-      completion_tokens_details: { reasoning_tokens: 24 },
-    })).toEqual({
-      // 283 wire prompt_tokens minus the 256 cached → 27 uncached input
-      // (TokenUsage counts are disjoint).
-      inputTokens: 27,
-      outputTokens: 69,
-      totalTokens: 352,
-      cacheReadTokens: 256,
-      reasoningTokens: 24,
-    })
-  })
-
-  it('falls back to prompt_cache_hit_tokens when details are absent', () => {
-    expect(mapUsage({ prompt_tokens: 10, completion_tokens: 2, prompt_cache_hit_tokens: 8 }))
-      .toEqual({ inputTokens: 2, outputTokens: 2, totalTokens: 12, cacheReadTokens: 8 })
-  })
-
-  it('reconstructs an exact total when the wire omits it', () => {
-    expect(mapUsage({ prompt_tokens: 10, completion_tokens: 2 }))
-      .toEqual({ inputTokens: 10, outputTokens: 2, totalTokens: 12 })
-  })
-
-  it.each([
-    ['contradictory total', { prompt_tokens: 10, completion_tokens: 2, total_tokens: 99 }],
-    ['negative prompt', { prompt_tokens: -1, completion_tokens: 2 }],
-    ['fractional prompt', { prompt_tokens: 1.5, completion_tokens: 2 }],
-    ['negative completion', { prompt_tokens: 2, completion_tokens: -1 }],
-    ['fractional completion', { prompt_tokens: 2, completion_tokens: 1.5 }],
-    ['unsafe aggregate', { prompt_tokens: Number.MAX_SAFE_INTEGER, completion_tokens: 1 }],
-  ])('omits the exact total for %s without changing existing buckets', (_name, wire) => {
-    expect(mapUsage(wire)).toEqual({
-      inputTokens: wire.prompt_tokens,
-      outputTokens: wire.completion_tokens,
-    })
-  })
-})
-
-describe('translate: defensive tool-call branches', () => {
-  it('handles deltas that never carry id or name (empty-string fallbacks)', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      // Hypothetical lenient wire: argument fragments with no id/name at all.
-      { choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: '{}' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks).toEqual([
-      { type: 'block-start', index: 0, blockType: 'tool-call' },
-      { type: 'tool-call-delta', index: 0, id: '', argumentsDelta: '{}' },
-      { type: 'block-end', index: 0, block: { type: 'tool-call', id: '', name: '', arguments: '{}' } },
-      { type: 'finish', reason: { kind: 'tool-calls' } },
-    ])
-  })
-
-  it('handles tool_call deltas with a function object but no arguments field', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'c', type: 'function', function: { name: 'f' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks[1]).toEqual({ type: 'tool-call-delta', index: 0, id: 'c', name: 'f', argumentsDelta: '' })
-  })
-
-  it('handles tool_call deltas with no function object at all', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'c' }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks[1]).toEqual({ type: 'tool-call-delta', index: 0, id: 'c', argumentsDelta: '' })
-  })
-})
-
-describe('translate: tool-call identity across deltas', () => {
-  it('keeps the established identity when continuation deltas re-send it empty', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_00_x', type: 'function', function: { name: 'get_weather', arguments: '' } }] } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: '', type: 'function', function: { name: '', arguments: '{"city"' } }] } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: '', type: 'function', function: { name: '', arguments: ': "Paris"}' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks.filter(chunk => chunk.type === 'block-end')).toEqual([{
-      type: 'block-end',
-      index: 0,
-      block: { type: 'tool-call', id: 'call_00_x', name: 'get_weather', arguments: '{"city": "Paris"}' },
-    }])
-  })
-
-  it('keeps the established identity when continuation deltas re-send it null', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', type: 'function', function: { name: 'Glob', arguments: '' } }] } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: null, function: { name: null, arguments: '{}' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks.filter(chunk => chunk.type === 'block-end')).toEqual([{
-      type: 'block-end',
-      index: 0,
-      block: { type: 'tool-call', id: 'call_1', name: 'Glob', arguments: '{}' },
-    }])
-  })
-
-  it('re-sending the same non-empty identity does not duplicate it', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', type: 'function', function: { name: 'Glob', arguments: '' } }] } }] },
-      { choices: [{ delta: { tool_calls: [{ index: 0, id: 'call_1', type: 'function', function: { name: 'Glob', arguments: '{}' } }] } }] },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks.filter(chunk => chunk.type === 'block-end')).toEqual([{
-      type: 'block-end',
-      index: 0,
-      block: { type: 'tool-call', id: 'call_1', name: 'Glob', arguments: '{}' },
-    }])
-  })
-
-  it('maintains each parallel call identity separately under empty continuation deltas', async () => {
-    const chunks = await collect(translate(feed(
-      firstChunk,
-      {
-        choices: [{
-          delta: {
-            tool_calls: [
-              { index: 0, id: 'a', type: 'function', function: { name: 'one', arguments: '' } },
-              { index: 1, id: 'b', type: 'function', function: { name: 'two', arguments: '' } },
-            ],
-          },
-        }],
-      },
-      {
-        choices: [{
-          delta: {
-            tool_calls: [
-              { index: 1, id: '', function: { name: '', arguments: '{"b":1}' } },
-              { index: 0, id: '', function: { name: '', arguments: '{"a":1}' } },
-            ],
-          },
-        }],
-      },
-      { choices: [{ delta: {}, finish_reason: 'tool_calls' }] },
-      DONE,
-    )))
-    expect(chunks.filter(chunk => chunk.type === 'block-end')).toEqual([
-      { type: 'block-end', index: 0, block: { type: 'tool-call', id: 'a', name: 'one', arguments: '{"a":1}' } },
-      { type: 'block-end', index: 1, block: { type: 'tool-call', id: 'b', name: 'two', arguments: '{"b":1}' } },
-    ])
-  })
-})
diff --git a/packages/llm/llm-deepseek/tests/upload-index.spec.ts b/packages/llm/llm-deepseek/tests/upload-index.spec.ts
index ddff23e060..989a921e69 100644
--- a/packages/llm/llm-deepseek/tests/upload-index.spec.ts
+++ b/packages/llm/llm-deepseek/tests/upload-index.spec.ts
@@ -3,8 +3,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { AttachmentId, ImageVariantId } from '@deepseek-ai/dsh-attachment'
-import { DeepSeekFileId } from '../src/common/file-id.ts'
-import { deepSeekFileScope, DeepSeekUploadIndex } from '../src/common/upload-index.ts'
+import { DeepSeekFileId } from '../src/file-id.ts'
+import { deepSeekFileScope, DeepSeekUploadIndex } from '../src/upload-index.ts'
 
 const ATTACHMENT = AttachmentId(`sha256:${'a'.repeat(64)}`)
 const VARIANT = ImageVariantId(`sha256:${'b'.repeat(64)}`)
diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml
index 175e1ab36e..06072e5b87 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: 4b3297ab96c2c691f9bbf849d8e49cb10a126a6a
-README.zh.md: b33381468891fa81b199cca40f22a59183f5076a
+README.md: 35d4ce1ad9318c4c27a71af362014d53bf3e3798
+README.zh.md: bd12102d0b35963495907ee53a69d2dd339f5ffc
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index 4b3297ab96..35d4ce1ad9 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -229,6 +229,7 @@ These limits define where the adapter stops and future work begins. They are cur
 - **Only a leading in-history `system` message becomes pi-ai's `systemPrompt`** — pi-ai has one system slot, so a later `system` message, or a leading one when `GenerateOptions.system` is also set, folds into a `user` message at its position; provider-specific placement of the prompt follows pi-ai rather than a harness-owned wire override. Images in system or assistant history, including the leading system message, fail with `UNSUPPORTED_CONTENT` on both conversion paths.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers.
 - **Retry policy is provider-owned, not an SDK retry** — pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
+- **Streamed tool-call arguments are parsed once, when the call ends** — the installed pi-ai carries [`patches/@earendil-works__pi-ai@0.85.1.patch`](../../../patches/@earendil-works__pi-ai@0.85.1.patch), which removes the per-delta re-parse of the whole accumulated argument JSON in every stream adapter (upstream [earendil-works/pi#9265](https://github.com/earendil-works/pi/issues/9265)); unpatched, a multi-megabyte argument stream costs O(n²) CPU on the event loop and stalls every session in the process. Until `toolcall_end`, a pi-ai partial's tool-call `arguments` stays `{}`; this adapter reads only the delta strings and the finalized arguments. Re-apply or retire the patch on every pi-ai upgrade.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md
index b333814688..bd12102d0b 100644
--- a/packages/llm/llm-pi-ai/README.zh.md
+++ b/packages/llm/llm-pi-ai/README.zh.md
@@ -229,6 +229,7 @@ pi-ai 事件变成 harness 的推理、文本、工具调用、用量与 finish
 - **只有历史中首条 `system` 消息会成为 pi-ai 的 `systemPrompt`**——pi-ai 只有一个系统槽位，因此后续的 `system` 消息，或在同时设置了 `GenerateOptions.system` 时的首条消息，会在原位置折叠为 `user` 消息；系统提示词的提供方专属放置遵循 pi-ai，而非 harness 自有的协议覆盖。system 或 assistant 历史中的图片（包括首条系统消息中的图片）在两条转换路径上都会以 `UNSUPPORTED_CONTENT` 失败。
 - **提供方 HTTP 状态不可用**——pi-ai 错误事件不跨提供方暴露稳定 HTTP 状态。
 - **重试策略由提供方自有，而非 SDK 重试**——pi-ai SDK 重试保持禁用，因此持久 agent（智能体）步骤与 `llm/retry` 事件拥有每个可见尝试，直接 `ctx.llm.stream()` 调用仍是单次尝试。
+- **流式工具调用参数只在调用结束时解析一次**——安装的 pi-ai 带有 [`patches/@earendil-works__pi-ai@0.85.1.patch`](../../../patches/@earendil-works__pi-ai@0.85.1.patch)，它移除了每个流适配器中对整段累计参数 JSON 的逐 delta 重新解析（上游 [earendil-works/pi#9265](https://github.com/earendil-works/pi/issues/9265)）；未打补丁时，数 MB 的参数流会在事件循环上消耗 O(n²) CPU，并使进程内所有会话停滞。在 `toolcall_end` 之前，pi-ai partial 的工具调用 `arguments` 保持为 `{}`；本适配器只读取 delta 字符串与最终参数。每次升级 pi-ai 时都要重新应用或撤销该补丁。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/llm/llm-pi-ai/tests/adapter.e2e.ts b/packages/llm/llm-pi-ai/tests/adapter.e2e.ts
index de8cd86532..2787a1ab7d 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.e2e.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.e2e.ts
@@ -24,7 +24,6 @@ async function harness(_model: string, config: Partial<PiAiProviderProfile> = {}
     providers: {
       deepseek: {
         ...process.env.DEEPSEEK_API_KEY === undefined ? {} : { apiKey: process.env.DEEPSEEK_API_KEY },
-        baseURL: LlmDeepSeek.PUBLIC_BASE_URL,
         ...config,
       },
     },
diff --git a/packages/llm/llm-pi-ai/tests/tool-argument-streaming.spec.ts b/packages/llm/llm-pi-ai/tests/tool-argument-streaming.spec.ts
new file mode 100644
index 0000000000..14a4e09a9b
--- /dev/null
+++ b/packages/llm/llm-pi-ai/tests/tool-argument-streaming.spec.ts
@@ -0,0 +1,81 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import type { AssistantMessageEvent, Model } from '@earendil-works/pi-ai'
+import { stream as streamCompletions } from '@earendil-works/pi-ai/api/openai-completions'
+import { stream as streamResponses } from '@earendil-works/pi-ai/api/openai-responses'
+import { closeMockServers, mockServer } from './mock-server.ts'
+
+afterEach(closeMockServers)
+
+/** A write call whose arguments arrive in many small deltas. */
+const args = { file_path: 'notes.md', content: 'x'.repeat(2048) }
+const argsJson = JSON.stringify(args)
+const fragments = argsJson.match(/.{1,7}/gs) ?? []
+
+function model<A extends 'openai-completions' | 'openai-responses'>(api: A, baseUrl: string): Model<A> {
+  return {
+    id: 'm', name: 'm', api, provider: 'test', baseUrl, reasoning: false, input: ['text'],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 8192, maxTokens: 1024,
+  }
+}
+
+/** The arguments each `toolcall_delta` partial carries, and the finalized arguments. */
+async function collect(events: AsyncIterable<AssistantMessageEvent>): Promise<{ partials: unknown[]; final: unknown }> {
+  const partials: unknown[] = []
+  let final: unknown
+  for await (const event of events) {
+    if (event.type === 'toolcall_delta' && event.delta.length > 0) {
+      const block = event.partial.content[event.contentIndex]
+      partials.push(block?.type === 'toolCall' ? block.arguments : undefined)
+    } else if (event.type === 'toolcall_end') {
+      final = event.toolCall.arguments
+    } else if (event.type === 'error') {
+      throw new Error(event.error.errorMessage)
+    }
+  }
+  return { partials, final }
+}
+
+const context = { messages: [{ role: 'user' as const, content: 'hi', timestamp: 0 }] }
+
+describe('streamed tool-call arguments (patched pi-ai)', () => {
+  it('openai-completions parses arguments once, at the end of the call', async () => {
+    const server = await mockServer([{ events: [
+      JSON.stringify({ choices: [{
+        delta: {
+          role: 'assistant',
+          tool_calls: [{ index: 0, id: 'call_1', type: 'function', function: { name: 'write', arguments: '' } }],
+        },
+        index: 0, finish_reason: null,
+      }] }),
+      ...fragments.map(fragment => JSON.stringify({
+        choices: [{ delta: { tool_calls: [{ index: 0, function: { arguments: fragment } }] }, index: 0, finish_reason: null }],
+      })),
+      '{"choices":[{"delta":{},"index":0,"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":3,"completion_tokens":1}}',
+      '[DONE]',
+    ] }])
+    const events = streamCompletions(model('openai-completions', server.url), context, { apiKey: 'test-key' })
+    const { partials, final } = await collect(events)
+    expect(partials).toHaveLength(fragments.length)
+    expect(partials.every(partial => JSON.stringify(partial) === '{}')).toBe(true)
+    expect(final).toEqual(args)
+  })
+
+  it('openai-responses parses arguments once, at the end of the call', async () => {
+    const item = { type: 'function_call', call_id: 'call_1', id: 'fc_1', name: 'write' }
+    const server = await mockServer([{ events: [
+      '{"type":"response.created","response":{"id":"resp_1"}}',
+      JSON.stringify({ type: 'response.output_item.added', output_index: 0, item: { ...item, arguments: '' } }),
+      ...fragments.map(fragment => JSON.stringify({ type: 'response.function_call_arguments.delta', output_index: 0, delta: fragment })),
+      JSON.stringify({ type: 'response.function_call_arguments.done', output_index: 0, arguments: argsJson }),
+      JSON.stringify({ type: 'response.output_item.done', output_index: 0, item: { ...item, arguments: argsJson } }),
+      JSON.stringify({ type: 'response.completed', response: {
+        id: 'resp_1', status: 'completed', output: [], usage: { input_tokens: 3, output_tokens: 1, total_tokens: 4 },
+      } }),
+    ] }])
+    const events = streamResponses(model('openai-responses', server.url), context, { apiKey: 'test-key' })
+    const { partials, final } = await collect(events)
+    expect(partials).toHaveLength(fragments.length)
+    expect(partials.every(partial => JSON.stringify(partial) === '{}')).toBe(true)
+    expect(final).toEqual(args)
+  })
+})
diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts
index a502f07c50..8fd91ece9e 100644
--- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts
+++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts
@@ -14,19 +14,26 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import * as Retry from '../src/index.ts'
 
 let context: Context | undefined
-const servers: MockLlmServer[] = []
+const servers: Promise<MockLlmServer>[] = []
 
 afterEach(async () => {
-  await context?.fiber.dispose()
+  const ownedContext = context
   context = undefined
-  await Promise.all(servers.splice(0).map(server => server.close()))
+  // A failed transport can still await a stalled socket while its context disposes.
+  const results = await Promise.allSettled([
+    ownedContext?.fiber.dispose(),
+    ...servers.splice(0).map(async server => (await server).close()),
+  ])
+  vi.unstubAllEnvs()
+  const failure = results.find(result => result.status === 'rejected')
+  if (failure?.status === 'rejected') throw failure.reason
 })
 
-async function start(
+function start(
   sequence: readonly MockLlmBehavior[],
   options: Omit<Parameters<typeof startMockLlmServer>[0], 'sequence'> = {},
 ): Promise<MockLlmServer> {
-  const server = await startMockLlmServer({ sequence, ...options })
+  const server = startMockLlmServer({ sequence, ...options })
   servers.push(server)
   return server
 }
@@ -39,7 +46,6 @@ async function harness(
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   await ctx.plugin(LlmDeepSeek, {
-    protocol: 'chat-completions',
     baseURL,
     streamIdleTimeoutMs: options.streamIdleTimeoutMs ?? 1_000,
     retryPolicy: {
@@ -196,7 +202,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
     expect(agent.session.snapshotEvents().some(event => event.type === 'llm/retry')).toBe(false)
     expect(agent.session.snapshotEvents().at(-1)).toMatchObject({
       type: 'turn/end',
-      data: { reason: { kind: 'error', error: { message: 'SSE stream ended without [DONE]', code: 'STREAM_CLOSED' } } },
+      data: { reason: { kind: 'error', error: { message: 'DeepSeek Messages stream ended before message_stop', code: 'STREAM_CLOSED' } } },
     })
   })
 
@@ -219,7 +225,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
     expect(agent.session.snapshotEvents().filter(event => event.type === 'llm/retry').map(event => event.data.failure.code))
       .toEqual(['TIMEOUT'])
     expect(finalAssistantText(agent)).toBe('recovered after timeout')
-  }, 10_000)
+  })
 
   it('stops after the configured transport retry budget is exhausted', async () => {
     const server = await start(['connection_reset', 'connection_reset', 'connection_reset'], {
@@ -242,7 +248,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => {
       data: { reason: { kind: 'error', error: { code: 'TRANSPORT' } } },
     })
     if (end?.type === 'turn/end' && end.data.reason.kind === 'error') {
-      expect(end.data.reason.error.message).toContain('DeepSeek API request to')
+      expect(end.data.reason.error.message).toBe('DeepSeek Messages transport failed')
     }
   })
 })
diff --git a/packages/llm/llm/README.i18n.yaml b/packages/llm/llm/README.i18n.yaml
index 6fac0fb24a..dbc3bd15e7 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: cdda682cebc720d51692a1b0c4c8691fa84359a3
-README.zh.md: 8c679ecc6910376f7270450ae5be867d0da353fc
+README.md: 04de24592379dcb0d815f3b033ca2f9f22e2ff6a
+README.zh.md: bee35d4a0b62dd61a61b435dfc4eb27b62cdce69
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index cdda682ceb..04de245923 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -127,7 +127,7 @@ File detection reads current content, including tool-role result content, on eve
 Read these pages when the package-level contract is not enough. They move from the shared types to the concrete adapters, the retry executor, and the measurement service.
 
 - [LLM streaming subsystem](../../../docs/subsystems/llm-streaming.md) — the message and block types, compact Assistant stream records, the `StreamChunk` protocol, and the adapter contract.
-- [llm-deepseek adapter](../llm-deepseek/README.md) — the direct DeepSeek chat-completions implementation.
+- [llm-deepseek adapter](../llm-deepseek/README.md) — the direct DeepSeek Messages implementation.
 - [llm-pi-ai adapter](../llm-pi-ai/README.md) — the pi-ai-backed multi-provider implementation.
 - [llm-retry](../llm-retry/README.md) — the retry executor that re-runs failed model requests.
 - [Token meter](../token-meter/README.md) — replay-aware request and context pressure measurement.
diff --git a/packages/llm/llm/README.zh.md b/packages/llm/llm/README.zh.md
index 8c679ecc69..bee35d4a0b 100644
--- a/packages/llm/llm/README.zh.md
+++ b/packages/llm/llm/README.zh.md
@@ -127,7 +127,7 @@ for await (const chunk of ctx.llm.stream({
 当包级约定不够用时阅读以下页面。它们从共享类型逐步进入具体适配器、重试执行器与计量服务。
 
 - [LLM（大语言模型）流式子系统](../../../docs/subsystems/llm-streaming.zh.md)——消息与块类型、紧凑的 Assistant 流记录、`StreamChunk` 协议与适配器约定。
-- [llm-deepseek 适配器](../llm-deepseek/README.zh.md)——DeepSeek chat-completions 直连实现。
+- [llm-deepseek 适配器](../llm-deepseek/README.zh.md)——DeepSeek Messages 直连实现。
 - [llm-pi-ai 适配器](../llm-pi-ai/README.zh.md)——基于 pi-ai 的多提供方实现。
 - [llm-retry](../llm-retry/README.zh.md)——重跑失败模型请求的重试执行器。
 - [Token 计量](../token-meter/README.zh.md)——具备回放感知的请求与上下文压力测量。
diff --git a/packages/preset/agent-presets/presets/cordis/agent.cordis.yml b/packages/preset/agent-presets/presets/cordis/agent.cordis.yml
index 9df711310c..c0a5ab802a 100644
--- a/packages/preset/agent-presets/presets/cordis/agent.cordis.yml
+++ b/packages/preset/agent-presets/presets/cordis/agent.cordis.yml
@@ -5,37 +5,21 @@
 #
 # It exists so a person can ask an agent to author another agent. Everything in
 # `standard` is here unchanged; Creator adds persistent plugin management,
-# runtime inspection, composition-authoring skills, and a persona that explains
-# where profile and preset changes belong.
+# runtime inspection, and composition-authoring skills. The persona is the
+# `standard` one: tool descriptions and the skill catalog carry the operating
+# detail, and the skills own the off-limits rule (an upgrade overwrites the
+# shipped preset install, and corrupting the `cordis` preset disables this mode).
 #
 # Profile management persists configuration shared by every session in that profile.
 
-# The preset's own persona, shadowing the deployment default for this agent.
+# Same persona as `standard`, shadowing the deployment default for this agent.
 # `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
     suffix: Your working directory is {{cwd}}.
-    prefix: |-
-      You are a coding agent powered by the {{model}} model, running on the DeepSeek Harness.
-
-      You can read and modify the harness you run on. Its composition is Cordis: every capability is a plugin row in a `cordis.yml`, and an agent preset is one such file mounted for a single session.
-
-      Two planes decide where an edit belongs. The HOST composition holds the registries and anything shared across sessions — persistence, the sandbox and approval stack, the model route, the subagent registry and its backends. An AGENT PRESET holds what one session contributes to those registries: its tools, its persona, its prompt sections. A row that publishes a service belongs in the host composition, or inside an `isolate` realm if the preset genuinely owns that service and nothing outside one agent reads it.
-
-      Presets you author live one directory per preset under `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<id>/`. Load `editing-cordis-compositions` for file discovery and copying instructions. NEVER edit or delete the shipped preset install (the `agent-presets` directory beside the deployment's own config): it belongs to the deployment, an upgrade overwrites it, and corrupting the `cordis` preset would disable this very mode. To change what a shipped preset does, copy its composition into a new preset directory and edit the copy.
-
-      Load the `editing-cordis-compositions` skill before writing or changing a composition.
-
-      Use plugin_manager for persistent bundle installation, removal and enablement in the current profile. Author plugin code and configuration as ordinary workspace bundle files. Changes affect every session in that profile. Read saved-state and activation outcomes separately; restart-required means the new capability is not available yet.
-
-      In Creator mode, requests to make a visual object, decoration, or widget mean creating an installed UI plugin that displays it in this Harness Web UI, unless the user specifies another destination. Choose reasonable visual details and proceed. Load cordis-plugin-development, inspect the Client slots, build the plugin in the workspace, and install it with plugin_manager. Install a minimal working version before visual refinement; use the connected page as its preview. Verify that the open page renders it; a standalone image or HTML file does not complete an in-app creation request.
-
-      Load the cordis-plugin-development skill before authoring an installed plugin. Use cordis_inspect_list to discover Host and Client providers, then cordis_inspect_query to read exact Service, Event, Tool, Theme or Slot APIs. These tools are read-only; queries do not invoke business methods.
-
-      To connect an MCP server, create a configuration-only bundle whose patch inserts @deepseek-ai/dsh-mcp-client, then install it with plugin_manager. Load cordis-plugin-development for the package and YAML examples. After successful activation, call one of the newly available mcp__<serverName>__<tool> tools to verify the connection.
-
-      Use installed bundles for new plugin code. Package installation may require explicit user approval for build scripts. Preserve returned failures and pending states; only report success after observing the requested capability.
+    prefix: >-
+      You are a coding agent powered by the {{model}} model.
 
 - id: agent-instructions
   name: '@deepseek-ai/dsh-agent-instructions'
@@ -279,5 +263,8 @@
 - id: present
   name: '@deepseek-ai/dsh-tool-present'
 
+# Enabled exactly when the host `plugin-manager` service is (`dsh-base` gates
+# it on a launched profile), so a profile-less embedding still mounts the preset.
 - id: tool-plugin-manager
   name: '@deepseek-ai/dsh-plugin-manager/tools'
+  disabled: !!js "!ctx.get('profileContext')"
diff --git a/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md b/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md
index 84a48f2a75..67aadc1cd7 100644
--- a/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md
+++ b/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: cordis-plugin-development
-description: Use when authoring, installing, configuring, or debugging persistent plugins and MCP connections in the current Harness profile.
+description: Use when authoring, installing, configuring, or debugging persistent plugins and MCP connections in the current Harness profile, and for any visual object, decoration, or widget request that names no other destination, which means an installed UI plugin rendered in the Harness Web UI.
 ---
 
 # Persistent Harness plugins
@@ -9,7 +9,7 @@ Use ordinary workspace files to author a bundle, then `plugin_manager install_bu
 
 ## Deliver a working plugin first
 
-1. Resolve the requested result and destination. In Creator mode, an unspecified visual destination is the current Harness Web UI. Choose reasonable visual details and implement a small first version.
+1. Resolve the requested result and destination. An unspecified visual destination is the current Harness Web UI; a standalone image or HTML file does not complete such a request. Choose reasonable visual details and implement a small first version; install it before visual refinement.
 2. Discover only the APIs needed for that version: `cordis_inspect_list`, then targeted `cordis_inspect_query` calls. For UI, query Client `Slots.listSubTree` and the selected slot's registration options and props. Treat the recipes below and returned API declarations as the supported implementation path. Once the chosen slot and registration API are known, write the plugin. Before the first installation, resolve missing declarations through inspection; do not re-check these recipes by reading Loader, manifest-parser, package-manager, React, or slot implementation source. Source-level diagnosis starts from a concrete installation or runtime failure.
 3. The first files you write are the installable package, patch, and required Host/Client files in one workspace directory. Check JavaScript syntax and the manifest, then install it. Before that first installation, do not create preview HTML, mock shells, design variants, screenshot scripts, or rasterizer tooling. Use the installed plugin itself as the first preview.
 4. Read the installation result. After `application: applied`, exercise the capability or inspect the live Client registration. Use the connected page for visual verification when browser control is available. State any verification limitation explicitly; installation and slot registration alone do not establish what the user can see.
@@ -47,7 +47,7 @@ For a simple drawing, prefer a slot with allocated space, such as `conversation.
       name: '@local/my-decoration'
 ```
 
-Call `plugin_manager` with `action: install_bundle` and the absolute package directory as `target`. It performs package installation and bundle selection; do not reproduce those steps with shell commands. Only pass `approvedBuilds` after the user explicitly approves the reported pending build scripts.
+Call `plugin_manager` with `action: install_bundle` and the absolute package directory as `target`. It performs package installation and bundle selection; do not reproduce those steps with shell commands. Only pass `approvedBuilds` after the user explicitly approves the reported pending build scripts. Preserve returned failures and pending states; report success only after observing the requested capability.
 
 Use `list_plugins` or `list_bundles` to obtain exact identifiers for existing installations. `set_plugin` and `set_bundle` toggle them; `remove_bundle` removes a bundle. Inspect saved-state and activation outcomes separately: `failed` requires diagnosis, `overridden` means a higher-priority layer wins, and `restart-required` means the change is not live. Installing a new bundle can activate through HMR; replacing an installed package requires restart to load a fresh JavaScript module generation. Do not infer updated browser code from an unchanged slot id.
 
@@ -105,4 +105,4 @@ Create a configuration-only bundle: its manifest needs a unique name, version, a
         failOnStartupError: true
 ```
 
-Replace the endpoint, install the bundle through `plugin_manager`, then call `mcp__demo__ping` or another discovered tool. For stdio, use `transport: stdio`, `command`, and optional `args`, `env`, and `cwd`. Ambient credentials are scrubbed; reference existing credentials with Loader `!!js` rather than copying secrets into conversation text. Repair the same bundle on failure instead of creating duplicates.
+Replace the endpoint, install the bundle through `plugin_manager`, then call `mcp__demo__ping` or another newly available `mcp__<serverName>__<tool>` tool to verify the connection. For stdio, use `transport: stdio`, `command`, and optional `args`, `env`, and `cwd`. Ambient credentials are scrubbed; reference existing credentials with Loader `!!js` rather than copying secrets into conversation text. Repair the same bundle on failure instead of creating duplicates.
diff --git a/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md b/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md
index 727099f6fc..dfdc4de73a 100644
--- a/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md
+++ b/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: editing-cordis-compositions
-description: Use when creating, changing, or validating a Cordis composition for this harness — writing or editing an agent preset, adding or removing a plugin row, deciding whether something belongs to the host composition or to one session, checking whether a preset you authored actually mounts, or diagnosing a row that mounted but contributed nothing.
+description: Use when creating, changing, or validating an agent preset or other Cordis composition for this harness, including deciding host versus preset placement and checking that an authored preset mounts.
 ---
 
 # Editing Cordis compositions
diff --git a/packages/preset/agent-presets/tests/shipped-root.spec.ts b/packages/preset/agent-presets/tests/shipped-root.spec.ts
index 8ae0d8a261..1882d0d5b7 100644
--- a/packages/preset/agent-presets/tests/shipped-root.spec.ts
+++ b/packages/preset/agent-presets/tests/shipped-root.spec.ts
@@ -16,6 +16,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import Include, { entryListSchema } from '@deepseek-ai/cordis-plugin-include'
+import { evaluate, isJsExpr } from '@deepseek-ai/cordis-plugin-loader'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import * as yaml from 'js-yaml'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
@@ -153,6 +154,19 @@ describe('the shipped preset root', () => {
     }
   })
 
+  it('enables the cordis plugin-manager tool exactly when a launched profile provides profileContext', async () => {
+    // Same condition as the host `plugin-manager` row in `dsh-base`: the tool
+    // injects `pluginManager`, so without that service the row must be
+    // disabled rather than left waiting and blocking the whole mount.
+    const disabled = findEntry(await shippedEntries('cordis'), 'tool-plugin-manager')?.disabled
+    if (!isJsExpr(disabled)) throw new TypeError('cordis tool-plugin-manager must gate on a !!js expression')
+    const scope = (profileContext: object | undefined) => ({
+      ctx: { get: (name: string) => (name === 'profileContext' ? profileContext : undefined) },
+    })
+    expect(evaluate(scope(undefined), disabled.__jsExpr)).toBe(true)
+    expect(evaluate(scope({ name: 'web' }), disabled.__jsExpr)).toBe(false)
+  })
+
   it('disables the ralph tool in every shipped preset that carries it', async () => {
     for (const id of ['cordis', 'ptc', 'standard']) {
       expect(findEntry(await shippedEntries(id), 'tool-ralph')?.disabled, id).toBe(true)
diff --git a/packages/sdk/client/tests/sdk-client.spec.ts b/packages/sdk/client/tests/sdk-client.spec.ts
index 0fb2eafad1..10a1a431e4 100644
--- a/packages/sdk/client/tests/sdk-client.spec.ts
+++ b/packages/sdk/client/tests/sdk-client.spec.ts
@@ -647,6 +647,9 @@ describe('HarnessClient', () => {
     const inject = (method: string, params: Record<string, unknown>): void => {
       (client as unknown as { dispatchNotification(n: HarnessNotification): void }).dispatchNotification({ method, params })
     }
+    const unknownChild = { type: 'subagent/catalog', seq: 0, time: 1,
+      data: { version: 1, childId: 'unreadable-child', childCreatedAt: 1, mode: 'unknown' } }
+    inject('session.event', { sessionId: 'root', event: unknownChild })
     inject('subagent.started', { parentSessionId: 'root', childSessionId: 'child' })
     inject('subagent.started', { parentSessionId: 'child', childSessionId: 'grandchild' })
     inject('session.event', { sessionId: 'grandchild', event: { type: 'noop' } })
@@ -658,6 +661,7 @@ describe('HarnessClient', () => {
     inject('subagent.started', { parentSessionId: '', childSessionId: 'x' })
     inject('subagent.finished', { childSessionId: 'root' })
 
+    expect(await tree.next()).toEqual({ method: 'session.event', params: { sessionId: 'root', event: unknownChild } })
     expect((await tree.next()).method).toBe('subagent.started')
     expect((await tree.next()).method).toBe('subagent.started')
     expect((await tree.next()).params.sessionId).toBe('grandchild')
diff --git a/packages/session-query/session-query/src/observation.ts b/packages/session-query/session-query/src/observation.ts
index 8c08108775..69ddf1f19c 100644
--- a/packages/session-query/session-query/src/observation.ts
+++ b/packages/session-query/session-query/src/observation.ts
@@ -54,8 +54,8 @@ export interface SessionObservationOptions {
  * instance still reports the same revision.
  */
 interface PreparedEntry {
-  /** The persistence instance whose `stat` produced {@link revision}; revisions from another instance are incomparable. */
-  readonly persistence: SessionPersistence
+  /** Stable service identity whose `stat` produced this revision; proxy references are not instance identities. */
+  readonly persistenceIdentity: symbol
   /** Durable revision observed by `stat` immediately before the log read. */
   readonly revision: SessionPersistenceRevision
   /** Unpublished Session restored from the balanced log; never entered into the store. */
@@ -109,7 +109,7 @@ export class SessionObservationReader {
       const snapshot = await this.statSource(persistence, sessionId, signal)
       const attachedDuringStat = this.ctx.sessions.get(sessionId)
       if (attachedDuringStat !== undefined) return this.live(attachedDuringStat, projectionMode)
-      let entry = this.cachedEntry(persistence, sessionId, snapshot.revision)
+      let entry = this.cachedEntry(persistence.identity, sessionId, snapshot.revision)
       if (entry === undefined) {
         const loaded = await this.loadSource(persistence, sessionId, signal)
         throwIfObservationAborted(signal)
@@ -138,7 +138,7 @@ export class SessionObservationReader {
           )
         }
         entry = {
-          persistence,
+          persistenceIdentity: persistence.identity,
           revision: snapshot.revision,
           session,
           events: Object.freeze(seed),
@@ -201,12 +201,12 @@ export class SessionObservationReader {
 
   /** Return a still-valid cached entry and mark it most recently used. */
   private cachedEntry(
-    persistence: SessionPersistence,
+    persistenceIdentity: symbol,
     sessionId: SessionId,
     revision: SessionPersistenceRevision,
   ): PreparedEntry | undefined {
     const cached = this.cache.get(sessionId)
-    if (cached === undefined || cached.persistence !== persistence || cached.revision !== revision) {
+    if (cached === undefined || cached.persistenceIdentity !== persistenceIdentity || cached.revision !== revision) {
       return undefined
     }
     this.cache.delete(sessionId)
diff --git a/packages/session/session-format-v3-to-v4/README.i18n.yaml b/packages/session/session-format-v3-to-v4/README.i18n.yaml
index 892da2ad10..afd45897dc 100644
--- a/packages/session/session-format-v3-to-v4/README.i18n.yaml
+++ b/packages/session/session-format-v3-to-v4/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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-format-v3-to-v4/README.md
-README.md: 2c2d3b4342d68cec5e9a9f94f969a380bbbf15f2
-README.zh.md: a92ae34a73f134253880fec3f931815e067bc344
+README.md: 7a1b188194b54ff3ba7730388126fa0d2164fa06
+README.zh.md: 9d0f48ac375501d7dbd1e0b914bb882e43b02ac8
diff --git a/packages/session/session-format-v3-to-v4/README.md b/packages/session/session-format-v3-to-v4/README.md
index 2c2d3b4342..7a1b188194 100644
--- a/packages/session/session-format-v3-to-v4/README.md
+++ b/packages/session/session-format-v3-to-v4/README.md
@@ -144,17 +144,17 @@ There is no recursive source search. Captured request text, assistant replay sta
 |---|---|
 | One descriptor with version 1 | Require string provider and label; derive `mode: 'continuable'`. |
 | One descriptor with version 2 or 3 | Require string provider; use its mode and optional label under catalog rules. |
-| Zero descriptors, or an unsupported descriptor version | May retain an existing parent entry; cannot create a missing entry. |
-| More than one own descriptor | Retain an existing parent entry without mode/label comparison; do not create a missing entry. |
+| Zero descriptors, or an unsupported descriptor version | Retain an existing parent entry; otherwise append unknown-mode membership. |
+| More than one own descriptor | Retain an existing parent entry without mode/label comparison; otherwise append unknown-mode membership. |
 | Existing own parent entry | Retain it and its extensions; require matching child creation time and mode/label from exactly one supported own descriptor, when available. |
 | Missing own parent entry with complete supported evidence | Append a version-0 catalog fact with child id, creation time, mode, and optional label. |
-| Missing own parent entry without complete evidence | Preserve the parent without inventing a catalog entry. |
+| Missing own parent entry without complete evidence | Append a version-1 `subagent/catalog` with header identity and unknown mode, without inventing a label. |
 
-Catalog version 0 requires string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable` or `one-shot`, and a string label for continuable mode; a present one-shot label must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments.
+Catalog versions 0 and 1 require string `childId`, nonnegative safe-integer `childCreatedAt`, mode `continuable` or `one-shot` (version 1 additionally accepts `unknown`), and a string label for continuable mode; a present label in any mode must also be a string. Duplicate own child ids are refused. Existing entries without a corresponding retained child remain in the parent. Descriptor collection does not restore a child's old continuation composition or recover deleted children from tool arguments. Unknown-mode entries retain header identity without asserting a supported child descriptor.
 
 The stage considers parent catalog records only after the final inherited cut. Every inherited marker discards earlier catalog candidates without interpreting their payloads. Missing entries append after all source events, sorted by creation time then child id, with dense new sequences. Their time is the final source event's time, or header creation time for an empty log. They neither enter the model surface nor change the inherited count.
 
-Storage supplies the complete recognizable child set within its root and rechecks membership and physical revisions during preparation, memo reuse, and publication. Incomplete descriptor evidence only prevents that child’s backfill. Unreadable headers that prevent classifying membership, unsupported selected generations, or source drift refuse the operation. The package itself reads no files; [persistence](../session-persistence-jsonl/README.md) owns encoding, locks, cancellation, and publication.
+Storage supplies recognizable direct-child evidence and rechecks membership and physical revisions during preparation, memo reuse, and publication. The JSONL provider isolates unreadable child headers, child decoding failures, and invalid descriptor fields while retaining other catalog entries; it does not migrate child catalogs during parent preparation. The converter still rejects conflicting supplied facts and changed parent history. [JSONL persistence](../session-persistence-jsonl/README.md) owns warnings, source checks, and child-local failure handling. Current V4 reads never invoke this converter and validate native catalog fields, uniqueness, and delivery ownership directly.
 
 <a id="sequence-references"></a>
 ### Sequence references and inheritance
@@ -243,7 +243,7 @@ Current common admission does not validate each user/tool/developer content bloc
 | `compaction/start`, `compaction/summary`, `compaction/end` | Match compaction id, source command, and the active turn context. Summary spans name exact current-surface nodes and exclude the protected head; successful completion has one summary. Inherited unfinished compactions expire at the end-seed marker. |
 | `compaction/prune` | Its span names exact current-surface nodes and excludes the protected head; it does not require a compaction transaction or its owner fields. |
 | Compact checkpoint replacement | Its `compact-checkpoint` source identifies the active compaction. |
-| Native `subagent/catalog` | Check own version-0 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
+| Native `subagent/catalog` | Check own version-0/version-1 payload fields and unique child ids after the inherited cut. Native reads neither collect child logs nor compare their physical facts; inherited entries do not establish own membership. |
 | Inherited cut and delivery | Apply the marker, coordinate, and generation-ownership rules stated above. |
 
 These checks are generation-owned in [relationships.ts](src/relationships.ts). Full common message/envelope acceptance and plugin-owned message projections additionally use the installed Session; the exported V4 restorer alone is not a replacement for complete catalog restoration.
@@ -334,7 +334,7 @@ The edge preserves the recorded request prefix. Provider cache availability and
 - **Nested historical tool results** — migration currently refuses results containing another tool-result wrapper. The original generation remains intact and no V4 successor is published. A later converter may support evidenced source cases without changing the established V4 format; the [migration cookbook](../../../docs/cookbook/adding-a-session-format-version.md#stages-and-validation) defines that distinction.
 - **Historical extension consumers** — prefixed message and result fields preserve JSON data without activating core fields. A consumer must explicitly understand those fields before interpreting them.
 - **Retained child logs required** — a parent alone cannot recover unrecorded child ids, creation times, or descriptors. Deleted children cannot be reconstructed from tool arguments; existing parent catalog records remain.
-- **Missing historical catalog entries** — without exactly one supported own descriptor, an absent parent entry is not backfilled. The child log remains readable by id; current V4 reads do not rescan children to repair that omission.
+- **Unknown historical modes** — without exactly one supported own descriptor, a missing parent entry records unknown mode. Current reads do not rewrite that entry; opening the child resolves available descriptor information or reports its own error.
 - **Storage scope** — facts cover recognizable children within the same persistence root. Cross-root import and corrupt-log repair are outside this migration.
 
 <a id="dev-note"></a>
diff --git a/packages/session/session-format-v3-to-v4/README.zh.md b/packages/session/session-format-v3-to-v4/README.zh.md
index a92ae34a73..9d0f48ac37 100644
--- a/packages/session/session-format-v3-to-v4/README.zh.md
+++ b/packages/session/session-format-v3-to-v4/README.zh.md
@@ -144,17 +144,17 @@ V3 未知内容标签变为 `plugin:<original-type>`，其他字段原样保留
 |---|---|
 | 一个 version 1 descriptor | 要求字符串 provider 与 label；导出 `mode: 'continuable'`。 |
 | 一个 version 2 或 3 descriptor | 要求字符串 provider；按目录规则使用其 mode 和可选 label。 |
-| 没有 descriptor，或 descriptor 版本不受支持 | 可以保留已有父目录项；不能创建缺失项。 |
-| 多个自身 descriptor | 保留已有父目录项，不比较 mode／label；不创建缺失项。 |
+| 没有 descriptor，或 descriptor 版本不受支持 | 保留已有父目录项；否则追加模式未知的目录项。 |
+| 多个自身 descriptor | 保留已有父目录项，不比较 mode／label；否则追加模式未知的目录项。 |
 | 已有自身父目录项 | 保留条目及其扩展；要求子创建时间一致，并在恰好一个受支持的自身 descriptor 可用时比较其 mode／label。 |
 | 缺少自身父目录项，且受支持证据完整 | 追加带 child id、创建时间、mode 和可选 label 的 version-0 目录事实。 |
-| 缺少自身父目录项，且证据不完整 | 保留父 Session，不凭空创建目录项。 |
+| 缺少自身父目录项，且证据不完整 | 追加 version-1 `subagent/catalog`，记录 header 身份和未知模式，不编造标签。 |
 
-Catalog version 0 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable` 或 `one-shot` mode，以及 continuable mode 下的字符串 label；存在的 one-shot label 也必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。
+Catalog version 0 和 1 要求字符串 `childId`、非负安全整数 `childCreatedAt`、`continuable` 或 `one-shot` mode（version 1 还接受 `unknown`），以及 continuable mode 下的字符串 label；任何 mode 下存在的 label 都必须是字符串。重复的自身 child id 被拒绝。没有对应保留子日志的已有条目仍保留在父日志中。Descriptor 收集不恢复子级的旧 continuation composition，也不从工具参数恢复已删除子级。未知模式条目保留 header 身份信息，不声明子 descriptor 受支持。
 
 Stage 只把最终继承截点之后的父目录记录作为候选。每个 inherited marker 都会丢弃更早的目录候选，不解释其载荷。缺失项追加在所有源事件之后，按创建时间、child id 排序，并使用连续的新序号。时间取最后一个源事件的 time；空日志则取 header 创建时间。这些记录既不进入模型表面，也不改变继承计数。
 
-存储层提供其根目录内完整的可识别子级集合，并在准备、复用 memo 与发布时复查成员及物理版本。不完整的 descriptor 证据只阻止补填对应子 Session 的目录项。无法据此判断成员关系的不可读 header、不受支持的所选代际或源变化都会拒绝操作。本包不读取文件；[持久化层](../session-persistence-jsonl/README.zh.md)负责编码、锁、取消与发布。
+存储提供可识别的直属子证据，并在准备、memo 复用与发布时重新检查成员集合和物理修订。JSONL 提供方隔离不可读子 header、子日志解码失败和无效 descriptor 字段，同时保留其他目录项；准备父目录时不会迁移子目录。转换器仍拒绝冲突的已提供事实和发生变化的父历史。[JSONL 持久化](../session-persistence-jsonl/README.zh.md)拥有警告、来源检查与子会话错误隔离。当前 V4 读取不调用本转换器，直接校验原生目录字段、唯一性及投递归属。
 
 <a id="sequence-references"></a>
 ### 序号引用与继承
@@ -243,7 +243,7 @@ System image 接纳要求非空 attachment id、PNG／JPEG／WebP／GIF MIME 类
 | `compaction/start`、`compaction/summary`、`compaction/end` | 匹配 compaction id、源 command 和活动 turn 上下文。Summary 区间引用精确的当前表面节点且排除 protected head；成功完成需要一个 summary。继承的未完成 compaction 在 end-seed marker 处过期。 |
 | `compaction/prune` | 其区间引用精确的当前表面节点且排除 protected head；它不要求存在 compaction 事务或其所有者字段。 |
 | Compact checkpoint 替换 | 其 `compact-checkpoint` 来源标识活动 compaction。 |
-| 原生 `subagent/catalog` | 检查继承截点之后的自身 version-0 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
+| 原生 `subagent/catalog` | 检查继承截点之后的自身 version-0/version-1 载荷字段与 child id 唯一性。原生读取既不收集子日志，也不比较其物理事实；继承项不建立自身成员关系。 |
 | 继承截点与 delivery | 应用上文的 marker、坐标及代际归属规则。 |
 
 这些检查由 [relationships.ts](src/relationships.ts) 按代际拥有。完整的通用消息／信封接纳与插件拥有的消息投影还使用已安装 Session；单独的导出 V4 恢复器不能替代完整 catalog 恢复。
@@ -334,7 +334,7 @@ Fork 种子构造归核心 Session 所有，不属于此迁移。原生 V4 接
 - **历史嵌套工具结果**——当前迁移拒绝包含另一个 tool-result wrapper 的结果。原始代际保持完整，且不发布 V4 successor。后续转换器可以支持有证据的源数据场景，而不改变既定 V4 格式；[迁移 cookbook](../../../docs/cookbook/adding-a-session-format-version.zh.md#stages-and-validation) 定义了这一区别。
 - **历史扩展消费者**——带前缀的消息与结果字段保留 JSON 数据，不激活核心字段。消费者必须明确理解这些字段后才能解释它们。
 - **依赖保留的子日志**——仅凭父日志无法恢复未记录的子 id、创建时间或 descriptor。删除的子 Session 无法从工具参数恢复；已存在的父目录记录仍保留。
-- **历史目录项缺失**——没有恰好一个受支持的自身 descriptor 时，不补填父目录缺失项。子日志仍可按 id 读取；当前 V4 读取不会重新扫描子日志来补齐该条目。
+- **历史模式未知**——没有恰好一个受支持的自身 descriptor 时，缺失的父目录项记录未知模式。当前读取不重写该项；打开子会话时解析可用的 descriptor 信息，或报告该子会话的错误。
 - **存储范围**——事实只覆盖同一持久化根目录内可识别的子 Session。跨根目录导入和损坏日志修复不属于此迁移。
 
 <a id="dev-note"></a>
diff --git a/packages/session/session-format-v3-to-v4/src/facts.ts b/packages/session/session-format-v3-to-v4/src/facts.ts
index a08f2bda20..aa99fd32fa 100644
--- a/packages/session/session-format-v3-to-v4/src/facts.ts
+++ b/packages/session/session-format-v3-to-v4/src/facts.ts
@@ -6,7 +6,8 @@ import type { SessionFormatArtifact, SessionFormatJsonObject, SessionFormatJsonV
 /**
  * Collect a child's own descriptor without requiring one before its parent catalog is read.
  * @param artifact - validated historical child artifact with its exact inherited cut.
- * @returns compact child identity and descriptor evidence for catalog completion.
+ * @returns compact child identity and descriptor evidence with validated discovery fields for catalog completion.
+ * @throws SessionFormatError when a supported own descriptor has invalid discovery fields.
  */
 export function historicalChildCatalogSource(artifact: SessionFormatArtifact): SessionFormatJsonObject {
   const header = artifact.header
@@ -14,10 +15,12 @@ export function historicalChildCatalogSource(artifact: SessionFormatArtifact): S
     throw new SessionFormatUnsupportedMigrationError('catalog migration requires a subagent child with a direct parent')
   }
   const descriptors = artifact.events.filter(event => event.type === 'subagent/descriptor' && event.seq >= artifact.inheritedEventCount)
-  return {
+  const source = {
     childId: header.id, childCreatedAt: header.createdAt,
     descriptorCount: descriptors.length, descriptor: descriptors[0]?.data ?? null,
   }
+  childCatalogFact(source)
+  return source
 }
 
 /**
@@ -49,6 +52,9 @@ export function childCatalogFact(source: SessionFormatJsonObject): SessionFormat
   if (typeof descriptor['provider'] !== 'string') {
     throw new SessionFormatUnsupportedMigrationError(`${childCatalogSubject(source)} has an invalid subagent descriptor provider`)
   }
+  if (descriptor['version'] !== 1 && descriptor['mode'] !== 'continuable' && descriptor['mode'] !== 'one-shot') {
+    throw new SessionFormatUnsupportedMigrationError(`${childCatalogSubject(source)} has an invalid subagent descriptor mode`)
+  }
   return catalogFact({
     version: 0, childId: id, childCreatedAt: source['childCreatedAt'] as number,
     // V1 described only continuable children and carried no mode field.
@@ -64,12 +70,13 @@ export function childCatalogFact(source: SessionFormatJsonObject): SessionFormat
  * @returns validated catalog payload.
  */
 export function catalogFact(value: SessionFormatJsonValue, subject = 'subagent/catalog'): SessionFormatJsonObject {
-  if (!isSessionFormatJsonObject(value) || value['version'] !== 0
+  if (!isSessionFormatJsonObject(value) || (value['version'] !== 0 && value['version'] !== 1)
     || typeof value['childId'] !== 'string'
-    || (value['mode'] !== 'continuable' && value['mode'] !== 'one-shot')
+    || (value['mode'] !== 'continuable' && value['mode'] !== 'one-shot' && value['mode'] !== 'unknown')
+    || (value['version'] === 0 && value['mode'] === 'unknown')
     || (value['mode'] === 'continuable' && typeof value['label'] !== 'string')
     || (value['label'] !== undefined && typeof value['label'] !== 'string')) {
-    throw new SessionFormatError(`${subject} requires a complete version 0 catalog fact`)
+    throw new SessionFormatError(`${subject} requires a supported versioned catalog fact`)
   }
   sessionFormatCount(value['childCreatedAt'], 'catalog child creation time')
   return value
diff --git a/packages/session/session-format-v3-to-v4/src/migration.ts b/packages/session/session-format-v3-to-v4/src/migration.ts
index 3b1c1de60a..c2a28e04b2 100644
--- a/packages/session/session-format-v3-to-v4/src/migration.ts
+++ b/packages/session/session-format-v3-to-v4/src/migration.ts
@@ -122,9 +122,10 @@ class ReleasedV3ToV4Stage implements SessionFormatMigrationStage {
         }
         continue
       }
-      if (fact === undefined) continue
-      existingCatalogs.set(id, fact)
-      context.emitEvent({ type: 'subagent/catalog', seq: this.nextSeq++, time: this.time, data: fact })
+      const entry = fact ?? { version: 1, childId: id, childCreatedAt: source['childCreatedAt'] as number, mode: 'unknown' }
+      existingCatalogs.set(id, entry)
+      context.emitEvent({ type: 'subagent/catalog',
+        seq: this.nextSeq++, time: this.time, data: entry })
     }
     return cut
   }
diff --git a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
index 7b1ad7e3c0..455535ed79 100644
--- a/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/catalog-completion.spec.ts
@@ -67,14 +67,14 @@ describe('V3 parent catalog completion', () => {
     expect(migrate(source, [child], true).events).toEqual([
       ...source, { type: 'subagent/catalog', seq: 4, time: 2, data: child },
     ])
-    expect(() => migrate([...source, { ...opaque, seq: 4 }], [], true)).toThrow('complete version 0')
-    expect(() => migrate([opaque], [])).toThrow('complete version 0')
+    expect(() => migrate([...source, { ...opaque, seq: 4 }], [], true)).toThrow('supported versioned')
+    expect(() => migrate([opaque], [])).toThrow('supported versioned')
   })
 
   it('requires explicit corpus facts and refuses conflicting identities', () => {
     expect(() => sessionFormatV3ToV4.createStage({ sourceHeader: header, targetHeader: { ...header, version: 4 },
       sourceKind: 'decoded', sourceInheritedEventCount: 0 })).toThrow('explicit historical child facts')
-    expect(() => migrate([], [{ ...child, mode: 'unknown' }])).toThrow('complete version 0')
+    expect(() => migrate([], [{ ...child, mode: 'invalid' }])).toThrow('supported versioned')
     expect(() => migrate([{ type: 'subagent/catalog', seq: 0, time: 2, data: child }], [{ ...child, childCreatedAt: 3 }])).toThrow('conflicts')
   })
 
@@ -88,8 +88,8 @@ describe('V3 parent catalog completion', () => {
       ],
     }
     expect(childCatalogFact(historicalChildCatalogSource(artifact))).toEqual(child)
-    expect(migrate([], [historicalChildCatalogSource({ ...artifact, inheritedEventCount: 0 })]).events).toEqual([])
-    expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [] })]).events).toEqual([])
+    expect(migrate([], [historicalChildCatalogSource({ ...artifact, inheritedEventCount: 0 })]).events).toMatchObject([{ data: { childId: 'child', mode: 'unknown' } }])
+    expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [] })]).events).toMatchObject([{ data: { childId: 'child', mode: 'unknown' } }])
   })
   it('orders tied and differently dated children independently of directory enumeration', () => {
     const children = [{ ...child, childId: 'z' }, { ...child, childId: 'a' }, { ...child, childId: 'first', childCreatedAt: 1 }]
@@ -114,13 +114,13 @@ describe('V3 parent catalog completion', () => {
     expect(() => migrate([preceding, { ...delivery, data: { ...delivery.data, sessionFormatVersion: 3 } }], [])).toThrow('wrong Session')
   })
 
-  it('skips unavailable descriptors while requiring complete discovery fields for new facts', () => {
+  it('retains unknown children while validating available descriptor fields', () => {
     const artifact = { header: { ...header, origin: 'subagent' as const, parentSession: 'parent' }, inheritedEventCount: 0, events: [] }
     expect(() => historicalChildCatalogSource({ ...artifact, header })).toThrow('direct parent')
     for (const data of [null, {}, { version: 4, mode: 'one-shot', provider: 'spawn' }]) {
-      expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [{ type: 'subagent/descriptor', seq: 0, time: 1, data }] })]).events).toEqual([])
+      expect(migrate([], [historicalChildCatalogSource({ ...artifact, events: [{ type: 'subagent/descriptor', seq: 0, time: 1, data }] })]).events).toMatchObject([{ data: { childId: 'parent', mode: 'unknown' } }])
     }
-    for (const value of [null, { ...child, version: 1 }, { ...child, childId: null },
+    for (const value of [null, { ...child, version: 2 }, { ...child, childId: null },
       { ...child, label: null }, { ...child, childCreatedAt: -1 }]) {
       expect(() => migrate([], [value])).toThrow()
     }
@@ -148,7 +148,8 @@ describe('V3 parent catalog completion', () => {
     const unavailable = { childId: 'unavailable', childCreatedAt: 1,
       descriptorCount: kind === 'missing' ? 0 : kind === 'multiple' ? 2 : 1, descriptor }
     expect(migrate([], [child, unavailable]).events).toEqual([
-      { type: 'subagent/catalog', seq: 0, time: 1, data: child },
+      { type: 'subagent/catalog', seq: 0, time: 1, data: { version: 1, childId: 'unavailable', childCreatedAt: 1, mode: 'unknown' } },
+      { type: 'subagent/catalog', seq: 1, time: 1, data: child },
     ])
   })
 
diff --git a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
index 2d3c447842..7142c6ab45 100644
--- a/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
+++ b/packages/session/session-format-v3-to-v4/tests/validation.spec.ts
@@ -113,6 +113,22 @@ describe('restoreReleasedV4Artifact', () => {
       .toThrow(/unseeded format v4 Session has inherited events/)
   })
 
+  it('retains unknown child membership and rejects invalid identities or duplicate child ids', () => {
+    const known = new Set([...KNOWN, 'subagent/catalog'])
+    const data = { version: 1, childId: 'unreadable', childCreatedAt: 2, mode: 'unknown' }
+    const event = { type: 'subagent/catalog', seq: 0, time: 1, data }
+    const valid = artifact([event])
+    expect(restoreReleasedV4Artifact(valid, known)).toBe(valid)
+    expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: { ...data, label: 'retained' } }]), known)).not.toThrow()
+    for (const invalid of [null, { ...data, version: 0 }, { ...data, version: 2 }, { ...data, childId: 1 },
+      { ...data, childCreatedAt: -1 }, { ...data, mode: 'invalid' }, { ...data, label: null }]) {
+      expect(() => restoreReleasedV4Artifact(artifact([{ ...event, data: invalid }]), known)).toThrow()
+    }
+    expect(() => restoreReleasedV4Artifact(artifact([event, { ...event, seq: 1 }]), known)).toThrow('duplicate catalog child')
+    expect(() => restoreReleasedV4Artifact(artifact([event, { type: 'subagent/catalog', seq: 1, time: 1,
+      data: { ...data, mode: 'one-shot' } }]), known)).toThrow('duplicate catalog child')
+  })
+
   it('validates only the envelope in physical mode', () => {
     const unknown = conversation()
     unknown.splice(2, 0, { type: 'campaign/unknown', seq: 0, time: 1, data: { x: 1 } })
diff --git a/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts b/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts
index 7bf73bc369..2a91b33f33 100644
--- a/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts
+++ b/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts
@@ -53,7 +53,7 @@ it('uploads freeform feedback and message put/edit/delete through the unchanged
       : name === '@deepseek-ai/dsh-message-feedback'
         ? { config: { maxNoteBytes: 1024 } }
         : name === '@deepseek-ai/dsh-llm-deepseek'
-          ? { config: { protocol: 'chat-completions', baseURL: server!.baseURL } }
+          ? { config: { baseURL: server!.baseURL } }
           : name === '@deepseek-ai/dsh-session-log-deepseek'
             ? { config: { enabled: true } }
             : {},
@@ -128,11 +128,11 @@ it('uploads freeform feedback and message put/edit/delete through the unchanged
     expect(session.deriveMessages()).toEqual(messages)
     expect(await ctx.messageFeedback.list({ sessionId: session.id })).toEqual({ ok: true, value: { items: [] } })
     for (const wire of server.requests) {
-      expect(wire.path).toBe('/chat/completions')
+      expect(wire.path).toBe('/v1/messages')
       expect(wire.body).not.toHaveProperty('dsh_feedback')
       expect(wire.body).toMatchObject({ model: 'deepseek-v4-flash', messages: [
-        { role: 'user', content: 'Question' },
-        { role: 'assistant', content: 'Answer' },
+        { role: 'user', content: [{ type: 'text', text: 'Question' }] },
+        { role: 'assistant', content: [{ type: 'text', text: 'Answer' }] },
       ] })
     }
     await ctx.sessions.flush(session)
diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml
index 1589a1d5c7..4b42d7fa5e 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: 96c333d9f845943ff44c8d5d539c40d07b9dc0f6
-README.zh.md: 71126dd909c92aabdee5c07d23505f708dc5e038
+README.md: 5846404961caaef7a91fb4dda562655d15fd2be9
+README.zh.md: b7dd646e57b75fe47f3683d2b230dace628f8eee
diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md
index 96c333d9f8..5846404961 100644
--- a/packages/session/session-persistence-jsonl/README.md
+++ b/packages/session/session-persistence-jsonl/README.md
@@ -81,7 +81,7 @@ The current-generation scanner applies the current codec owner’s structural ad
 
 `open(id, 'read'|'write')` selects the highest canonical generation. Current input follows the ordinary fast path. For historical input, a read open decodes and migrates the source once, validates the current logical result, and returns it without publishing a successor. A write open reuses that revision-keyed preparation when available, or performs the same preparation, then encodes a same-directory temporary file in bounded chunks, verifies it in a Worker Thread, rechecks the source revision, and publishes the current successor without overwrite before returning. The source remains byte-identical. Source drift after preparation rejects that write open without replacing the logical history already returned to readers; a later write open prepares the new revision. The backend marks decoded event graphs `shared-frozen` when it freezes them before memoization; every nested object and array is frozen, and handle reads and slices preserve that state, including empty slices. Only an unmaterialized pending log reports `detached`. `stat(id)` and `list()` select and translate only the highest generation header without reading event rows or starting migration; snapshots carry the selected file’s `sizeBytes` and a best-effort revision. Current revisions identify that file; historical revisions also fingerprint the selected files across the persistence root, so child changes invalidate cached logical events. Fingerprinting reads filesystem metadata only; unrelated changes conservatively invalidate historical revisions. One `list()` call shares a corpus fingerprint across its historical entries. With `compression: 'none'`, the log is newline-delimited text an external reader can consume directly; the compressed default must be read through the backend.
 
-Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It scans headers, decodes only direct children one at a time, and retains compact descriptor evidence plus source revisions. It rechecks membership and revisions before returning preparation, reusing it, and publishing. Source drift invalidates preparation: read open retries preparation once automatically, while write open refuses publication. Diagnostics name the changed, added, removed, or unreadable child path. An unsupported selected generation or unreadable header anywhere else in the scan refuses migration because it cannot establish complete membership. Ordinary listing still skips those files. Missing, unsupported, or multiple child descriptors prevent only that child’s catalog backfill; existing parent entries and child logs remain available. Invalid fields in exactly one supported own descriptor still report an unsupported format; malformed child events, JSON records, and compressed data report corruption at the child path. Filesystem errors and cancellation retain their original errors. Current V4 opens bypass this scan and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
+Historical body preparation completes the parent catalog through [V3→V4](../session-format-v3-to-v4/README.md). It finds candidate direct children from headers, reads each child's own descriptor through historical codecs, and retains compact evidence plus source revisions. It neither prepares child catalogs nor publishes child successors. Unreadable or unsupported headers, including corrupt Zstandard header frames, are omitted from discovery and `list()`. Direct access to a corrupt compressed header still rejects; header I/O and cancellation errors propagate. Child decoding and descriptor-field failures produce warnings naming the child path and retain header identity through `subagent/catalog` when the parent has no complete entry; healthy children and existing parent catalog entries remain available. Opening a damaged child still reports that child's error. Missing, unsupported, or multiple descriptors likewise produce unknown-mode membership without inventing a label. Published unknown entries remain browsable; child history reads retry the actual log and resolve its mode from a valid descriptor. Preparation rechecks membership and inspected source revisions before returning, reuse, and publication, including failed child reads so a repaired child invalidates stale preparation. Source drift retries a read open once and refuses a write open. Cancellation still aborts the operation. Current V4 opens bypass discovery and validate catalog fields, uniqueness, and current delivery ownership before exposing events.
 
 Historical `stat` and `list` revisions require metadata work proportional to the root’s Session count. Fresh body preparation scans all selected headers and decodes direct-child bodies; memo reuse still scans membership and checks revisions. Read-only access never publishes an upgrade, so cold processes and evicted preparations repeat that work. Current V4 body reads and revisions avoid the historical corpus scan. See the [measured costs and diagnostic command](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md#catalog-scan-measurements).
 
diff --git a/packages/session/session-persistence-jsonl/README.zh.md b/packages/session/session-persistence-jsonl/README.zh.md
index 71126dd909..b7dd646e57 100644
--- a/packages/session/session-persistence-jsonl/README.zh.md
+++ b/packages/session/session-persistence-jsonl/README.zh.md
@@ -81,7 +81,7 @@ kind: "package-reference"
 
 `open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；每个嵌套对象和数组都会冻结，句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的修订号。当前格式修订号标识该文件；历史格式修订号还包含持久化根目录中所选文件的指纹，因此子日志变化会使缓存的逻辑事件失效。指纹只读取文件系统元数据；无关变化也会保守地使历史修订号失效。一次 `list()` 为其历史条目共用一个全库指纹。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
-历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：扫描 header，仅逐个解码直属子 Session，保留紧凑的 descriptor 证据及来源修订。在准备返回、复用和发布前重新检查成员集合与修订。来源变化会使准备缓存失效：只读打开自动重新准备一次，写打开则拒绝发布。诊断指出发生变化、新增、删除或无法读取的子日志路径。扫描中其他任何被选中的不支持代际或不可读 header 都会拒绝迁移，因为无法确认成员集合完整。普通列举仍跳过这些文件。子 descriptor 缺失、版本不受支持或存在多个时，只跳过该子 Session 的目录补填；已有父目录项和子日志仍可读取。恰好一个受支持的自身 descriptor 字段无效时，仍会报告格式不支持；子事件、JSON 记录或压缩数据畸形会在子日志路径报告损坏。文件系统错误与取消保留原始错误。当前 V4 打开跳过此扫描，并在暴露事件之前检查目录字段、唯一性及当前投递归属。
+历史正文准备通过 [V3→V4](../session-format-v3-to-v4/README.zh.md) 补齐父目录：从 header 找到候选直属子 Session，通过历史编解码器逐个读取其自身 descriptor，保留紧凑证据与来源修订。此过程不准备子目录，也不发布子后继。不可读或不支持的 header（包括损坏的 Zstandard header 帧）不参与发现，也不出现在 `list()` 中。直接访问损坏的压缩 header 仍会失败；header 的 I/O 错误与取消错误继续传播。子日志解码或 descriptor 字段失败会产生带子路径的警告；父目录没有完整条目时，通过 `subagent/catalog` 保留 header 身份信息。健康子项和已有父目录项仍可使用。打开损坏子 Session 时仍报告该子会话的错误。缺失、不支持或多个 descriptor 同样生成模式未知的目录项，不编造标签。已发布的未知条目仍可浏览；读取子历史时会重试实际日志，并从有效 descriptor 确定模式。准备返回、复用与发布前会重新检查成员集合及已检查来源的修订，也包括读取失败的子日志，使修复后的子日志能够使旧准备缓存失效。来源变化时只读打开重试一次，写打开拒绝发布。取消仍会中止操作。当前 V4 打开跳过发现，并在暴露事件前校验目录字段、唯一性及当前投递归属。
 
 历史格式的 `stat` 与 `list` 修订号需要与根目录 Session 数量成正比的元数据工作。首次正文准备扫描所有所选 header 并解码直属子正文；复用准备缓存仍扫描成员集合并检查修订。只读访问从不发布升级，因此冷进程与被淘汰的准备缓存会重复这些工作。当前 V4 正文读取和修订号避开历史全库扫描。见[实测成本与诊断命令](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md#catalog-scan-measurements)。
 
diff --git a/packages/session/session-persistence-jsonl/src/catalog-migration.ts b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
index 77e3d8b43e..f0aefc057f 100644
--- a/packages/session/session-persistence-jsonl/src/catalog-migration.ts
+++ b/packages/session/session-persistence-jsonl/src/catalog-migration.ts
@@ -4,8 +4,7 @@ import { stat } from 'node:fs/promises'
 import { basename } from 'node:path'
 import { historicalSessionFormatCatalog, sessionFormatCatalog } from '@deepseek-ai/dsh-session-format-catalog'
 import { historicalChildCatalogSource } from '@deepseek-ai/dsh-session-format-v3-to-v4'
-import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError } from '@deepseek-ai/dsh-session-persistence'
-import { SessionFormatError, SessionFormatUnsupportedMigrationError } from '@deepseek-ai/dsh-session-format'
+import { SessionFormatUnsupportedMigrationError } from '@deepseek-ai/dsh-session-format'
 import type { SessionFormatJsonObject } from '@deepseek-ai/dsh-session-format'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import { parseGenerationLogFilename } from './format.ts'
@@ -16,7 +15,8 @@ import type { JsonlPhysicalIdentity } from './generation.ts'
 /** Per-parent supplemental facts and the source checks required before serving or publishing them. */
 interface PreparedCatalogFacts {
   readonly facts: readonly SessionFormatJsonObject[]
-  /** @returns resolves while every decoded child still has the captured physical revision. */
+  readonly failures: readonly { readonly path: string; readonly error: unknown }[]
+  /** @returns resolves while every inspected child still has the captured physical revision. */
   validate(): Promise<void>
 }
 
@@ -26,7 +26,7 @@ interface PreparedCatalogFacts {
  * @param sources - header-indexed direct children in the selected source corpus.
  * @param compression - configured source encoding.
  * @param signal - cancellation forwarded through each source read.
- * @returns compact facts; complete child event arrays are released after extraction.
+ * @returns compact facts and child-local failures; complete child event arrays are released after extraction.
  */
 export async function prepareCatalogFacts(
   parentId: SessionId,
@@ -35,11 +35,18 @@ export async function prepareCatalogFacts(
   signal: AbortSignal,
 ): Promise<PreparedCatalogFacts> {
   const facts: SessionFormatJsonObject[] = []
+  const failures: { path: string; error: unknown }[] = []
   const witnesses: { path: string; identity: JsonlPhysicalIdentity }[] = []
   for (const source of sources) {
     signal.throwIfAborted()
     const version = parseGenerationLogFilename(basename(source.path), compression)
     if (version === undefined) throw new SessionFormatUnsupportedMigrationError(`unrecognized historical child generation ${source.path}`)
+    const witness: { path: string; identity: JsonlPhysicalIdentity } = {
+      path: source.path, identity: await stat(source.path, { bigint: true }),
+    }
+    witnesses.push(witness)
+    const unavailable = { childId: source.header.id, childCreatedAt: source.header.createdAt,
+      descriptorCount: 0, descriptor: null, sourcePath: source.path }
     let restored: Awaited<ReturnType<typeof readDecodedJsonlSource>>
     try {
       restored = await readDecodedJsonlSource(source.path, version, compression, {
@@ -48,28 +55,31 @@ export async function prepareCatalogFacts(
         }),
       }, signal)
     } catch (error: unknown) {
-      if (error instanceof SessionFormatUnsupportedMigrationError) {
-        throw new SessionFormatUnsupportedError(
-          `child Session ${source.header.id}: ${error.message} (raw log: ${source.path})`,
-          { kind: 'jsonl', path: source.path },
-        )
-      }
-      if (error instanceof SessionFormatError) {
-        throw new SessionPersistenceCorruptionError(`child Session ${source.header.id}: ${error.message} (raw log: ${source.path})`, { cause: error })
-      }
-      throw error
+      signal.throwIfAborted()
+      failures.push({ path: source.path, error })
+      facts.push(unavailable)
+      continue
     }
+    witness.identity = restored.identity
     const header = restored.artifact.header
     if (header.id !== source.header.id || header.createdAt !== source.header.createdAt
       || header.parentSession !== parentId || header.origin !== 'subagent'
       || ['cwd', 'isSeeded', 'delegationDepth', 'agentPreset'].some(key => header[key] !== source.header[key as keyof SessionHeader])) {
       throw new JsonlGenerationSourceChangedError(source.path)
     }
-    facts.push({ ...historicalChildCatalogSource(restored.artifact), sourcePath: source.path })
-    witnesses.push({ path: source.path, identity: restored.identity })
+    let fact: SessionFormatJsonObject
+    try {
+      fact = historicalChildCatalogSource(restored.artifact)
+    } catch (error: unknown) {
+      failures.push({ path: source.path, error })
+      facts.push(unavailable)
+      continue
+    }
+    facts.push({ ...fact, sourcePath: source.path })
   }
   return {
     facts,
+    failures,
     async validate() {
       for (const witness of witnesses) {
         const current = await stat(witness.path, { bigint: true })
diff --git a/packages/session/session-persistence-jsonl/src/index.ts b/packages/session/session-persistence-jsonl/src/index.ts
index 6e7e7b5628..1a89b76d29 100644
--- a/packages/session/session-persistence-jsonl/src/index.ts
+++ b/packages/session/session-persistence-jsonl/src/index.ts
@@ -629,10 +629,13 @@ class JsonlSessionPersistence extends SessionPersistence {
     let prepared: Awaited<ReturnType<typeof prepareJsonlMigration>>
     let validateRelatedSources: () => Promise<void>
     try {
-      const children = async () => (await this.listArtifacts(signal, selected.sourcePath))
+      const children = async () => (await this.listArtifacts(signal))
         .filter(source => source.header.origin === 'subagent' && source.header.parentSession === id)
       const sources = await children()
       const related = await prepareCatalogFacts(id, sources, this.compression, signal)
+      for (const failure of related.failures) {
+        this.ctx.logger.warn(`${this.name}: session "${id}" catalog retained a child with unknown descriptor (raw log: ${failure.path}): ${String(failure.error)}`)
+      }
       const membership = sources.map(source => source.path).sort()
       validateRelatedSources = async () => {
         const current = (await children()).map(source => source.path).sort()
@@ -1052,7 +1055,6 @@ class JsonlSessionPersistence extends SessionPersistence {
 
   private async listArtifacts(
     signal?: AbortSignal,
-    migrationSource?: string,
   ): Promise<Array<{ header: SessionHeader; path: string; sourceVersion: number }>> {
     signal?.throwIfAborted()
     await this.ensureRootEncoding()
@@ -1061,26 +1063,14 @@ class JsonlSessionPersistence extends SessionPersistence {
     const ids = new Set<SessionId>()
     for (const selected of await this.listGenerations(signal)) {
       signal?.throwIfAborted()
-      if (migrationSource !== undefined && selected.sourceVersion > SESSION_FORMAT_VERSION) {
-        throw new SessionFormatUnsupportedError(
-          `catalog migration cannot inspect Session format v${selected.sourceVersion}; upgrade the harness (raw log: ${selected.sourcePath})`,
-          { kind: 'jsonl', path: selected.sourcePath },
-        )
-      }
       let header: SessionHeader | undefined
       try {
         header = await this.readGenerationHeader(selected, undefined, signal)
       } catch (error: unknown) {
-        if (error instanceof SessionFormatUnsupportedError && migrationSource === undefined) continue
+        if (error instanceof SessionFormatUnsupportedError || error instanceof SessionPersistenceCorruptionError) continue
         throw error
       }
       if (header === undefined) {
-        if (migrationSource !== undefined && selected.sourcePath !== migrationSource) {
-          throw new SessionFormatUnsupportedError(
-            `cannot establish complete catalog membership from an unreadable Session header (raw log: ${selected.sourcePath})`,
-            { kind: 'jsonl', path: selected.sourcePath },
-          )
-        }
         continue
       }
       if (ids.has(header.id)) {
@@ -1416,7 +1406,7 @@ class JsonlSessionPersistence extends SessionPersistence {
     }
   }
 
-  /** Read and validate only the independently compressed header frame. */
+  /** Read only the header frame; compression failures reject as corruption, while I/O and cancellation propagate. */
   private async readFirstZstdLine(path: string, signal?: AbortSignal): Promise<string | undefined> {
     signal?.throwIfAborted()
     const handle = await open(path, 'r')
@@ -1432,21 +1422,21 @@ class JsonlSessionPersistence extends SessionPersistence {
         signal?.throwIfAborted()
         content = Buffer.concat([content, chunk.subarray(0, bytesRead)])
         signal?.throwIfAborted()
-        const first = scanZstdFrames(content, 1).frames[0]
-        signal?.throwIfAborted()
-        if (first === undefined) continue
-        let plaintext: Buffer
         try {
+          const first = scanZstdFrames(content, 1).frames[0]
+          if (first === undefined) continue
+          const plaintext = await decompressZstdFrame(content.subarray(first.start, first.end))
           signal?.throwIfAborted()
-          plaintext = await decompressZstdFrame(content.subarray(first.start, first.end))
+          assertZstdHeaderFrame(plaintext)
+          return plaintext.subarray(0, -1).toString('utf8')
         } catch (error) {
           /* v8 ignore next -- decoder failure plus concurrent abort is timing-dependent */
           if (signal?.aborted) signal.throwIfAborted()
-          throw new Error('corrupt Zstandard session log: header frame failed validation', { cause: error })
+          throw new SessionPersistenceCorruptionError(
+            `corrupt Zstandard session log: header frame failed validation: ${String(error)} (raw log: ${path})`,
+            { cause: error },
+          )
         }
-        signal?.throwIfAborted()
-        assertZstdHeaderFrame(plaintext)
-        return plaintext.subarray(0, -1).toString('utf8')
       }
     } finally {
       await handle.close()
diff --git a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
index af86cdbfe6..6abb14c0db 100644
--- a/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/catalog-migration.spec.ts
@@ -2,7 +2,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { SessionId, type SessionHeader } from '@deepseek-ai/dsh-session'
 import { SessionFormatUnsupportedError, SessionPersistenceCorruptionError } from '@deepseek-ai/dsh-session-persistence'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -14,6 +14,7 @@ const roots: string[] = []
 const contexts: Context[] = []
 
 afterEach(async () => {
+  vi.restoreAllMocks()
   await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
   await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })))
 })
@@ -57,16 +58,36 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     await expect(f.ctx.sessionPersistence.open(f.parent, access)).rejects.toThrow('wrong Session')
   })
 
-  it('does not publish incomplete membership after a child header becomes unreadable', async () => {
-    const f = await fixture()
-    const path = await f.write('child', [], true)
-    const broken = '{broken header\n'
-    await writeFile(path, compression === 'none' ? broken : await compressZstdFrame(broken))
-    await expect(f.read()).rejects.toThrow(path)
-    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(path)
-    expect((await readdir(dirname(generationLogPath(f.root, undefined, f.parent, 3, compression)))).filter(name => name !== 'session.lock'))
-      .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
-  })
+  it.each(compression === 'none' ? ['json'] as const : ['json', 'magic', 'checksum', 'lines'] as const)(
+    'opens the parent when another Session header has corrupt %s', async (damage) => {
+      const f = await fixture()
+      await f.write('child', [f.descriptor], true)
+      const path = await f.write('unrelated', [])
+      let damaged: Buffer
+      if (damage === 'json') {
+        damaged = compression === 'none' ? Buffer.from('{broken header\n') : await compressZstdFrame('{broken header\n')
+      } else if (damage === 'lines') {
+        damaged = await compressZstdFrame('{}\n{}\n')
+      } else {
+        damaged = await readFile(path)
+        const offset = damage === 'magic' ? 0 : damaged.length - 1
+        damaged[offset] = damaged[offset]! ^ 0xFF
+      }
+      await writeFile(path, damaged)
+      expect((await f.ctx.sessionPersistence.list()).map(row => row.header.id).sort()).toEqual(['child', f.parent])
+      const expected = [{ type: 'subagent/catalog', data: { childId: 'child', mode: 'continuable', label: 'old child' } }]
+      expect(await f.read()).toMatchObject(expected)
+      const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+      try { expect((await writer.read()).events).toMatchObject(expected) } finally { await writer.close() }
+      expect(await readFile(generationLogPath(f.root, undefined, f.parent, 4, compression))).not.toHaveLength(0)
+      for (const access of ['read', 'write'] as const) {
+        await expect(f.ctx.sessionPersistence.open(SessionId('unrelated'), access)).rejects.toThrow()
+      }
+      expect(await readFile(path)).toEqual(damaged)
+      await expect(readFile(generationLogPath(f.root, undefined, SessionId('unrelated'), 4, compression)))
+        .rejects.toMatchObject({ code: 'ENOENT' })
+    },
+  )
 
   it('invalidates lightweight revisions on child membership and contents while retaining stable tokens', async () => {
     const f = await fixture()
@@ -114,34 +135,35 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect((await f.ctx.sessionPersistence.list()).find(row => row.header.id === f.parent)?.revision).not.toBe(removed)
   })
 
-  it('reports a corrupt child body at the child location', async () => {
+  it('isolates a corrupt child catalog and reports its path', async () => {
     const f = await fixture()
+    const warn = vi.spyOn(f.ctx.logger, 'warn')
     const catalog = { type: 'subagent/catalog', seq: 0, time: 1,
       data: { version: 0, childId: 'grandchild', childCreatedAt: 3, mode: 'one-shot' } }
     const path = await f.write('child', [catalog, { ...catalog, seq: 1 }], true, 4)
-    await expect(f.read()).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
-    await expect(f.read()).rejects.toThrow(path)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
   })
 
-  it.each(['read', 'write'] as const)('locates physical child JSON corruption during %s access', async (access) => {
+  it.each(['read', 'write'] as const)('isolates malformed child JSON during parent %s access', async (access) => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
     const first = JSON.stringify({ ...f.header, id: 'child', origin: 'subagent', parentSession: f.parent, delegationDepth: 1 }) + '\n'
-    // A sealed turn makes the malformed row corruption rather than a recoverable tail.
     const body = '{broken\n' + JSON.stringify({ type: 'turn/end', seq: 1, time: 2,
       data: { turn: 1, reason: { kind: 'completed' } } }) + '\n'
     await writeFile(childPath, compression === 'none' ? first + body
       : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
-    const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
-    const original = await Promise.all([readFile(parentPath), readFile(childPath)])
-    const error: unknown = await f.ctx.sessionPersistence.open(f.parent, access).catch((error: unknown) => error)
-    expect(error).toBeInstanceOf(SessionPersistenceCorruptionError)
-    expect((error as Error).message).toContain(childPath)
-    expect((error as Error).message).not.toContain(parentPath)
-    expect((error as Error).message).toContain('row 1 is not valid JSON')
-    expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
-    expect((await readdir(dirname(parentPath))).filter(name => name !== 'session.lock'))
-      .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
+    const original = await readFile(childPath)
+    await f.write('healthy', [f.descriptor], true)
+    const parent = await f.ctx.sessionPersistence.open(f.parent, access)
+    try { expect((await parent.read()).events).toMatchObject([
+      { type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } },
+      { type: 'subagent/catalog', data: { childId: 'healthy', mode: 'continuable' } },
+    ]) } finally { await parent.close() }
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), access)).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
+    expect(await readFile(childPath)).toEqual(original)
+    await expect(readFile(generationLogPath(f.root, undefined, SessionId('child'), 4, compression))).rejects.toMatchObject({ code: 'ENOENT' })
   })
 
   it('preserves opaque inherited catalogs through read preparation and write publication', async () => {
@@ -165,21 +187,20 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     expect(await readFile(parentPath)).toEqual(original)
   })
 
-  it.skipIf(compression !== 'zstd')('locates invalid compressed child frames at the child path', async () => {
+  it.skipIf(compression !== 'zstd')('isolates invalid compressed child frames', async () => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
     await writeFile(childPath, Buffer.concat([await readFile(childPath), Buffer.alloc(8)]))
-    const error: unknown = await f.read().catch((error: unknown) => error)
-    expect(error).toBeInstanceOf(SessionPersistenceCorruptionError)
-    expect((error as Error).message).toContain(childPath)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionPersistenceCorruptionError)
   })
 
-  it('keeps a complete parent catalog when a published child never writes a descriptor', async () => {
+  it.each([false, true])('keeps a complete parent catalog when child metadata is unavailable (corrupt=%s)', async (corrupt) => {
     const f = await fixture()
     const catalog = { type: 'subagent/catalog', seq: 0, time: 2,
       data: { version: 0, childId: 'child', childCreatedAt: 2, mode: 'one-shot', label: 'failed startup' } }
     const parentPath = await f.write(f.parent, [catalog])
-    const childPath = await f.write('child', [], true)
+    const childPath = await f.write('child', corrupt ? [{ type: 'future/required', seq: 0, time: 2, data: {} }] : [], true)
     const original = await Promise.all([readFile(parentPath), readFile(childPath)])
     expect(await f.read()).toEqual([catalog])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
@@ -208,10 +229,10 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const childPath = await f.write('child', events, true)
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
     const original = await Promise.all([readFile(parentPath), readFile(childPath)])
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
-    try { expect((await writer.read()).events).toEqual([]) } finally { await writer.close() }
-    expect(await f.read()).toEqual([])
+    try { expect((await writer.read()).events).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }]) } finally { await writer.close() }
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
     try { expect((await child.read()).events).toEqual(events) } finally { await child.close() }
     expect(await Promise.all([readFile(parentPath), readFile(childPath)])).toEqual(original)
@@ -219,35 +240,37 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
       .toEqual(compression === 'none' ? ['session.v3.jsonl', 'session.v4.jsonl'] : ['session.v3.jsonl.zstd', 'session.v4.jsonl.zstd'])
   })
 
-  it.each([false, true])('refuses an opaque future generation before publishing membership (prepared=%s)', async (prepared) => {
+  it.each([false, true])('omits an unsupported child generation (prepared=%s)', async (prepared) => {
     const f = await fixture()
     await f.write('child', [f.descriptor], true)
     if (prepared) expect(await f.read()).toHaveLength(1)
     await f.write('child', [], true, 5)
-    await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-    expect((await readdir(dirname(generationLogPath(f.root, undefined, f.parent, 3, compression)))).filter(name => name !== 'session.lock'))
-      .toEqual([compression === 'none' ? 'session.v3.jsonl' : 'session.v3.jsonl.zstd'])
+    expect(await f.read()).toEqual([])
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
   })
 
-  it('requires a readable corpus even when an unknown header cannot identify its parent', async () => {
+  it('opens the parent independently of an unrelated future generation', async () => {
     const f = await fixture()
     await f.write('future-root', [], false, 5)
     expect((await f.ctx.sessionPersistence.list()).map(row => row.header.id)).toEqual([f.parent])
-    await expect(f.read()).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
+    expect(await f.read()).toEqual([])
   })
 
-  it('preserves unsupported child decoding errors instead of reporting parent corruption', async () => {
+  it('retains unknown child identity without migrating unsupported contents', async () => {
     const f = await fixture()
-    const path = await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
-    await expect(f.read()).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-    await expect(f.read()).rejects.toThrow(path)
+    await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
+    await expect(f.ctx.sessionPersistence.open(SessionId('child'), 'read')).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
   })
 
-  it('locates incomplete historical descriptor fields at their child source', async () => {
+  it('retains unknown child identity and reports invalid descriptor fields', async () => {
     const f = await fixture()
+    const warn = vi.spyOn(f.ctx.logger, 'warn')
     const path = await f.write('child', [{ ...f.descriptor, data: { version: 2, provider: 'spawn', mode: 'unknown' } }], true)
-    await expect(f.read()).rejects.toBeInstanceOf(SessionFormatUnsupportedError)
-    await expect(f.read()).rejects.toThrow(path)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(path))
   })
 
   it.each(['read', 'write'] as const)('rejects duplicate own catalogs through a current %s open', async (access) => {
@@ -281,7 +304,7 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
   it('recollects newly available discovery fields before publishing a prepared parent', async () => {
     const f = await fixture()
     const childPath = await f.write('child', [], true)
-    expect(await f.read()).toEqual([])
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
     await f.write('child', [f.descriptor], true)
     await expect(f.ctx.sessionPersistence.open(f.parent, 'write')).rejects.toThrow(childPath)
     const parentPath = generationLogPath(f.root, undefined, f.parent, 3, compression)
@@ -377,4 +400,48 @@ describe.each(['none', 'zstd'] as const)('historical catalog publication (%s)',
     const reopened = await ctx.sessionPersistence.open(parent, 'read')
     try { expect((await reopened.read()).events).toEqual(expected) } finally { await reopened.close() }
   })
+
+  it('recollects a repaired child before publishing a prepared parent', async () => {
+    const f = await fixture()
+    await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child', mode: 'unknown' } }])
+    await f.write('child', [f.descriptor], true)
+    expect(await f.read()).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child' } }])
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+  })
+
+  it('keeps published unknown membership while a repaired child opens independently', async () => {
+    const f = await fixture()
+    await f.write('child', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    await writer.close()
+    const current = generationLogPath(f.root, undefined, f.parent, 4, compression)
+    const published = await readFile(current)
+    await f.write('child', [f.descriptor], true)
+    const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'read')
+    try { expect((await child.read()).events).toEqual([f.descriptor]) } finally { await child.close() }
+    expect(await f.read()).toMatchObject([{ data: { childId: 'child', mode: 'unknown' } }])
+    expect(await readFile(current)).toEqual(published)
+  })
+
+  it('completes only the opened parent catalog and defers its child catalog', async () => {
+    const f = await fixture()
+    const childPath = await f.write('child', [f.descriptor], true)
+    const grandchildPath = await f.write('grandchild', [{ type: 'future/required', seq: 0, time: 2, data: {} }], true)
+    // Reparent the physical fixture so only opening the child can inspect this damaged log.
+    const first = JSON.stringify({ ...f.header, id: 'grandchild', origin: 'subagent', parentSession: 'child', createdAt: 3, delegationDepth: 2 }) + '\n'
+    const body = JSON.stringify({ type: 'future/required', seq: 0, time: 3, data: {} }) + '\n'
+    await writeFile(grandchildPath, compression === 'none' ? first + body : Buffer.concat([await compressZstdFrame(first), await compressZstdFrame(body)]))
+    const warn = vi.spyOn(f.ctx.logger, 'warn')
+    const source = await readFile(childPath)
+    const writer = await f.ctx.sessionPersistence.open(f.parent, 'write')
+    try { expect((await writer.read()).events).toMatchObject([{ type: 'subagent/catalog', data: { childId: 'child' } }]) } finally { await writer.close() }
+    expect(warn).not.toHaveBeenCalled()
+    expect(await readFile(childPath)).toEqual(source)
+    await expect(readFile(generationLogPath(f.root, undefined, SessionId('child'), 4, compression))).rejects.toMatchObject({ code: 'ENOENT' })
+    const child = await f.ctx.sessionPersistence.open(SessionId('child'), 'write')
+    await child.close()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(grandchildPath))
+  })
 })
diff --git a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
index 4ec279ac61..f7b2f98628 100644
--- a/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/zstd.spec.ts
@@ -782,7 +782,7 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
     expect((await readAll(ctx.sessionPersistence, header.id)).events).toEqual([...oneTurnLog(), ...secondTurn])
   })
 
-  it('skips empty, incomplete, and non-header compressed artifacts while rejecting malformed header frames', async () => {
+  it('skips unreadable compressed headers during discovery while rejecting targeted reads', async () => {
     const root = await freshRoot()
     for (const [id, content] of [
       ['empty', Buffer.alloc(0)],
@@ -803,7 +803,7 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       JSON.stringify({ type: 'turn/start' }),
       '',
     ].join('\n')))
-    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/first frame is not exactly one header line/)
+    expect(await ctx.sessionPersistence.list()).toEqual([])
     await expect(ctx.sessionPersistence.open(twoLinesId, 'read'))
       .rejects.toThrow(/first frame is not exactly one header line/)
   })
@@ -824,7 +824,11 @@ describe('JsonlSessionPersistence: default Zstandard encoding', () => {
       .rejects.toThrow(/empty or header-less Zstandard session log/)
     await expect(ctx.sessionPersistence.open(SessionId('empty-header'), 'read'))
       .rejects.toThrow(/first frame is not exactly one header line/)
-    await expect(ctx.sessionPersistence.list()).rejects.toThrow(/header frame failed validation/)
+    expect(await ctx.sessionPersistence.list()).toEqual([])
+    await expect(ctx.sessionPersistence.stat(SessionId('bad-checksum')))
+      .rejects.toThrow(/header frame failed validation/)
+    await expect(ctx.sessionPersistence.open(SessionId('bad-checksum'), 'read'))
+      .rejects.toThrow(/frame at byte 0 failed validation/)
   })
 })
 
diff --git a/packages/session/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
index f17ec2e777..80b344c4e9 100644
--- a/packages/session/session-persistence/src/index.ts
+++ b/packages/session/session-persistence/src/index.ts
@@ -133,6 +133,9 @@ declare module '@deepseek-ai/cordis' {
  * on this backend instance observe at least that prefix.
  */
 export abstract class SessionPersistence extends Service {
+  /** Process-local instance identity, stable through Context proxies and distinct after service replacement. */
+  readonly identity: symbol = Symbol('sessionPersistence')
+
   constructor(ctx: Context) {
     super(ctx, 'sessionPersistence')
   }
diff --git a/packages/shell/bash-local/README.i18n.yaml b/packages/shell/bash-local/README.i18n.yaml
index 0b83b6bf09..72667a855c 100644
--- a/packages/shell/bash-local/README.i18n.yaml
+++ b/packages/shell/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/shell/bash-local/README.md
-README.md: 2cd69993b454a462bcbfa43175ff7dc7dba72e01
-README.zh.md: 81436511992d93a2bb81c4f3e242dd2046ec11e8
+README.md: a91eae878ec1fd6db115e11c6a4fea86763f8153
+README.zh.md: f4f5af410310086f7e639c492c31b10943e0f0c8
diff --git a/packages/shell/bash-local/README.md b/packages/shell/bash-local/README.md
index 2cd69993b4..a91eae878e 100644
--- a/packages/shell/bash-local/README.md
+++ b/packages/shell/bash-local/README.md
@@ -139,7 +139,7 @@ These limits define when this executor is a poor fit. They are current package c
 - **Unconfined by itself** — commands run with the harness process's authority; deployments needing confinement compose `dsh-bash-sandbox`, while per-call allow/deny/ask policy belongs on the tools' `pre-execute` waterfall.
 - **No persistent shell or PTY** — every call starts a fresh non-login `bash -c`; cwd-only persistence and interactive terminal sessions remain deferred until a real workflow requires them.
 - **POSIX-only** — the `bash` binary is hardcoded and the underlying service's group semantics are POSIX; Windows is unsupported.
-- **A background provider-failure note is single-delivery** — `SubprocessHandle.done` can reject before or after target execution begins, so the executor injects the stage-neutral `subprocess failed before reporting an outcome: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it.
+- **A background provider-failure note is the whole stderr stream** — `SubprocessHandle.done` can reject before or after target execution begins, and the subprocess service buffers no output for a target that never reported, so the executor serves the stage-neutral `subprocess failed before reporting an outcome: …` as the observed stderr stream (offset readers re-read it at their own offsets) and folds it into exactly one `readOutput()` delta; a consuming reader that discards that delta recovers it only through `observed.stderr`.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/shell/bash-local/README.zh.md b/packages/shell/bash-local/README.zh.md
index 8143651199..f4f5af4103 100644
--- a/packages/shell/bash-local/README.zh.md
+++ b/packages/shell/bash-local/README.zh.md
@@ -139,7 +139,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合 `dsh-bash-sandbox`，每次调用的 allow/deny/ask 策略则属于工具的 `pre-execute` waterfall（瀑布式事件）。
 - **没有持久 shell 或 PTY**——每次调用都启动全新的非登录 `bash -c`；仅持久化 cwd 与交互式终端会话均继续延期，直到真实工作流需要它们。
 - **仅支持 POSIX**——`bash` 二进制已硬编码，底层服务的进程组语义也是 POSIX 的；不支持 Windows。
-- **后台提供方失败提示只交付一次**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
+- **后台提供方失败提示就是整条 stderr 流**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，而 subprocess 服务不会为从未上报结果的目标命令 缓冲任何输出，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 作为观测到的 stderr 流提供（偏移读取方按各自偏移重读），并只折入恰好一个 `readOutput()` 增量；丢弃了该增量的消耗式读取方只能经 `observed.stderr` 恢复它。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/shell/bash-local/src/index.ts b/packages/shell/bash-local/src/index.ts
index c455eebff5..725e4cbdfc 100644
--- a/packages/shell/bash-local/src/index.ts
+++ b/packages/shell/bash-local/src/index.ts
@@ -287,13 +287,24 @@ export class LocalBashExecutor extends ShellExecutor {
     const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, this.config.maxOutputBytes, spec.signal))
     const collected = LocalBashExecutor.collected(running)
 
-    // A provider rejection has no direct outcome to display; its stage is not
-    // public, so a neutral note is delivered once through the read path.
+    // A provider rejection produces no process output, so the subprocess
+    // service has nothing to buffer: once the provider rejected, its
+    // stage-neutral note is the whole stderr stream for every reader. The
+    // observed reader serves it at offset 0 and the consuming read folds it in
+    // exactly once.
     let providerFailureNote: string | undefined
+    let providerFailureReported = false
     const consumeProviderFailure = (): string => {
-      const note = providerFailureNote ?? ''
-      providerFailureNote = undefined
-      return note
+      if (providerFailureNote === undefined || providerFailureReported) return ''
+      providerFailureReported = true
+      return providerFailureNote
+    }
+    const observedStderr: SubprocessOutputReader = {
+      readFrom: (fromByte) => {
+        if (providerFailureNote === undefined) return collected.stderr.readFrom(fromByte)
+        const note = Buffer.from(providerFailureNote, 'utf8')
+        return { text: note.subarray(Math.min(fromByte, note.length)).toString('utf8'), nextOffset: note.length, lossy: false }
+      },
     }
 
     let stdoutOffset = 0
@@ -302,6 +313,7 @@ export class LocalBashExecutor extends ShellExecutor {
       status: 'running',
       exitCode: null,
       signal: null,
+      observed: { stdout: collected.stdout, stderr: observedStderr },
       done: running.done.then((outcome) => {
         // Any signal termination is killed, including a command signaling itself.
         if (proc.status === 'running') {
@@ -311,7 +323,7 @@ export class LocalBashExecutor extends ShellExecutor {
         proc.signal = outcome.signal
         this.onProcessDone(proc, collected.stderr.readFrom(0).text, false)
       }, (error: unknown) => {
-        // Background provider failures settle as killed and surface through the read path.
+        // Background provider failures settle as killed and surface on stderr for every reader.
         proc.status = 'killed'
         let detail = 'unprintable provider failure'
         try {
diff --git a/packages/shell/bash-local/tests/executor.spec.ts b/packages/shell/bash-local/tests/executor.spec.ts
index 36ae874486..8a8873a627 100644
--- a/packages/shell/bash-local/tests/executor.spec.ts
+++ b/packages/shell/bash-local/tests/executor.spec.ts
@@ -370,7 +370,15 @@ describe('LocalBashExecutor.start (background process handles)', () => {
     // done resolves (never rejects) even though the process never ran.
     await expect(proc.done).resolves.toBeUndefined()
     expect(proc.status).toBe('killed')
-    expect(proc.readOutput().delta).toContain('subprocess failed before reporting an outcome:')
+    // Observers read the note as the whole stderr stream at their own offsets.
+    const first = proc.observed.stderr.readFrom(0)
+    expect(first.text).toMatch(/^subprocess failed before reporting an outcome: /)
+    expect(first).toMatchObject({ nextOffset: Buffer.byteLength(first.text, 'utf8'), lossy: false })
+    expect(proc.observed.stderr.readFrom(first.nextOffset)).toEqual({ text: '', nextOffset: first.nextOffset, lossy: false })
+    expect(proc.observed.stdout.readFrom(0).text).toBe('')
+    // The consuming read folds the same note in exactly once.
+    expect(proc.readOutput().delta).toBe(`[stderr]\n${first.text}`)
+    expect(proc.readOutput().delta).toBe('')
   })
 })
 
diff --git a/packages/shell/pwsh-local/README.i18n.yaml b/packages/shell/pwsh-local/README.i18n.yaml
index ce3d9b02a3..4029d81bb7 100644
--- a/packages/shell/pwsh-local/README.i18n.yaml
+++ b/packages/shell/pwsh-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/pwsh-local/README.md
-README.md: 1dbc90835cb95a0e171a33b10c7409a181dd98cf
-README.zh.md: f87c7d435cccb600d123cf80264e027657ef1835
+README.md: 752a0c6cdae826102ca2de35ba671f7b116ff20d
+README.zh.md: 731f6ccc9b20d06e39e7f447c29dd17bcacba2a1
diff --git a/packages/shell/pwsh-local/README.md b/packages/shell/pwsh-local/README.md
index 1dbc90835c..752a0c6cda 100644
--- a/packages/shell/pwsh-local/README.md
+++ b/packages/shell/pwsh-local/README.md
@@ -145,7 +145,7 @@ These limits define when this executor is a poor fit. They are current package c
 - **Unconfined by itself** — commands run with the harness process's authority; deployments needing confinement compose a sandboxing executor or policy instead.
 - **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`.
 - **The command string is PowerShell text** — the `-Command` domain has no shell-quoting layer, but a model-facing command is parsed by PowerShell itself, so PowerShell syntax errors are command failures, not launch failures.
-- **A background provider-failure note is single-delivery** — `SubprocessHandle.done` can reject before or after target execution begins, so the executor injects the stage-neutral `subprocess failed before reporting an outcome: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it.
+- **A background provider-failure note is the whole stderr stream** — `SubprocessHandle.done` can reject before or after target execution begins, and the subprocess service buffers no output for a target that never reported, so the executor serves the stage-neutral `subprocess failed before reporting an outcome: …` as the observed stderr stream (offset readers re-read it at their own offsets) and folds it into exactly one `readOutput()` delta; a consuming reader that discards that delta recovers it only through `observed.stderr`.
 - **Windows termination reports no signal** — a force-killed process settles as exit 1 with `signal: null`, so signal-based status classification does not apply on Windows; `kill()`-initiated stops still stamp `killed` directly.
 - **The encoding preamble precedes the command** — PowerShell requires `param(...)`, `#requires`, and `using` statements at the very top of a script, so a command whose first statement is one of those cannot run under the UTF-8 output preamble; wrap a `param(...)` script in `& { … }`, and run `using`/`#requires` scripts from a file instead.
 - **Non-ASCII stdin under Windows PowerShell 5.1 may be mis-decoded** — the preamble pins output encoding only; `[Console]::InputEncoding` stays at the host default because setting it under redirected stdin throws; pwsh 7 defaults to UTF-8 and is unaffected.
diff --git a/packages/shell/pwsh-local/README.zh.md b/packages/shell/pwsh-local/README.zh.md
index f87c7d435c..731f6ccc9b 100644
--- a/packages/shell/pwsh-local/README.zh.md
+++ b/packages/shell/pwsh-local/README.zh.md
@@ -145,7 +145,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合沙箱执行器或策略。
 - **没有持久 shell 或 PTY**——每次调用都启动全新的 `pwsh -Command`。
 - **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。
-- **后台提供方失败提示只投递一次**——`SubprocessHandle.done` 可能在目标开始执行前或后被拒绝，因此执行器会将不指明失败阶段的 `subprocess failed before reporting an outcome: …` 注入且仅注入一个 `readOutput()` 增量；丢弃该增量的读取方无法恢复它。
+- **后台提供方失败提示就是整条 stderr 流**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，而 subprocess 服务不会为从未上报结果的目标命令 缓冲任何输出，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 作为观测到的 stderr 流提供（偏移读取方按各自偏移重读），并只折入恰好一个 `readOutput()` 增量；丢弃了该增量的消耗式读取方只能经 `observed.stderr` 恢复它。
 - **Windows 终止不报告信号**——被强制终止的进程以退出码 1、`signal: null` 结算，因此基于信号的状态分类在 Windows 上不适用；`kill()` 发起的停止仍会直接标记为 `killed`。
 - **编码 preamble 位于命令之前**——PowerShell 要求 `param(...)`、`#requires` 与 `using` 语句位于脚本最顶部，因此以其中一种开头的命令无法在 UTF-8 输出 preamble 下运行；`param(...)` 脚本请包进 `& { … }`，`using`/`#requires` 脚本请改从文件运行。
 - **Windows PowerShell 5.1 下的非 ASCII stdin 可能被错误解码**——preamble 只固定输出编码；`[Console]::InputEncoding` 保持主机默认，因为在重定向 stdin 下设置它会抛出异常；pwsh 7 默认 UTF-8，不受影响。
diff --git a/packages/shell/pwsh-local/src/index.ts b/packages/shell/pwsh-local/src/index.ts
index bf1dd1cd10..167878f93a 100644
--- a/packages/shell/pwsh-local/src/index.ts
+++ b/packages/shell/pwsh-local/src/index.ts
@@ -321,13 +321,24 @@ export class PwshLocalExecutor extends ShellExecutor {
     const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal, argv))
     const collected = PwshLocalExecutor.collected(running)
 
-    // A provider rejection has no direct outcome to display; its stage is not
-    // public, so a neutral note is delivered once through the read path.
+    // A provider rejection produces no process output, so the subprocess
+    // service has nothing to buffer: once the provider rejected, its
+    // stage-neutral note is the whole stderr stream for every reader. The
+    // observed reader serves it at offset 0 and the consuming read folds it in
+    // exactly once.
     let providerFailureNote: string | undefined
+    let providerFailureReported = false
     const consumeProviderFailure = (): string => {
-      const note = providerFailureNote ?? ''
-      providerFailureNote = undefined
-      return note
+      if (providerFailureNote === undefined || providerFailureReported) return ''
+      providerFailureReported = true
+      return providerFailureNote
+    }
+    const observedStderr: SubprocessOutputReader = {
+      readFrom: (fromByte) => {
+        if (providerFailureNote === undefined) return collected.stderr.readFrom(fromByte)
+        const note = Buffer.from(providerFailureNote, 'utf8')
+        return { text: note.subarray(Math.min(fromByte, note.length)).toString('utf8'), nextOffset: note.length, lossy: false }
+      },
     }
 
     let stdoutOffset = 0
@@ -336,6 +347,7 @@ export class PwshLocalExecutor extends ShellExecutor {
       status: 'running',
       exitCode: null,
       signal: null,
+      observed: { stdout: collected.stdout, stderr: observedStderr },
       done: running.done.then((outcome) => {
         // Any signal termination is killed, including a command signaling itself.
         if (proc.status === 'running') {
@@ -345,7 +357,7 @@ export class PwshLocalExecutor extends ShellExecutor {
         proc.signal = outcome.signal
         this.onProcessDone(proc, collected.stderr.readFrom(0).text, false)
       }, (error: unknown) => {
-        // Background provider failures settle as killed and surface through the read path.
+        // Background provider failures settle as killed and surface on stderr for every reader.
         proc.status = 'killed'
         let detail = 'unprintable provider failure'
         try {
diff --git a/packages/shell/pwsh-local/tests/executor.spec.ts b/packages/shell/pwsh-local/tests/executor.spec.ts
index 1e21231a26..3d893e0cd3 100644
--- a/packages/shell/pwsh-local/tests/executor.spec.ts
+++ b/packages/shell/pwsh-local/tests/executor.spec.ts
@@ -294,6 +294,45 @@ describe('spawn construction (pure, every platform)', () => {
   })
 })
 
+describe('background spawn failure (fake backend, every platform)', () => {
+  /** A subprocess service whose spawn rejects the way a missing pwsh does. */
+  class RejectingSubprocessRuntime extends SubprocessRuntime {
+    override async terminalEnvironment() { return { platform: 'posix' as const } }
+    override async resolveExecutable(command: string): Promise<string> { return command }
+    override spawnTerminal(): Promise<never> { throw new Error('pwsh spawns pipes, never terminals') }
+    private readonly reader: SubprocessOutputReader = {
+      readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }),
+    }
+    override spawn(): SubprocessHandle {
+      return {
+        stdin: undefined,
+        stdout: undefined,
+        stderr: undefined,
+        control: undefined,
+        collected: { stdout: this.reader, stderr: this.reader },
+        done: Promise.reject(new Error('spawn pwsh ENOENT')),
+        terminate: () => {},
+        waitForExit: async () => true,
+      }
+    }
+  }
+
+  it('serves the note as the whole observed stderr stream and folds it into one consuming delta', async () => {
+    const ctx = new Context()
+    new RejectingSubprocessRuntime(ctx)
+    await ctx.plugin(PwshLocalExecutor)
+    const proc = await ctx.shell.start(ctx.shell.resolve({ command: 'Write-Output hi' }))
+    await expect(proc.done).resolves.toBeUndefined()
+    expect(proc.status).toBe('killed')
+    const note = 'subprocess failed before reporting an outcome: Error: spawn pwsh ENOENT'
+    expect(proc.observed.stderr.readFrom(0)).toEqual({ text: note, nextOffset: Buffer.byteLength(note), lossy: false })
+    expect(proc.observed.stderr.readFrom(Buffer.byteLength(note))).toEqual({ text: '', nextOffset: Buffer.byteLength(note), lossy: false })
+    expect(proc.observed.stdout.readFrom(0).text).toBe('')
+    expect(proc.readOutput().delta).toBe(`[stderr]\n${note}`)
+    expect(proc.readOutput().delta).toBe('')
+  })
+})
+
 describe.skipIf(!hasPwsh)('PwshLocalExecutor.run', () => {
   it('resolves with output and the effective timeout', { timeout: 15_000 }, async () => {
     const { bash } = await setup({ timeoutMs: 10_000 })
diff --git a/packages/shell/shell/README.i18n.yaml b/packages/shell/shell/README.i18n.yaml
index 2d142673ab..556c7479d9 100644
--- a/packages/shell/shell/README.i18n.yaml
+++ b/packages/shell/shell/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/shell/README.md
-README.md: 9b32149691a8cf4d4d8316101f4feec6762d0846
-README.zh.md: 9d23b0c5957f9d59169c53c92b960c0b26b77a23
+README.md: 49e101612618405ad0b877df3e4cbf4d3f491155
+README.zh.md: 77e89a9b4bf749d91e1120541bf6799f9d72f3e3
diff --git a/packages/shell/shell/README.md b/packages/shell/shell/README.md
index 9b32149691..49e1016126 100644
--- a/packages/shell/shell/README.md
+++ b/packages/shell/shell/README.md
@@ -38,7 +38,7 @@ console.log(result.exitCode, result.stdout.text)
 
 ### Background processes
 
-Await `start` with a resolved spec to launch a background process; it publishes the handle after preparation and applies no background execution timeout. Cancellation or preparation failure rejects before publication. Read output incrementally with `readOutput()` — consecutive reads never repeat output, and lossy reads point at full-stream spill files. Terminate the provider-managed range with `kill()` (returns `false` once the direct command has finished) and await `done` for direct-command settlement. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, where the tool layer registers the handle.
+Await `start` with a resolved spec to launch a background process; it publishes the handle after preparation and applies no background execution timeout. Cancellation or preparation failure rejects before publication. Read output incrementally with `readOutput()` — consecutive reads never repeat output, and lossy reads point at full-stream spill files. Terminate the provider-managed range with `kill()` (returns `false` once the direct command has finished) and await `done` for direct-command settlement. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, where the tool layer registers the handle. `ShellProcess.observed` exposes non-consuming offset readers over the same captured streams — for observers independent of the consuming cursor, such as the job registry's pump — and every provider serves them, including the provider-failure note of a spawn that never ran.
 
 ### Requests and resolved specs
 
diff --git a/packages/shell/shell/README.zh.md b/packages/shell/shell/README.zh.md
index 9d23b0c595..77e89a9b4b 100644
--- a/packages/shell/shell/README.zh.md
+++ b/packages/shell/shell/README.zh.md
@@ -38,7 +38,7 @@ console.log(result.exitCode, result.stdout.text)
 
 ### 后台进程
 
-用已解析的 spec 等待 `start` 即可启动后台进程；它在准备完成后发布句柄，不应用后台执行超时。取消或准备失败会在发布前拒绝调用。用 `readOutput()` 增量读取输出——连续读取绝不会重复交付，有损读取会指向完整流的 spill 文件。用 `kill()` 终止由提供方管理的进程范围（直接命令结束后返回 `false`），并等待 `done` 完成直接命令结算。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
+用已解析的 spec 等待 `start` 即可启动后台进程；它在准备完成后发布句柄，不应用后台执行超时。取消或准备失败会在发布前拒绝调用。用 `readOutput()` 增量读取输出——连续读取绝不会重复交付，有损读取会指向完整流的 spill 文件。用 `kill()` 终止由提供方管理的进程范围（直接命令结束后返回 `false`），并等待 `done` 完成直接命令结算。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。`ShellProcess.observed` 在同一份捕获流上暴露非消费的偏移读取器——供独立于消费游标的观察者（例如 job 注册表的泵）使用——每个提供方都必须提供，包括从未真正运行的命令留下的提供方失败提示。
 
 ### 请求与已解析 spec
 
diff --git a/packages/shell/shell/src/types.ts b/packages/shell/shell/src/types.ts
index 8964d76b5b..ba32255167 100644
--- a/packages/shell/shell/src/types.ts
+++ b/packages/shell/shell/src/types.ts
@@ -8,10 +8,24 @@
  */
 
 import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import type { CollectedOutput, DshEnvironment } from '@deepseek-ai/dsh-subprocess'
+import type { CollectedOutput, DshEnvironment, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
 
 export { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-subprocess'
-export type { CollectedOutput, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-subprocess'
+export type { CollectedOutput, DshEnvironment, DshEnvironmentKey, SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
+
+/**
+ * Non-consuming offset readers over a background process's captured streams,
+ * for observers independent of the consuming {@link ShellProcess.readOutput}
+ * cursor. Every background process exposes both streams; a spawn that
+ * rejected produced no process output, so its stderr reader serves the
+ * `spawn failed: …` note as the whole stream.
+ */
+export interface ShellObservedStreams {
+  /** Offset reader over captured stdout. */
+  stdout: SubprocessOutputReader
+  /** Offset reader over captured stderr (the spawn-failure note after a rejected spawn). */
+  stderr: SubprocessOutputReader
+}
 
 /**
  * Sandbox facts for one run, present iff a sandboxing executor handled it.
@@ -178,6 +192,13 @@ export interface ShellProcess {
    * full-stream spill files when available.
    */
   readOutput(): ShellProcessRead
+  /**
+   * Non-consuming offset readers over the same captured streams the consuming
+   * {@link readOutput} cursor drains, including the provider-failure note a
+   * rejected spawn leaves on stderr. Independent observers read here at their
+   * own offsets without stealing bytes from `readOutput`.
+   */
+  observed: ShellObservedStreams
   /**
    * Terminate the provider-managed range. Returns false when it had already finished
    * (no-op); idempotent.
diff --git a/packages/shell/shell/tests/service.spec.ts b/packages/shell/shell/tests/service.spec.ts
index 1a988ed8f3..91523cdfd9 100644
--- a/packages/shell/shell/tests/service.spec.ts
+++ b/packages/shell/shell/tests/service.spec.ts
@@ -3,6 +3,9 @@ import { Context } from '@deepseek-ai/cordis'
 import { ShellExecutor } from '@deepseek-ai/dsh-shell'
 import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellRunResult } from '@deepseek-ai/dsh-shell'
 
+/** Empty offset readers for fakes that never produce output. */
+const silentReader = { readFrom: (fromByte: number) => ({ text: '', nextOffset: fromByte, lossy: false }) }
+
 /**
  * Minimal concrete executor: canned foreground results, a hand-built process
  * handle. The seam is TASK-FREE (start returns a {@link ShellProcess} handle;
@@ -40,6 +43,7 @@ class StubExecutor extends ShellExecutor {
       signal: null,
       done: Promise.resolve(),
       readOutput: (): ShellProcessRead => ({ delta: '', lossy: false }),
+      observed: { stdout: silentReader, stderr: silentReader },
       kill: (): boolean => {
         if (proc.status !== 'running') return false
         proc.status = 'killed'
diff --git a/packages/shell/tool-bash/README.i18n.yaml b/packages/shell/tool-bash/README.i18n.yaml
index f3b351a17c..730d782903 100644
--- a/packages/shell/tool-bash/README.i18n.yaml
+++ b/packages/shell/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/shell/tool-bash/README.md
-README.md: 5426cc17ccefc7eecf511355734e168377fc2d0f
-README.zh.md: f48c6cb1a9f37da08ccc816eed37c9fbd35eeb62
+README.md: 34b3042e4cd0ab2d54d3cbc038b71b584391b47d
+README.zh.md: 0872a0f1fbf41389483df44624d15ffcb07936ec
diff --git a/packages/shell/tool-bash/README.md b/packages/shell/tool-bash/README.md
index 5426cc17cc..34b3042e4c 100644
--- a/packages/shell/tool-bash/README.md
+++ b/packages/shell/tool-bash/README.md
@@ -56,7 +56,7 @@ The tool executes `bash -c <command>` and returns the combined output. Commands
 <a id="running-long-commands-in-the-background"></a>
 ### Running long commands in the background
 
-Passing `run_in_background: true` admits a job and returns its id immediately; confinement preparation may still be pending, and no background execution timeout applies. Output is empty until the process is available. Job cancellation aborts preparation and stops any process that arrives afterward; startup failure settles the admitted job as failed. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted.
+Passing `run_in_background: true` admits a job and returns its id immediately; confinement preparation may still be pending, and no background execution timeout applies. Output is empty until the process is available. Job cancellation aborts preparation and stops any process that arrives afterward; startup failure settles the admitted job as failed. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job hands the run's non-consuming `observed` readers to the job registry as pull sources; the registry pumps them into the job's output ring at its own cadence (`pumpPollMs` on `dsh-jobs-local`), so the Web client streams live output and the model's `job_output` reads consume the same bytes through a separate cursor. A reader that throws is logged once and its stream stops; the job runs on to its own settlement. The ring is a best-effort live preview: stdout and stderr are copied per poll round, so writes the two streams made inside one poll window appear stdout first rather than in write order.
 
 ### Sandboxed execution and escalation
 
diff --git a/packages/shell/tool-bash/README.zh.md b/packages/shell/tool-bash/README.zh.md
index f48c6cb1a9..0872a0f1fb 100644
--- a/packages/shell/tool-bash/README.zh.md
+++ b/packages/shell/tool-bash/README.zh.md
@@ -56,7 +56,7 @@ kind: "package-reference"
 <a id="running-long-commands-in-the-background"></a>
 ### 后台运行长时间命令
 
-传入 `run_in_background: true` 会准入任务并立即返回 job id；限制准备可能仍在进行，且不设后台执行超时。进程可用前输出为空。任务取消会中止准备并停止随后返回的进程；启动失败使已准入任务以失败状态结算。agent 用 `job_output` 读取输出（除非 `wait: true`，否则非阻塞）、用 `job_list` 列出任务、用 `job_kill` 停止任务；完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时（`dsh-jobs-local`）及其控制工具（`dsh-tool-jobs`）。
+传入 `run_in_background: true` 会准入任务并立即返回 job id；限制准备可能仍在进行，且不设后台执行超时。进程可用前输出为空。任务取消会中止准备并停止随后返回的进程；启动失败使已准入任务以失败状态结算。agent 用 `job_output` 读取输出（除非 `wait: true`，否则非阻塞）、用 `job_list` 列出任务、用 `job_kill` 停止任务；完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时（`dsh-jobs-local`）及其控制工具（`dsh-tool-jobs`）。后台 job 把运行的非消费 `observed` 读取器交给 job 注册表作为拉式源；注册表按自己的节奏（`dsh-jobs-local` 的 `pumpPollMs`）把它们泵入 job 的输出环，Web 客户端由此流式看到实时输出，模型的 `job_output` 读取则经另一个游标消费同一份字节。读取器抛错只记录一次，该流就此停止，job 继续跑到自己的结算。输出环是尽力而为的实时预览：stdout 与 stderr 按轮询轮次复制，同一个轮询窗口内两条流的写入会先 stdout 后 stderr 出现，而不是按写入顺序。
 
 ### 沙箱执行与升权
 
diff --git a/packages/shell/tool-bash/src/background.ts b/packages/shell/tool-bash/src/background.ts
index c2087f3698..0bdb2dc4d1 100644
--- a/packages/shell/tool-bash/src/background.ts
+++ b/packages/shell/tool-bash/src/background.ts
@@ -1,41 +1,87 @@
 /**
- * Generic-task adaptation for background bash process handles.
+ * Generic-job adaptation for background bash process handles: the terminal
+ * outcome the registry records and the pull sources it pumps.
  *
  * @module @deepseek-ai/dsh-tool-bash/background
  */
 
-import type { ShellProcess } from '@deepseek-ai/dsh-shell'
-import type { JobHooks, JobOutcome } from '@deepseek-ai/dsh-jobs'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
+import type { ShellProcess, ShellSandboxInfo } from '@deepseek-ai/dsh-shell'
+import type { JobHooks, JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs'
 
 /**
- * Map a settled background process onto the generic task-outcome vocabulary:
+ * Sandbox facts worth the terminal detail: a runner that never ran the
+ * command, or a denial (with the escalation hint this composition offers).
+ * @param sandbox - settled sandbox facts, when this was a confined process.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the markers to append, oldest first.
+ */
+function sandboxNotes(sandbox: ShellSandboxInfo | undefined, escalationModes: readonly SandboxMode[]): string[] {
+  if (sandbox?.runnerFailed) {
+    return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`]
+  }
+  if (sandbox?.denied) {
+    const notes = [sandboxDenialMarker(sandbox.mode)]
+    if (escalationModes.length > 0) notes.push(escalationHintMarker('command'))
+    return notes
+  }
+  return []
+}
+
+/**
+ * Map a settled background process onto the generic job-outcome vocabulary:
  * `killed` stays `killed` (detail: the signal when one is known), everything
  * else is `completed` with the exit code as detail. A nonzero command exit is
- * reported, not failed, exactly like the foreground rendering.
+ * reported, not failed, exactly like the foreground rendering. Sandbox facts
+ * join the detail, since a job's terminal reason is the one line every
+ * reader — the model's status line, the roster row — shows.
  * @param proc - the settled process handle.
+ * @param escalationModes - escalation targets advertised by this composition.
  * @returns the outcome for the `ctx.jobs` registration.
  */
-export function processOutcome(proc: ShellProcess): { status: 'completed' | 'killed'; detail: string } {
+export function processOutcome(proc: ShellProcess, escalationModes: readonly SandboxMode[] = []): JobOutcome {
   // TODO(background-infrastructure-outcome): widen ShellProcess with an explicit
-  // infrastructure-failure outcome, then map it to task `failed`. Restricted
+  // infrastructure-failure outcome, then map it to job `failed`. Restricted
   // runner failures expose sandbox.runnerFailed, but unconfined spawn failures
   // still alias a signal-less kill; real nonzero command exits must remain
   // `completed`.
-  if (proc.status === 'killed') {
-    return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
-  }
-  return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+  const base: JobOutcome = proc.status === 'killed'
+    ? { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
+    : { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+  const notes = sandboxNotes(proc.sandbox, escalationModes)
+  return notes.length === 0 ? base : { ...base, detail: `${base.detail}; ${notes.join(' ')}` }
+}
+
+/**
+ * The process's non-consuming stream readers as registry pull sources. They
+ * bind lazily because the process is spawned inside the starter, after the
+ * registry admitted the job; a read before the spawn yields nothing, and the
+ * pump keeps the model's consuming cursor untouched. A rejected spawn's
+ * stderr reader carries the provider's `spawn failed: …` note.
+ * @param proc - the started process's observed streams, once the starter has spawned it.
+ * @returns one source per stream, stdout first.
+ */
+export function processSources(proc: () => Pick<ShellProcess, 'observed'> | undefined): JobOutputSource[] {
+  const source = (channel: 'stdout' | 'stderr'): JobOutputSource => ({
+    channel,
+    read: (fromByte) => {
+      const live = proc()
+      return live === undefined ? { text: '', nextOffset: fromByte, lossy: false } : live.observed[channel].readFrom(fromByte)
+    },
+  })
+  return [source('stdout'), source('stderr')]
 }
 
 /**
  * Adapt asynchronous shell preparation after job admission without exposing a partial process.
  * @param start - starts the process with job-owned cancellation.
- * @param renderOutput - consumes output from a published process.
+ * @param outcome - projects the settled process into the job outcome.
  * @returns synchronous job hooks whose completion includes preparation and process settlement.
  */
 export function processJob(
   start: (signal: AbortSignal) => Promise<ShellProcess>,
-  renderOutput: (process: ShellProcess) => string,
+  outcome: (process: ShellProcess) => JobOutcome,
 ): JobHooks {
   const controller = new AbortController()
   let process: ShellProcess | undefined
@@ -47,7 +93,7 @@ export function processJob(
       } finally {
         await process.done
       }
-      return processOutcome(process)
+      return outcome(process)
     } catch (error: unknown) {
       return {
         status: controller.signal.aborted && process === undefined ? 'killed' : 'failed',
@@ -62,6 +108,5 @@ export function processJob(
       process?.kill()
     },
     done,
-    readOutput: () => process === undefined ? '' : renderOutput(process),
   }
 }
diff --git a/packages/shell/tool-bash/src/index.ts b/packages/shell/tool-bash/src/index.ts
index fd59129f49..7e1f6227e2 100644
--- a/packages/shell/tool-bash/src/index.ts
+++ b/packages/shell/tool-bash/src/index.ts
@@ -22,9 +22,9 @@ import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandb
 import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell'
-import type { ShellRunResult } from '@deepseek-ai/dsh-shell'
-import { processJob } from './background.ts'
-import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'
+import type { ShellRunResult, ShellProcess } from '@deepseek-ai/dsh-shell'
+import { processJob, processOutcome, processSources } from './background.ts'
+import { parseExitStatus, renderResult } from './render.ts'
 
 export const name = 'tool-bash'
 export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv']
@@ -363,14 +363,21 @@ export function apply(ctx: Context, config: Config = {}): void {
           error.name = 'AbortError'
           throw error
         }
-        // Task preflight finishes before the starter can spawn a process.
+        // The registry pumps the process's non-consuming readers into the
+        // job's ring; the sources bind lazily because the process is spawned
+        // only once admission has passed.
+        let proc: ShellProcess | undefined
         const id = jobs.start({
           kind: 'bash',
           label: args.command,
-          ...exec.agent ? { owner: exec.agent } : {},
+          ...exec.agent ? { owner: exec.agent.id } : {},
+          output: processSources(() => proc),
           run: () => processJob(
-            signal => ctx.shell.start(ctx.shell.resolve({ ...request, signal })),
-            proc => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes),
+            async (signal) => {
+              proc = await ctx.shell.start(ctx.shell.resolve({ ...request, signal }))
+              return proc
+            },
+            started => processOutcome(started, escalationModes),
           ),
         })
         return { kind: 'background' as const, jobId: id }
diff --git a/packages/shell/tool-bash/src/render.ts b/packages/shell/tool-bash/src/render.ts
index 82403cca44..a13b8348f1 100644
--- a/packages/shell/tool-bash/src/render.ts
+++ b/packages/shell/tool-bash/src/render.ts
@@ -4,7 +4,7 @@
  * @module @deepseek-ai/dsh-tool-bash/render
  */
 
-import type { ShellProcessRead, ShellRunResult, ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell'
+import type { ShellRunResult, CollectedOutput } from '@deepseek-ai/dsh-shell'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
 
@@ -62,38 +62,6 @@ export function renderResult(
   return body + markers.join('\n')
 }
 
-/**
- * Shape one background-process read into the `job_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 job 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.
- * @returns the delta text with any loss or sandbox notice appended.
- */
-export function renderProcessRead(
-  read: ShellProcessRead,
-  sandbox?: ShellSandboxInfo,
-  escalationModes: readonly SandboxMode[] = [],
-): string {
-  const notices: string[] = []
-  if (read.lossy) {
-    const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path): path is string => path !== undefined)
-    notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`)
-  }
-  if (sandbox?.runnerFailed) {
-    notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`)
-  } else if (sandbox?.denied) {
-    notices.push(sandboxDenialMarker(sandbox.mode))
-    if (escalationModes.length > 0) {
-      notices.push(escalationHintMarker('command'))
-    }
-  }
-  if (notices.length === 0) return read.delta
-  return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}`
-}
-
 /**
  * The exit-status parse is the shared marker-contract half of the shell-tool
  * rendering story, owned by `@deepseek-ai/dsh-shell` so `dsh-tool-pwsh` reuses
diff --git a/packages/shell/tool-bash/tests/background-start.spec.ts b/packages/shell/tool-bash/tests/background-start.spec.ts
index 19e31e3a10..4140d50c44 100644
--- a/packages/shell/tool-bash/tests/background-start.spec.ts
+++ b/packages/shell/tool-bash/tests/background-start.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import type { ShellProcess } from '@deepseek-ai/dsh-shell'
-import { processJob } from '../src/background.ts'
+import { processJob, processOutcome, processSources } from '../src/background.ts'
 
 function processHandle() {
   const exited = Promise.withResolvers<undefined>()
@@ -12,25 +12,34 @@ function processHandle() {
     killed.resolve(undefined)
     return true
   })
+  const readOutput = vi.fn(() => ({ delta: 'output', lossy: false }))
   const process: ShellProcess = {
     status: 'running', exitCode: null, signal: null, done: exited.promise,
-    readOutput: () => ({ delta: 'output', lossy: false }), kill,
+    readOutput, kill,
+    observed: {
+      stdout: { readFrom: fromByte => ({ text: 'output'.slice(fromByte), nextOffset: 6, lossy: false }) },
+      stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) },
+    },
   }
   onTestFinished(() => { exited.resolve(undefined) })
-  return { process, exited, killed, kill }
+  return { process, exited, killed, kill, readOutput }
 }
 
 describe('background job ownership during asynchronous shell startup', () => {
-  it('keeps output empty until a process is published and then consumes its output', async () => {
+  it('keeps observation empty during preparation and reads published output without consuming it', async () => {
     const child = processHandle()
     const prepared = Promise.withResolvers<ShellProcess>()
-    const render = vi.fn((process: ShellProcess) => process.readOutput().delta)
-    const hooks = processJob(() => prepared.promise, render)
-    expect(hooks.readOutput!()).toBe('')
-    expect(render).not.toHaveBeenCalled()
+    let published: ShellProcess | undefined
+    const source = processSources(() => published)[0]!
+    const outcome = vi.fn(processOutcome)
+    const hooks = processJob(async () => { published = await prepared.promise; return published }, outcome)
+    expect(source.read(0).text).toBe('')
+    expect(outcome).not.toHaveBeenCalled()
     prepared.resolve(child.process)
     await Promise.resolve()
-    expect(hooks.readOutput!()).toBe('output')
+    expect(source.read(0).text).toBe('output')
+    expect(source.read(0).text).toBe('output')
+    expect(child.readOutput).not.toHaveBeenCalled()
     child.process.status = 'completed'
     child.process.exitCode = 5
     child.exited.resolve(undefined)
@@ -44,19 +53,18 @@ describe('background job ownership during asynchronous shell startup', () => {
       return new Promise<ShellProcess>((_resolve, reject) => {
         signal.addEventListener('abort', () => { reject(new Error(String(signal.reason))) }, { once: true })
       })
-    }, () => 'unreachable')
+    }, processOutcome)
     expect(received?.aborted).toBe(false)
     hooks.cancel('cancel pending confinement')
     hooks.cancel('later cancellation')
     expect(received?.reason).toBe('cancel pending confinement')
     expect(await hooks.done).toEqual({ status: 'killed', detail: 'cancel pending confinement' })
-    expect(hooks.readOutput!()).toBe('')
   })
 
   it('kills a process that materializes after cancellation and awaits its exit', async () => {
     const child = processHandle()
     const prepared = Promise.withResolvers<ShellProcess>()
-    const hooks = processJob(() => prepared.promise, () => 'output')
+    const hooks = processJob(() => prepared.promise, processOutcome)
     let settled = false
     void hooks.done.then(() => { settled = true })
     hooks.cancel('cancel before process publication')
@@ -70,7 +78,7 @@ describe('background job ownership during asynchronous shell startup', () => {
 
   it('cancels a published process once and keeps done pending until exit', async () => {
     const child = processHandle()
-    const hooks = processJob(async () => child.process, () => 'output')
+    const hooks = processJob(async () => child.process, processOutcome)
     await Promise.resolve()
     let settled = false
     void hooks.done.then(() => { settled = true })
@@ -88,7 +96,7 @@ describe('background job ownership during asynchronous shell startup', () => {
     const attempted = Promise.withResolvers<undefined>()
     vi.mocked(child.kill).mockImplementation(() => { attempted.resolve(undefined); throw new Error('termination failed') })
     const prepared = Promise.withResolvers<ShellProcess>()
-    const hooks = processJob(() => prepared.promise, () => '')
+    const hooks = processJob(() => prepared.promise, processOutcome)
     let settled = false
     void hooks.done.then(() => { settled = true })
     hooks.cancel('stop before publication')
@@ -100,17 +108,16 @@ describe('background job ownership during asynchronous shell startup', () => {
   })
 
   it('reports a startup failure through job completion without publishing output', async () => {
-    const render = vi.fn(() => 'unreachable')
+    const render = vi.fn(processOutcome)
     const hooks = processJob(async () => { throw new Error('remote sandbox unavailable') }, render)
     expect(await hooks.done).toEqual({ status: 'failed', detail: 'remote sandbox unavailable' })
-    expect(hooks.readOutput!()).toBe('')
     expect(render).not.toHaveBeenCalled()
   })
 
   it('reports a primitive upstream abort reason as a failed startup', async () => {
     const upstream = new AbortController()
     upstream.abort('upstream preparation stopped')
-    const hooks = processJob(async () => { upstream.signal.throwIfAborted(); throw new Error('unreachable') }, () => '')
+    const hooks = processJob(async () => { upstream.signal.throwIfAborted(); throw new Error('unreachable') }, processOutcome)
     expect(await hooks.done).toEqual({ status: 'failed', detail: 'upstream preparation stopped' })
   })
 })
diff --git a/packages/shell/tool-bash/tests/background.spec.ts b/packages/shell/tool-bash/tests/background.spec.ts
new file mode 100644
index 0000000000..1fe2292f37
--- /dev/null
+++ b/packages/shell/tool-bash/tests/background.spec.ts
@@ -0,0 +1,216 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session/types'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
+import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
+import type { JobId } from '@deepseek-ai/dsh-jobs'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
+import type { ShellProcess } from '@deepseek-ai/dsh-shell'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
+import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
+import { processSources } from '../src/background.ts'
+import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env'
+
+const testToolSignal = new AbortController().signal
+const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-background-spec-'))
+
+/** Job harness with a fast registry pump for tests. */
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRuntime)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LocalJobRegistry, { pumpPollMs: 25 })
+  await ctx.plugin(ToolTasks)
+  await ctx.plugin(LocalSubprocessRuntime)
+  ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir }
+  await ctx.plugin(BashEnvPlugin)
+  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
+  await ctx.plugin(ToolBash)
+  return ctx
+}
+
+let callCounter = 0
+function call(ctx: Context, args: Record<string, unknown>) {
+  return ctx.tools.execute({
+    signal: testToolSignal,
+    callId: ToolCallId(`background-call-${++callCounter}`),
+    name: 'bash',
+    arguments: args,
+  })
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+async function until<T>(read: () => T | undefined, timeoutMs = 5_000): Promise<T> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const value = read()
+    if (value !== undefined) return value
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+  throw new Error('condition not reached before timeout')
+}
+
+function retainedText(ctx: Context, id: JobId, caller?: Agent): string {
+  return ctx.jobs.readAt(id, 0, caller?.id).chunks.map(chunk => chunk.text).join('')
+}
+
+describe('background bash output', () => {
+  it('streams a background run into the job ring with live output and settlement', async () => {
+    const ctx = await setup()
+    const ack = await call(ctx, {
+      command: 'printf "line-1\\n"; sleep 0.4; printf "line-2\\n"',
+      description: 'test command',
+      run_in_background: true,
+    })
+    expect(text(ack)).toContain('started background job')
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    expect(job).toBeDefined()
+
+    // Live output appears in the ring while the command is still running.
+    await until(() => retainedText(ctx, job!.id).includes('line-1') ? true : undefined)
+    expect(jobs.get(job!.id).status).toBe('running')
+
+    // Settlement ends the ring with the job; the trailing bytes are drained first.
+    await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined)
+    expect(jobs.get(job!.id).detail).toBe('exit code: 0')
+    expect(retainedText(ctx, job!.id)).toContain('line-2')
+
+    // The model-facing consuming cursor reads the same bytes: observation stole nothing.
+    const consumed = jobs.read(job!.id).chunks.map(chunk => chunk.text).join('')
+    expect(consumed).toContain('line-1')
+    expect(consumed).toContain('line-2')
+  })
+
+  it('a killed background job settles killed with the kill reason merged into its detail', async () => {
+    const ctx = await setup()
+    await call(ctx, { command: 'sleep 60', description: 'test command', run_in_background: true })
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    jobs.kill(job!.id, undefined, 'test cleanup')
+    await until(() => jobs.get(job!.id).status === 'killed' ? true : undefined)
+    expect(jobs.get(job!.id).detail).toMatch(/(signal|killed before exit).*; test cleanup$/)
+  })
+
+  it('a background spawn failure reaches the model as the stderr note master rendered', async () => {
+    const ctx = await setup()
+    const started = await call(ctx, {
+      command: 'true',
+      description: 'test command',
+      workdir: '/nonexistent-dsh',
+      run_in_background: true,
+    })
+    expect(text(started)).toMatch(/^started background job bash-\d+$/)
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    await until(() => jobs.get(job!.id).status === 'killed' ? true : undefined)
+    const read = text(await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: ToolCallId('background-spawn-failure-read'),
+      name: 'job_output',
+      arguments: { job_id: String(job!.id) },
+    }))
+    expect(read).toMatch(/^\[stderr\]\nsubprocess failed before reporting an outcome: .*\n\[status: killed, killed before exit\]$/s)
+  })
+
+  it('labels stderr chunks with their channel', async () => {
+    const ctx = await setup()
+    await call(ctx, {
+      command: 'echo out-line; echo err-line 1>&2',
+      description: 'test command',
+      run_in_background: true,
+    })
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined)
+    const chunks = jobs.readAt(job!.id, 0).chunks
+    expect(chunks.find(chunk => chunk.text.includes('out-line'))?.channel).toBe('stdout')
+    expect(chunks.find(chunk => chunk.text.includes('err-line'))?.channel).toBe('stderr')
+  })
+})
+
+describe('processSources', () => {
+  it('reads nothing while the process is not spawned yet', () => {
+    const [stdout, stderr] = processSources(() => undefined)
+    expect(stdout!.channel).toBe('stdout')
+    expect(stderr!.channel).toBe('stderr')
+    expect(stdout!.read(0)).toEqual({ text: '', nextOffset: 0, lossy: false })
+    expect(stderr!.read(3)).toEqual({ text: '', nextOffset: 3, lossy: false })
+  })
+
+  it('forwards each read to the matching stream reader at its own offset once the process exists', () => {
+    const reads: { channel: string; from: number }[] = []
+    const reader = (channel: string, text: string): ShellProcess['observed']['stdout'] => ({
+      readFrom: (from: number) => { reads.push({ channel, from }); return { text, nextOffset: from + text.length, lossy: false } },
+    })
+    const proc: Pick<ShellProcess, 'observed'> = { observed: { stdout: reader('stdout', 'out'), stderr: reader('stderr', 'err!') } }
+    const [stdout, stderr] = processSources(() => proc)
+    expect(stdout!.read(2)).toEqual({ text: 'out', nextOffset: 5, lossy: false })
+    expect(stderr!.read(7)).toEqual({ text: 'err!', nextOffset: 11, lossy: false })
+    expect(reads).toEqual([{ channel: 'stdout', from: 2 }, { channel: 'stderr', from: 7 }])
+  })
+
+  it("passes a lossy read's spill file through, so the model's notice can name it", () => {
+    const proc: Pick<ShellProcess, 'observed'> = {
+      observed: {
+        stdout: { readFrom: (from: number) => ({ text: '', nextOffset: from, lossy: false }) },
+        stderr: { readFrom: (from: number) => ({ text: 'tail', nextOffset: from + 4, lossy: true, spillPath: '/spill/err.log' }) },
+      },
+    }
+    const [, stderr] = processSources(() => proc)
+    expect(stderr!.read(0)).toEqual({ text: 'tail', nextOffset: 4, lossy: true, spillPath: '/spill/err.log' })
+  })
+})
+
+describe('owned background output', () => {
+  it('fences an owned background run under the owning session', async () => {
+    const ctx = await setup()
+    const ownerId = SessionId('background-owner')
+    const owner: Agent = {
+      id: ownerId,
+      options: {},
+      session: Session.create(ownerId, undefined, {
+        version: SESSION_FORMAT_VERSION, id: ownerId, createdAt: 0, cwd: process.cwd(), isSeeded: false,
+      }),
+      inbox: unsupportedInbox(),
+      status: 'idle',
+      ctx,
+      send: () => {},
+      followup: () => {},
+      steer: () => {},
+      inject: () => {},
+      cancel: () => {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
+    }
+    ctx.agents.register(owner)
+    await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: ToolCallId('background-owned-1'),
+      name: 'bash',
+      arguments: { command: 'echo owned', description: 'test command', run_in_background: true },
+      agent: owner,
+    })
+    const owned = ctx.jobs
+    const job = owned.list(owner.id)[0]
+    expect(job).toBeDefined()
+    expect(job!.owner).toBe(owner.id)
+    await until(() => owned.get(job!.id, owner.id).status === 'completed' ? true : undefined)
+    expect(() => retainedText(ctx, job!.id)).toThrow(/belongs to another session/)
+    await until(() => retainedText(ctx, job!.id, owner).includes('owned') ? true : undefined)
+  })
+})
diff --git a/packages/shell/tool-bash/tests/tools.spec.ts b/packages/shell/tool-bash/tests/tools.spec.ts
index c2291d0812..525c9e8220 100644
--- a/packages/shell/tool-bash/tests/tools.spec.ts
+++ b/packages/shell/tool-bash/tests/tools.spec.ts
@@ -5,7 +5,7 @@ import { afterAll, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { ToolCallId } from '@deepseek-ai/dsh-llm'
 import { ShellExecutor } from '@deepseek-ai/dsh-shell'
-import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellRunResult } from '@deepseek-ai/dsh-shell'
+import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime, { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
@@ -22,8 +22,12 @@ import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env'
+import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
 import { processOutcome } from '../src/background.ts'
-import { renderProcessRead, renderResult } from '../src/render.ts'
+import { renderResult } from '../src/render.ts'
+
+/** Empty offset readers for fakes that never produce output. */
+const silentReader = { readFrom: (fromByte: number) => ({ text: '', nextOffset: fromByte, lossy: false }) }
 
 const testToolSignal = new AbortController().signal
 
@@ -152,6 +156,7 @@ class RecordingSandboxExecutor extends ShellExecutor {
       done: Promise.resolve(),
       sandbox: { mode: spec.sandboxPolicy?.mode ?? 'read-only', denied: false },
       readOutput: () => ({ delta: '', lossy: false }),
+      observed: { stdout: silentReader, stderr: silentReader },
       kill: () => false,
     }
   }
@@ -181,6 +186,7 @@ class CountingStartExecutor extends ShellExecutor {
       signal: null,
       done: Promise.resolve(),
       readOutput: () => ({ delta: '', lossy: false }),
+      observed: { stdout: silentReader, stderr: silentReader },
       kill: () => false,
     }
   }
@@ -794,53 +800,6 @@ describe('sandbox escalation through the generic task producer', () => {
   })
 })
 
-describe('renderProcessRead', () => {
-  const base: ShellProcessRead = { delta: 'out\n', lossy: false }
-
-  it('returns the delta verbatim for a lossless read', () => {
-    expect(renderProcessRead(base)).toBe('out\n')
-    expect(renderProcessRead({ delta: '', lossy: false })).toBe('')
-  })
-
-  it('appends the loss notice with the available spill paths', () => {
-    expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log' }))
-      .toBe('out\n[some output was dropped from memory; full output: /spill/out.log]')
-    expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log', stderrSpillPath: '/spill/err.log' }))
-      .toBe('out\n[some output was dropped from memory; full output: /spill/out.log, /spill/err.log]')
-  })
-
-  it('reports (unavailable) when a lossy read has no safe spill path', () => {
-    expect(renderProcessRead({ ...base, lossy: true }))
-      .toBe('out\n[some output was dropped from memory; full output: (unavailable)]')
-  })
-
-  it('an empty lossy delta is the notice alone', () => {
-    expect(renderProcessRead({ delta: '', lossy: true, stderrSpillPath: '/spill/err.log' }))
-      .toBe('[some output was dropped from memory; full output: /spill/err.log]')
-  })
-
-  it('inserts the separating newline only when the delta lacks one', () => {
-    expect(renderProcessRead({ delta: 'tail', lossy: true }))
-      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
-    expect(renderProcessRead({ delta: 'tail\n', lossy: true }))
-      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
-  })
-
-  it('appends settled sandbox denial and runner-failure facts', () => {
-    expect(renderProcessRead(base, { mode: 'read-only', denied: true }, ['workspace-write']))
-      .toContain('[sandbox: escalation available')
-    expect(renderProcessRead({ delta: 'tail', lossy: false }, { mode: 'read-only', denied: true }))
-      .toBe('tail\n[sandbox: file access denied under read-only mode]')
-    const runner = renderProcessRead(
-      { delta: '', lossy: false },
-      { mode: 'workspace-write', denied: true, runnerFailed: true },
-      ['danger-full-access'],
-    )
-    expect(runner).toContain('sandbox runner itself failed under workspace-write mode')
-    expect(runner).not.toContain('file access denied')
-  })
-})
-
 describe('processOutcome', () => {
   function settled(over: Partial<ShellProcess>): ShellProcess {
     return {
@@ -849,6 +808,7 @@ describe('processOutcome', () => {
       signal: null,
       done: Promise.resolve(),
       readOutput: () => ({ delta: '', lossy: false }),
+      observed: { stdout: silentReader, stderr: silentReader },
       kill: () => false,
       ...over,
     }
@@ -873,6 +833,16 @@ describe('processOutcome', () => {
     expect(processOutcome(settled({ exitCode: null })))
       .toEqual({ status: 'completed', detail: 'exit code: 0' })
   })
+
+  it('appends sandbox facts to the terminal detail', () => {
+    const denied = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } }), ['workspace-write'])
+    expect(denied.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')} ${escalationHintMarker('command')}`)
+    const deniedWithoutEscalation = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } }))
+    expect(deniedWithoutEscalation.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')}`)
+    const runnerFailed = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: false, runnerFailed: true } }))
+    expect(runnerFailed.detail).toContain('the sandbox runner itself failed under read-only mode')
+    expect(processOutcome(settled({ sandbox: { mode: 'read-only', denied: false } })).detail).toBe('exit code: 0')
+  })
 })
 
 describe('session-cwd routing (per-session workdir)', () => {
@@ -1172,6 +1142,7 @@ describe('the model-facing bash tool builds its request from named args only (no
         signal: null,
         done: Promise.resolve(),
         readOutput: () => ({ delta: '', lossy: false }),
+        observed: { stdout: silentReader, stderr: silentReader },
         kill: () => false,
       }
     }
diff --git a/packages/shell/tool-pwsh/README.i18n.yaml b/packages/shell/tool-pwsh/README.i18n.yaml
index 348769a6d8..274c7e20be 100644
--- a/packages/shell/tool-pwsh/README.i18n.yaml
+++ b/packages/shell/tool-pwsh/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md
-README.md: a1b8755c50862bb318f72af90f3cdbae158e7746
-README.zh.md: efcf188b31365f6897eb14fb6482c973f23f6a7b
+README.md: ef6a347545652be5cd388ad06ddc72d9491759d7
+README.zh.md: 59b98c232d39e0eedae7b8cb584782875407d54a
diff --git a/packages/shell/tool-pwsh/README.md b/packages/shell/tool-pwsh/README.md
index a1b8755c50..ef6a347545 100644
--- a/packages/shell/tool-pwsh/README.md
+++ b/packages/shell/tool-pwsh/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `dsh-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `DSH_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin.
+`dsh-tool-pwsh` lets the agent run PowerShell commands through a mounted shell executor. Each call uses a fresh process; `run_in_background` keeps long-running commands active as jobs with observable output. Commands use native Windows paths and `$env:NAME` variables without dialect translation. Calls receive the managed `DSH_*` environment, and sandboxed execution enforces Windows language-mode and named-pipe requirements. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin.
 
 ## Table of Contents
 
diff --git a/packages/shell/tool-pwsh/README.zh.md b/packages/shell/tool-pwsh/README.zh.md
index efcf188b31..59b98c232d 100644
--- a/packages/shell/tool-pwsh/README.zh.md
+++ b/packages/shell/tool-pwsh/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-pwsh` 为 agent（智能体）提供 `pwsh` 工具，通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `dsh-tool-bash` 的 Windows 对应物，逐调用镜像。每次调用都运行在全新 pwsh 进程中，因此状态不会保留；`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量，不做方言翻译。每次调用都运行在受管 `DSH_*` 环境中；在沙箱执行器下，工具会向模型说明并强制执行 Windows 特有的语言模式与命名管道约定。请与 `dsh-pwsh-local` 等 PowerShell 执行器以及 `dsh-shell-env` 插件一起挂载。
+`dsh-tool-pwsh` 让 agent（智能体）通过已挂载的 shell 执行器运行 PowerShell 命令。每次调用使用全新进程；`run_in_background` 将长时间运行的命令保持为输出可观测的任务。命令使用原生 Windows 路径和 `$env:NAME` 变量，不做方言翻译。调用获得受管 `DSH_*` 环境，沙箱执行会落实 Windows 语言模式与命名管道要求。请与 `dsh-pwsh-local` 等 PowerShell 执行器及 `dsh-shell-env` 插件一起挂载。
 
 ## 目录
 
diff --git a/packages/shell/tool-pwsh/package.json b/packages/shell/tool-pwsh/package.json
index 5b1d2a8bc4..b8ce764201 100644
--- a/packages/shell/tool-pwsh/package.json
+++ b/packages/shell/tool-pwsh/package.json
@@ -46,6 +46,7 @@
     "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/dsh-jobs": "workspace:^",
     "@deepseek-ai/dsh-jobs-local": "workspace:^",
diff --git a/packages/shell/tool-pwsh/src/background.ts b/packages/shell/tool-pwsh/src/background.ts
index ce506a569d..ec4c2d4836 100644
--- a/packages/shell/tool-pwsh/src/background.ts
+++ b/packages/shell/tool-pwsh/src/background.ts
@@ -1,44 +1,90 @@
 /**
- * Generic-task adaptation for background pwsh process handles — the shell-agnostic
- * twin of `dsh-tool-bash`'s background adaptation.
+ * Generic-job adaptation for background pwsh process handles — the
+ * shell-agnostic twin of `dsh-tool-bash`'s background adaptation: the terminal
+ * outcome the registry records and the pull sources it pumps.
  *
  * @module @deepseek-ai/dsh-tool-pwsh/background
  */
 
-import type { ShellProcess } from '@deepseek-ai/dsh-shell'
-import type { JobHooks, JobOutcome } from '@deepseek-ai/dsh-jobs'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
+import type { ShellProcess, ShellSandboxInfo } from '@deepseek-ai/dsh-shell'
+import type { JobHooks, JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs'
 
 /* jscpd:ignore-start -- deliberate twin of dsh-tool-bash/background.ts (Agent Note). */
 
 /**
- * Map a settled background process onto the generic task-outcome vocabulary:
+ * Sandbox facts worth the terminal detail: a runner that never ran the
+ * command, or a denial (with the escalation hint this composition offers).
+ * @param sandbox - settled sandbox facts, when this was a confined process.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the markers to append, oldest first.
+ */
+function sandboxNotes(sandbox: ShellSandboxInfo | undefined, escalationModes: readonly SandboxMode[]): string[] {
+  if (sandbox?.runnerFailed) {
+    return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`]
+  }
+  if (sandbox?.denied) {
+    const notes = [sandboxDenialMarker(sandbox.mode)]
+    if (escalationModes.length > 0) notes.push(escalationHintMarker('command'))
+    return notes
+  }
+  return []
+}
+
+/**
+ * Map a settled background process onto the generic job-outcome vocabulary:
  * `killed` stays `killed` (detail: the signal when one is known), everything
  * else is `completed` with the exit code as detail. A nonzero command exit is
- * reported, not failed, exactly like the foreground rendering.
+ * reported, not failed, exactly like the foreground rendering. Sandbox facts
+ * join the detail, since a job's terminal reason is the one line every
+ * reader — the model's status line, the roster row — shows.
  * @param proc - the settled process handle.
+ * @param escalationModes - escalation targets advertised by this composition.
  * @returns the outcome for the `ctx.jobs` registration.
  */
-export function processOutcome(proc: ShellProcess): { status: 'completed' | 'killed'; detail: string } {
+export function processOutcome(proc: ShellProcess, escalationModes: readonly SandboxMode[] = []): JobOutcome {
   // TODO(background-infrastructure-outcome): widen ShellProcess with an explicit
   // infrastructure-failure outcome, then map spawn failures and
-  // sandbox.runnerFailed to task `failed`. The current contract aliases a spawn
+  // sandbox.runnerFailed to job `failed`. The current contract aliases a spawn
   // failure with a signal-less kill and a runner failure with an ordinary
   // wrapper exit; real nonzero command exits must remain `completed`.
-  if (proc.status === 'killed') {
-    return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
-  }
-  return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+  const base: JobOutcome = proc.status === 'killed'
+    ? { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
+    : { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+  const notes = sandboxNotes(proc.sandbox, escalationModes)
+  return notes.length === 0 ? base : { ...base, detail: `${base.detail}; ${notes.join(' ')}` }
+}
+
+/**
+ * The process's non-consuming stream readers as registry pull sources. They
+ * bind lazily because the process is spawned inside the starter, after the
+ * registry admitted the job; a read before the spawn yields nothing, and the
+ * pump keeps the model's consuming cursor untouched. A rejected spawn's
+ * stderr reader carries the provider's `spawn failed: …` note.
+ * @param proc - the started process's observed streams, once the starter has spawned it.
+ * @returns one source per stream, stdout first.
+ */
+export function processSources(proc: () => Pick<ShellProcess, 'observed'> | undefined): JobOutputSource[] {
+  const source = (channel: 'stdout' | 'stderr'): JobOutputSource => ({
+    channel,
+    read: (fromByte) => {
+      const live = proc()
+      return live === undefined ? { text: '', nextOffset: fromByte, lossy: false } : live.observed[channel].readFrom(fromByte)
+    },
+  })
+  return [source('stdout'), source('stderr')]
 }
 
 /**
  * Adapt asynchronous shell preparation after job admission without exposing a partial process.
  * @param start - starts the process with job-owned cancellation.
- * @param renderOutput - consumes output from a published process.
+ * @param outcome - projects the settled process into the job outcome.
  * @returns synchronous job hooks whose completion includes preparation and process settlement.
  */
 export function processJob(
   start: (signal: AbortSignal) => Promise<ShellProcess>,
-  renderOutput: (process: ShellProcess) => string,
+  outcome: (process: ShellProcess) => JobOutcome,
 ): JobHooks {
   const controller = new AbortController()
   let process: ShellProcess | undefined
@@ -50,7 +96,7 @@ export function processJob(
       } finally {
         await process.done
       }
-      return processOutcome(process)
+      return outcome(process)
     } catch (error: unknown) {
       return {
         status: controller.signal.aborted && process === undefined ? 'killed' : 'failed',
@@ -65,7 +111,6 @@ export function processJob(
       process?.kill()
     },
     done,
-    readOutput: () => process === undefined ? '' : renderOutput(process),
   }
 }
 /* jscpd:ignore-end */
diff --git a/packages/shell/tool-pwsh/src/index.ts b/packages/shell/tool-pwsh/src/index.ts
index 76e43401c4..bbb266ba38 100644
--- a/packages/shell/tool-pwsh/src/index.ts
+++ b/packages/shell/tool-pwsh/src/index.ts
@@ -32,10 +32,10 @@ import type {} from '@deepseek-ai/dsh-user-approval'
 import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
-import type { ShellRunResult } from '@deepseek-ai/dsh-shell'
+import type { ShellRunResult, ShellProcess } from '@deepseek-ai/dsh-shell'
 import { parseExitStatus } from '@deepseek-ai/dsh-shell'
-import { processJob } from './background.ts'
-import { renderPwshProcessRead, renderPwshResult } from './render.ts'
+import { processJob, processOutcome, processSources } from './background.ts'
+import { renderPwshResult } from './render.ts'
 import type { RenderablePwshResult } from './render.ts'
 
 declare module '@deepseek-ai/dsh-jobs' {
@@ -47,6 +47,7 @@ declare module '@deepseek-ai/dsh-jobs' {
 export const name = 'tool-pwsh'
 export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv']
 
+/* jscpd:ignore-start -- the pwsh Config mirrors tool-bash's by design, like render/background. */
 /** Configuration for the pwsh tool. */
 export interface Config {
   /** Expose `run_in_background` (default true); disabled calls are also rejected. */
@@ -57,6 +58,7 @@ export interface Config {
 export const Config: z<Config> = z.object({
   enableRunInBackground: z.boolean().default(true),
 })
+/* jscpd:ignore-end */
 
 /** Parsed tool args; execute validates value constraints absent from ParameterSchemaSpec. */
 interface PwshToolArgs {
@@ -376,14 +378,21 @@ export function apply(ctx: Context, config: Config = {}): void {
           error.name = 'AbortError'
           throw error
         }
-        // Task preflight finishes before the starter can spawn a process.
+        // The registry pumps the process's non-consuming readers into the
+        // job's ring; the sources bind lazily because the process is spawned
+        // only once admission has passed.
+        let proc: ShellProcess | undefined
         const id = jobs.start({
           kind: 'pwsh',
           label: args.command,
-          ...exec.agent ? { owner: exec.agent } : {},
+          ...exec.agent ? { owner: exec.agent.id } : {},
+          output: processSources(() => proc),
           run: () => processJob(
-            signal => ctx.shell.start(ctx.shell.resolve({ ...request, signal })),
-            proc => renderPwshProcessRead(proc.readOutput(), proc.sandbox, escalationModes),
+            async (signal) => {
+              proc = await ctx.shell.start(ctx.shell.resolve({ ...request, signal }))
+              return proc
+            },
+            started => processOutcome(started, escalationModes),
           ),
         })
         return { kind: 'background' as const, jobId: id }
diff --git a/packages/shell/tool-pwsh/src/render.ts b/packages/shell/tool-pwsh/src/render.ts
index cc7b8a661d..01e0a51e2e 100644
--- a/packages/shell/tool-pwsh/src/render.ts
+++ b/packages/shell/tool-pwsh/src/render.ts
@@ -10,7 +10,7 @@
  * @module @deepseek-ai/dsh-tool-pwsh/render
  */
 
-import type { ShellProcessRead, ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell'
+import type { ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
 
@@ -80,34 +80,4 @@ export function renderPwshResult(
   return body + markers.join('\n')
 }
 
-/**
- * Shape one background-process read into the `job_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.
- * @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.
- * @returns the delta text with any loss or sandbox notice appended.
- */
-export function renderPwshProcessRead(
-  read: ShellProcessRead,
-  sandbox?: ShellSandboxInfo,
-  escalationModes: readonly SandboxMode[] = [],
-): string {
-  const notices: string[] = []
-  if (read.lossy) {
-    const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path): path is string => path !== undefined)
-    notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`)
-  }
-  if (sandbox?.runnerFailed) {
-    notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`)
-  } else if (sandbox?.denied) {
-    notices.push(sandboxDenialMarker(sandbox.mode))
-    if (escalationModes.length > 0) {
-      notices.push(escalationHintMarker('command'))
-    }
-  }
-  if (notices.length === 0) return read.delta
-  return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}`
-}
 /* jscpd:ignore-end */
diff --git a/packages/shell/tool-pwsh/tests/background-start.spec.ts b/packages/shell/tool-pwsh/tests/background-start.spec.ts
index 19e31e3a10..4140d50c44 100644
--- a/packages/shell/tool-pwsh/tests/background-start.spec.ts
+++ b/packages/shell/tool-pwsh/tests/background-start.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, onTestFinished, vi } from 'vitest'
 import type { ShellProcess } from '@deepseek-ai/dsh-shell'
-import { processJob } from '../src/background.ts'
+import { processJob, processOutcome, processSources } from '../src/background.ts'
 
 function processHandle() {
   const exited = Promise.withResolvers<undefined>()
@@ -12,25 +12,34 @@ function processHandle() {
     killed.resolve(undefined)
     return true
   })
+  const readOutput = vi.fn(() => ({ delta: 'output', lossy: false }))
   const process: ShellProcess = {
     status: 'running', exitCode: null, signal: null, done: exited.promise,
-    readOutput: () => ({ delta: 'output', lossy: false }), kill,
+    readOutput, kill,
+    observed: {
+      stdout: { readFrom: fromByte => ({ text: 'output'.slice(fromByte), nextOffset: 6, lossy: false }) },
+      stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) },
+    },
   }
   onTestFinished(() => { exited.resolve(undefined) })
-  return { process, exited, killed, kill }
+  return { process, exited, killed, kill, readOutput }
 }
 
 describe('background job ownership during asynchronous shell startup', () => {
-  it('keeps output empty until a process is published and then consumes its output', async () => {
+  it('keeps observation empty during preparation and reads published output without consuming it', async () => {
     const child = processHandle()
     const prepared = Promise.withResolvers<ShellProcess>()
-    const render = vi.fn((process: ShellProcess) => process.readOutput().delta)
-    const hooks = processJob(() => prepared.promise, render)
-    expect(hooks.readOutput!()).toBe('')
-    expect(render).not.toHaveBeenCalled()
+    let published: ShellProcess | undefined
+    const source = processSources(() => published)[0]!
+    const outcome = vi.fn(processOutcome)
+    const hooks = processJob(async () => { published = await prepared.promise; return published }, outcome)
+    expect(source.read(0).text).toBe('')
+    expect(outcome).not.toHaveBeenCalled()
     prepared.resolve(child.process)
     await Promise.resolve()
-    expect(hooks.readOutput!()).toBe('output')
+    expect(source.read(0).text).toBe('output')
+    expect(source.read(0).text).toBe('output')
+    expect(child.readOutput).not.toHaveBeenCalled()
     child.process.status = 'completed'
     child.process.exitCode = 5
     child.exited.resolve(undefined)
@@ -44,19 +53,18 @@ describe('background job ownership during asynchronous shell startup', () => {
       return new Promise<ShellProcess>((_resolve, reject) => {
         signal.addEventListener('abort', () => { reject(new Error(String(signal.reason))) }, { once: true })
       })
-    }, () => 'unreachable')
+    }, processOutcome)
     expect(received?.aborted).toBe(false)
     hooks.cancel('cancel pending confinement')
     hooks.cancel('later cancellation')
     expect(received?.reason).toBe('cancel pending confinement')
     expect(await hooks.done).toEqual({ status: 'killed', detail: 'cancel pending confinement' })
-    expect(hooks.readOutput!()).toBe('')
   })
 
   it('kills a process that materializes after cancellation and awaits its exit', async () => {
     const child = processHandle()
     const prepared = Promise.withResolvers<ShellProcess>()
-    const hooks = processJob(() => prepared.promise, () => 'output')
+    const hooks = processJob(() => prepared.promise, processOutcome)
     let settled = false
     void hooks.done.then(() => { settled = true })
     hooks.cancel('cancel before process publication')
@@ -70,7 +78,7 @@ describe('background job ownership during asynchronous shell startup', () => {
 
   it('cancels a published process once and keeps done pending until exit', async () => {
     const child = processHandle()
-    const hooks = processJob(async () => child.process, () => 'output')
+    const hooks = processJob(async () => child.process, processOutcome)
     await Promise.resolve()
     let settled = false
     void hooks.done.then(() => { settled = true })
@@ -88,7 +96,7 @@ describe('background job ownership during asynchronous shell startup', () => {
     const attempted = Promise.withResolvers<undefined>()
     vi.mocked(child.kill).mockImplementation(() => { attempted.resolve(undefined); throw new Error('termination failed') })
     const prepared = Promise.withResolvers<ShellProcess>()
-    const hooks = processJob(() => prepared.promise, () => '')
+    const hooks = processJob(() => prepared.promise, processOutcome)
     let settled = false
     void hooks.done.then(() => { settled = true })
     hooks.cancel('stop before publication')
@@ -100,17 +108,16 @@ describe('background job ownership during asynchronous shell startup', () => {
   })
 
   it('reports a startup failure through job completion without publishing output', async () => {
-    const render = vi.fn(() => 'unreachable')
+    const render = vi.fn(processOutcome)
     const hooks = processJob(async () => { throw new Error('remote sandbox unavailable') }, render)
     expect(await hooks.done).toEqual({ status: 'failed', detail: 'remote sandbox unavailable' })
-    expect(hooks.readOutput!()).toBe('')
     expect(render).not.toHaveBeenCalled()
   })
 
   it('reports a primitive upstream abort reason as a failed startup', async () => {
     const upstream = new AbortController()
     upstream.abort('upstream preparation stopped')
-    const hooks = processJob(async () => { upstream.signal.throwIfAborted(); throw new Error('unreachable') }, () => '')
+    const hooks = processJob(async () => { upstream.signal.throwIfAborted(); throw new Error('unreachable') }, processOutcome)
     expect(await hooks.done).toEqual({ status: 'failed', detail: 'upstream preparation stopped' })
   })
 })
diff --git a/packages/shell/tool-pwsh/tests/background.spec.ts b/packages/shell/tool-pwsh/tests/background.spec.ts
new file mode 100644
index 0000000000..8ceb0b88bf
--- /dev/null
+++ b/packages/shell/tool-pwsh/tests/background.spec.ts
@@ -0,0 +1,244 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session/types'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
+import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs'
+import { ShellExecutor } from '@deepseek-ai/dsh-shell'
+import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell'
+import * as ToolPwsh from '@deepseek-ai/dsh-tool-pwsh'
+import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env'
+import { processSources } from '../src/background.ts'
+
+const testToolSignal = new AbortController().signal
+
+/** ASCII-only scripted stream: readFrom offsets are byte-exact string indexes. */
+function scriptedReader(state: { text: string }) {
+  return {
+    readFrom(fromByte: number) {
+      return { text: state.text.slice(fromByte), nextOffset: state.text.length, lossy: false }
+    },
+  }
+}
+
+/** A running fake background handle over scripted non-consuming observed streams. */
+function observableProcess(streams: { stdout: { text: string }; stderr: { text: string } } = { stdout: { text: '' }, stderr: { text: '' } }) {
+  let resolveDone: () => void = () => {}
+  const done = new Promise<void>((resolve) => { resolveDone = resolve })
+  const proc: ShellProcess = {
+    status: 'running',
+    exitCode: null,
+    signal: null,
+    done,
+    readOutput: () => ({ delta: '', lossy: false }),
+    kill: () => false,
+    observed: { stdout: scriptedReader(streams.stdout), stderr: scriptedReader(streams.stderr) },
+  }
+  return {
+    proc,
+    finish() {
+      proc.status = 'completed'
+      proc.exitCode = 0
+      resolveDone()
+    },
+  }
+}
+
+class FakePwsh extends ShellExecutor {
+  backgroundHandler: (spec: ShellExecSpec) => ShellProcess = () => { throw new Error('unscripted start') }
+
+  override resolve(request: ShellExecRequest): ShellExecSpec {
+    return {
+      command: request.command,
+      workdir: request.workdir ?? process.cwd(),
+      timeoutMs: request.timeoutMs ?? 60_000,
+      stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
+      ...request.signal ? { signal: request.signal } : {},
+      ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
+      sandboxPolicy: request.sandboxPolicy,
+    }
+  }
+
+  override async run(): Promise<ShellRunResult> {
+    throw new Error('foreground is not exercised here')
+  }
+
+  override async start(spec: ShellExecSpec): Promise<ShellProcess> {
+    return this.backgroundHandler(spec)
+  }
+}
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRuntime)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LocalJobRegistry, { pumpPollMs: 5 })
+  await ctx.plugin(ToolTasks)
+  await ctx.plugin(BashEnvPlugin)
+  await ctx.plugin(FakePwsh)
+  await ctx.plugin(ToolPwsh)
+  return { ctx, pwsh: ctx.shell as FakePwsh }
+}
+
+let callCounter = 0
+function call(ctx: Context, args: Record<string, unknown>) {
+  return ctx.tools.execute({
+    signal: testToolSignal,
+    callId: ToolCallId(`pwsh-background-${++callCounter}`),
+    name: 'pwsh',
+    arguments: args,
+  })
+}
+
+async function until<T>(read: () => T | undefined, timeoutMs = 5_000): Promise<T> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const value = read()
+    if (value !== undefined) return value
+    await new Promise(resolve => setTimeout(resolve, 5))
+  }
+  throw new Error('condition not reached before timeout')
+}
+
+describe('background pwsh output', () => {
+  it('streams observed channels into the job ring and settles with the mapped outcome', async () => {
+    const { ctx, pwsh } = await setup()
+    const stdout = { text: '' }
+    const stderr = { text: '' }
+    const scripted = observableProcess({ stdout, stderr })
+    pwsh.backgroundHandler = () => scripted.proc
+
+    await call(ctx, { command: 'Get-Progress', description: 'test command', run_in_background: true })
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    expect(job).toBeDefined()
+    expect(job!.kind).toBe('pwsh')
+    expect(job!.output).toEqual({ total: 0, earliest: 0 })
+
+    stdout.text = 'progress-line\n'
+    stderr.text = 'warn-line\n'
+    await until(() => {
+      const chunks = jobs.readAt(job!.id, 0).chunks
+      return chunks.some(chunk => chunk.text.includes('progress-line'))
+        && chunks.some(chunk => chunk.text.includes('warn-line'))
+        ? true
+        : undefined
+    })
+    const chunks = jobs.readAt(job!.id, 0).chunks
+    expect(chunks.find(chunk => chunk.text.includes('progress-line'))?.channel).toBe('stdout')
+    expect(chunks.find(chunk => chunk.text.includes('warn-line'))?.channel).toBe('stderr')
+
+    scripted.finish()
+    await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined)
+    expect(jobs.get(job!.id).detail).toBe('exit code: 0')
+  })
+
+  it('a failing reader warns once and never fakes a terminal state onto the running job', async () => {
+    const { ctx, pwsh } = await setup()
+    const warn = vi.fn()
+    ctx.logger.warn = warn as never
+    let resolveDone: () => void = () => {}
+    const done = new Promise<void>((resolve) => { resolveDone = resolve })
+    const proc: ShellProcess = {
+      status: 'running',
+      exitCode: null,
+      signal: null,
+      done,
+      readOutput: () => ({ delta: '', lossy: false }),
+      kill: () => false,
+      observed: {
+        stdout: { readFrom() { throw new Error('reader boom') } },
+        stderr: { readFrom: () => ({ text: '', nextOffset: 0, lossy: false }) },
+      },
+    }
+    pwsh.backgroundHandler = () => proc
+    await call(ctx, { command: 'Get-Broken', description: 'test command', run_in_background: true })
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    await until(() => warn.mock.calls.some(args => String(args[0]).includes('output source for')) ? true : undefined)
+    // The reader already failed; the job must wait for real settlement rather
+    // than freezing a fake terminal state onto the running process.
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(jobs.get(job!.id).status).toBe('running')
+    expect(warn).toHaveBeenCalledTimes(1)
+    proc.status = 'completed'
+    proc.exitCode = 0
+    resolveDone()
+    await until(() => jobs.get(job!.id).status !== 'running' ? true : undefined)
+    expect(jobs.get(job!.id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' })
+  })
+
+  it('a silent process settles with an empty ring', async () => {
+    const { ctx, pwsh } = await setup()
+    const scripted = observableProcess()
+    pwsh.backgroundHandler = () => scripted.proc
+
+    await call(ctx, { command: 'Start-Job', description: 'test command', run_in_background: true })
+    const jobs = ctx.jobs
+    const job = jobs.list()[0]
+    expect(jobs.readAt(job!.id, 0).chunks).toEqual([])
+
+    scripted.finish()
+    await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined)
+    expect(jobs.get(job!.id).output).toEqual({ total: 0, earliest: 0 })
+  })
+})
+
+describe('owned background output (pwsh)', () => {
+  it('keeps an owned background run under the owning session', async () => {
+    const { ctx, pwsh } = await setup()
+    const ownerId = SessionId('pwsh-background-owner')
+    const owner: Agent = {
+      id: ownerId,
+      options: {},
+      session: Session.create(ownerId, undefined, {
+        version: SESSION_FORMAT_VERSION, id: ownerId, createdAt: 0, cwd: process.cwd(), isSeeded: false,
+      }),
+      inbox: unsupportedInbox(),
+      status: 'idle',
+      ctx,
+      send: () => {},
+      followup: () => {},
+      steer: () => {},
+      inject: () => {},
+      cancel: () => {},
+      runMaintenance: task => task(new AbortController().signal),
+      whenIdle: () => Promise.resolve(),
+    }
+    ctx.agents.register(owner)
+    const scripted = observableProcess()
+    pwsh.backgroundHandler = () => scripted.proc
+    await ctx.tools.execute({
+      signal: testToolSignal,
+      callId: ToolCallId('pwsh-background-owned'),
+      name: 'pwsh',
+      arguments: { command: 'Get-Slow', description: 'test command', run_in_background: true },
+      agent: owner,
+    })
+    const owned = ctx.jobs
+    const job = owned.list(owner.id)[0]
+    expect(job).toBeDefined()
+    expect(job!.owner).toBe(owner.id)
+    expect(() => ctx.jobs.readAt(job!.id, 0)).toThrow(/belongs to another session/)
+    expect(owned.readAt(job!.id, 0, owner.id).chunks).toEqual([])
+    scripted.finish()
+    await until(() => owned.get(job!.id, owner.id).status === 'completed' ? true : undefined)
+  })
+})
+
+describe('processSources (pwsh)', () => {
+  it('reads nothing while the process is not spawned yet', () => {
+    const [stdout, stderr] = processSources(() => undefined)
+    expect(stdout!.channel).toBe('stdout')
+    expect(stderr!.channel).toBe('stderr')
+    expect(stdout!.read(0)).toEqual({ text: '', nextOffset: 0, lossy: false })
+    expect(stderr!.read(3)).toEqual({ text: '', nextOffset: 3, lossy: false })
+  })
+})
diff --git a/packages/shell/tool-pwsh/tests/tools.spec.ts b/packages/shell/tool-pwsh/tests/tools.spec.ts
index 34e095d49c..d5c14d363d 100644
--- a/packages/shell/tool-pwsh/tests/tools.spec.ts
+++ b/packages/shell/tool-pwsh/tests/tools.spec.ts
@@ -32,9 +32,12 @@ import { turnBoundaryProjectionDefinition } from '@deepseek-ai/dsh-agent-loop'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
 import * as ToolPwsh from '@deepseek-ai/dsh-tool-pwsh'
 import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env'
-import type { ShellProcessRead } from '@deepseek-ai/dsh-shell'
+import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
 import { processOutcome } from '../src/background.ts'
-import { renderPwshProcessRead, renderPwshResult } from '../src/render.ts'
+import { renderPwshResult } from '../src/render.ts'
+
+/** Empty offset readers for fakes that never produce output. */
+const silentReader = { readFrom: (fromByte: number) => ({ text: '', nextOffset: fromByte, lossy: false }) }
 
 const testToolSignal = new AbortController().signal
 
@@ -97,20 +100,19 @@ function runResult(stdout: string, overrides?: Partial<ShellRunResult>): ShellRu
   }
 }
 
-/** A settled successful background handle; overrides script failure shapes. */
+/** A settled successful background handle whose stdout the registry pump reads by offset (ASCII: offsets are string indexes). */
 function fakeProcess(delta = 'bg-ok\n'): ShellProcess {
-  let consumed = false
   return {
     status: 'completed',
     exitCode: 0,
     signal: null,
     done: Promise.resolve(),
-    readOutput: () => {
-      if (consumed) return { delta: '', lossy: false }
-      consumed = true
-      return { delta, lossy: false }
-    },
+    readOutput: () => ({ delta: '', lossy: false }),
     kill: () => false,
+    observed: {
+      stdout: { readFrom: (fromByte: number) => ({ text: delta.slice(fromByte), nextOffset: delta.length, lossy: false }) },
+      stderr: { readFrom: (fromByte: number) => ({ text: '', nextOffset: fromByte, lossy: false }) },
+    },
   }
 }
 
@@ -124,6 +126,7 @@ function killableProcess(): ShellProcess {
     signal: null,
     done,
     readOutput: () => ({ delta: '', lossy: false }),
+    observed: { stdout: silentReader, stderr: silentReader },
     kill: () => {
       if (proc.status !== 'running') return false
       proc.status = 'killed'
@@ -1018,58 +1021,6 @@ describe('renderPwshResult sandbox markers', () => {
   })
 })
 
-describe('renderPwshProcessRead', () => {
-  const base: ShellProcessRead = { delta: 'out\n', lossy: false }
-
-  it('returns the delta verbatim for a lossless read', () => {
-    expect(renderPwshProcessRead(base)).toBe('out\n')
-    expect(renderPwshProcessRead({ delta: '', lossy: false })).toBe('')
-  })
-
-  it('appends the loss notice with the available spill paths', () => {
-    expect(renderPwshProcessRead({ ...base, lossy: true, stdoutSpillPath: 'C:\\spill\\out.log' }))
-      .toBe('out\n[some output was dropped from memory; full output: C:\\spill\\out.log]')
-    expect(renderPwshProcessRead({
-      ...base,
-      lossy: true,
-      stdoutSpillPath: 'C:\\spill\\out.log',
-      stderrSpillPath: 'C:\\spill\\err.log',
-    }))
-      .toBe('out\n[some output was dropped from memory; full output: C:\\spill\\out.log, C:\\spill\\err.log]')
-  })
-
-  it('reports (unavailable) when a lossy read has no safe spill path', () => {
-    expect(renderPwshProcessRead({ ...base, lossy: true }))
-      .toBe('out\n[some output was dropped from memory; full output: (unavailable)]')
-  })
-
-  it('an empty lossy delta is the notice alone', () => {
-    expect(renderPwshProcessRead({ delta: '', lossy: true, stderrSpillPath: 'C:\\spill\\err.log' }))
-      .toBe('[some output was dropped from memory; full output: C:\\spill\\err.log]')
-  })
-
-  it('inserts the separating newline only when the delta lacks one', () => {
-    expect(renderPwshProcessRead({ delta: 'tail', lossy: true }))
-      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
-    expect(renderPwshProcessRead({ delta: 'tail\n', lossy: true }))
-      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
-  })
-
-  it('appends the runner-failed notice (denial outranked)', () => {
-    expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true, runnerFailed: true }))
-      .toBe('x\n[sandbox: the sandbox runner itself failed under read-only mode — the command did not run; this is a sandbox problem, not a command failure]')
-  })
-
-  it('appends the denial marker and hints only when escalation is advertised', () => {
-    expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true }))
-      .toBe('x\n[sandbox: file access denied under read-only mode]')
-    expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true }, ['workspace-write']))
-      .toBe('x\n[sandbox: file access denied under read-only mode]\n'
-        + '[sandbox: escalation available — retry this exact command once with sandbox_permissions '
-        + '(the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
-  })
-})
-
 describe('processOutcome', () => {
   function settled(over: Partial<ShellProcess>): ShellProcess {
     return {
@@ -1078,6 +1029,7 @@ describe('processOutcome', () => {
       signal: null,
       done: Promise.resolve(),
       readOutput: () => ({ delta: '', lossy: false }),
+      observed: { stdout: silentReader, stderr: silentReader },
       kill: () => false,
       ...over,
     }
@@ -1102,4 +1054,14 @@ describe('processOutcome', () => {
     expect(processOutcome(settled({ exitCode: null })))
       .toEqual({ status: 'completed', detail: 'exit code: 0' })
   })
+
+  it('appends sandbox facts to the terminal detail', () => {
+    const denied = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } }), ['workspace-write'])
+    expect(denied.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')} ${escalationHintMarker('command')}`)
+    const deniedWithoutEscalation = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } }))
+    expect(deniedWithoutEscalation.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')}`)
+    const runnerFailed = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: false, runnerFailed: true } }))
+    expect(runnerFailed.detail).toContain('the sandbox runner itself failed under read-only mode')
+    expect(processOutcome(settled({ sandbox: { mode: 'read-only', denied: false } })).detail).toBe('exit code: 0')
+  })
 })
diff --git a/packages/skill/README.i18n.yaml b/packages/skill/README.i18n.yaml
index b147ecb55a..bcc2766dbf 100644
--- a/packages/skill/README.i18n.yaml
+++ b/packages/skill/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/skill/README.md
-README.md: 9546dfbfb2081480a1af8078d65481d0fc080ae3
-README.zh.md: eb1231b6fc7e110afdcc22fb25db3dd55b830092
+README.md: 75261bdca06b658f04fac17a3eab4306dbe5cecd
+README.zh.md: 7d1c38a4fb456f26bf038c8ddfe6f8182d0058f8
diff --git a/packages/skill/README.md b/packages/skill/README.md
index 9546dfbfb2..75261bdca0 100644
--- a/packages/skill/README.md
+++ b/packages/skill/README.md
@@ -29,6 +29,7 @@ The skill family lets agents and users discover and load reusable task instructi
 | [`skill-badge/`](skill-badge/README.md) | Bundles the official "powered by dsh" badge skill, disabled by default | registers on `ctx.skills` |
 | [`skill-office/`](skill-office/README.md) | Bundles Word, PowerPoint, and Excel workflows with structural file checks | registers on `ctx.skills` |
 | [`tool-skill/`](tool-skill/README.md) | Publishes the session skill catalog and the model-facing `skill` loader tool | registers on `ctx.tools` |
+| [`tool-workspace-dependencies/`](tool-workspace-dependencies/README.md) | Reports bundled Office interpreter paths and versions for Desktop and SDK carriers | registers on `ctx.tools` |
 
 -----
 
diff --git a/packages/skill/README.zh.md b/packages/skill/README.zh.md
index eb1231b6fc..7d1c38a4fb 100644
--- a/packages/skill/README.zh.md
+++ b/packages/skill/README.zh.md
@@ -29,6 +29,7 @@ skill 家族让 agent 和用户仅在需要时发现并加载可复用的任务
 | [`skill-badge/`](skill-badge/README.zh.md) | 随包附带官方「powered by dsh」徽章 skill，默认禁用 | 注册到 `ctx.skills` |
 | [`skill-office/`](skill-office/README.zh.md) | 随包提供 Word、PowerPoint 和 Excel 工作流及文件结构检查 | 注册到 `ctx.skills` |
 | [`tool-skill/`](tool-skill/README.zh.md) | 发布会话 skill 目录与面向模型的 `skill` 加载工具 | 注册到 `ctx.tools` |
+| [`tool-workspace-dependencies/`](tool-workspace-dependencies/README.zh.md) | 为 Desktop 与 SDK 载体报告内置 Office 解释器路径和版本 | 注册到 `ctx.tools` |
 
 -----
 
diff --git a/packages/skill/tool-workspace-dependencies/README.i18n.yaml b/packages/skill/tool-workspace-dependencies/README.i18n.yaml
new file mode 100644
index 0000000000..e4f60d45f5
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/skill/tool-workspace-dependencies/README.md
+README.md: 1f7147a1febeb0210befe64dc462e2527013dab3
+README.zh.md: f2a1934256776ef97d414be4709a6b918989ae35
diff --git a/packages/skill/tool-workspace-dependencies/README.md b/packages/skill/tool-workspace-dependencies/README.md
new file mode 100644
index 0000000000..1f7147a1fe
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/README.md
@@ -0,0 +1,128 @@
+---
+description: "The load_workspace_dependencies tool: absolute paths into a bundled Python, Node.js, and pnpm payload, used in place or installed under the Harness home."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-workspace-dependencies
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Deployments that ship their own script runtimes (Desktop's primary runtime, or a container image layer) mount this tool so the agent can ask where the bundled Python, Node.js, and pnpm live instead of discovering a system interpreter. The tool returns absolute paths and recorded distribution versions; it changes neither `PATH` nor package-manager settings. The payload is either copied under the Harness home on first use (Desktop) or used where it lies (read-only carriers).
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the plugin beside the tool registry with the payload directory. Configuration validation requires a nonempty `source` and rejects empty `root` values before activation; both paths must be absolute. The bundled Office skills (`@deepseek-ai/dsh-skill-office`) reference this tool by name for their default interpreter.
+
+### Minimal configuration
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-workspace-dependencies'
+  config:
+    source: /path/to/primary-runtime
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `source` | required | Absolute payload directory carrying `runtime.json` and `dependencies/`. |
+| `root` | unset | Absolute installation directory under the Harness home. Set: the payload is copied there on the first call and reused while `runtime.json` is unchanged. Unset: the payload is validated and used in place; nothing is copied. |
+
+### Payload layout
+
+`runtime.json` records `desktopVersion`, `platform` (`win32`, `darwin`, or `linux`), `arch`, optional `payloadDigest`, top-level `python`, optional `node`/`pnpm` versions, and the complete `pythonPackages` distribution-version map. A pnpm entry requires Node.js. Python libraries, including numpy and pandas, appear only in `pythonPackages`. Entries live under `dependencies/`: `python/bin/python3` (`python/python.exe` on Windows) with `site-packages` beneath it, and, when declared, `node/bin/node` with `node/node_modules` and `pnpm/bin/pnpm.mjs`. A manifest whose platform or architecture differs from the running process is rejected.
+
+The packaged `sdk` profile uses its bundled Python and Office skills by default; `DSH_PRIMARY_RUNTIME` overrides the resource location, and an empty value opts out. Source launches without a carrier default remain opt-in. See [runtime configuration](../../../python/sdk-runtime/README.md) for independent skill selection. Missing skill resources produce a startup warning; invalid or incomplete external runtime payloads fail the first tool call. Profile configuration changes require restarting the SDK process.
+
+### Build a carrier payload
+
+From a repository checkout with dependencies installed, `CI=true pnpm run prepare:primary-runtime --target linux-x64 --output /tmp/dsh-office` writes `primary-runtime/` and `office-skills/`. The shared [download lock](../../../scripts/primary-runtime/lock.json) also covers `linux-arm64`, `mac-arm64`, `mac-x64`, and `win-x64`. `--python-only` omits Node.js and pnpm; `--cache` selects the hash-verified archive cache. The entry executes interpreter and Office read/write checks only for a native target. Cross-target builds require those checks on the target host before deployment.
+
+A container can copy both directories into an immutable image layer and set `DSH_PRIMARY_RUNTIME` to the absolute `primary-runtime/` path. The SDK queries that payload in place. Desktop uses the same builder and retains its Harness-home installation and signing checks.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+`readPrimaryRuntime` and build smoke checks share `parsePrimaryRuntime`. It validates the flat manifest and rejects duplicate normalized distribution names. Legacy `components` metadata is normalized in memory, retaining its consistency checks; a missing legacy distribution map becomes empty. Mixed flat and legacy version fields are rejected. Reads do not rewrite metadata, and equivalent normalized manifests can reuse an installed payload. `workspaceDependencyPaths` derives the platform-specific entries. `installPrimaryRuntime` copies into a staging directory, requires declared interpreters and scripts to be files and package roots to be directories, and swaps it into place while retaining the previous tree on failure; `resolvePrimaryRuntime` verifies the same entries without copying. The tool memoizes the first successful preparation for the plugin's lifetime.
+
+| File | Responsibility |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Manifest validation, path derivation, in-place and installed preparation, tool registration. |
+| — | No runtime invariant companion is published: the payload manifest is validated on every preparation, and the tool registry owns registration lifecycle. |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Office skills](../skill-office/README.md) — the workflows that call this tool for their interpreter.
+- [Tool registry](../../core/tools/README.md) — registration and schemas.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`load_workspace_dependencies` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workspace-dependencies).
+
+#### Token effect
+
+Fixed schema cost per request where the tool is visible; the description names the bundled Office libraries so the model can choose the interpreter without loading a skill first.
+
+#### KV Cache effect
+
+Prefix-stable while the tool definition and visibility are unchanged.
+
+### Tool result
+
+#### What the model sees
+
+One JSON object with absolute `python` and `pythonPackages` paths, `pythonDistributions` from `runtime.json`, and `node`, `nodePackages`, and `pnpm` when the payload declares them. Repeated calls return the same object.
+
+#### Token effect
+
+A few hundred characters per call; paths dominate.
+
+#### KV Cache effect
+
+Append-only tool result in the turn history; no prompt section is added.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Linux targets require glibc; musl payloads are not locked.
+- Windows payloads used in place must already be executable from their carrier; the in-place mode performs no permission repair.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+Placement and carrier choices are recorded in the [shared-runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.md).
+
+</details>
diff --git a/packages/skill/tool-workspace-dependencies/README.zh.md b/packages/skill/tool-workspace-dependencies/README.zh.md
new file mode 100644
index 0000000000..f2a1934256
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/README.zh.md
@@ -0,0 +1,128 @@
+---
+description: "load_workspace_dependencies 工具：返回随包附带的 Python、Node.js 与 pnpm 的绝对路径，payload 可原地使用或安装到 Harness home。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-workspace-dependencies
+
+[English](README.md) | 中文
+
+## 概述
+
+自带脚本运行时的部署（Desktop 的 primary runtime，或容器镜像层）挂载本工具，让 agent 询问随包的 Python、Node.js 与 pnpm 在哪里，而不是自行寻找系统解释器。工具返回绝对路径与记录的发行版版本，不改 `PATH`，不改包管理器设置。payload 或在首次调用时复制到 Harness home 下（Desktop），或原地使用（只读载体）。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [了解实现](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+与工具注册表一起挂载，给出 payload 目录。配置校验在激活前要求非空 `source` 并拒绝空 `root`；两条路径都必须为绝对路径。内置 Office skills（`@deepseek-ai/dsh-skill-office`）按名字引用本工具取默认解释器。
+
+### 最小配置
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-workspace-dependencies'
+  config:
+    source: /path/to/primary-runtime
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `source` | 必填 | 含 `runtime.json` 与 `dependencies/` 的 payload 绝对目录。 |
+| `root` | 未设置 | Harness home 下的绝对安装目录。设置时首次调用把 payload 复制过去，`runtime.json` 不变则复用；未设置时校验后原地使用，不复制。 |
+
+### payload 布局
+
+`runtime.json` 记录 `desktopVersion`、`platform`（`win32`、`darwin` 或 `linux`）、`arch`、可选的 `payloadDigest`、顶层 `python` 与可选的 `node`/`pnpm` 版本，以及完整的 `pythonPackages` 分发包版本表。声明 pnpm 时必须同时声明 Node.js。numpy、pandas 等 Python 库只出现在 `pythonPackages` 中。条目位于 `dependencies/`：`python/bin/python3`（Windows 为 `python/python.exe`）及其下的 `site-packages`；声明了才有的 `node/bin/node`、`node/node_modules` 与 `pnpm/bin/pnpm.mjs`。平台或架构与当前进程不符的清单被拒绝。
+
+打包的 `sdk` profile 默认使用随包 Python 和 Office skills；`DSH_PRIMARY_RUNTIME` 覆盖资源位置，空值表示禁用。没有载体默认路径的源码启动仍需显式启用。独立选择 skills 的方式见[运行时配置](../../../python/sdk-runtime/README.zh.md)。缺少 skill 资源会产生启动警告；无效或不完整的外部运行时 payload 在首次工具调用时失败。profile 配置变更需要重启 SDK 进程。
+
+### 构建载体 payload
+
+在已安装依赖的仓库 checkout 中运行 `CI=true pnpm run prepare:primary-runtime --target linux-x64 --output /tmp/dsh-office`，会生成 `primary-runtime/` 和 `office-skills/`。[共享下载锁](../../../scripts/primary-runtime/lock.json)还覆盖 `linux-arm64`、`mac-arm64`、`mac-x64` 和 `win-x64`。`--python-only` 省略 Node.js 和 pnpm；`--cache` 选择经过哈希校验的归档缓存。入口仅对本机目标执行解释器与 Office 读写检查。跨目标构建必须在部署前到目标主机执行这些检查。
+
+容器可将这两个目录复制到不可变镜像层，并将 `DSH_PRIMARY_RUNTIME` 设为 `primary-runtime/` 的绝对路径。SDK 原位查询该 payload。Desktop 使用同一构建器，并保留 Harness-home 安装与签名检查。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 了解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+`readPrimaryRuntime` 与构建冒烟检查共用 `parsePrimaryRuntime`。它校验扁平清单，拒绝归一化后重名的分发包。旧 `components` 元数据在内存中归一化，并保留旧格式的一致性校验；旧分发包版本表缺失时转换为空表。混用顶层与旧组件版本字段会被拒绝。读取不改写元数据，归一化后等价的清单可复用已安装产物。`workspaceDependencyPaths` 推导各平台的条目路径。`installPrimaryRuntime` 复制到暂存目录、要求声明的解释器和脚本为文件、库路径为目录、再换入正式位置，失败时保留旧树；`resolvePrimaryRuntime` 做同样的校验但不复制。工具在插件生命周期内记住首次成功的结果。
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 清单校验、路径推导、原地与安装两种准备方式、工具注册。 |
+| — | 不发布运行时不变量伴随入口：每次准备都校验 payload 清单，工具注册表负责注册生命周期。 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [Office skills](../skill-office/README.zh.md)——调用本工具取解释器的工作流。
+- [工具注册表](../../core/tools/README.zh.md)——注册与 schema。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到什么
+
+模型看到生成的 [`load_workspace_dependencies` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-workspace-dependencies)。
+
+#### Token 影响
+
+工具可见的每个请求固定一份 schema 开销；描述里列出了随包的 Office 库，模型不必先加载 skill 就能选择解释器。
+
+#### KV 缓存影响
+
+工具定义与可见性不变时前缀稳定。
+
+### 工具结果
+
+#### 模型看到什么
+
+一个 JSON 对象：绝对路径 `python` 与 `pythonPackages`、来自 `runtime.json` 的 `pythonDistributions`，以及 payload 声明了才有的 `node`、`nodePackages` 与 `pnpm`。重复调用返回同一对象。
+
+#### Token 影响
+
+每次调用几百个字符，以路径为主。
+
+#### KV 缓存影响
+
+作为工具结果追加进轮次历史；不增加提示词分区。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Linux 目标需要 glibc；尚未锁定 musl payload。
+- Windows 上原地使用的 payload 须在载体里已可执行；原地模式不修复权限。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+包归属与载体选择记录在[共享运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-09-17-shared-office-runtime.zh.md) 中。
+
+</details>
diff --git a/packages/skill/tool-workspace-dependencies/package.json b/packages/skill/tool-workspace-dependencies/package.json
new file mode 100644
index 0000000000..81597a74dc
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-tool-workspace-dependencies",
+  "description": "The load_workspace_dependencies tool: absolute paths into a bundled Python, Node.js, and pnpm payload",
+  "version": "0.1.6-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/skill/tool-workspace-dependencies"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/cordis-plugin-loader": "workspace:^",
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "workspace:^"
+  }
+}
diff --git a/packages/skill/tool-workspace-dependencies/src/index.ts b/packages/skill/tool-workspace-dependencies/src/index.ts
new file mode 100644
index 0000000000..973a5220b8
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/src/index.ts
@@ -0,0 +1,277 @@
+/** Model-facing query for a bundled Python, Node.js, and pnpm payload, in place or installed under the Harness home. */
+
+import { cp, lstat, mkdir, mkdtemp, readFile, rename, rm, stat } from 'node:fs/promises'
+import { dirname, isAbsolute, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+/** Cordis plugin identity. */
+export const name = 'tool-workspace-dependencies'
+/** Registry the tool registers into. */
+export const inject = ['tools']
+
+/** Payload location and optional installation directory. */
+export interface Config {
+  /** Payload directory carrying `runtime.json` and `dependencies/`. */
+  readonly source: string
+  /**
+   * Installation directory under the Harness home. When set, the payload is copied there on the
+   * first call (the Desktop behavior); when omitted, the payload is used in place without copying,
+   * which suits read-only carriers such as container image layers.
+   */
+  readonly root?: string
+}
+
+/** Require a named payload source before the Loader activates the tool. */
+export const Config: z<Config> = z.object({
+  source: z.string().min(1).required(),
+  root: z.string().min(1),
+})
+
+/** Canonical build metadata, independent of user-installed packages; legacy files are normalized on read. */
+export interface PrimaryRuntimeManifest {
+  readonly desktopVersion: string
+  readonly platform: string
+  readonly arch: string
+  /** Locked payload identity; absent only in installations made before payload hashing. */
+  readonly payloadDigest?: string
+  /** Bundled Python interpreter version. */
+  readonly python: string
+  /** Absent when the payload ships no Node.js. */
+  readonly node?: string
+  /** Bundled pnpm version; requires a bundled Node.js executable. */
+  readonly pnpm?: string
+  /** All recorded Python distribution versions; empty for legacy files without a distribution map. */
+  readonly pythonPackages: Readonly<Record<string, string>>
+}
+
+/** Absolute entry points and bundled versions; pnpm runs through the returned Node executable. */
+export interface WorkspaceDependencies {
+  readonly python: string
+  readonly node?: string
+  readonly pnpm?: string
+  readonly pythonPackages: string
+  readonly nodePackages?: string
+  /** Locked distribution versions; excludes packages users add to the installed environment. */
+  readonly pythonDistributions: Readonly<Record<string, string>>
+}
+
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/u
+const PLATFORMS = ['win32', 'darwin', 'linux']
+
+function isVersion(value: unknown): value is string {
+  return typeof value === 'string' && VERSION.test(value)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isDistributionMap(value: unknown): value is Readonly<Record<string, string>> {
+  return isRecord(value) && Object.entries(value).every(([name, version]) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name)
+    && typeof version === 'string' && /^\d[\w.!+-]*$/u.test(version))
+}
+
+/**
+ * Validate payload JSON and normalize legacy component fields to top-level versions.
+ * @param value - Untrusted decoded runtime.json contents.
+ * @returns Canonical metadata with one Python distribution map and no components field.
+ * @throws For malformed or mixed formats, duplicate distribution names, or inconsistent legacy metadata.
+ */
+export function parsePrimaryRuntime(value: unknown): PrimaryRuntimeManifest {
+  if (!isRecord(value)) throw new Error('primary runtime: invalid metadata')
+  const legacy = value.components !== undefined
+  const versions = legacy ? value.components : value
+  if (!isRecord(versions) || (legacy && ['python', 'node', 'pnpm'].some(key => value[key] !== undefined))) {
+    throw new Error('primary runtime: invalid metadata')
+  }
+  const { desktopVersion, platform, arch, payloadDigest } = value
+  const { python, node, pnpm } = versions
+  const pythonPackages = value.pythonPackages === undefined && legacy ? {} : value.pythonPackages
+  if (typeof desktopVersion !== 'string' || desktopVersion.length === 0
+    || typeof platform !== 'string' || !PLATFORMS.includes(platform)
+    || typeof arch !== 'string' || !['x64', 'arm64'].includes(arch)
+    || !isVersion(python)
+    || (node !== undefined && !isVersion(node))
+    || (pnpm !== undefined && (!isVersion(pnpm) || node === undefined))
+    || (payloadDigest !== undefined && (typeof payloadDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(payloadDigest)))
+    || !isDistributionMap(pythonPackages)) {
+    throw new Error('primary runtime: invalid metadata')
+  }
+  const entries = Object.entries(pythonPackages)
+  const distributions = new Map(entries.map(([name, version]) => [name.toLowerCase().replace(/[-_.]+/gu, '-'), version]))
+  if (distributions.size !== entries.length) throw new Error('primary runtime: invalid metadata')
+  // Only the old on-disk format duplicates these versions. New manifests use the distribution map alone.
+  if (legacy) {
+    for (const name of ['numpy', 'pandas'] as const) {
+      if (!isVersion(versions[name])) throw new Error('primary runtime: invalid metadata')
+      const version = distributions.get(name)
+      if (version !== undefined && version !== versions[name]) {
+        throw new Error(`primary runtime: conflicting ${name} distribution version`)
+      }
+    }
+  }
+  return {
+    desktopVersion, platform, arch,
+    ...(payloadDigest === undefined ? {} : { payloadDigest }),
+    python,
+    ...(node === undefined ? {} : { node }),
+    ...(pnpm === undefined ? {} : { pnpm }),
+    pythonPackages,
+  }
+}
+
+/**
+ * Read and normalize build metadata without rewriting the source file.
+ * @param root - Installed or bundled primary runtime directory.
+ * @returns Validated top-level versions and target identifiers, including for legacy components manifests.
+ */
+export async function readPrimaryRuntime(root: string): Promise<PrimaryRuntimeManifest> {
+  const value: unknown = JSON.parse(await readFile(join(root, 'runtime.json'), 'utf8'))
+  return parsePrimaryRuntime(value)
+}
+
+/**
+ * Resolve platform-specific interpreter and library locations without changing the environment.
+ * @param root - Absolute payload or installation directory.
+ * @param manifest - Validated runtime metadata.
+ * @returns Absolute paths for explicit script execution and recorded bundled Python versions.
+ */
+export function workspaceDependencyPaths(root: string, manifest: PrimaryRuntimeManifest): WorkspaceDependencies {
+  const dependencies = join(root, 'dependencies')
+  const windows = manifest.platform === 'win32'
+  const node = manifest.node === undefined ? {} : {
+    node: join(dependencies, 'node', 'bin', windows ? 'node.exe' : 'node'),
+    nodePackages: join(dependencies, 'node', 'node_modules'),
+  }
+  const pnpm = manifest.pnpm === undefined ? {} : { pnpm: join(dependencies, 'pnpm', 'bin', 'pnpm.mjs') }
+  return {
+    python: join(dependencies, 'python', ...(windows ? ['python.exe'] : ['bin', 'python3'])),
+    ...node,
+    ...pnpm,
+    pythonPackages: join(dependencies, 'python', ...(windows ? ['Lib'] : ['lib', `python${manifest.python.split('.').slice(0, 2).join('.')}`]), 'site-packages'),
+    pythonDistributions: manifest.pythonPackages,
+  }
+}
+
+async function validatePayloadEntries(paths: WorkspaceDependencies): Promise<void> {
+  for (const [path, kind] of [
+    [paths.python, 'file'], [paths.node, 'file'], [paths.pnpm, 'file'],
+    [paths.pythonPackages, 'directory'], [paths.nodePackages, 'directory'],
+  ] as const) {
+    if (path === undefined) continue
+    const entry = await stat(path)
+    if (!(kind === 'file' ? entry.isFile() : entry.isDirectory())) {
+      throw new Error(`primary runtime: expected ${kind} at ${path}`)
+    }
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    if ((await lstat(path)).isSymbolicLink()) throw new Error(`primary runtime: installation path is a filesystem link: ${path}`)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+async function compatibleManifest(source: string): Promise<PrimaryRuntimeManifest> {
+  const manifest = await readPrimaryRuntime(source)
+  if (manifest.platform !== process.platform || manifest.arch !== process.arch) throw new Error('primary runtime: incompatible platform or architecture')
+  return manifest
+}
+
+/**
+ * Use a payload where it lies: validate its metadata and entries, copying nothing.
+ * @param source - Payload directory, typically a read-only carrier.
+ * @returns Paths into the payload itself.
+ */
+export async function resolvePrimaryRuntime(source: string): Promise<WorkspaceDependencies> {
+  const paths = workspaceDependencyPaths(source, await compatibleManifest(source))
+  await validatePayloadEntries(paths)
+  return paths
+}
+
+/**
+ * Install the application-owned payload locally, retaining a complete previous tree on copy failure.
+ * @param source - Payload carried by the current installation.
+ * @param root - Fixed primary runtime directory under the Harness home.
+ * @returns Paths into the installed payload; no PATH or package-manager configuration is changed.
+ */
+export async function installPrimaryRuntime(source: string, root: string): Promise<WorkspaceDependencies> {
+  const manifest = await compatibleManifest(source)
+  await mkdir(dirname(root), { recursive: true })
+  const previous = `${root}.previous`
+  const previousExists = await exists(previous)
+  const rootExists = await exists(root)
+  if (!rootExists && previousExists) await rename(previous, root)
+  if (await exists(join(root, 'runtime.json')) && JSON.stringify(await readPrimaryRuntime(root)) === JSON.stringify(manifest)) {
+    const paths = workspaceDependencyPaths(root, manifest)
+    await validatePayloadEntries(paths)
+    return paths
+  }
+  const staging = await mkdtemp(join(dirname(root), '.primary-runtime-'))
+  try {
+    await cp(source, staging, { recursive: true, dereference: true })
+    const paths = workspaceDependencyPaths(staging, manifest)
+    await validatePayloadEntries(paths)
+    await rm(previous, { recursive: true, force: true })
+    const replacing = await exists(root)
+    if (replacing) await rename(root, previous)
+    try { await rename(staging, root) } catch (error) {
+      if (replacing) await rename(previous, root)
+      throw error
+    }
+    await rm(previous, { recursive: true, force: true })
+  } finally {
+    await rm(staging, { recursive: true, force: true })
+  }
+  return workspaceDependencyPaths(root, manifest)
+}
+
+/**
+ * Register the read-only path query; the first invocation prepares (or merely validates) the payload.
+ * @param ctx - Tool registry owner.
+ * @param config - Payload location and optional installation directory.
+ */
+export function apply(ctx: Context, config: Config): void {
+  if (!isAbsolute(config.source) || (config.root !== undefined && !isAbsolute(config.root))) {
+    throw new Error('workspace dependencies: source and root must be absolute paths')
+  }
+  let preparation: Promise<WorkspaceDependencies> | undefined
+  ctx.effect(() => async () => {
+    // Tool execution reports preparation failures; disposal only waits for filesystem work to settle.
+    await preparation?.catch(() => undefined)
+  })
+  ctx.tools.register(defineTool({
+    name: 'load_workspace_dependencies',
+    description: 'Get absolute paths to bundled Python and library directories, plus bundled Python distribution versions. Node.js and pnpm paths are included when the payload provides them. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. When Node.js and pnpm paths are returned, run pnpm with that Node executable and pnpm script path. This does not change PATH or package-manager settings.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          python: { type: 'string', required: true },
+          node: { type: 'string', description: 'Absent when the payload ships no Node.js.' },
+          pnpm: { type: 'string', description: 'Absent when the payload ships no pnpm.' },
+          pythonPackages: { type: 'string', required: true },
+          nodePackages: { type: 'string', description: 'Absent when the payload ships no Node.js.' },
+          pythonDistributions: { type: 'object', additionalProperties: true, required: true, description: 'Bundled distribution names and versions recorded in runtime.json; excludes user-installed additions.' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, undefined, 2) }],
+    },
+    execute: () => {
+      preparation ??= (config.root === undefined ? resolvePrimaryRuntime(config.source) : installPrimaryRuntime(config.source, config.root))
+        .catch((error: unknown) => {
+          preparation = undefined
+          throw error
+        })
+      return preparation
+    },
+    presentCall: () => ({ card: 'generic', title: 'Load workspace dependencies', kind: 'read' }),
+  }))
+}
diff --git a/packages/skill/tool-workspace-dependencies/tests/tool-workspace-dependencies.spec.ts b/packages/skill/tool-workspace-dependencies/tests/tool-workspace-dependencies.spec.ts
new file mode 100644
index 0000000000..57f1eb1c15
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/tests/tool-workspace-dependencies.spec.ts
@@ -0,0 +1,427 @@
+import * as fs from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rename, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, expect, it, vi } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import z from '@deepseek-ai/schemastery'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import * as workspaceDependencies from '../src/index.ts'
+import { installPrimaryRuntime, parsePrimaryRuntime, readPrimaryRuntime, resolvePrimaryRuntime, workspaceDependencyPaths, type PrimaryRuntimeManifest } from '../src/index.ts'
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof fs>()
+  return { ...actual, rename: vi.fn(actual.rename), lstat: vi.fn(actual.lstat), cp: vi.fn(actual.cp) }
+})
+
+const roots: string[] = []
+afterEach(async () => {
+  vi.resetAllMocks()
+  await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true })))
+})
+
+async function fixture() {
+  const directory = await mkdtemp(join(tmpdir(), 'dsh-primary-runtime-'))
+  roots.push(directory)
+  const source = join(directory, 'resources')
+  const root = join(directory, 'home', 'dsh-runtimes', 'dsh-primary-runtime')
+  const manifest: PrimaryRuntimeManifest = {
+    desktopVersion: '1.0.0', platform: process.platform, arch: process.arch,
+    python: '3.12.14', node: '24.21.0', pnpm: '11.7.0',
+    pythonPackages: { 'python-docx': '1.2.0', 'python-pptx': '1.0.2', openpyxl: '3.1.5' },
+  }
+  const paths = workspaceDependencyPaths(source, manifest)
+  for (const path of [paths.python, paths.node, paths.pnpm]) {
+    if (path === undefined) continue
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(path, 'interpreter')
+  }
+  await mkdir(paths.pythonPackages, { recursive: true })
+  if (paths.nodePackages !== undefined) await mkdir(paths.nodePackages, { recursive: true })
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(manifest))
+  return { source, root, manifest, directory }
+}
+
+it.each(['win32', 'darwin', 'linux'])('returns %s interpreter and package paths', (platform) => {
+  const manifest: PrimaryRuntimeManifest = { desktopVersion: '1', platform, arch: 'x64', python: '3.12.14', node: '24.21.0', pnpm: '11.7.0', pythonPackages: {} }
+  const paths = workspaceDependencyPaths('/runtime', manifest)
+  expect(paths.pythonDistributions).toEqual({})
+  expect(paths.python).toBe(join('/runtime', 'dependencies', 'python', ...(platform === 'win32' ? ['python.exe'] : ['bin', 'python3'])))
+  expect(paths.pythonPackages).toBe(join('/runtime', 'dependencies', 'python', ...(platform === 'win32' ? ['Lib'] : ['lib', 'python3.12']), 'site-packages'))
+})
+
+it('installs offline, reuses the same release, and leaves environment and user packages unchanged', async () => {
+  const { source, root, manifest } = await fixture()
+  const environment = { ...process.env }
+  const installed = await installPrimaryRuntime(source, root)
+  await writeFile(join(installed.pythonPackages, 'user-package.py'), 'user content')
+  expect(await installPrimaryRuntime(source, root)).toEqual(installed)
+  expect(installed.pythonDistributions).toEqual(manifest.pythonPackages)
+  expect(await readFile(join(installed.pythonPackages, 'user-package.py'), 'utf8')).toBe('user content')
+  expect(process.env).toEqual(environment)
+})
+
+it('replaces release components and recovers an interrupted directory swap', async () => {
+  const { source, root, manifest } = await fixture()
+  await installPrimaryRuntime(source, root)
+  await rename(root, `${root}.previous`)
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, desktopVersion: '2.0.0' }))
+  await installPrimaryRuntime(source, root)
+  expect((await readPrimaryRuntime(root)).desktopVersion).toBe('2.0.0')
+})
+
+it('replaces dependencies when the locked payload changes without a Desktop version change', async () => {
+  const { source, root, manifest } = await fixture()
+  const first = { ...manifest, payloadDigest: 'a'.repeat(64), pythonPackages: { 'python-docx': '1.1.2' } }
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(first))
+  const installed = await installPrimaryRuntime(source, root)
+  await writeFile(join(installed.pythonPackages, 'old-package.py'), 'old dependency')
+  const next = { ...first, payloadDigest: 'b'.repeat(64), pythonPackages: { 'python-docx': '1.2.0' } }
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(next))
+  await writeFile(join(workspaceDependencyPaths(source, next).pythonPackages, 'new-package.py'), 'new dependency')
+  await installPrimaryRuntime(source, root)
+  expect(await readPrimaryRuntime(root)).toEqual(next)
+  expect(await readFile(join(installed.pythonPackages, 'new-package.py'), 'utf8')).toBe('new dependency')
+  await expect(readFile(join(installed.pythonPackages, 'old-package.py'))).rejects.toMatchObject({ code: 'ENOENT' })
+})
+
+it('upgrades a release manifest without a payload digest', async () => {
+  const { source, root, manifest } = await fixture()
+  await installPrimaryRuntime(source, root)
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, payloadDigest: 'a'.repeat(64), pythonPackages: { 'python-docx': '1.2.0' } }))
+  await installPrimaryRuntime(source, root)
+  expect((await readPrimaryRuntime(root)).payloadDigest).toBe('a'.repeat(64))
+})
+
+it('replaces changed payload bytes when only the digest changes', async () => {
+  const { source, root, manifest } = await fixture()
+  const first = { ...manifest, payloadDigest: 'a'.repeat(64), pythonPackages: { 'python-docx': '1.2.0' } }
+  const sourceFile = join(workspaceDependencyPaths(source, first).pythonPackages, 'library.py')
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(first))
+  await writeFile(sourceFile, 'first wheel bytes')
+  const installed = await installPrimaryRuntime(source, root)
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...first, payloadDigest: 'b'.repeat(64) }))
+  await writeFile(sourceFile, 'repacked wheel bytes')
+  await installPrimaryRuntime(source, root)
+  expect(await readFile(join(installed.pythonPackages, 'library.py'), 'utf8')).toBe('repacked wheel bytes')
+  expect((await readPrimaryRuntime(root)).pythonPackages).toEqual(first.pythonPackages)
+})
+
+it('keeps the installed release when the replacement payload is incomplete', async () => {
+  const { source, root, manifest } = await fixture()
+  await installPrimaryRuntime(source, root)
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, desktopVersion: '2.0.0' }))
+  await rm(workspaceDependencyPaths(source, manifest).python)
+  await expect(installPrimaryRuntime(source, root)).rejects.toThrow()
+  expect((await readPrimaryRuntime(root)).desktopVersion).toBe('1.0.0')
+})
+
+it('refuses linked installation directories without modifying their targets', async () => {
+  const { source, root, directory } = await fixture()
+  const outside = join(directory, 'outside')
+  await mkdir(outside)
+  await writeFile(join(outside, 'keep'), 'untouched')
+  await mkdir(dirname(root), { recursive: true })
+  await symlink(outside, root, process.platform === 'win32' ? 'junction' : 'dir')
+  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('filesystem link')
+  expect(await readFile(join(outside, 'keep'), 'utf8')).toBe('untouched')
+})
+
+it.each(['in-place', 'copy', 'reuse'] as const)('rejects wrong payload entry types during %s preparation', async (mode) => {
+  for (const field of ['python', 'node', 'pnpm', 'pythonPackages', 'nodePackages'] as const) {
+    const { source, root, manifest } = await fixture()
+    if (mode === 'reuse') await installPrimaryRuntime(source, root)
+    const paths = workspaceDependencyPaths(mode === 'reuse' ? root : source, manifest)
+    const path = paths[field]!
+    const directory = field.endsWith('Packages')
+    await rm(path, { recursive: true })
+    if (directory) await writeFile(path, 'not a library directory')
+    else await mkdir(path)
+    const operation = mode === 'in-place' ? resolvePrimaryRuntime(source) : installPrimaryRuntime(source, root)
+    await expect(operation).rejects.toThrow(`expected ${directory ? 'directory' : 'file'} at`)
+    if (mode === 'copy') await expect(readFile(join(root, 'runtime.json'))).rejects.toMatchObject({ code: 'ENOENT' })
+  }
+})
+
+it('rejects malformed metadata and incompatible targets', async () => {
+  const { source, root, manifest } = await fixture()
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, arch: process.arch === 'x64' ? 'arm64' : 'x64' }))
+  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('incompatible')
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, python: '../escape' }))
+  await expect(readPrimaryRuntime(source)).rejects.toThrow('invalid metadata')
+})
+
+/** Previous Desktop files carry interpreter and selected library versions under components. */
+function legacyManifest(manifest: PrimaryRuntimeManifest) {
+  const { python, node, pnpm, ...metadata } = manifest
+  return { ...metadata, components: { python, node, pnpm, numpy: '2.3.5', pandas: '3.0.1' } }
+}
+
+it.each([['numpy', 'numpy'], ['pandas', 'pandas'], ['Numpy', 'numpy'], ['PANDAS', 'pandas']] as const)(
+  'rejects conflicting %s versions in a legacy manifest', async (distribution, name) => {
+    const { source, manifest } = await fixture()
+    const legacy = legacyManifest(manifest)
+    await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...legacy, pythonPackages: { [distribution]: '0.0.1' } }))
+    await expect(readPrimaryRuntime(source)).rejects.toThrow(`conflicting ${name} distribution version`)
+    const pythonPackages = { [distribution]: legacy.components[name] }
+    await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...legacy, pythonPackages }))
+    expect(await readPrimaryRuntime(source)).toEqual({ ...manifest, pythonPackages })
+  },
+)
+
+it.each([
+  { payloadDigest: 'invalid' },
+  { pythonPackages: ['python-docx'] },
+  { pythonPackages: { 'python-docx': '../escape' } },
+  { pythonPackages: { '../escape': '1.2.0' } },
+  { pythonPackages: { numpy: '2.3.5', Numpy: '2.3.5' } },
+  { pythonPackages: { Pillow: '12.3.0', pillow: '12.3.0' } },
+  { pythonPackages: { typing_extensions: '4.16.0', 'typing.extensions': '4.16.0' } },
+])('rejects invalid locked payload metadata: %j', async (invalid) => {
+  const { source, manifest } = await fixture()
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, ...invalid }))
+  await expect(readPrimaryRuntime(source)).rejects.toThrow('invalid metadata')
+})
+
+it('loads the real tool through Cordis, exposes payload paths in place, and unregisters on disposal', async () => {
+  const { source, manifest, directory } = await fixture()
+  const ctx = new Context()
+  try {
+    ctx.baseUrl = pathToFileURL(directory).href + '/'
+    await ctx.plugin(Loader)
+    ctx.loader.builtins.include = Include
+    Object.assign(ctx.loader.builtins, {
+      agents: AgentRegistry, systemPrompt: SystemPrompt, tools: ToolRuntime, dependencies: workspaceDependencies,
+    })
+    const config = join(directory, 'cordis.yml')
+    await writeFile(config, `- name: cordis:agents\n- name: cordis:systemPrompt\n- name: cordis:tools\n- name: cordis:dependencies\n  config:\n    source: ${JSON.stringify(source)}\n`)
+    await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(config).href } })
+    await ctx.loader.await()
+    for (const entry of ctx.loader.entries()) await entry.fiber?.await()
+    const environment = { ...process.env }
+    const request = { signal: new AbortController().signal, name: 'load_workspace_dependencies', arguments: {} }
+    const results = await Promise.all(['first', 'second'].map(id => ctx.tools.execute({ ...request, callId: ToolCallId(id) })))
+    for (const result of results) {
+      expect(result.isError).toBe(false)
+      expect(result.content).toEqual([{ type: 'text', text: JSON.stringify(workspaceDependencyPaths(source, manifest), undefined, 2) }])
+    }
+    expect(process.env).toEqual(environment)
+    const entry = [...ctx.loader.entries()].find(entry => entry.options.name === 'cordis:dependencies')
+    expect(entry).toBeDefined()
+    await entry?.fiber?.dispose()
+    expect(ctx.tools.schemas().some(tool => tool.name === 'load_workspace_dependencies')).toBe(false)
+  } finally {
+    await ctx.fiber.dispose()
+  }
+})
+
+it('uses a payload in place without copying and tolerates a payload without Node.js or pnpm', async () => {
+  const { source, directory } = await fixture()
+  const manifest: PrimaryRuntimeManifest = {
+    desktopVersion: '1.0.0', platform: process.platform, arch: process.arch,
+    python: '3.12.14',
+    pythonPackages: { 'python-docx': '1.2.0' },
+  }
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(manifest))
+  const paths = await resolvePrimaryRuntime(source)
+  expect(paths).toEqual({
+    python: join(source, 'dependencies', 'python', ...(process.platform === 'win32' ? ['python.exe'] : ['bin', 'python3'])),
+    pythonPackages: join(source, 'dependencies', 'python', ...(process.platform === 'win32' ? ['Lib'] : ['lib', 'python3.12']), 'site-packages'),
+    pythonDistributions: { 'python-docx': '1.2.0' },
+  })
+  await expect(readFile(join(directory, 'home', 'dsh-runtimes', 'dsh-primary-runtime', 'runtime.json'))).rejects.toMatchObject({ code: 'ENOENT' })
+  await rm(paths.python)
+  await expect(resolvePrimaryRuntime(source)).rejects.toMatchObject({ code: 'ENOENT' })
+})
+
+it('rejects a payload whose Node.js or pnpm version is malformed', async () => {
+  const { source, manifest } = await fixture()
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, node: 'latest' }))
+  await expect(readPrimaryRuntime(source)).rejects.toThrow('invalid metadata')
+})
+
+/** Create the real scoped tool registry for lifecycle and failure-path assertions. */
+async function tool(config: workspaceDependencies.Config) {
+  const ctx = new Context()
+  try {
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRuntime)
+    const fiber = ctx.plugin(workspaceDependencies, config)
+    await fiber
+    const execute = () => ctx.tools.execute({
+      signal: new AbortController().signal, name: 'load_workspace_dependencies',
+      arguments: {}, callId: ToolCallId('dependencies'),
+    })
+    return { ctx, fiber, execute }
+  } catch (error) {
+    await ctx.fiber.dispose()
+    throw error
+  }
+}
+
+it.each([null, [], { desktopVersion: '' }, { platform: 'unsupported' }, { arch: 'ia32' },
+  { python: undefined }, { python: 3 }, { node: 24 }, { pnpm: 'latest' }, { payloadDigest: 1 },
+  { pythonPackages: undefined }, { pythonPackages: null }, { pythonPackages: 3 }, { pythonPackages: { numpy: 3 } },
+  { desktopVersion: 1 }, { platform: ['linux'] }, { arch: ['x64'] },
+])('rejects malformed manifest fields: %j', async (invalid) => {
+  const { source, manifest } = await fixture()
+  const value = invalid === null || Array.isArray(invalid) ? invalid : { ...manifest, ...invalid }
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(value))
+  await expect(readPrimaryRuntime(source)).rejects.toThrow('invalid metadata')
+})
+
+it('reads legacy metadata without a distribution map and rejects incompatible platforms', async () => {
+  const { source, manifest } = await fixture()
+  const { pythonPackages: _packages, ...legacy } = legacyManifest(manifest)
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(legacy))
+  expect((await resolvePrimaryRuntime(source)).pythonDistributions).toEqual({})
+  await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, platform: process.platform === 'linux' ? 'darwin' : 'linux' }))
+  await expect(resolvePrimaryRuntime(source)).rejects.toThrow('incompatible')
+})
+
+it('propagates filesystem access failures without touching the installation', async () => {
+  const { source, root } = await fixture()
+  vi.mocked(fs.lstat).mockRejectedValueOnce(Object.assign(new Error('denied'), { code: 'EACCES' }))
+  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('denied')
+  await expect(readFile(join(root, 'runtime.json'))).rejects.toMatchObject({ code: 'ENOENT' })
+})
+
+it.each([false, true])('preserves the previous installation if publication fails (previous: %s)', async (previous) => {
+  const { source, root, manifest } = await fixture()
+  if (previous) {
+    await installPrimaryRuntime(source, root)
+    await writeFile(join(source, 'runtime.json'), JSON.stringify({ ...manifest, desktopVersion: '2.0.0' }))
+  }
+  const actual = await vi.importActual<typeof fs>('node:fs/promises')
+  vi.mocked(fs.rename).mockImplementationOnce(previous ? actual.rename : async () => { throw new Error('publication failed') })
+  if (previous) vi.mocked(fs.rename).mockRejectedValueOnce(new Error('publication failed'))
+  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('publication failed')
+  if (previous) expect((await readPrimaryRuntime(root)).desktopVersion).toBe('1.0.0')
+  else await expect(readFile(join(root, 'runtime.json'))).rejects.toMatchObject({ code: 'ENOENT' })
+  expect((await fs.readdir(dirname(root))).filter(name => name.startsWith('.primary-runtime-'))).toEqual([])
+})
+
+it('retries a failed tool preparation and renders its call presentation', async () => {
+  const { source, root } = await fixture()
+  const metadata = await readFile(join(source, 'runtime.json'))
+  await rm(join(source, 'runtime.json'))
+  const { ctx, execute } = await tool({ source, root })
+  try {
+    expect((await execute()).isError).toBe(true)
+    await writeFile(join(source, 'runtime.json'), metadata)
+    expect((await execute()).isError).toBe(false)
+    expect(await readFile(join(root, 'runtime.json'))).toEqual(metadata)
+    const descriptor = ctx.tools.get('load_workspace_dependencies')!
+    expect(descriptor.presentCall?.({})).toEqual({ card: 'generic', title: 'Load workspace dependencies', kind: 'read' })
+  } finally { await ctx.fiber.dispose() }
+})
+
+it.each([false, true])('disposal waits for pending filesystem preparation (failure: %s)', async (failure) => {
+  const { source, root } = await fixture()
+  const actual = await vi.importActual<typeof fs>('node:fs/promises')
+  let release!: () => void
+  let copying!: () => void
+  const entered = new Promise<void>((resolve) => { copying = resolve })
+  const proceed = new Promise<void>((resolve) => { release = resolve })
+  vi.mocked(fs.cp).mockImplementationOnce(async (...args) => {
+    copying()
+    await proceed
+    if (failure) throw new Error('copy failed')
+    await actual.cp(...args)
+  })
+  const { ctx, fiber, execute } = await tool({ source, root })
+  const pending = execute()
+  try {
+    await entered
+    let disposed = false
+    const disposal = fiber.dispose().then(() => { disposed = true })
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+    release()
+    await disposal
+    expect((await pending).isError).toBe(failure)
+    expect(ctx.tools.schemas().some(value => value.name === 'load_workspace_dependencies')).toBe(false)
+  } finally {
+    release()
+    await pending
+    await ctx.fiber.dispose()
+  }
+})
+
+it('disposes an unused tool without preparing the payload', async () => {
+  const { source, root } = await fixture()
+  const { ctx } = await tool({ source, root })
+  await ctx.fiber.dispose()
+  await expect(readFile(join(root, 'runtime.json'))).rejects.toMatchObject({ code: 'ENOENT' })
+})
+
+it.each([{ source: 'relative' }, { source: process.cwd(), root: 'relative' }])('rejects relative runtime configuration at plugin load: %j', async (config) => {
+  await expect(tool(config)).rejects.toThrow('must be absolute paths')
+})
+
+it.each([{}, { source: '' }, { source: 1 }])('rejects invalid payload configuration with a named source error: %j', (config) => {
+  expect(() => z.resolve(config, workspaceDependencies.Config, {})).toThrow('source')
+})
+
+it('validates the previous directory even when a current installation exists', async () => {
+  const { source, root, directory } = await fixture()
+  await installPrimaryRuntime(source, root)
+  const outside = join(directory, 'outside-previous')
+  await mkdir(outside)
+  await writeFile(join(outside, 'keep'), 'untouched')
+  await symlink(outside, `${root}.previous`, process.platform === 'win32' ? 'junction' : 'dir')
+  await expect(installPrimaryRuntime(source, root)).rejects.toThrow('filesystem link')
+  expect(await readFile(join(outside, 'keep'), 'utf8')).toBe('untouched')
+})
+
+it('normalizes legacy metadata without rewriting the source or leaking components', async () => {
+  const { source, manifest } = await fixture()
+  const stored = JSON.stringify(legacyManifest(manifest))
+  await writeFile(join(source, 'runtime.json'), stored)
+  expect(await readPrimaryRuntime(source)).toEqual(manifest)
+  expect(await readFile(join(source, 'runtime.json'), 'utf8')).toBe(stored)
+  expect(await resolvePrimaryRuntime(source)).toEqual(workspaceDependencyPaths(source, manifest))
+})
+
+it('reuses an equivalent legacy installation without replacing user-added packages', async () => {
+  const { source, root, manifest } = await fixture()
+  const stored = JSON.stringify(legacyManifest(manifest))
+  await writeFile(join(source, 'runtime.json'), stored)
+  const installed = await installPrimaryRuntime(source, root)
+  await writeFile(join(installed.pythonPackages, 'user-package.py'), 'keep')
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(manifest))
+  expect(await installPrimaryRuntime(source, root)).toEqual(installed)
+  expect(await readFile(join(root, 'runtime.json'), 'utf8')).toBe(stored)
+  expect(await readFile(join(installed.pythonPackages, 'user-package.py'), 'utf8')).toBe('keep')
+})
+
+it('accepts flat Python libraries without requiring or singling out numpy and pandas', async () => {
+  const { source, manifest } = await fixture()
+  const flat = { ...manifest, pythonPackages: { 'custom-library': '1.0.0' } }
+  await writeFile(join(source, 'runtime.json'), JSON.stringify(flat))
+  expect(await readPrimaryRuntime(source)).toEqual(flat)
+  expect((await resolvePrimaryRuntime(source)).pythonDistributions).toEqual(flat.pythonPackages)
+})
+
+it.each(['python', 'node', 'pnpm'])('rejects mixed legacy and flat %s fields', async (name) => {
+  const { manifest } = await fixture()
+  expect(() => parsePrimaryRuntime({ ...legacyManifest(manifest), [name]: '1.0.0' })).toThrow('invalid metadata')
+})
+
+it.each([null, [], 'invalid', { python: '3.12.14' }])('rejects malformed legacy components: %j', async (components) => {
+  const { manifest } = await fixture()
+  expect(() => parsePrimaryRuntime({ ...legacyManifest(manifest), components })).toThrow('invalid metadata')
+})
+
+it.each(['flat', 'legacy'])('rejects pnpm without a Node.js interpreter in %s metadata', async (format) => {
+  const { manifest } = await fixture()
+  const { node: _node, ...input } = manifest
+  expect(() => parsePrimaryRuntime(format === 'legacy' ? legacyManifest(input) : input)).toThrow('invalid metadata')
+})
diff --git a/packages/skill/tool-workspace-dependencies/tsconfig.json b/packages/skill/tool-workspace-dependencies/tsconfig.json
new file mode 100644
index 0000000000..a3e6344b9d
--- /dev/null
+++ b/packages/skill/tool-workspace-dependencies/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/tools"
+    }
+  ]
+}
diff --git a/packages/ssh/fs-ssh/README.i18n.yaml b/packages/ssh/fs-ssh/README.i18n.yaml
index 9c53eeb146..33b115144a 100644
--- a/packages/ssh/fs-ssh/README.i18n.yaml
+++ b/packages/ssh/fs-ssh/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ssh/fs-ssh/README.md
-README.md: a950726df972952a8430ef0d00ba455f2e0de11e
-README.zh.md: fa69aaee52c705b094de1b0f4860109023c2069f
+README.md: fe777f672ab7cf474adf10b05f6d6f646864548f
+README.zh.md: 9aa92d99584c48d9179e26ccd1f733d2bda36441
diff --git a/packages/ssh/fs-ssh/README.md b/packages/ssh/fs-ssh/README.md
index a950726df9..fe777f672a 100644
--- a/packages/ssh/fs-ssh/README.md
+++ b/packages/ssh/fs-ssh/README.md
@@ -67,7 +67,7 @@ This provider contributes no request-prefix content. Its consumers own model-vis
 <a id="known-limitations-and-deferred-work"></a>
 
 - Whole-text reads and individual byte windows are limited to 8 MiB by the helper. Use text streaming or multiple byte windows for larger reads; other JSON transfers also obey the connection’s frame cap.
-- Filesystem watching is unsupported: `watch()` throws without polling or opening a local watcher for a remote path. Ordinary reads and consumer-owned manual refresh remain available.
+- Filesystem watching is unsupported: the provider keeps no `watch()` override, so the base `FS_IO_ERROR` rejection applies without polling or opening a local watcher for a remote path. Ordinary reads and consumer-owned manual refresh remain available.
 - Remote file URLs are execution coordinates, not host filesystem handles or Web download links.
 
 <a id="dev-note"></a>
diff --git a/packages/ssh/fs-ssh/README.zh.md b/packages/ssh/fs-ssh/README.zh.md
index fa69aaee52..9aa92d9958 100644
--- a/packages/ssh/fs-ssh/README.zh.md
+++ b/packages/ssh/fs-ssh/README.zh.md
@@ -67,7 +67,7 @@ kind: "package-reference"
 <a id="known-limitations-and-deferred-work"></a>
 
 - 辅助程序将整段文本读取及单次字节窗口限制为 8 MiB。更大的读取需使用文本流或多个字节窗口；其他 JSON 传输也受连接消息大小上限约束。
-- 不支持文件系统监听：`watch()` 直接抛错，不使用轮询，也不为远程路径建立本地监听。普通读取与消费方提供的手动刷新仍可用。
+- 不支持文件系统监听：提供方不覆写 `watch()`，由基类以 `FS_IO_ERROR` 拒绝；不使用轮询，也不为远程路径建立本地监听。普通读取与消费方提供的手动刷新仍可用。
 - 远端文件 URL 是执行坐标，不是主机文件系统句柄或 Web 下载链接。
 
 <a id="dev-note"></a>
diff --git a/packages/ssh/fs-ssh/src/index.ts b/packages/ssh/fs-ssh/src/index.ts
index 1bbcfbf097..9a20414a95 100644
--- a/packages/ssh/fs-ssh/src/index.ts
+++ b/packages/ssh/fs-ssh/src/index.ts
@@ -20,8 +20,6 @@ const errorCodes: Record<FsErrorCode, true> = {
 export class SshFileSystem extends FileSystem {
   static inject = ['ssh', 'sandboxPolicy']
 
-  override watch(): never { throw new Error('SSH filesystem watching is not supported') }
-
   override get sandboxMode(): SandboxMode { return this.ctx.sandboxPolicy.defaultMode }
 
   override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
diff --git a/packages/ssh/fs-ssh/tests/provider.spec.ts b/packages/ssh/fs-ssh/tests/provider.spec.ts
index d242d4184e..b6e6626abf 100644
--- a/packages/ssh/fs-ssh/tests/provider.spec.ts
+++ b/packages/ssh/fs-ssh/tests/provider.spec.ts
@@ -33,8 +33,8 @@ async function setup() {
 describe('SSH filesystem provider', () => {
   it('declares watching unsupported without sending a remote request', async () => {
     const { fs, dispatch } = await setup()
-    expect(() => fs.watch(target, vi.fn(), new AbortController().signal))
-      .toThrow('SSH filesystem watching is not supported')
+    await expect(fs.watch(target, vi.fn(), new AbortController().signal))
+      .rejects.toMatchObject({ code: 'FS_IO_ERROR' })
     expect(dispatch).not.toHaveBeenCalled()
   })
 
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index f2d1e1d365..fb26e9f540 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: 7d62e423189906c49d9479bd7a6dbd14b7303afd
-README.zh.md: af62ad97bc4821222d46ed73509c823851953e1d
+README.md: 4ed03104d3d8ab70816ee0cff7334a253196aef2
+README.zh.md: 92acf7498f282cdefea4f440d59e17f6dfffc81a
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 7d62e42318..4ed03104d3 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -109,7 +109,7 @@ A request is validated against the provider's advertised capabilities, a durable
 
 The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; browser human prompts choose Queue or best-effort Steer through an internal adapter, while other host protocols may retain Queue for distinct turns. A Session queue command admits a live subagent-owned Agent only from its own continuable descriptor. Settlement waits for Agent activity to finish, an empty Inbox, and no owned children, then flushes final Session state with admission open. Under the child lock, the manager revalidates the wake generation, Session sequence, Inbox, and owned children; the synchronous task entry of `Agent.runMaintenance()` claims the idle phase and closes the private subagent Inbox in the same JavaScript turn before handle disposal. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream.
 
-Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives.
+Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Each child's `subagentTiming` projection accumulates post-descriptor duration and records whether its latest closed turn ended with `completed`, clearing that completion when another turn opens. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Projection state-version changes refold cached rows from the durable log. The catalog view preserves parent event order in O(D) time for D facts, and its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives. Catalog payload v0 records known modes; v1 also accepts unknown mode. Readers support both versions. Historical migration appends a v1 `subagent/catalog` from a readable child header when its descriptor is unavailable; normal creation retains v0. Its `mode: 'unknown'` projection keeps the child visible without claiming continuation support; an existing complete entry remains authoritative.
 
 ### Ownership and invariants
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index af62ad97bc..92acf7498f 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -109,7 +109,7 @@ kind: "package-reference"
 
 管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；浏览器人类 prompt 通过内部适配器选择 Queue 或 best-effort Steer，其他 host 协议仍可保留 Queue 以创建独立轮次。Session queue command 仅根据 child 自身的 continuable descriptor 准入在线 subagent-owned Agent。Settlement 会等待 Agent 活动结束、Inbox 为空且没有所拥有子级，再在准入开放时 flush 最终 Session 状态。管理器随后在 child lock 内重新验证 wake generation、Session 序号、Inbox 与所拥有子级；`Agent.runMaintenance()` 的同步 task 入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭私有 subagent Inbox，然后才释放句柄。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。
 
-本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。
+本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在提供方返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。每个 child 的 `subagentTiming` projection 会累加 descriptor 之后的耗时，并记录最近一个已结束轮次是否以 `completed` 结束；新轮次打开时会清除该完成状态。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。projection 状态版本变更会从持久日志重新折叠缓存行。目录视图对 D 条事实以 O(D) 时间保留父目录事件顺序，其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。Catalog 载荷 v0 记录已知模式，v1 还接受未知模式，读取器支持两版。历史迁移在 descriptor 不可用时根据可读子 header 追加 v1 `subagent/catalog`；正常创建保留 v0。其 `mode: 'unknown'` 投影让子会话保持可见，但不表示支持继续执行；已有完整条目仍具有权威性。
 
 ### 所有权与不变式
 
diff --git a/packages/subagent/subagent/src/catalog.ts b/packages/subagent/subagent/src/catalog.ts
index 3ec29bbd2f..81edf47fb6 100644
--- a/packages/subagent/subagent/src/catalog.ts
+++ b/packages/subagent/subagent/src/catalog.ts
@@ -17,24 +17,27 @@ import type {
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
 import type { SubagentCatalogEntry } from './projection-types.ts'
 
-/** Current payload version for `subagent/catalog` events. */
+/** Catalog payload version emitted by live child creation. */
 export const SUBAGENT_CATALOG_VERSION = 0
 
-/** One complete parent-owned catalog fact. */
+type KnownCatalogMode =
+  | { readonly mode: 'one-shot'; readonly label?: string }
+  | { readonly mode: 'continuable'; readonly label: string }
+
+/** Parent catalog v0 records known modes; v1 also retains children with unknown mode. */
 export type SubagentCatalogEvent =
   & {
-    readonly version: 0
     readonly childId: SessionId
     readonly childCreatedAt: number
   } & (
-    | { readonly mode: 'one-shot'; readonly label?: string }
-    | { readonly mode: 'continuable'; readonly label: string }
+    | ({ readonly version: 0 } & KnownCatalogMode)
+    | ({ readonly version: 1 } & (KnownCatalogMode | { readonly mode: 'unknown'; readonly label?: string }))
   )
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
     /**
-     * A direct child's complete discovery fact.
+     * A direct child's identity and available discovery fields.
      * @param data - versioned parent-owned catalog entry.
      */
     'subagent/catalog': SubagentCatalogEvent
@@ -49,23 +52,25 @@ export interface SubagentCatalogState {
 
 const sessionIdSchema = z.string() as unknown as z.ZodType<SessionId>
 const oneShotCatalogSchema = z.object({
-  version: z.literal(SUBAGENT_CATALOG_VERSION),
+  version: z.union([z.literal(0), z.literal(1)]),
   childId: sessionIdSchema,
   childCreatedAt: z.number().int().nonnegative(),
   mode: z.literal('one-shot'),
   label: z.string().optional(),
 }).strict()
 const continuableCatalogSchema = z.object({
-  version: z.literal(SUBAGENT_CATALOG_VERSION),
+  version: z.union([z.literal(0), z.literal(1)]),
   childId: sessionIdSchema,
   childCreatedAt: z.number().int().nonnegative(),
   mode: z.literal('continuable'),
   label: z.string(),
 }).strict()
+const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') })
 const eventDataSchema = z.union([
   oneShotCatalogSchema,
   continuableCatalogSchema,
-]) as unknown as z.ZodType<SubagentCatalogEvent>
+  unknownCatalogSchema,
+]) as z.ZodType<SubagentCatalogEvent>
 const viewSchema = z.array(z.union([
   oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
     id: sessionIdSchema,
@@ -75,7 +80,11 @@ const viewSchema = z.array(z.union([
     id: sessionIdSchema,
     createdAt: continuableCatalogSchema.shape.childCreatedAt,
   }),
-])) as unknown as z.ZodType<SubagentCatalogEntry[]>
+  unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+    id: sessionIdSchema,
+    createdAt: unknownCatalogSchema.shape.childCreatedAt,
+  }),
+])) as z.ZodType<SubagentCatalogEntry[]>
 const stateSchema: z.ZodType<SubagentCatalogState> = z.object({
   inheritedEventCount: z.number().int().nonnegative() as unknown as z.ZodType<SessionLogOffset>,
   head: chunkedListSchema(eventDataSchema).optional(),
@@ -88,14 +97,14 @@ declare module '@deepseek-ai/dsh-session-projection/types' {
 }
 
 /**
- * Materialize direct children from their parent's successful creation facts.
+ * Materialize complete and unknown-mode child identities from parent catalog events.
  * @param state - parent catalog fold state.
  * @returns current direct-child rows in parent catalog event order.
  */
 function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[] {
   const entries: SubagentCatalogEntry[] = []
   for (const data of iterateChunkedList(state.head)) {
-    entries.push(data.mode === 'one-shot'
+    entries.push(data.mode !== 'continuable'
       ? {
         id: data.childId,
         createdAt: data.childCreatedAt,
@@ -121,7 +130,7 @@ export const subagentCatalogProjectionDefinition = {
     if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount) return state
     return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) }
   },
-  stateVersion: 2,
+  stateVersion: 3,
   wire: { viewSchema, view: subagentCatalogEntries },
 } satisfies ProjectionDefinition<'subagentCatalog', SubagentCatalogState>
 
diff --git a/packages/subagent/subagent/src/control-types.ts b/packages/subagent/subagent/src/control-types.ts
index 10a8cfc426..965f4d70dc 100644
--- a/packages/subagent/subagent/src/control-types.ts
+++ b/packages/subagent/subagent/src/control-types.ts
@@ -71,7 +71,7 @@ export type SubagentListEntry =
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
-/** Durable parent/child address that selects subagent transport in the client. */
+/** Durable parent/child browsing address; unknown mode is resolved when child history is read. */
 export type SubagentAddress =
   & {
     readonly parentSessionId: SessionId
@@ -80,6 +80,7 @@ export type SubagentAddress =
   & (
     | { readonly mode: 'one-shot' }
     | { readonly mode: 'continuable' }
+    | { readonly mode: 'unknown' }
   )
 
 /** One human message addressed to a continuable direct child. */
diff --git a/packages/subagent/subagent/src/projection-types.ts b/packages/subagent/subagent/src/projection-types.ts
index c33a2df9fb..27201624fb 100644
--- a/packages/subagent/subagent/src/projection-types.ts
+++ b/packages/subagent/subagent/src/projection-types.ts
@@ -15,6 +15,7 @@ export type SubagentCatalogEntry =
   & (
     | { readonly mode: 'one-shot'; readonly label?: string }
     | { readonly mode: 'continuable'; readonly label: string }
+    | { readonly mode: 'unknown'; readonly label?: string }
   )
 
 /** Durable active-turn timing for one descriptor-backed child session. */
diff --git a/packages/subagent/subagent/src/run-settlement.ts b/packages/subagent/subagent/src/run-settlement.ts
index 90eb9eec43..8d46ffbff4 100644
--- a/packages/subagent/subagent/src/run-settlement.ts
+++ b/packages/subagent/subagent/src/run-settlement.ts
@@ -37,7 +37,7 @@ function failureDetail(result: SubagentResult): string {
 function runOutcome(result: SubagentResult): JobOutcome {
   switch (result.stopReason) {
     case 'completed':
-      return { status: 'completed', output: finalText(result.output) }
+      return { status: 'completed', result: finalText(result.output) }
     case 'aborted':
       return result.diagnostic === undefined
         ? { status: 'killed' }
diff --git a/packages/subagent/subagent/tests/catalog.spec.ts b/packages/subagent/subagent/tests/catalog.spec.ts
index cfd51813fe..ffc95e1606 100644
--- a/packages/subagent/subagent/tests/catalog.spec.ts
+++ b/packages/subagent/subagent/tests/catalog.spec.ts
@@ -102,11 +102,26 @@ describe('subagent catalog projection', () => {
       .toEqual(Array.from({ length: 130 }, (_, i) => SessionId(`child-${i}`)))
   })
 
+  it.each([0, 1] as const)('reads known catalog modes at payload version %s', (version) => {
+    const events: SessionEvent[] = [
+      { type: 'subagent/catalog', seq: SessionSeq(0), time: 0,
+        data: { version, childId: SessionId('once'), childCreatedAt: 1, mode: 'one-shot' } },
+      { type: 'subagent/catalog', seq: SessionSeq(1), time: 0,
+        data: { version, childId: SessionId('ongoing'), childCreatedAt: 2, mode: 'continuable', label: 'child' } },
+    ]
+    expect(subagentCatalogProjectionDefinition.wire.view(fold(events))).toEqual([
+      { id: SessionId('once'), createdAt: 1, mode: 'one-shot' },
+      { id: SessionId('ongoing'), createdAt: 2, mode: 'continuable', label: 'child' },
+    ])
+  })
+
   it('validates recursive chunk state and materializes every label variant in event order', () => {
     const events: SessionEvent[] = [
       fact(0, 'child-b', 1, { mode: 'one-shot' }),
       fact(1, 'child-a', 1, { mode: 'one-shot', label: 'once' }),
       fact(2, 'child-d', 3, { mode: 'continuable', label: 'later' }),
+      { type: 'subagent/catalog', seq: SessionSeq(3), time: 0,
+        data: { version: 1, childId: SessionId('unreadable'), childCreatedAt: 4, mode: 'unknown' } },
     ]
     const state = fold(events)
 
@@ -121,6 +136,7 @@ describe('subagent catalog projection', () => {
       { id: SessionId('child-b'), createdAt: 1, mode: 'one-shot' },
       { id: SessionId('child-a'), createdAt: 1, mode: 'one-shot', label: 'once' },
       { id: SessionId('child-d'), createdAt: 3, mode: 'continuable', label: 'later' },
+      { id: SessionId('unreadable'), createdAt: 4, mode: 'unknown' },
     ])
   })
 
@@ -140,6 +156,7 @@ describe('subagent catalog projection', () => {
   })
 
   it.each([
+    { version: 0, childId: 'child', childCreatedAt: 0, mode: 'unknown' },
     { version: 9, childId: 'child', childCreatedAt: 0, mode: 'one-shot' },
     { version: 0, childId: 'child', childCreatedAt: 0, mode: 'continuable' },
     { version: 0, childId: 'child', childCreatedAt: -1, mode: 'one-shot' },
diff --git a/packages/subagent/subagent/tests/continuation-messages-adapter.spec.ts b/packages/subagent/subagent/tests/continuation-messages-adapter.spec.ts
index 0458b7696d..380a47fbda 100644
--- a/packages/subagent/subagent/tests/continuation-messages-adapter.spec.ts
+++ b/packages/subagent/subagent/tests/continuation-messages-adapter.spec.ts
@@ -11,7 +11,7 @@ import { DeepSeekAdapter, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-dee
 import { SessionId } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn-in-process'
-import { end, MODEL, server, sse, start } from '../../../llm/llm-deepseek/tests/messages/helpers.ts'
+import { end, MODEL, server, sse, start } from '../../../llm/llm-deepseek/tests/helpers.ts'
 import SubagentRuntime, { type SubagentRunEndInfo } from '../src/index.ts'
 import { loadStoredSession } from './persistence-helpers.ts'
 
diff --git a/packages/subagent/subagent/tests/run-settlement.spec.ts b/packages/subagent/subagent/tests/run-settlement.spec.ts
index 146181d43a..20fc514504 100644
--- a/packages/subagent/subagent/tests/run-settlement.spec.ts
+++ b/packages/subagent/subagent/tests/run-settlement.spec.ts
@@ -9,7 +9,7 @@ const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096
 
 describe('outcome mapping helpers', () => {
   it.each([
-    ['completed', { status: 'completed', output: 'partial' }],
+    ['completed', { status: 'completed', result: 'partial' }],
     ['aborted', { status: 'killed' }],
     ['error', { status: 'failed', detail: 'error' }],
     ['max-tokens', { status: 'failed', detail: 'max-tokens' }],
@@ -34,7 +34,7 @@ describe('outcome mapping helpers', () => {
       dispose() { order.push('dispose'); return Promise.resolve() },
     })
     order.push('reported')
-    expect(completed).toEqual({ status: 'completed', output: 'ok' })
+    expect(completed).toEqual({ status: 'completed', result: 'ok' })
     expect(order).toEqual(['dispose', 'reported'])
 
     // An infrastructure rejection still disposes and reports failed.
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index 3c70b80c6b..e16a70f949 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -545,7 +545,7 @@ export function apply(ctx: Context, config: Config, session?: Session): void {
             const id = jobs.start({
               kind: 'subagent',
               label: args.description,
-              owner: parent,
+              owner: parent.id,
               run: () => {
                 const controller = new AbortController()
                 const start = runtimeCtx.subagents.start(config.provider, { ...request, signal: controller.signal })
@@ -554,7 +554,7 @@ export function apply(ctx: Context, config: Config, session?: Session): void {
                     controller.abort(reason ?? 'background subagent task killed')
                   },
                   done: settleStart(start, controller.signal),
-                  // No readOutput: the child session owns intermediate detail.
+                  // No output sources: the child session owns intermediate detail.
                 }
               },
             })
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 5b58115cfa..b7d20b8946 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -883,7 +883,7 @@ describe('dsh-tool-subagent background mode', () => {
     })
     expect(text(collected)).toBe('background answer\n[status: completed]')
 
-    // Final-output reads are idempotent (not consumed).
+    // The result rides the first read after settlement; a later read carries only the status.
     const again = await ctx.tools.execute({
       signal: testToolSignal,
       callId: ToolCallId('collect-2'),
@@ -891,7 +891,7 @@ describe('dsh-tool-subagent background mode', () => {
       arguments: { job_id: 'subagent-1' },
       agent: parent,
     })
-    expect(text(again)).toBe('background answer\n[status: completed]')
+    expect(text(again)).toBe('(no new output)\n[status: completed]')
   })
 
   it('preserves provider diagnostics in one-shot background failure detail', async () => {
@@ -972,7 +972,7 @@ describe('dsh-tool-subagent background mode', () => {
     const result = await resultPromise
 
     expect(result.isError).toBe(true)
-    expect(ctx.jobs.list(parent)).toEqual([])
+    expect(ctx.jobs.list(parent.id)).toEqual([])
   })
 
   it('rejects startup when the provider changes during asynchronous route preflight', async () => {
@@ -1082,7 +1082,8 @@ describe('dsh-tool-subagent background mode', () => {
       arguments: { job_id: 'subagent-1', wait: true },
       agent: parent,
     })
-    expect(text(output)).toBe('(no new output)\n[status: killed]')
+    // The registry records the model's kill reason as the terminal detail.
+    expect(text(output)).toBe('(no new output)\n[status: killed, no longer needed]')
   })
 
   it('reports startup rollback failure after cancellation as a failed job', async () => {
@@ -1169,7 +1170,7 @@ describe('dsh-tool-subagent background mode', () => {
 
     // The aborted children settle as killed tasks.
     const killed = await ctx.tools.execute({ signal: testToolSignal, callId: ToolCallId('w1'), name: 'job_output', arguments: { job_id: 'subagent-1', wait: true }, agent: parent })
-    expect(text(killed)).toBe('(no new output)\n[status: killed]')
+    expect(text(killed)).toBe('(no new output)\n[status: killed, superseded]')
   })
 
 })
@@ -1240,7 +1241,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
     expect(match).not.toBeNull()
     const [, childId] = match!
     // No Task was created for the continuable child.
-    expect(ctx.jobs.list(parent)).toEqual([])
+    expect(ctx.jobs.list(parent.id)).toEqual([])
 
     await vi.waitFor(() => {
       expect(ctx.agents.get(SessionId(childId!))).toBeUndefined()
@@ -1271,7 +1272,7 @@ describe('dsh-tool-subagent continuable background mode', () => {
     if (result.isError) throw new Error('expected foreground subagent success')
     expect(result.value).toMatchObject({ kind: 'foreground' })
     expect(text(result)).toBe('continuable answer')
-    expect(ctx.jobs.list(parent)).toEqual([])
+    expect(ctx.jobs.list(parent.id)).toEqual([])
   })
 
   it('isolates a cancelled continuable preparation from a concurrent sibling', async () => {
diff --git a/packages/terminal/terminal-bash/tests/local.spec.ts b/packages/terminal/terminal-bash/tests/local.spec.ts
index 7ef28c6929..962421ce9c 100644
--- a/packages/terminal/terminal-bash/tests/local.spec.ts
+++ b/packages/terminal/terminal-bash/tests/local.spec.ts
@@ -233,9 +233,10 @@ describe.skipIf(process.platform === 'win32')('terminal-bash real shell', () =>
     const child = /CHILD=(\d+)/.exec(output)?.[1]
     expect(child).toBeDefined()
     const pid = Number(child)
-    expect(() => process.kill(pid, 0)).not.toThrow()
+    expect(processIsRunning(pid)).toBe(true)
     await ctx.terminals.kill(agent, created.sessionId)
-    expect(() => process.kill(pid, 0)).toThrow()
+    // Linux can retain a stopped descendant as a zombie until its parent reaps it.
+    expect(processIsRunning(pid)).toBe(false)
   }, 10_000)
 
   it('quiesces a disowned same-session descendant after the shell exits naturally', async () => {
diff --git a/packages/terminal/tool-terminal/src/background.ts b/packages/terminal/tool-terminal/src/background.ts
new file mode 100644
index 0000000000..47494f7cff
--- /dev/null
+++ b/packages/terminal/tool-terminal/src/background.ts
@@ -0,0 +1,31 @@
+/**
+ * Generic-job adaptation for background terminal sends: the registry pull
+ * source over the backend's consuming send reader.
+ *
+ * @module @deepseek-ai/dsh-tool-terminal/background
+ */
+
+import type { JobOutputSource } from '@deepseek-ai/dsh-jobs'
+import type { TerminalSendOperation } from '@deepseek-ai/dsh-terminal'
+import { renderSendRead } from './render.ts'
+
+/**
+ * Adapt the backend's consuming send reader to a registry pull source. The
+ * reader has no offsets of its own — each call hands over what arrived since
+ * the previous one — so the source counts the bytes it delivered to keep the
+ * registry's cursor monotonic. It binds lazily because the send starts inside
+ * the job starter, after the registry admitted the job; a read before that
+ * point delivers nothing.
+ * @param operation - the live send, once the starter has begun it.
+ * @returns one unlabeled source over the send's bounded delta.
+ */
+export function sendSource(operation: () => TerminalSendOperation | undefined): JobOutputSource {
+  return {
+    read: (fromByte) => {
+      const live = operation()
+      if (live === undefined) return { text: '', nextOffset: fromByte, lossy: false }
+      const text = renderSendRead(live.readOutput())
+      return { text, nextOffset: fromByte + Buffer.byteLength(text), lossy: false }
+    },
+  }
+}
diff --git a/packages/terminal/tool-terminal/src/index.ts b/packages/terminal/tool-terminal/src/index.ts
index 1865ebe165..6da2af03fe 100644
--- a/packages/terminal/tool-terminal/src/index.ts
+++ b/packages/terminal/tool-terminal/src/index.ts
@@ -9,11 +9,12 @@ import z from '@deepseek-ai/schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { TerminalSessionId } from '@deepseek-ai/dsh-terminal'
-import type { TerminalSendResult, TerminalSessionId as TerminalSessionIdType, TerminalSignal } from '@deepseek-ai/dsh-terminal'
+import type { TerminalSendOperation, TerminalSendResult, TerminalSessionId as TerminalSessionIdType, TerminalSignal } from '@deepseek-ai/dsh-terminal'
 import type {} from '@deepseek-ai/dsh-jobs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
-import { boundTerminalText, renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts'
+import { sendSource } from './background.ts'
+import { boundTerminalText, renderList, renderRead, renderSend, renderSpawn } from './render.ts'
 
 declare module '@deepseek-ai/dsh-jobs' {
   interface JobKindMap {
@@ -252,23 +253,25 @@ export function apply(ctx: Context, config: Config = {}): void {
         const jobs = ctx.get('jobs')
         if (jobs === undefined) throw new Error('background terminal sends require @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs')
         let cancelRequested = false
+        let operation: TerminalSendOperation | undefined
         const jobId = jobs.start({
           kind: 'pty-send',
           label: `${id}: ${args.text || '(input)'}`,
-          owner,
+          owner: owner.id,
           outputLimitBytes: maxResultBytes,
+          output: [sendSource(() => operation)],
           run: () => {
-            const operation = ctx.terminals.startSend(owner, id, request)
+            const started = ctx.terminals.startSend(owner, id, request)
+            operation = started
             return {
               cancel: () => {
                 cancelRequested = true
-                operation.cancel()
+                started.cancel()
               },
-              done: operation.done.then(
+              done: started.done.then(
                 result => ({ status: cancelRequested ? 'killed' as const : 'completed' as const, detail: sendDetail(result) }),
                 (error: unknown) => ({ status: 'failed' as const, detail: String(error) }),
               ),
-              readOutput: () => renderSendRead(operation.readOutput()),
             }
           },
         })
diff --git a/packages/terminal/tool-terminal/tests/tools.spec.ts b/packages/terminal/tool-terminal/tests/tools.spec.ts
index 934b4c6d60..e110562551 100644
--- a/packages/terminal/tool-terminal/tests/tools.spec.ts
+++ b/packages/terminal/tool-terminal/tests/tools.spec.ts
@@ -8,10 +8,11 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRuntime, { renderToolsSdk } from '@deepseek-ai/dsh-tools'
 import type { ToolSdkSchema } from '@deepseek-ai/dsh-tools/src/ts-types.ts'
 import TerminalSessionService, { TerminalSessionId } from '@deepseek-ai/dsh-terminal'
-import type { TerminalBackend, TerminalBackendSession, TerminalSendOperation, TerminalSendRequest, TerminalSessionStatus, TerminalSignal } from '@deepseek-ai/dsh-terminal'
+import type { TerminalBackend, TerminalBackendSession, TerminalSendOperation, TerminalSendRead, TerminalSendRequest, TerminalSessionStatus, TerminalSignal } from '@deepseek-ai/dsh-terminal'
 import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local'
 import * as ToolJobs from '@deepseek-ai/dsh-tool-jobs'
 import * as ToolPty from '@deepseek-ai/dsh-tool-terminal'
+import { sendSource } from '../src/background.ts'
 import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
 
 async function fakeAgent(ctx: Context, rawId: string): Promise<Agent> {
@@ -55,7 +56,11 @@ class StubSession implements TerminalBackendSession {
     }))
     const operation: TerminalSendOperation = {
       done,
-      readOutput: () => ({ delta: this.delta, truncated: this.deltaTruncated }),
+      readOutput: () => {
+        const delta = this.delta
+        this.delta = ''
+        return { delta, truncated: this.deltaTruncated }
+      },
       cancel: () => {
         if (cancelled) return false
         cancelled = true
@@ -403,6 +408,19 @@ describe('tool-terminal foreground API', () => {
   })
 })
 
+describe('sendSource', () => {
+  it('reads nothing before the send starts and counts delivered bytes afterwards', () => {
+    const reads: TerminalSendRead[] = [{ delta: '界', truncated: false }, { delta: '', truncated: true }]
+    const send: { operation?: TerminalSendOperation } = {}
+    const source = sendSource(() => send.operation)
+    expect(source.read(0)).toEqual({ text: '', nextOffset: 0, lossy: false })
+    send.operation = { readOutput: () => reads.shift()!, cancel: () => false, done: new Promise(() => {}) }
+    expect(source.read(0)).toEqual({ text: '界', nextOffset: 3, lossy: false })
+    // A truncated delta carries the same marker the foreground read shows.
+    expect(source.read(3)).toEqual({ text: '[output truncated]', nextOffset: 21, lossy: false })
+  })
+})
+
 describe('tool-terminal task integration', () => {
   it('registers a generic task and exposes incremental output', async () => {
     const { ctx, agent } = await setup(true)
diff --git a/packages/test-support/client-runtime/README.i18n.yaml b/packages/test-support/client-runtime/README.i18n.yaml
index d37d28f763..6a6ad363c6 100644
--- a/packages/test-support/client-runtime/README.i18n.yaml
+++ b/packages/test-support/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/test-support/client-runtime/README.md
-README.md: 1e9a9aeabe8b27f67557216f354d31a6ccf9d594
-README.zh.md: 27f3f5447f2845f5dbcbc928d62222cb0fbefe84
+README.md: b4197ffc750ec585e4df1b9da9af1731558bfc99
+README.zh.md: 087d464ba900965d23b09d1ff9f67b9259f08933
diff --git a/packages/test-support/client-runtime/README.md b/packages/test-support/client-runtime/README.md
index 1e9a9aeabe..b4197ffc75 100644
--- a/packages/test-support/client-runtime/README.md
+++ b/packages/test-support/client-runtime/README.md
@@ -89,7 +89,7 @@ The [generic Remote proxy](../remote-mock/README.md#remote-proxy) supports every
 
 ### Roster and startup behavior
 
-`webApp` is the `web` profile's browser roster, read when the assembly entry is first imported from its bundles (`dsh-base`, then `dsh-web-app`) as the launcher composes them, except that a patch matching nothing throws here where the launcher warns: each bundle's `dsh.bundle.patch` list is parsed with the include plugin's YAML dialect and composed by its `applyEntryPatches`, and every enabled row whose package declares `dsh.client.platform === 'web'` becomes a row carrying that declaration's `inject` and `immediately`; `bundleRoster(bundles)` does the same for any bundle list. Nothing is copied from the bundles, so a bundle change is visible at the next test run. `webApp.closure(names)` keeps the named rows plus everything they inject, transitively (the rows a spec needs to boot those plugins as the bundle composes them), `webApp.pick(names)` and `webApp.without(names)` cut it down by hand, all three throw on unknown names, and `ClientRoster.of(rows)` builds one inline. `remoteDefaultResponses` holds default responses for exactly the Remote endpoints the roster calls while booting with no sessions, no workspaces, and default settings; a spec layers its own `RemoteTable` on top with `mock.load(table)`, and any call without a rule fails the test at `dispose()` through `mock.assertNoUnmatched()`. `mount` requires a roster that provides `uiRenderer`; `start` fails loud otherwise instead of returning an empty container. `client.connection` is the roster's Connection service (no `Context` augmentation declares it), and `connectTimeoutMs` bounds the readiness wait, whose failure message lists the mock log. `reload(name)` rebuilds one Loader entry through the shared Client Modules helper (registry-first teardown, then `entry.refresh()`); each client retains its own module system and instance-bound Connection replacement, so starts and reloads can overlap without changing a page global. `unload(name)` removes an entry and waits for plugin cleanup; `flush()` settles React inside `act`. jsdom implements neither `EventSource` (client-hmr opens one at apply) nor `ResizeObserver` (layout components observe size at mount), so `start` reference-counts inert stubs for whichever global is absent and `dispose` removes exactly those — a jsdom gap, not a client identity channel. The `@deepseek-ai/dsh-api-remotes` row is dropped from every roster: its generated Remote clients exist only in built `lib/`, and `remote.<ns>` is what the tier replaces anyway. `start` instead provides one contract-free proxy per `remote.<ns>` service the roster injects (plus the namespaces the mock has rules for at that point; a namespace first registered later has no proxy); `ctx.remote.<ns>.<method>(...args)` becomes a call on the endpoint `<ns>/<method>` carrying the positional args, a stream when the mock registered a `stream()` script and a unary call otherwise, with the generated client's outcome folding (`gateway/internal` for carrier throws, `gateway/cancelled` on abort). An endpoint without a rule is still dispatched, so the mock logs it and `dispose()` fails the test.
+`webApp` is the `web` profile's browser roster, read when the assembly entry is first imported from its bundles (`dsh-base`, then `dsh-web-app`) as the launcher composes them, except that a patch matching nothing throws here where the launcher warns: each bundle's `dsh.bundle.patch` list is parsed with the include plugin's YAML dialect and composed by its `applyEntryPatches`, and every enabled row whose package declares `dsh.client.platform === 'web'` becomes a row carrying that declaration's `inject` and `immediately`; `bundleRoster(bundles, anchor, disabledContext)` accepts an explicit Loader evaluation scope for conditional `disabled` flags; without one, browser expressions are rejected. `webApp` supplies the Web profile name, not business Host services. Nothing is copied from the bundles, so a bundle change is visible at the next test run. `webApp.closure(names)` keeps the named rows plus everything they inject, transitively (the rows a spec needs to boot those plugins as the bundle composes them), `webApp.pick(names)` and `webApp.without(names)` cut it down by hand, all three throw on unknown names, and `ClientRoster.of(rows)` builds one inline. `remoteDefaultResponses` holds default responses for exactly the Remote endpoints the roster calls while booting with no sessions, no workspaces, and default settings; a spec layers its own `RemoteTable` on top with `mock.load(table)`, and any call without a rule fails the test at `dispose()` through `mock.assertNoUnmatched()`. `mount` requires a roster that provides `uiRenderer`; `start` fails loud otherwise instead of returning an empty container. `client.connection` is the roster's Connection service (no `Context` augmentation declares it), and `connectTimeoutMs` bounds the readiness wait, whose failure message lists the mock log. `reload(name)` rebuilds one Loader entry through the shared Client Modules helper (registry-first teardown, then `entry.refresh()`); each client retains its own module system and instance-bound Connection replacement, so starts and reloads can overlap without changing a page global. `unload(name)` removes an entry and waits for plugin cleanup; `flush()` settles React inside `act`. jsdom implements neither `EventSource` (client-hmr opens one at apply) nor `ResizeObserver` (layout components observe size at mount), so `start` reference-counts inert stubs for whichever global is absent and `dispose` removes exactly those — a jsdom gap, not a client identity channel. The `@deepseek-ai/dsh-api-remotes` row is dropped from every roster: its generated Remote clients exist only in built `lib/`, and `remote.<ns>` is what the tier replaces anyway. `start` instead provides one contract-free proxy per `remote.<ns>` service the roster injects (plus the namespaces the mock has rules for at that point; a namespace first registered later has no proxy); `ctx.remote.<ns>.<method>(...args)` becomes a call on the endpoint `<ns>/<method>` carrying the positional args, a stream when the mock registered a `stream()` script and a unary call otherwise, with the generated client's outcome folding (`gateway/internal` for carrier throws, `gateway/cancelled` on abort). An endpoint without a rule is still dispatched, so the mock logs it and `dispose()` fails the test.
 
 ### When to use it
 
diff --git a/packages/test-support/client-runtime/README.zh.md b/packages/test-support/client-runtime/README.zh.md
index 27f3f5447f..087d464ba9 100644
--- a/packages/test-support/client-runtime/README.zh.md
+++ b/packages/test-support/client-runtime/README.zh.md
@@ -89,7 +89,7 @@ test('registers into the sidebar', async ({ remote, start }) => {
 
 ### Roster 与启动行为
 
-`webApp` 是 `web` profile 的浏览器 roster，首次 import 装配入口时从它的 bundle（先 `dsh-base`、再 `dsh-web-app`）按启动器的方式现读，只是匹配不到任何行的补丁在这里抛错、启动器只警告：每个 bundle 的 `dsh.bundle.patch` 列表用 include 插件的 YAML 方言解析、用它的 `applyEntryPatches` 合成，每个未禁用且其包声明 `dsh.client.platform === 'web'` 的行成为一行，带上该声明的 `inject` 与 `immediately`；`bundleRoster(bundles)` 对任意 bundle 列表做同样的事。没有任何东西从 bundle 拷贝出来，bundle 一改下次跑测试就能看见。`webApp.closure(names)` 保留点名的行及其传递注入的全部行（即按 bundle 组合方式起这些插件所需的行），`webApp.pick(names)` 与 `webApp.without(names)` 手工裁剪，三者都对未知名字抛错，`ClientRoster.of(rows)` 内联构造一份。`remoteDefaultResponses` 是 roster 在没有 session、没有 workspace、默认设置下启动时恰好会打的那些 Remote 端点的默认响应；测试用 `mock.load(table)` 在其上叠加自己的 `RemoteTable`，任何没有规则的调用都会在 `dispose()` 时经 `mock.assertNoUnmatched()` 让测试失败。`mount` 要求 roster 提供 `uiRenderer`；否则 `start` 响亮失败而不是返回一个空容器。`client.connection` 是 roster 的 Connection 服务（没有任何 `Context` 增强声明它），`connectTimeoutMs` 限定等就绪的时长，超时消息列出 mock log。`reload(name)` 通过共享的 Client Modules 辅助函数重建一个 Loader entry（先拆 registry，再 `entry.refresh()`）；每个客户端都保留自己的模块系统和绑定实例的 Connection 替换，因此启动与重载可以重叠而无需改写页面全局变量。`unload(name)` 移除 entry 并等待插件清理完成，`flush()` 在 `act` 内让 React 落定。jsdom 既没有 `EventSource`（client-hmr 在 apply 时打开一个）也没有 `ResizeObserver`（布局组件挂载时观察尺寸），所以 `start` 对缺失的全局惰性桩做引用计数，`dispose` 只移除它装的那些——这是 jsdom 的缺口，不是客户端身份通道。每个 roster 里的 `@deepseek-ai/dsh-api-remotes` 行都会被去掉：它生成的 Remote 客户端只存在于构建后的 `lib/`，而 `remote.<ns>` 正是本档要替掉的东西。`start` 改为给 roster 注入的每个 `remote.<ns>` 服务（加上此刻 mock 登记过规则的命名空间；之后才首次登记的命名空间没有代理）提供一个无契约代理；`ctx.remote.<ns>.<method>(...args)` 变成对端点 `<ns>/<method>` 的调用，携带位置参数，mock 登记了 `stream()` 脚本的走流、否则走一元，并沿用生成客户端的结果折叠（载体抛错折成 `gateway/internal`，中止折成 `gateway/cancelled`）。没有规则的端点照样发出，所以 mock 会记下它、`dispose()` 让测试失败。
+`webApp` 是 `web` profile 的浏览器 roster，首次 import 装配入口时从它的 bundle（先 `dsh-base`、再 `dsh-web-app`）按启动器的方式现读，只是匹配不到任何行的补丁在这里抛错、启动器只警告：每个 bundle 的 `dsh.bundle.patch` 列表用 include 插件的 YAML 方言解析、用它的 `applyEntryPatches` 合成，每个未禁用且其包声明 `dsh.client.platform === 'web'` 的行成为一行，带上该声明的 `inject` 与 `immediately`；`bundleRoster(bundles, anchor, disabledContext)` 接受显式 Loader 求值作用域来处理条件 `disabled` 标记；未提供作用域时拒绝浏览器表达式。`webApp` 仅提供 Web profile 名称，不提供业务 Host 服务。没有任何东西从 bundle 拷贝出来，bundle 一改下次跑测试就能看见。`webApp.closure(names)` 保留点名的行及其传递注入的全部行（即按 bundle 组合方式起这些插件所需的行），`webApp.pick(names)` 与 `webApp.without(names)` 手工裁剪，三者都对未知名字抛错，`ClientRoster.of(rows)` 内联构造一份。`remoteDefaultResponses` 是 roster 在没有 session、没有 workspace、默认设置下启动时恰好会打的那些 Remote 端点的默认响应；测试用 `mock.load(table)` 在其上叠加自己的 `RemoteTable`，任何没有规则的调用都会在 `dispose()` 时经 `mock.assertNoUnmatched()` 让测试失败。`mount` 要求 roster 提供 `uiRenderer`；否则 `start` 响亮失败而不是返回一个空容器。`client.connection` 是 roster 的 Connection 服务（没有任何 `Context` 增强声明它），`connectTimeoutMs` 限定等就绪的时长，超时消息列出 mock log。`reload(name)` 通过共享的 Client Modules 辅助函数重建一个 Loader entry（先拆 registry，再 `entry.refresh()`）；每个客户端都保留自己的模块系统和绑定实例的 Connection 替换，因此启动与重载可以重叠而无需改写页面全局变量。`unload(name)` 移除 entry 并等待插件清理完成，`flush()` 在 `act` 内让 React 落定。jsdom 既没有 `EventSource`（client-hmr 在 apply 时打开一个）也没有 `ResizeObserver`（布局组件挂载时观察尺寸），所以 `start` 对缺失的全局惰性桩做引用计数，`dispose` 只移除它装的那些——这是 jsdom 的缺口，不是客户端身份通道。每个 roster 里的 `@deepseek-ai/dsh-api-remotes` 行都会被去掉：它生成的 Remote 客户端只存在于构建后的 `lib/`，而 `remote.<ns>` 正是本档要替掉的东西。`start` 改为给 roster 注入的每个 `remote.<ns>` 服务（加上此刻 mock 登记过规则的命名空间；之后才首次登记的命名空间没有代理）提供一个无契约代理；`ctx.remote.<ns>.<method>(...args)` 变成对端点 `<ns>/<method>` 的调用，携带位置参数，mock 登记了 `stream()` 脚本的走流、否则走一元，并沿用生成客户端的结果折叠（载体抛错折成 `gateway/internal`，中止折成 `gateway/cancelled`）。没有规则的端点照样发出，所以 mock 会记下它、`dispose()` 让测试失败。
 
 ### 何时使用
 
diff --git a/packages/test-support/client-runtime/src/assembly/bundle-roster.ts b/packages/test-support/client-runtime/src/assembly/bundle-roster.ts
index 14284556f5..3650afe792 100644
--- a/packages/test-support/client-runtime/src/assembly/bundle-roster.ts
+++ b/packages/test-support/client-runtime/src/assembly/bundle-roster.ts
@@ -1,6 +1,6 @@
 /**
  * The browser roster of a `dsh --profile`, read from its bundle patch files
- * the way the launcher composes them: each bundle's `dsh.bundle.patch` list is
+ * the way the launcher composes them: each bundle's `dsh.bundle.patch` file list is
  * parsed with the include plugin's YAML dialect (`entryListSchema`) and
  * composed by its `applyEntryPatches`; every enabled row whose package
  * declares `dsh.client.platform === 'web'` becomes a roster row carrying that
@@ -17,7 +17,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
+import { evaluate, isJsExpr, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import { applyEntryPatches, entryListSchema, type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import { exactPackageSpecifier, parseDshClient } from '@deepseek-ai/dsh-client-modules/client'
 import * as yaml from 'js-yaml'
@@ -41,11 +41,16 @@ interface BundleLayer {
  * Compose the browser roster of `bundles`, applied in order.
  * @param bundles - bundle package names in application order.
  * @param anchor - file whose package resolution locates the bundles; default this package.
+ * @param disabledContext - optional Loader evaluation scope for trusted `disabled` expressions.
  * @returns the roster in composition order, one row per package.
  * @throws {Error} when a bundle, its patch file, or an enabled row's package does not resolve, when the patch list
- * is not a list or does not apply as written, or when a browser row's `disabled` is a `!!js` expression.
+ * is not a list or does not apply as written, or when a browser row has an unevaluated `disabled` expression.
  */
-export function bundleRoster(bundles: readonly string[], anchor: string = fileURLToPath(import.meta.url)): ClientRoster {
+export function bundleRoster(
+  bundles: readonly string[],
+  anchor: string = fileURLToPath(import.meta.url),
+  disabledContext?: object,
+): ClientRoster {
   const layers = bundles.map(name => readLayer(name, anchor))
   const entries = applyEntryPatches([], layers.flatMap(layer => layer.patches), (message: string, ...args: unknown[]) => {
     throw new Error(`client-test-runtime: bundle patch ${describe(message, args)}`)
@@ -55,7 +60,9 @@ export function bundleRoster(bundles: readonly string[], anchor: string = fileUR
   const seen = new Set<string>()
   for (const { entry, disabled } of flattenGroups(entries)) {
     const name = exactPackageSpecifier(entry.name)
-    if (name === undefined || disabled === true || seen.has(name)) continue
+    if (name === undefined || disabled.includes(true) || seen.has(name)) continue
+    if (disabledContext !== undefined
+      && disabled.some(value => isJsExpr(value) && Boolean(evaluate(disabledContext, value.__jsExpr)))) continue
     seen.add(name)
     const manifestPath = locateManifest(anchors, name)
     if (manifestPath === undefined) {
@@ -67,7 +74,8 @@ export function bundleRoster(bundles: readonly string[], anchor: string = fileUR
     }
     const declaration = parseDshClient(name, manifest.dsh?.client)
     if (declaration === undefined || declaration.platform !== 'web') continue
-    if (disabled !== undefined && disabled !== null && typeof disabled !== 'boolean') {
+    if (disabled.some(value => value !== undefined && value !== null && typeof value !== 'boolean'
+      && !(disabledContext !== undefined && isJsExpr(value)))) {
       throw new Error(`client-test-runtime: browser row ${name} has a \`disabled\` value this reader cannot evaluate (a !!js expression)`)
     }
     rows.push({ name, inject: declaration.inject ?? [], immediately: declaration.immediately === true })
@@ -78,32 +86,37 @@ export function bundleRoster(bundles: readonly string[], anchor: string = fileUR
 function readLayer(bundle: string, anchor: string): BundleLayer {
   const manifestPath = locateManifest([anchor], bundle)
   if (manifestPath === undefined) throw new Error(`client-test-runtime: cannot resolve bundle ${bundle} from ${anchor}`)
-  const patch = readManifest(manifestPath).dsh?.bundle?.patch
-  if (typeof patch !== 'string') throw new Error(`client-test-runtime: bundle ${bundle} declares no dsh.bundle.patch in ${manifestPath}`)
-  const file = join(dirname(manifestPath), patch)
-  const parsed: unknown = yaml.load(readFileSync(file, 'utf8'), { schema: entryListSchema })
-  if (!Array.isArray(parsed)) throw new Error(`client-test-runtime: ${file} must be a top-level list of patches`)
-  return { manifestPath, patches: parsed as PatchOptions[] }
+  const declared = readManifest(manifestPath).dsh?.bundle?.patch
+  const files = typeof declared === 'string' ? [declared] : declared
+  if (!Array.isArray(files) || !files.every(file => typeof file === 'string')) {
+    throw new Error(`client-test-runtime: bundle ${bundle} declares no dsh.bundle.patch file list in ${manifestPath}`)
+  }
+  const patches = files.flatMap((patch) => {
+    const file = join(dirname(manifestPath), patch)
+    const parsed: unknown = yaml.load(readFileSync(file, 'utf8'), { schema: entryListSchema })
+    if (!Array.isArray(parsed)) throw new Error(`client-test-runtime: ${file} must be a top-level list of patches`)
+    return parsed as PatchOptions[]
+  })
+  return { manifestPath, patches }
 }
 
-/** One Loader row with the `disabled` value that governs it: its own, or the nearest enclosing group's when that is set. */
+/** One Loader row with its ancestor and own disable conditions, in outer-to-inner order. */
 interface FlatEntry {
   readonly entry: EntryOptions
-  readonly disabled: unknown
+  readonly disabled: readonly unknown[]
 }
 
 /**
  * Rows in Loader order with groups descended, as the Loader loads them: a group is never a plugin itself, and a group's
  * `disabled` disables every row beneath it.
  * @param entries - composed entries, possibly nested.
- * @param inherited - the enclosing group's `disabled` when set.
+ * @param inherited - the enclosing groups' disable conditions.
  * @returns the plugin rows.
  */
-function flattenGroups(entries: readonly EntryOptions[], inherited?: unknown): FlatEntry[] {
+function flattenGroups(entries: readonly EntryOptions[], inherited: readonly unknown[] = []): FlatEntry[] {
   const rows: FlatEntry[] = []
   for (const entry of entries) {
-    const own = (entry as { disabled?: unknown }).disabled
-    const disabled = inherited !== undefined && inherited !== null && inherited !== false ? inherited : own
+    const disabled = [...inherited, (entry as { disabled?: unknown }).disabled]
     if (entry.group === true && Array.isArray(entry.config)) {
       rows.push(...flattenGroups(entry.config as EntryOptions[], disabled))
       continue
@@ -134,5 +147,9 @@ function describe(message: string, args: readonly unknown[]): string {
   return message.replace(/%C/g, () => JSON.stringify(args[index++]))
 }
 
-/** The `web` profile's browser roster, composed from its bundles at import. */
-export const webApp: ClientRoster = bundleRoster(WEB_PROFILE_BUNDLES)
+const webProfileServices: Readonly<Record<string, object | undefined>> = { profileContext: { name: 'web' } }
+
+/** The `web` profile's browser roster, composed with its profile name and no business Host services. */
+export const webApp: ClientRoster = bundleRoster(WEB_PROFILE_BUNDLES, undefined, {
+  get: (name: string) => webProfileServices[name],
+})
diff --git a/packages/test-support/client-runtime/src/assembly/remote-default-responses.ts b/packages/test-support/client-runtime/src/assembly/remote-default-responses.ts
index c54130bca5..074db36701 100644
--- a/packages/test-support/client-runtime/src/assembly/remote-default-responses.ts
+++ b/packages/test-support/client-runtime/src/assembly/remote-default-responses.ts
@@ -13,6 +13,8 @@ export const remoteDefaultResponses: RemoteTable = {
   unary: {
     // api-session-controller `sessions.handleConnected()` on `connection/reset`.
     'session/list': ok({ items: [] }),
+    // ui-workspace startup with no entries; first-use initialization is ineligible.
+    'workspace/initializeDefault': ok(undefined),
     // ui-settings `mirror.ensure()` at apply and again on `connection/reset`.
     'settings/describe': ok({ writable: true, hasDocument: false, namespaces: [] }),
     // ui-model-selection `ModelDirectoryResolver` constructor.
@@ -40,7 +42,7 @@ export const remoteDefaultResponses: RemoteTable = {
   ],
   stream: {
     // api-session-controller client `apply`: the control stream's opening baseline, then open.
-    'session/control': openStream([{ type: 'baseline', value: { jobs: {}, projections: {} } }]),
+    'session/control': openStream([{ type: 'baseline', value: { projections: {} } }]),
     // api-workspace-controller client `apply`: the follow stream's opening baseline, then open.
     'workspace/follow': openStream([{ type: 'baseline', value: { items: [], archivedSessionIds: [], pinnedSessionIds: [] } }]),
   },
diff --git a/packages/test-support/client-runtime/src/sessions.ts b/packages/test-support/client-runtime/src/sessions.ts
index dd07c98254..5ad261b5b0 100644
--- a/packages/test-support/client-runtime/src/sessions.ts
+++ b/packages/test-support/client-runtime/src/sessions.ts
@@ -328,7 +328,7 @@ export class TestSessions implements ISessions {
    */
   constructor(private readonly stabilize: Stabilizer, private readonly rootCtx: Context) {
     this.list = createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, phase: 'ready', projectionsBySession: {}, jobsBySession: {},
+      ids: [], byId: {}, phase: 'ready', projectionsBySession: {},
     })
     rootCtx.effect(() => async () => {
       this.closed = true
diff --git a/packages/test-support/client-runtime/src/workspaces.ts b/packages/test-support/client-runtime/src/workspaces.ts
index 68a5c61d09..63c1ec78d9 100644
--- a/packages/test-support/client-runtime/src/workspaces.ts
+++ b/packages/test-support/client-runtime/src/workspaces.ts
@@ -1,7 +1,7 @@
 /** Test-owned workspaces face: the renderer standard-kit observable plus recorded actions. */
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type {
-  IWorkspaces, WorkspaceId, WorkspaceSnapshot, WorkspaceView,
+  IWorkspaces, WorkspaceId, WorkspaceInitializeDefaultRequest, WorkspaceSnapshot, WorkspaceView,
 } from '@deepseek-ai/dsh-api-workspace-controller/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
@@ -80,6 +80,18 @@ export class TestWorkspaces implements IWorkspaces {
     } as unknown as WorkspaceView
   }
 
+  /**
+   * Initialize the default Workspace through a test stub; defaults to an ineligible first use.
+   * @param request - initial directory name and title.
+   * @param signal - caller lifetime.
+   * @returns the stubbed Workspace, or undefined when initialization is ineligible.
+   */
+  async initializeDefault(request: WorkspaceInitializeDefaultRequest, signal?: AbortSignal): Promise<WorkspaceView | undefined> {
+    this.calls.push({ method: 'initializeDefault', args: [request, signal] })
+    const stub = this.stubs.get('initializeDefault')
+    return await (stub?.(request, signal) as Promise<WorkspaceView | undefined> | undefined)
+  }
+
   /**
    * Rename a Workspace (recorded). The default echoes a minimal view.
    * @param workspaceId - target workspace.
diff --git a/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts b/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts
index e73ce00818..e29ebf0027 100644
--- a/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts
+++ b/packages/test-support/client-runtime/tests/assembly-bundle-roster.client.spec.ts
@@ -7,6 +7,11 @@ import { afterAll, describe, expect, it } from 'vitest'
 import { MODULES_PACKAGE } from '../src/assembly/modules.ts'
 import { WEB_PROFILE_BUNDLES, bundleRoster, webApp } from '../src/assembly/bundle-roster.ts'
 
+function profileScope(name: string) {
+  const services: Record<string, object | undefined> = { profileContext: { name } }
+  return { get: (key: string) => services[key] }
+}
+
 describe('webApp (the real web profile)', () => {
   it('composes dsh-base then dsh-web-app: unique names, inject edges on roster rows or platform seed words', () => {
     expect(WEB_PROFILE_BUNDLES).toEqual(['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'])
@@ -15,7 +20,10 @@ describe('webApp (the real web profile)', () => {
     const known = new Set([...names, ...Object.keys(getStaticModules())])
     const dangling = webApp.rows.flatMap(row => row.inject.filter(target => !known.has(target)).map(target => `${row.name} -> ${target}`))
     expect(dangling).toEqual([])
-    expect(bundleRoster(WEB_PROFILE_BUNDLES).rows).toEqual(webApp.rows)
+    expect(bundleRoster(WEB_PROFILE_BUNDLES, undefined, profileScope('web')).rows).toEqual(webApp.rows)
+    expect(names).not.toContain('@deepseek-ai/dsh-client-ui-sidebar-browser')
+    expect(bundleRoster(WEB_PROFILE_BUNDLES, undefined, profileScope('desktop')).rows.map(row => row.name))
+      .toContain('@deepseek-ai/dsh-client-ui-sidebar-browser')
   })
 
   it('keeps browser rows with their declarations and drops Host-only, disabled, and subpath rows', () => {
@@ -114,6 +122,15 @@ describe('bundleRoster on a scratch installation', () => {
     expect(scratch.roster(['@t/base'])).toEqual(['@t/a', '@t/c'])
   })
 
+  it('concatenates a dsh.bundle.patch list in order', () => {
+    scratch.web('@t/listed')
+    scratch.pkg('@t/list', { dsh: { bundle: { patch: ['./first.yml', './second.yml'] } } }, {
+      'first.yml': '- insert:\n    - id: listed\n      name: \'@t/listed\'\n      disabled: true\n',
+      'second.yml': '- id: listed\n  disabled: false\n',
+    })
+    expect(scratch.roster(['@t/list'])).toEqual(['@t/listed'])
+  })
+
   it('descends into Loader groups and lets a disabled group disable every row beneath it', () => {
     scratch.web('@t/grouped')
     scratch.web('@t/grouped-off')
@@ -154,10 +171,90 @@ describe('bundleRoster on a scratch installation', () => {
     expect(() => scratch.roster(['@t/maybe-bundle'])).toThrow('browser row @t/maybe has a `disabled` value this reader cannot evaluate')
   })
 
+  it('evaluates profile conditions before deduplication and skips ignored row expressions', () => {
+    scratch.web('@t/conditional')
+    scratch.bundle('@t/conditional-bundle', `
+- insert:
+    - id: ignored
+      name: ./ignored.mjs
+      disabled: !!js missingIgnoredValue
+    - id: first
+      name: '@t/conditional'
+      disabled: !!js ctx.get('profileContext').name !== 'desktop'
+    - id: second
+      name: '@t/conditional'
+      disabled: false
+`)
+    expect(bundleRoster(['@t/conditional-bundle'], scratch.anchor, profileScope('web')).rows.map(row => row.name))
+      .toEqual(['@t/conditional'])
+  })
+
+  it('combines ancestor and child conditions without evaluating disabled subtrees', () => {
+    scratch.web('@t/conditional-on')
+    scratch.web('@t/conditional-off')
+    scratch.bundle('@t/conditional-groups', `
+- insert:
+    - id: parent-off
+      name: cordis:group
+      group: true
+      disabled: !!js true
+      config:
+        - id: unreachable
+          name: '@t/not-installed'
+          disabled: !!js missingInactiveValue
+    - id: literal-off
+      name: cordis:group
+      group: true
+      disabled: true
+      config:
+        - id: also-unreachable
+          name: '@t/not-installed-either'
+          disabled: !!js missingInactiveValue
+    - id: parent-on
+      name: cordis:group
+      group: true
+      disabled: !!js false
+      config:
+        - id: child-off
+          name: '@t/conditional-off'
+          disabled: true
+        - id: nested-on
+          name: cordis:group
+          group: true
+          disabled: !!js false
+          config:
+            - id: child-on
+              name: '@t/conditional-on'
+              disabled: null
+`)
+    expect(bundleRoster(['@t/conditional-groups'], scratch.anchor, {}).rows.map(row => row.name))
+      .toEqual(['@t/conditional-on'])
+  })
+
+  it('propagates evaluation failures and rejects unsupported literal flags with a scope', () => {
+    scratch.web('@t/bad-condition')
+    scratch.bundle('@t/bad-expression', `
+- insert:
+    - id: bad
+      name: '@t/bad-condition'
+      disabled: !!js missingConditionValue
+`)
+    expect(() => bundleRoster(['@t/bad-expression'], scratch.anchor, {})).toThrow('missingConditionValue')
+    scratch.bundle('@t/bad-literal', `
+- insert:
+    - id: bad
+      name: '@t/bad-condition'
+      disabled: not-a-boolean
+`)
+    expect(() => bundleRoster(['@t/bad-literal'], scratch.anchor, {})).toThrow('disabled')
+  })
+
   it('fails loud on a bundle that does not resolve, declares no patch, or whose patch is not a list', () => {
     expect(() => scratch.roster(['@t/missing'])).toThrow('cannot resolve bundle @t/missing from')
     scratch.pkg('@t/no-patch', { dsh: {} })
-    expect(() => scratch.roster(['@t/no-patch'])).toThrow('bundle @t/no-patch declares no dsh.bundle.patch in')
+    expect(() => scratch.roster(['@t/no-patch'])).toThrow('bundle @t/no-patch declares no dsh.bundle.patch file list in')
+    scratch.pkg('@t/bad-patch-list', { dsh: { bundle: { patch: [1] } } })
+    expect(() => scratch.roster(['@t/bad-patch-list'])).toThrow('bundle @t/bad-patch-list declares no dsh.bundle.patch file list in')
     scratch.bundle('@t/not-a-list', 'insert: []\n')
     expect(() => scratch.roster(['@t/not-a-list'])).toThrow('must be a top-level list of patches')
   })
diff --git a/packages/test-support/client-runtime/tests/runtime.client.spec.tsx b/packages/test-support/client-runtime/tests/runtime.client.spec.tsx
index 7d29ba7f72..ca9523edbe 100644
--- a/packages/test-support/client-runtime/tests/runtime.client.spec.tsx
+++ b/packages/test-support/client-runtime/tests/runtime.client.spec.tsx
@@ -557,6 +557,28 @@ describe('workspaces', () => {
     expect(view.container.textContent).toContain('ws:pending')
     await runtime.dispose()
   })
+  it('skips default initialization without a fixture and forwards a configured request and lifetime', async () => {
+    const runtime = await SlotTestRuntime.create()
+    try {
+      const request = { directoryName: 'default-workspace', title: 'Default workspace' }
+      const signal = new AbortController().signal
+      await expect(runtime.workspaces.initializeDefault(request, signal)).resolves.toBeUndefined()
+      const workspace = {
+        workspaceId: 'default' as WorkspaceId, title: request.title, path: '/default', sessionIds: [],
+        createdAt: '2026-09-20T00:00:00Z', updatedAt: '2026-09-20T00:00:00Z',
+      }
+      const initialize = vi.fn(async () => workspace)
+      runtime.workspaces.stub('initializeDefault', initialize)
+      await expect(runtime.workspaces.initializeDefault(request, signal)).resolves.toBe(workspace)
+      expect(initialize).toHaveBeenCalledWith(request, signal)
+      expect(runtime.workspaces.calls).toEqual([
+        { method: 'initializeDefault', args: [request, signal] },
+        { method: 'initializeDefault', args: [request, signal] },
+      ])
+    } finally {
+      await runtime.dispose()
+    }
+  })
 })
 
 describe('feature mount and disposal', () => {
diff --git a/packages/test-support/llm-mock-server/README.i18n.yaml b/packages/test-support/llm-mock-server/README.i18n.yaml
index 10ca40b376..22fcf568b1 100644
--- a/packages/test-support/llm-mock-server/README.i18n.yaml
+++ b/packages/test-support/llm-mock-server/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/test-support/llm-mock-server/README.md
-README.md: be311d9c83bcd35ad5bd0c003f6e95861b6d6976
-README.zh.md: 7a022131d9ef09d9ef89c91cae418f093f77aca1
+README.md: 2f83cf66c02728820a4f8aa6f14b1a091d092626
+README.zh.md: ad85853fb4a20c3ccdb444508da8032c18d7538a
diff --git a/packages/test-support/llm-mock-server/README.md b/packages/test-support/llm-mock-server/README.md
index be311d9c83..2f83cf66c0 100644
--- a/packages/test-support/llm-mock-server/README.md
+++ b/packages/test-support/llm-mock-server/README.md
@@ -1,5 +1,5 @@
 ---
-description: "Scriptable OpenAI-compatible fault server for testing LLM adapters and recovery policy without a provider key, for test authors and demos."
+description: "Scriptable Messages-compatible fault server for testing LLM adapters and recovery policy without a provider key, for test authors and demos."
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-This package gives tests and demos a scriptable OpenAI-compatible HTTP/SSE endpoint, so they can exercise model-provider failures and successes without a provider key. Each accepted `/chat/completions` request consumes the next scripted behavior, including resets, stalls, malformed chunks, rate limits, server errors, completions, and tool calls. Test authors can run it with `pnpm run mock:llm` or call `startMockLlmServer`, which returns captured requests for assertions. Seeded `random` behavior supports reproducible mixed-failure stress runs.
+This package gives tests and demos a scriptable Messages-compatible HTTP/SSE endpoint, so they can exercise model-provider failures and successes without a provider key. Each accepted `/v1/messages` request consumes the next scripted behavior, including resets, stalls, malformed chunks, rate limits, server errors, completions, and tool calls. Test authors can run it with `pnpm run mock:llm` or call `startMockLlmServer`, which returns captured requests for assertions. Seeded `random` behavior supports reproducible mixed-failure stress runs.
 
 ## Table of Contents
 
@@ -39,7 +39,7 @@ pnpm run mock:llm \
   --partial-text "discard this half"
 ```
 
-Point the shipping DeepSeek adapter at the server; it appends `/chat/completions` to the configured base:
+Point the shipping DeepSeek adapter at the server; it sends requests to `/messages` beneath the server's `/v1` root:
 
 ```sh
 DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 \
@@ -88,13 +88,13 @@ Omitting `--seed` generates one and prints it in the `ready` record. `--random-w
 
 ### Timing and content controls
 
-The CLI exposes `--success-text`, `--partial-text`, `--reasoning-text`, `--chunk-size`, `--chunk-delay-ms`, `--disconnect-delay-ms`, `--retry-after-ms`, `--request-id`, `--tool-name`, and `--tool-arguments`. Millisecond delays are bounded integers within Node's timer range; `retryAfterMs` must also be positive. The library accepts the same camel-case options. An optional exact `apiKey` validates `Authorization: Bearer <token>`; omission accepts any token.
+The CLI exposes `--success-text`, `--partial-text`, `--reasoning-text`, `--chunk-size`, `--chunk-delay-ms`, `--disconnect-delay-ms`, `--retry-after-ms`, `--request-id`, `--tool-name`, and `--tool-arguments`. Millisecond delays are bounded integers within Node's timer range; `retryAfterMs` must also be positive. The library accepts the same camel-case options. An optional exact `apiKey` validates `x-api-key: <token>`; omission accepts any token.
 
 ### What can go wrong
 
 - **The script runs out** — exhaustion returns a structured HTTP 500; set `--repeat-last` or lengthen the sequence when a run needs more requests.
 - **Random weights without a positive concrete behavior are rejected** — every entry must name an existing behavior and at least one must carry positive weight.
-- **Invalid requests do not consume the script** — wrong methods, paths, bearer tokens, and malformed JSON get ordinary 4xx responses, so a misconfigured client can burn retries without advancing the sequence.
+- **Invalid requests do not consume the script** — wrong methods, paths, API keys, and malformed JSON get ordinary 4xx responses, so a misconfigured client can burn retries without advancing the sequence.
 
 -----
 
@@ -108,7 +108,7 @@ This section explains the design of the server; the observable behavior is fully
 
 ### Design
 
-The server is built on one rule: each accepted chat-completions request consumes exactly one behavior from an arrival-ordered FIFO cursor, and the server never retries or interprets harness policy. Validation happens before the cursor advances — only a `POST` whose path ends in `/chat/completions`, with a valid bearer token when one is configured and a parseable JSON body, consumes the script; everything else receives an ordinary 4xx. `random` entries resolve at request time through a seeded PRNG over the configured weights, so a run is reproducible from its printed seed.
+The server is built on one rule: each accepted Messages request consumes exactly one behavior from an arrival-ordered FIFO cursor, and the server never retries or interprets harness policy. Validation happens before the cursor advances — only a `POST` whose path ends in `/v1/messages`, with a valid API key when one is configured and a parseable JSON body, consumes the script; everything else receives an ordinary 4xx. `random` entries resolve at request time through a seeded PRNG over the configured weights, so a run is reproducible from its printed seed.
 
 ### Source map
 
diff --git a/packages/test-support/llm-mock-server/README.zh.md b/packages/test-support/llm-mock-server/README.zh.md
index 7a022131d9..ad85853fb4 100644
--- a/packages/test-support/llm-mock-server/README.zh.md
+++ b/packages/test-support/llm-mock-server/README.zh.md
@@ -1,5 +1,5 @@
 ---
-description: "用于在无提供方密钥的情况下测试 LLM（大语言模型）适配器与恢复策略的可通过脚本控制的 OpenAI 兼容故障服务器，面向测试作者与演示。"
+description: "用于在无提供方密钥的情况下测试 LLM（大语言模型）适配器与恢复策略的可通过脚本控制的 Messages 兼容故障服务器，面向测试作者与演示。"
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-本包为测试与演示提供可编脚本的 OpenAI 兼容 HTTP／SSE（Server-Sent Events）端点，使其无需提供方密钥即可检验模型提供方的失败与成功。每个已接受的 `/chat/completions` 请求依次消费下一个脚本行为，包括重置、停滞、畸形分片、限流、服务器错误、补全与工具调用。测试作者可以通过 `pnpm run mock:llm` 运行服务器，也可以调用 `startMockLlmServer`，后者会返回捕获的请求供断言使用。带种子的 `random` 行为支持可复现的混合故障压力运行。
+本包为测试与演示提供可编脚本的 Messages 兼容 HTTP／SSE（Server-Sent Events）端点，使其无需提供方密钥即可检验模型提供方的失败与成功。每个已接受的 `/v1/messages` 请求依次消费下一个脚本行为，包括重置、停滞、畸形分片、限流、服务器错误、补全与工具调用。测试作者可以通过 `pnpm run mock:llm` 运行服务器，也可以调用 `startMockLlmServer`，后者会返回捕获的请求供断言使用。带种子的 `random` 行为支持可复现的混合故障压力运行。
 
 ## 目录
 
@@ -39,7 +39,7 @@ pnpm run mock:llm \
   --partial-text "discard this half"
 ```
 
-将发布的 DeepSeek 适配器指向服务器；它会将 `/chat/completions` 追加到已配置 base：
+将发布的 DeepSeek 适配器指向服务器；它会向服务器 `/v1` 根路径下的 `/messages` 发送请求：
 
 ```sh
 DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1 \
@@ -88,13 +88,13 @@ pnpm run mock:llm \
 
 ### 时序与内容控制
 
-CLI 公开 `--success-text`、`--partial-text`、`--reasoning-text`、`--chunk-size`、`--chunk-delay-ms`、`--disconnect-delay-ms`、`--retry-after-ms`、`--request-id`、`--tool-name` 与 `--tool-arguments`。毫秒延迟是 Node 定时器范围内的有界整数；`retryAfterMs` 还必须为正数。库接受相同的 camel-case 选项。可选的 `apiKey` 会精确验证 `Authorization: Bearer <token>`；省略时接受任何 token。
+CLI 公开 `--success-text`、`--partial-text`、`--reasoning-text`、`--chunk-size`、`--chunk-delay-ms`、`--disconnect-delay-ms`、`--retry-after-ms`、`--request-id`、`--tool-name` 与 `--tool-arguments`。毫秒延迟是 Node 定时器范围内的有界整数；`retryAfterMs` 还必须为正数。库接受相同的 camel-case 选项。可选的 `apiKey` 会精确验证 `x-api-key: <token>`；省略时接受任何 token。
 
 ### 可能出什么问题
 
 - **脚本耗尽**——耗尽时返回结构化 HTTP 500；当一次运行需要更多请求时设置 `--repeat-last` 或加长序列。
 - **没有正权重具体行为的随机权重会被拒绝**——每个条目都必须命名现有行为，且至少一个条目带正权重。
-- **无效请求不消费脚本**——错误方法、路径、Bearer token 与畸形 JSON 会收到普通 4xx 响应，因此配置错误的客户端可能耗尽重试却不推进序列。
+- **无效请求不消费脚本**——错误方法、路径、API key 与畸形 JSON 会收到普通 4xx 响应，因此配置错误的客户端可能耗尽重试却不推进序列。
 
 -----
 
@@ -108,7 +108,7 @@ CLI 公开 `--success-text`、`--partial-text`、`--reasoning-text`、`--chunk-s
 
 ### 设计
 
-服务器建立在一个规则之上：每个已接受的 chat-completions 请求从按到达顺序排列的 FIFO 游标消费恰好一个行为，服务器从不重试或解读 harness 策略。校验先于游标推进——只有 `POST` 且路径以 `/chat/completions` 结尾、配置密钥时携带有效 Bearer token、且 JSON 正文可解析的请求才消费脚本；其余请求都收到普通 4xx。`random` 条目在请求时通过带种子的 PRNG 按配置权重解析，因此一次运行可由其打印出的种子复现。
+服务器建立在一个规则之上：每个已接受的 Messages 请求从按到达顺序排列的 FIFO 游标消费恰好一个行为，服务器从不重试或解读 harness 策略。校验先于游标推进——只有 `POST` 且路径以 `/v1/messages` 结尾、配置密钥时携带有效 API key、且 JSON 正文可解析的请求才消费脚本；其余请求都收到普通 4xx。`random` 条目在请求时通过带种子的 PRNG 按配置权重解析，因此一次运行可由其打印出的种子复现。
 
 ### 源码地图
 
diff --git a/packages/test-support/llm-mock-server/package.json b/packages/test-support/llm-mock-server/package.json
index 6bed08aa80..225c056215 100644
--- a/packages/test-support/llm-mock-server/package.json
+++ b/packages/test-support/llm-mock-server/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-llm-mock-server",
-  "description": "Scriptable OpenAI-compatible HTTP/SSE fault server for LLM recovery tests",
+  "description": "Scriptable Messages HTTP/SSE fault server for LLM recovery tests",
   "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
diff --git a/packages/test-support/llm-mock-server/src/index.ts b/packages/test-support/llm-mock-server/src/index.ts
index b07a2bb09b..9ddab9a2cc 100644
--- a/packages/test-support/llm-mock-server/src/index.ts
+++ b/packages/test-support/llm-mock-server/src/index.ts
@@ -1,6 +1,6 @@
 /**
- * Scriptable OpenAI-compatible HTTP/SSE server for transport, protocol, and
- * semantic-empty LLM recovery tests. Each accepted chat-completions request
+ * Scriptable Messages HTTP/SSE server for transport, protocol, and
+ * semantic-empty LLM recovery tests. Each accepted Messages request
  * consumes one behavior; the server never retries or interprets harness policy.
  *
  * @module @deepseek-ai/dsh-llm-mock-server
@@ -95,7 +95,7 @@ export type MockLlmServerEvent =
 
 /** Captured wire request and its final server-side outcome. */
 export interface MockLlmRequestRecord {
-  /** One-based accepted chat-completions request number. */
+  /** One-based accepted Messages request number. */
   readonly attempt: number
   /** Script entry consumed for this request before random resolution. */
   readonly scriptBehavior: MockLlmBehavior | 'script_exhausted'
@@ -119,7 +119,7 @@ export interface MockLlmServerOptions {
   readonly host?: string
   /** TCP port; zero requests an OS-assigned port. */
   readonly port?: number
-  /** Optional exact bearer token; omission accepts any authorization header. */
+  /** Optional exact API key; omission accepts any x-api-key header. */
   readonly apiKey?: string
   /** Ordered request behaviors; exhaustion fails loud unless `repeatLast` is true. */
   readonly sequence: readonly MockLlmBehavior[]
@@ -155,7 +155,7 @@ export interface MockLlmServerOptions {
 
 /** Running mock server and captured request state. */
 export interface MockLlmServer {
-  /** Base URL without `/v1`; both root and `/v1` chat-completions paths are accepted. */
+  /** Base URL without `/v1`; the endpoint is `/v1/messages`. */
   readonly baseURL: string
   /** Actual bound port, including an OS-assigned value. */
   readonly port: number
@@ -325,7 +325,7 @@ function writeSse(record: MockLlmRequestRecord, response: ServerResponse, payloa
 }
 
 function writeDone(record: MockLlmRequestRecord, response: ServerResponse): void {
-  writeSse(record, response, '[DONE]')
+  writeSse(record, response, { type: 'message_stop' })
 }
 
 function finishRecord(
@@ -364,10 +364,22 @@ function httpError(
   finishRecord(options, record, 'completed')
 }
 
+function startMessage(record: MockLlmRequestRecord, response: ServerResponse): void {
+  writeSse(record, response, {
+    type: 'message_start',
+    message: { id: 'mock-message', type: 'message', role: 'assistant', model: 'mock-model', content: [], usage: { input_tokens: 3, output_tokens: 0 } },
+  })
+}
+
+function startText(record: MockLlmRequestRecord, response: ServerResponse, index: number): void {
+  writeSse(record, response, { type: 'content_block_start', index, content_block: { type: 'text', text: '' } })
+}
+
 function terminalChunk(reason: string, outputTokens: number): unknown {
   return {
-    choices: [{ index: 0, delta: { content: '' }, finish_reason: reason }],
-    usage: { prompt_tokens: 3, completion_tokens: outputTokens },
+    type: 'message_delta',
+    delta: { stop_reason: reason, stop_sequence: null },
+    usage: { output_tokens: outputTokens },
   }
 }
 
@@ -393,9 +405,10 @@ async function streamText(
   response: ServerResponse,
   text: string,
   delayMs: number,
+  index = 0,
 ): Promise<boolean> {
   for (const chunk of splitText(text, options.chunkSize)) {
-    writeSse(record, response, { choices: [{ index: 0, delta: { content: chunk }, finish_reason: null }] })
+    writeSse(record, response, { type: 'content_block_delta', index, delta: { type: 'text_delta', text: chunk } })
     if (!await pause(delayMs, response)) return false
   }
   return true
@@ -405,13 +418,16 @@ async function completeText(
   options: ResolvedOptions,
   record: MockLlmRequestRecord,
   response: ServerResponse,
-  reason: 'stop' | 'length',
+  reason: 'end_turn' | 'max_tokens',
   delayMs: number,
+  index = 0,
 ): Promise<void> {
-  if (!await streamText(options, record, response, options.successText, delayMs)) {
+  startText(record, response, index)
+  if (!await streamText(options, record, response, options.successText, delayMs, index)) {
     finishRecord(options, record, 'client_closed')
     return
   }
+  writeSse(record, response, { type: 'content_block_stop', index })
   writeSse(record, response, terminalChunk(reason, Array.from(options.successText).length))
   writeDone(record, response)
   response.end()
@@ -434,27 +450,11 @@ async function disconnect(
 function toolCallChunks(options: ResolvedOptions): readonly unknown[] {
   const midpoint = Math.max(1, Math.floor(options.toolArguments.length / 2))
   return [
-    {
-      choices: [{
-        index: 0,
-        delta: {
-          tool_calls: [{
-            index: 0,
-            id: 'mock-call-1',
-            type: 'function',
-            function: { name: options.toolName, arguments: options.toolArguments.slice(0, midpoint) },
-          }],
-        },
-        finish_reason: null,
-      }],
-    },
-    {
-      choices: [{
-        index: 0,
-        delta: { tool_calls: [{ index: 0, function: { arguments: options.toolArguments.slice(midpoint) } }] },
-        finish_reason: null,
-      }],
-    },
+    { type: 'content_block_start', index: 0, content_block: { type: 'tool_use', id: 'mock-call-1', name: options.toolName, input: {} } },
+    ...[options.toolArguments.slice(0, midpoint), options.toolArguments.slice(midpoint)].map(partial => ({
+      type: 'content_block_delta', index: 0, delta: { type: 'input_json_delta', partial_json: partial },
+    })),
+    { type: 'content_block_stop', index: 0 },
   ]
 }
 
@@ -478,7 +478,8 @@ async function runBehavior(
       return
     case 'empty':
       openSse(response)
-      writeSse(record, response, terminalChunk('stop', 0))
+      startMessage(record, response)
+      writeSse(record, response, terminalChunk('end_turn', 0))
       writeDone(record, response)
       response.end()
       finishRecord(options, record, 'completed')
@@ -490,18 +491,22 @@ async function runBehavior(
       return
     case 'stream_eof':
       openSse(response)
-      writeSse(record, response, { choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] })
+      startMessage(record, response)
       response.end()
       finishRecord(options, record, 'completed')
       return
     case 'partial_eof':
       openSse(response)
+      startMessage(record, response)
+      startText(record, response, 0)
       await streamText(options, record, response, options.partialText, 0)
       response.end()
       finishRecord(options, record, 'completed')
       return
     case 'partial_disconnect':
       openSse(response)
+      startMessage(record, response)
+      startText(record, response, 0)
       if (!await streamText(options, record, response, options.partialText, options.chunkDelayMs)) return
       await disconnect(options, record, response)
       return
@@ -518,14 +523,15 @@ async function runBehavior(
       return
     case 'malformed_event':
       openSse(response)
-      writeSse(record, response, { choices: [null] })
+      writeSse(record, response, { type: 'content_block_start', index: 0, content_block: null })
       writeDone(record, response)
       response.end()
       finishRecord(options, record, 'completed')
       return
     case 'wrong_content_type':
       openSse(response, 'application/json')
-      await completeText(options, record, response, 'stop', 0)
+      startMessage(record, response)
+      await completeText(options, record, response, 'end_turn', 0)
       return
     case 'rate_limit':
       httpError(options, record, response, 429, 'mock rate limit', 'rate_limit')
@@ -558,32 +564,37 @@ async function runBehavior(
       return
     case 'success':
       openSse(response)
-      await completeText(options, record, response, 'stop', 0)
+      startMessage(record, response)
+      await completeText(options, record, response, 'end_turn', 0)
       return
     case 'reasoning_success':
       openSse(response)
+      startMessage(record, response)
+      writeSse(record, response, { type: 'content_block_start', index: 0, content_block: { type: 'thinking', thinking: '' } })
       for (const chunk of splitText(options.reasoningText, options.chunkSize)) {
-        writeSse(record, response, {
-          choices: [{ index: 0, delta: { reasoning_content: chunk }, finish_reason: null }],
-        })
+        writeSse(record, response, { type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: chunk } })
       }
-      await completeText(options, record, response, 'stop', 0)
+      writeSse(record, response, { type: 'content_block_stop', index: 0 })
+      await completeText(options, record, response, 'end_turn', 0, 1)
       return
     case 'tool_call_success':
       openSse(response)
+      startMessage(record, response)
       for (const chunk of toolCallChunks(options)) writeSse(record, response, chunk)
-      writeSse(record, response, terminalChunk('tool_calls', 2))
+      writeSse(record, response, terminalChunk('tool_use', 2))
       writeDone(record, response)
       response.end()
       finishRecord(options, record, 'completed')
       return
     case 'max_tokens':
       openSse(response)
-      await completeText(options, record, response, 'length', 0)
+      startMessage(record, response)
+      await completeText(options, record, response, 'max_tokens', 0)
       return
     case 'slow_success':
       openSse(response)
-      await completeText(options, record, response, 'stop', options.chunkDelayMs)
+      startMessage(record, response)
+      await completeText(options, record, response, 'end_turn', options.chunkDelayMs)
       return
   }
 }
@@ -615,9 +626,9 @@ function chooseRandomBehavior(
 }
 
 /**
- * Start a local chat-completions server that consumes one configured behavior
- * per accepted request. Only a `POST` path ending in `/chat/completions` consumes the script;
- * invalid routes, methods, authorization, and JSON receive ordinary 4xx
+ * Start a local Messages server that consumes one configured behavior
+ * per accepted request. Only a `POST` path ending in `/v1/messages` consumes the script;
+ * invalid routes, methods, API keys, and JSON receive ordinary 4xx
  * responses. Closing the handle terminates stalled connections.
  *
  * @param options - listener, script, response content, timing, and telemetry options.
@@ -652,13 +663,13 @@ export async function startMockLlmServer(options: MockLlmServerOptions): Promise
       response.writeHead(405, { allow: 'POST' }).end()
       return
     }
-    if (!path.endsWith('/chat/completions')) {
+    if (!path.endsWith('/v1/messages')) {
       response.writeHead(404).end()
       return
     }
-    if (resolved.apiKey !== undefined && request.headers.authorization !== `Bearer ${resolved.apiKey}`) {
+    if (resolved.apiKey !== undefined && request.headers['x-api-key'] !== resolved.apiKey) {
       response.writeHead(401, { 'content-type': 'application/json' })
-      response.end(JSON.stringify({ error: { message: 'invalid mock bearer token', code: 'invalid_api_key' } }))
+      response.end(JSON.stringify({ error: { message: 'invalid mock API key', code: 'invalid_api_key' } }))
       return
     }
 
diff --git a/packages/test-support/llm-mock-server/tests/server.spec.ts b/packages/test-support/llm-mock-server/tests/server.spec.ts
index a32e5cc8b2..5d7bbfaba6 100644
--- a/packages/test-support/llm-mock-server/tests/server.spec.ts
+++ b/packages/test-support/llm-mock-server/tests/server.spec.ts
@@ -18,24 +18,24 @@ async function start(
   return server
 }
 
-function chat(
+function messages(
   server: MockLlmServer,
   options: { path?: string; key?: string; body?: string; signal?: AbortSignal } = {},
 ): Promise<Response> {
-  return fetch(`${server.baseURL}${options.path ?? '/v1/chat/completions'}`, {
+  return fetch(`${server.baseURL}${options.path ?? '/v1/messages'}`, {
     method: 'POST',
     headers: {
       'content-type': 'application/json',
-      ...options.key === undefined ? {} : { authorization: `Bearer ${options.key}` },
+      ...options.key === undefined ? {} : { 'x-api-key': options.key },
     },
     body: options.body ?? JSON.stringify({ model: 'mock', messages: [], stream: true }),
     ...options.signal === undefined ? {} : { signal: options.signal },
   })
 }
 
-function rawChat(server: MockLlmServer, chunks: readonly Buffer[]): Promise<void> {
+function rawMessages(server: MockLlmServer, chunks: readonly Buffer[]): Promise<void> {
   return new Promise((resolve, reject) => {
-    const outgoing = request(`${server.baseURL}/v1/chat/completions`, {
+    const outgoing = request(`${server.baseURL}/v1/messages`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
     }, (response) => {
@@ -59,22 +59,22 @@ describe('mock LLM server wire behaviors', () => {
       onEvent: (event) => { events.push(event) },
     })
 
-    const response = await chat(server, { key: 'mock-key' })
+    const response = await messages(server, { key: 'mock-key' })
     const body = await response.text()
 
     expect(response.status).toBe(200)
     expect(response.headers.get('content-type')).toContain('text/event-stream')
-    expect(body).toContain('"content":"rec"')
-    expect(body).toContain('"content":"ove"')
-    expect(body).toContain('"content":"red"')
-    expect(body).toContain('"finish_reason":"stop"')
-    expect(body).toContain('data: [DONE]')
+    expect(body).toContain('"text":"rec"')
+    expect(body).toContain('"text":"ove"')
+    expect(body).toContain('"text":"red"')
+    expect(body).toContain('"stop_reason":"end_turn"')
+    expect(body).toContain('"type":"message_stop"')
     expect(server.requests).toEqual([expect.objectContaining({
       attempt: 1,
       behavior: 'success',
-      path: '/v1/chat/completions',
+      path: '/v1/messages',
       body: { model: 'mock', messages: [], stream: true },
-      chunksSent: 5,
+      chunksSent: 8,
       outcome: 'completed',
     })])
     expect(events).toEqual([
@@ -83,7 +83,7 @@ describe('mock LLM server wire behaviors', () => {
         attempt: 1,
         scriptBehavior: 'success',
         behavior: 'success',
-        path: '/v1/chat/completions',
+        path: '/v1/messages',
       },
       {
         type: 'result',
@@ -91,39 +91,39 @@ describe('mock LLM server wire behaviors', () => {
         scriptBehavior: 'success',
         behavior: 'success',
         outcome: 'completed',
-        chunksSent: 5,
+        chunksSent: 8,
       },
     ])
   })
 
-  it('supports root paths and intentionally ignores telemetry observer failures', async () => {
+  it('supports gateway prefixes and intentionally ignores telemetry observer failures', async () => {
     const server = await start(['empty'], {
       onEvent() {
         throw new Error('observer failed')
       },
     })
-    const response = await chat(server, { path: '/chat/completions' })
+    const response = await messages(server, { path: '/anthropic/v1/messages' })
 
     expect(response.status).toBe(200)
-    expect(await response.text()).toContain('data: [DONE]')
-    expect(server.requests[0]).toMatchObject({ path: '/chat/completions', outcome: 'completed' })
+    expect(await response.text()).toContain('"type":"message_stop"')
+    expect(server.requests[0]).toMatchObject({ path: '/anthropic/v1/messages', outcome: 'completed' })
   })
 
   it.each([
     ['empty_body', 0, ''] as const,
     ['stream_eof', 1, '"role":"assistant"'] as const,
-    ['partial_eof', 1, 'discarded partial response'] as const,
+    ['partial_eof', 3, 'discarded partial response'] as const,
     ['malformed_json', 2, 'data: {not-json'] as const,
-    ['malformed_event', 2, '"choices":[null]'] as const,
+    ['malformed_event', 2, '"content_block":null'] as const,
   ])('serves %s without inventing a terminal completion', async (behavior, chunks, marker) => {
     const server = await start([behavior], { chunkSize: 100 })
-    const response = await chat(server)
+    const response = await messages(server)
     const body = await response.text()
 
     expect(response.status).toBe(200)
     expect(body).toContain(marker)
     if (behavior !== 'malformed_json' && behavior !== 'malformed_event') {
-      expect(body).not.toContain('[DONE]')
+      expect(body).not.toContain('message_stop')
     }
     expect(server.requests[0]).toMatchObject({ behavior, chunksSent: chunks, outcome: 'completed' })
   })
@@ -137,7 +137,7 @@ describe('mock LLM server wire behaviors', () => {
 
     let headersReceived = false
     await expect((async () => {
-      const response = await chat(server)
+      const response = await messages(server)
       headersReceived = true
       await response.text()
     })()).rejects.toThrow()
@@ -145,7 +145,7 @@ describe('mock LLM server wire behaviors', () => {
     expect(headersReceived).toBe(receivesHeaders)
     expect(server.requests[0]).toMatchObject({
       behavior,
-      chunksSent: behavior === 'partial_disconnect' ? 1 : 0,
+      chunksSent: behavior === 'partial_disconnect' ? 3 : 0,
       outcome: 'reset',
     })
   })
@@ -153,7 +153,7 @@ describe('mock LLM server wire behaviors', () => {
   it('holds a stalled stream until the client aborts and server close remains idempotent', async () => {
     const server = await start(['stall'])
     const controller = new AbortController()
-    const response = await chat(server, { signal: controller.signal })
+    const response = await messages(server, { signal: controller.signal })
 
     expect(response.status).toBe(200)
     expect(server.requests[0]).toMatchObject({ behavior: 'stall', outcome: 'stalled' })
@@ -180,7 +180,7 @@ describe('mock LLM server wire behaviors', () => {
       },
     })
     const controller = new AbortController()
-    const response = await chat(server, { signal: controller.signal })
+    const response = await messages(server, { signal: controller.signal })
     controller.abort()
     await expect(response.text()).rejects.toThrow()
     await result.promise
@@ -197,7 +197,7 @@ describe('mock LLM server wire behaviors', () => {
     const characterOffset = encoded.indexOf(Buffer.from('你'))
     expect(characterOffset).toBeGreaterThanOrEqual(0)
 
-    await rawChat(server, [
+    await rawMessages(server, [
       encoded.subarray(0, characterOffset + 1),
       encoded.subarray(characterOffset + 1),
     ])
@@ -209,7 +209,7 @@ describe('mock LLM server wire behaviors', () => {
     const server = await start(['success'], { host: '::1' })
 
     expect(server.baseURL).toMatch(/^http:\/\/\[::1\]:\d+$/)
-    expect((await chat(server)).status).toBe(200)
+    expect((await messages(server)).status).toBe(200)
   })
 
   it('emits reasoning, tool calls, max-token finishes, slow chunks, and a wrong content type', async () => {
@@ -231,17 +231,17 @@ describe('mock LLM server wire behaviors', () => {
     const bodies: string[] = []
     const contentTypes: Array<string | null> = []
     for (let index = 0; index < 5; index += 1) {
-      const response = await chat(server)
+      const response = await messages(server)
       contentTypes.push(response.headers.get('content-type'))
       bodies.push(await response.text())
     }
 
-    expect(bodies[0]).toContain('"reasoning_content":"th"')
+    expect(bodies[0]).toContain('"thinking":"th"')
     expect(bodies[1]).toContain('"name":"lookup"')
-    expect(bodies[1]).toContain('"arguments":"{\\"id"')
-    expect(bodies[1]).toContain('"finish_reason":"tool_calls"')
-    expect(bodies[2]).toContain('"finish_reason":"length"')
-    expect(bodies[3]).toContain('"finish_reason":"stop"')
+    expect(bodies[1]).toContain('"partial_json":"{\\"id"')
+    expect(bodies[1]).toContain('"stop_reason":"tool_use"')
+    expect(bodies[2]).toContain('"stop_reason":"max_tokens"')
+    expect(bodies[3]).toContain('"stop_reason":"end_turn"')
     expect(contentTypes[4]).toBe('application/json')
     expect(server.requests).toHaveLength(5)
     expect(server.requests.every(record => record.outcome === 'completed')).toBe(true)
@@ -257,7 +257,7 @@ describe('mock LLM server wire behaviors', () => {
     ['quota_exceeded', 429, 'insufficient_quota'] as const,
   ])('serves %s as a structured HTTP error', async (behavior, status, marker) => {
     const server = await start([behavior], { retryAfterMs: 1_001, requestId: 'mock-request-1' })
-    const response = await chat(server)
+    const response = await messages(server)
     const body = await response.text()
 
     expect(response.status).toBe(status)
@@ -270,15 +270,15 @@ describe('mock LLM server wire behaviors', () => {
 
   it('fails loud on script exhaustion and can explicitly repeat the final behavior', async () => {
     const exhausted = await start(['success'], { successText: 'once' })
-    await (await chat(exhausted)).text()
-    const exhaustedResponse = await chat(exhausted)
+    await (await messages(exhausted)).text()
+    const exhaustedResponse = await messages(exhausted)
     expect(exhaustedResponse.status).toBe(500)
     expect(await exhaustedResponse.text()).toContain('mock script exhausted')
     expect(exhausted.requests.map(record => record.behavior)).toEqual(['success', 'script_exhausted'])
 
     const repeating = await start(['empty'], { repeatLast: true })
-    await (await chat(repeating)).text()
-    await (await chat(repeating)).text()
+    await (await messages(repeating)).text()
+    await (await messages(repeating)).text()
     expect(repeating.requests.map(record => record.behavior)).toEqual(['empty', 'empty'])
   })
 
@@ -295,8 +295,8 @@ describe('mock LLM server wire behaviors', () => {
     running.push(first, second)
 
     for (let attempt = 0; attempt < 12; attempt += 1) {
-      await (await chat(first)).text()
-      await (await chat(second)).text()
+      await (await messages(first)).text()
+      await (await messages(second)).text()
     }
 
     const firstChoices = first.requests.map(record => record.behavior)
@@ -307,12 +307,12 @@ describe('mock LLM server wire behaviors', () => {
     expect(first.requests.every(record => record.scriptBehavior === 'random')).toBe(true)
   })
 
-  it('rejects invalid method, route, bearer token, and JSON without consuming the script', async () => {
+  it('rejects invalid method, route, API key, and JSON without consuming the script', async () => {
     const server = await start(['success'], { apiKey: 'expected' })
-    const method = await fetch(`${server.baseURL}/v1/chat/completions`)
-    const route = await fetch(`${server.baseURL}/v1/other`, { method: 'POST', body: '{}' })
-    const auth = await chat(server, { key: 'wrong' })
-    const json = await chat(server, { key: 'expected', body: '{' })
+    const method = await fetch(`${server.baseURL}/v1/messages`)
+    const route = await fetch(`${server.baseURL}/chat/completions`, { method: 'POST', body: '{}' })
+    const auth = await messages(server, { key: 'wrong' })
+    const json = await messages(server, { key: 'expected', body: '{' })
 
     expect(method.status).toBe(405)
     expect(method.headers.get('allow')).toBe('POST')
@@ -321,9 +321,9 @@ describe('mock LLM server wire behaviors', () => {
     expect(json.status).toBe(400)
     expect(server.requests).toHaveLength(0)
 
-    const emptyRequest = await fetch(`${server.baseURL}/v1/chat/completions`, {
+    const emptyRequest = await fetch(`${server.baseURL}/v1/messages`, {
       method: 'POST',
-      headers: { authorization: 'Bearer expected' },
+      headers: { 'x-api-key': 'expected' },
     })
     expect(emptyRequest.status).toBe(200)
     expect(server.requests[0]?.behavior).toBe('success')
diff --git a/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts b/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts
index c42345732a..588ff2d443 100644
--- a/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts
+++ b/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts
@@ -45,7 +45,7 @@ function overlayModuleLayers(path: string, patches: readonly PatchOptions[]): Pr
   return [...packages].map(([name, packageDir], index) => ({
     packageName: `test-overlay:${index}:${name}`,
     packageDir,
-    patchPath: path,
+    patchPaths: [path],
     patches: [],
   }))
 }
diff --git a/packages/test-support/remote-mock/README.i18n.yaml b/packages/test-support/remote-mock/README.i18n.yaml
index b34a83ebed..63dbc05d7e 100644
--- a/packages/test-support/remote-mock/README.i18n.yaml
+++ b/packages/test-support/remote-mock/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/test-support/remote-mock/README.md
-README.md: 82979e37052aecee6ec716702f634d25c969f5ad
-README.zh.md: 201ca011410dd5a4d65b6ebdfb0c47f23742b0d3
+README.md: 7f76ce6217d7cc6f86923aa1ee4f7257ad30926e
+README.zh.md: b79849fe3b23b5135feff7095468f65809b0d506
diff --git a/packages/test-support/remote-mock/README.md b/packages/test-support/remote-mock/README.md
index 82979e3705..7f76ce6217 100644
--- a/packages/test-support/remote-mock/README.md
+++ b/packages/test-support/remote-mock/README.md
@@ -73,7 +73,9 @@ mock.streams.fail('session/follow', new Error('gone'))
 await mock.streams.drained('session/follow')
 ```
 
-A failed stream rejects the consumer's next read with the given `Error`. Consumer cancellation (the opening signal or an early iterator `return()`) aborts `StreamHandle.signal`, ends the iteration without throwing, and logs the stream as `cancelled`.
+A failed stream rejects the consumer's next read with the given `Error`. Consumer cancellation (the opening signal or an early iterator `return()`) aborts `StreamHandle.signal`, ends the iteration without throwing, and logs the stream as `cancelled`. `StreamHandle.uplink` is what the script reads as the Client's uplink: through `rpc.open` it is the carrier's iterable; for a direct `mock.remote.<namespace>.<method>(...)` call it is fed by the returned handle, which is the `RemoteStreamHandle` a generated method returns (iterate it for the downlink, `send()` and `end()` feed the uplink, `dispose()` cancels the stream); `send()` rejects a non-lossless JSON item as the real handle does, and the uplink it owns closes once the stream settles, is cancelled, or the consumer leaves, so a later `send()` throws. The mock function is called with the method's own arguments only, so the uplink never appears in call assertions or logged args.
+
+A fake that stands in for a generated stream method returns the `RemoteStreamHandle` the generated method does. `streamHandle(source)` types an `AsyncIterable` as that handle with inert `send`, `end`, and `dispose`; `streamMethod<M>(generator)` lifts an async generator function written for the method's arguments into the method's own signature, for `vi.fn<M>()` and `mockImplementation`.
 
 ### Connect a client
 
@@ -108,7 +110,7 @@ A failed stream rejects the consumer's next read with the given `Error`. Consume
 | [`src/index.ts`](src/index.ts) | Public face re-exports |
 | [`src/remote-mock.ts`](src/remote-mock.ts) | `RemoteMock`: default responses, native mocks, Connection dispatch, controlled streams and missing-response checks; `ok` |
 | [`src/remote-proxy.ts`](src/remote-proxy.ts) | Namespace/method lookup and generated-map mock types |
-| [`src/streams.ts`](src/streams.ts) | `frames` / `openStream` scripts and `MockStream` (handle + `AsyncIterable`) |
+| [`src/streams.ts`](src/streams.ts) | `frames` / `openStream` scripts, `streamHandle` / `streamMethod` fake typing, and `MockStream` (handle + `AsyncIterable`) |
 | [`src/log.ts`](src/log.ts) | Log store with the shared `seq` counter |
 | — | No runtime invariant companion is published; this test-support library owns no production event stream or mutable process state, and its behavior is exercised by its package tests. |
 
@@ -130,7 +132,7 @@ None; this package neither assembles nor sends a provider request.
 <a id="known-limitations-and-deferred-work"></a>
 
 - **In-process carrier only** — `rpc` serves a Connection instance in the same realm; no HTTP or WebSocket carrier for browser-lane specs is provided.
-- **Values cross by reference** — answers and stream items reach the client unserialized, so a non-JSON value that the real wire would reject passes through unchanged.
+- **Values cross by reference** — answers and downlink items reach the client unserialized, so a non-JSON downlink value that the real wire would reject passes through unchanged; only the handle's `send()` applies the real uplink check.
 - **Values are not checked** — a unary answer must be the result the caller reads (`{ ok, value }` or `{ ok: false, error }`); the mock passes it through unchanged and does not check those fields.
 - **No payload matching** — rules match on endpoint only; discriminate on business arguments inside a handler.
 - **Native stream overrides own their iterable** — an override returning its own iterable bypasses scripted-stream logs, `requests`, `opened`, `drained`, and `push` / `end` / `fail`; the caller also owns cancellation. Native call assertions still work. Use a registered stream script when a scenario needs those controls.
diff --git a/packages/test-support/remote-mock/README.zh.md b/packages/test-support/remote-mock/README.zh.md
index 201ca01141..b79849fe3b 100644
--- a/packages/test-support/remote-mock/README.zh.md
+++ b/packages/test-support/remote-mock/README.zh.md
@@ -73,7 +73,9 @@ mock.streams.fail('session/follow', new Error('gone'))
 await mock.streams.drained('session/follow')
 ```
 
-失败的流让消费方的下一次读取以给定的 `Error` reject。消费方取消（打开时的 signal 或 iterator 提前 `return()`）会中止 `StreamHandle.signal`、结束迭代而不抛错，并把该流记为 `cancelled`。
+失败的流让消费方的下一次读取以给定的 `Error` reject。消费方取消（打开时的 signal 或 iterator 提前 `return()`）会中止 `StreamHandle.signal`、结束迭代而不抛错，并把该流记为 `cancelled`。`StreamHandle.uplink` 是脚本读到的 Client 上行：经 `rpc.open` 打开时它是载体传入的 iterable；直接调用 `mock.remote.<namespace>.<method>(...)` 时它由返回的句柄喂入——该句柄就是生成方法返回的 `RemoteStreamHandle`（迭代它读下行，`send()` 与 `end()` 喂上行，`dispose()` 取消流）；`send()` 像真实句柄一样拒绝非无损 JSON 项，它拥有的上行在流结束、取消或消费方离开时关闭，之后的 `send()` 抛错。mock 函数只以方法自己的参数被调用，上行不会出现在调用断言或记录的 args 里。
+
+替代生成流方法的假实现返回生成方法所返回的 `RemoteStreamHandle`。`streamHandle(source)` 把一个 `AsyncIterable` 标注为该句柄，其 `send`、`end`、`dispose` 为空操作；`streamMethod<M>(generator)` 把按方法参数编写的 async generator 函数提升为方法自己的签名，供 `vi.fn<M>()` 与 `mockImplementation` 使用。
 
 ### 接上客户端
 
@@ -108,7 +110,7 @@ await mock.streams.drained('session/follow')
 | [`src/index.ts`](src/index.ts) | 公开面转出 |
 | [`src/remote-mock.ts`](src/remote-mock.ts) | `RemoteMock`：默认响应、原生 mock、Connection 分发、受控流与缺失响应检查；`ok` |
 | [`src/remote-proxy.ts`](src/remote-proxy.ts) | 命名空间／方法查找与生成映射的 mock 类型 |
-| [`src/streams.ts`](src/streams.ts) | `frames` / `openStream` 脚本与 `MockStream`（句柄 + `AsyncIterable`） |
+| [`src/streams.ts`](src/streams.ts) | `frames` / `openStream` 脚本、`streamHandle` / `streamMethod` 假实现标注，以及 `MockStream`（句柄 + `AsyncIterable`） |
 | [`src/log.ts`](src/log.ts) | 带共享 `seq` 计数器的日志 |
 | — | 不发布运行时不变量伴生件；本测试支持库不拥有任何生产事件流或可变进程状态，其行为由本包测试覆盖。 |
 
@@ -130,7 +132,7 @@ await mock.streams.drained('session/follow')
 <a id="known-limitations-and-deferred-work"></a>
 
 - **仅进程内载体**——`rpc` 服务同一 realm 中的 Connection 实例；不提供给浏览器车道测试用的 HTTP 或 WebSocket 载体。
-- **值按引用传递**——应答与流项都未经序列化就到达客户端，真实线路会拒绝的非 JSON 值在这里原样通过。
+- **值按引用传递**——应答与下行项都未经序列化就到达客户端，真实线路会拒绝的非 JSON 下行值在这里原样通过；只有句柄的 `send()` 施加真实的上行校验。
 - **不校验值**——一元应答必须是调用方读取的结果（`{ ok, value }` 或 `{ ok: false, error }`）；mock 原样传递它，不检查这些字段。
 - **不做 payload 匹配**——规则只按端点匹配；在 handler 内按业务参数判别。
 - **原生流覆盖自行管理 iterable**——覆盖返回自有 iterable 时，不参与脚本流日志、`requests`、`opened`、`drained` 以及 `push` / `end` / `fail`；调用方也负责取消。原生调用断言仍然有效。需要这些控制能力的场景应使用已登记的流脚本。
diff --git a/packages/test-support/remote-mock/package.json b/packages/test-support/remote-mock/package.json
index c9b683d880..af878fcb05 100644
--- a/packages/test-support/remote-mock/package.json
+++ b/packages/test-support/remote-mock/package.json
@@ -26,7 +26,8 @@
     "@vitest/spy": "^4.1.8"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
diff --git a/packages/test-support/remote-mock/src/index.ts b/packages/test-support/remote-mock/src/index.ts
index d7c1850c2e..9ac425a88b 100644
--- a/packages/test-support/remote-mock/src/index.ts
+++ b/packages/test-support/remote-mock/src/index.ts
@@ -10,7 +10,8 @@
  */
 export { RemoteMock, ok } from './remote-mock.ts'
 export type { OpenStreams, RemoteMockOptions, RemoteTable, StreamFilter, UnaryRuleFn } from './remote-mock.ts'
-export { frames, openStream } from './streams.ts'
+export { frames, openStream, streamHandle, streamMethod } from './streams.ts'
 export type { StreamHandle, StreamScript } from './streams.ts'
+export { MockClientStream } from './streams.ts'
 export type { LoggedCall, LoggedMiss, LoggedStream, MockLog } from './log.ts'
 export type { MockedRemote } from './remote-proxy.ts'
diff --git a/packages/test-support/remote-mock/src/remote-mock.ts b/packages/test-support/remote-mock/src/remote-mock.ts
index fca6a7a09c..e35ffdb2e2 100644
--- a/packages/test-support/remote-mock/src/remote-mock.ts
+++ b/packages/test-support/remote-mock/src/remote-mock.ts
@@ -3,7 +3,7 @@
 import type { ClientConnectionRpc, ConnectionRpcResult } from '@deepseek-ai/dsh-client-connection/client'
 import { fn, type Mock } from '@vitest/spy'
 import { MockLogStore, type MockLog } from './log.ts'
-import { MockStream, toError, type StreamScript } from './streams.ts'
+import { HandleUplink, MockClientStream, MockStream, toError, type StreamScript } from './streams.ts'
 import { createRemoteProxy, type MockedRemote } from './remote-proxy.ts'
 
 /** A unary handler receives the caller's positional arguments, without its trailing `AbortSignal`. */
@@ -116,6 +116,8 @@ export class RemoteMock {
   private readonly logStore = new MockLogStore()
   private readonly unaryMocks = new Map<string, Mock<UnaryRuleFn>>()
   private readonly streamMocks = new Map<string, Mock<UnaryRuleFn>>()
+  /** The carrier's uplink for the open in progress through {@link open}; a direct call has none. */
+  private carrierUplink: AsyncIterable<unknown> | undefined
   private readonly proxy = createRemoteProxy(endpoint => this.modeOf(endpoint) === 'stream'
     ? this.streamMock(endpoint)
     : this.unaryMock(endpoint))
@@ -156,7 +158,7 @@ export class RemoteMock {
       // The carrier contract names the result envelope; the registered value is taken as that envelope unchecked.
       return value as ConnectionRpcResult<unknown>
     },
-    open: (_channel, endpoint, payload, signal) => this.open(endpoint, argsOf(endpoint, payload), signal),
+    open: (_channel, endpoint, payload, signal, uplink) => this.open(endpoint, argsOf(endpoint, payload), signal, uplink),
   }
 
   private constructor() {}
@@ -277,16 +279,30 @@ export class RemoteMock {
   }
 
   /**
-   * Open through the endpoint's native mock; its default runs the registered script as a controlled stream.
-   * A native override returns its own iterable: the caller owns consumption and cancellation, outside `OpenStreams`.
+   * Open through the endpoint's native mock, which is called with the generated
+   * signature's arguments only; its default runs the registered script as a
+   * controlled stream. A native override returns its own iterable: the caller
+   * owns consumption and cancellation, outside `OpenStreams`.
    * @param endpoint - endpoint.
    * @param args - positional args.
    * @param signal - consumer cancellation.
+   * @param uplink - the carrier's uplink for this open, which the script reads as `StreamHandle.uplink`;
+   *   absent for a direct call, whose returned handle owns the uplink.
    * @returns the controlled script stream or the native override's caller-owned iterable.
    * @throws {Error} when the default runs without a registered script (logged as unmatched).
    */
-  open(endpoint: string, args: readonly unknown[], signal: AbortSignal): AsyncIterable<unknown> {
-    return this.streamMock(endpoint)(...args, signal) as AsyncIterable<unknown>
+  open(
+    endpoint: string,
+    args: readonly unknown[],
+    signal: AbortSignal,
+    uplink?: AsyncIterable<unknown>,
+  ): AsyncIterable<unknown> {
+    this.carrierUplink = uplink
+    try {
+      return this.streamMock(endpoint)(...args, signal) as AsyncIterable<unknown>
+    } finally {
+      this.carrierUplink = undefined
+    }
   }
 
   private streamMock(endpoint: string): Mock<UnaryRuleFn> {
@@ -295,24 +311,37 @@ export class RemoteMock {
       mock = fn((...values: readonly unknown[]) => {
         const args = [...values]
         const signal = args.at(-1) instanceof AbortSignal ? args.pop() as AbortSignal : new AbortController().signal
-        return this.openScript(endpoint, args, signal)
+        return this.openScript(endpoint, args, signal, this.carrierUplink)
       })
       this.streamMocks.set(endpoint, mock)
     }
     return mock
   }
 
-  private openScript(endpoint: string, args: readonly unknown[], signal: AbortSignal): AsyncIterable<unknown> {
+  private openScript(
+    endpoint: string,
+    args: readonly unknown[],
+    signal: AbortSignal,
+    carrierUplink: AsyncIterable<unknown> | undefined,
+  ): MockClientStream {
     const script = this.scripts.get(endpoint)
     if (script === undefined) {
       this.logStore.miss(endpoint, 'stream')
       throw new Error(this.noRuleMessage(endpoint))
     }
-    const stream = new MockStream(this.logStore.stream(endpoint, args), signal)
+    let uplink: AsyncIterable<unknown>
+    let owned: HandleUplink | undefined
+    if (carrierUplink === undefined) {
+      owned = new HandleUplink()
+      uplink = owned
+    } else {
+      uplink = carrierUplink
+    }
+    const stream = new MockStream(this.logStore.stream(endpoint, args), signal, uplink, () => { owned?.close() })
     this.live.push(stream)
     this.wakeOpened(endpoint)
     stream.run(script, args)
-    return stream
+    return new MockClientStream(stream, owned)
   }
 
   /** Throw when any request found no rule, naming the endpoints and the registered ones. */
diff --git a/packages/test-support/remote-mock/src/streams.ts b/packages/test-support/remote-mock/src/streams.ts
index 0090087720..5c2093f136 100644
--- a/packages/test-support/remote-mock/src/streams.ts
+++ b/packages/test-support/remote-mock/src/streams.ts
@@ -1,7 +1,40 @@
 /** Stream scripts and the pushable, abort-aware stream a script drives. */
 
+import { isRemoteUplinkItem, type RemoteStreamHandle } from '@deepseek-ai/dsh-typert-protocol'
 import type { StreamRecord } from './log.ts'
 
+/**
+ * Type a fake stream method's result as the handle a generated Client method
+ * returns. The uplink members are inert: a fake built on it drives the downlink only.
+ * @param source - downlink items the fake yields.
+ * @returns a handle that iterates `source`.
+ */
+export function streamHandle<Out, In = never>(source: AsyncIterable<Out>): RemoteStreamHandle<Out, In> {
+  return {
+    [Symbol.asyncIterator]: () => source[Symbol.asyncIterator](),
+    send: () => undefined,
+    end: () => undefined,
+    dispose: () => undefined,
+  }
+}
+
+/** Downlink item type of one generated stream method. */
+type StreamItem<Method> = Method extends (...args: never[]) => RemoteStreamHandle<infer Out, unknown> ? Out : never
+
+/**
+ * Lift a fake stream method written as an async generator function into the
+ * signature of the generated method it stands in for.
+ * @param method - fake taking the method's arguments and yielding its downlink items.
+ * @returns the fake returning {@link streamHandle} of each call.
+ */
+export function streamMethod<Method extends (...args: never[]) => RemoteStreamHandle<unknown, unknown>>(
+  method: (...args: Parameters<Method>) => AsyncIterable<StreamItem<Method>>,
+): Method {
+  const lifted = (...args: Parameters<Method>): RemoteStreamHandle<StreamItem<Method>, unknown> =>
+    streamHandle(method(...args))
+  return lifted as Method
+}
+
 /** Test-side controls over one open stream. */
 export interface StreamHandle {
   /** Queue one item for the consumer. */
@@ -12,6 +45,12 @@ export interface StreamHandle {
   fail(error: Error): void
   /** Aborts when the opening signal aborts or the consumer returns early. */
   readonly signal: AbortSignal
+  /**
+   * Uplink items for the script: the carrier's iterable when the open came
+   * through `rpc.open`, otherwise what the returned handle's `send()` and
+   * `end()` feed.
+   */
+  readonly uplink: AsyncIterable<unknown>
 }
 
 /**
@@ -66,8 +105,15 @@ export class MockStream implements StreamHandle, AsyncIterable<unknown> {
   /**
    * @param record - log entry this stream updates.
    * @param sourceSignal - cancellation from the caller that opened the stream.
+   * @param uplink - the uplink the script reads.
+   * @param release - closes the uplink this stream owns; called once, when the stream settles, is cancelled, or the consumer leaves.
    */
-  constructor(readonly record: StreamRecord, private readonly sourceSignal: AbortSignal) {
+  constructor(
+    readonly record: StreamRecord,
+    private readonly sourceSignal: AbortSignal,
+    readonly uplink: AsyncIterable<unknown>,
+    private readonly release: () => void,
+  ) {
     if (sourceSignal.aborted) this.cancel(sourceSignal.reason)
     else sourceSignal.addEventListener('abort', this.onAbort, { once: true })
   }
@@ -92,6 +138,11 @@ export class MockStream implements StreamHandle, AsyncIterable<unknown> {
     this.settle({ kind: 'fail', error }, 'failed')
   }
 
+  /** The consumer left: cancel the stream and drop what it left. */
+  dispose(): void {
+    this.cancel(new Error(`remote-mock: ${this.record.endpoint} stream disposed`))
+  }
+
   /**
    * Start `script` on this stream.
    * @param script - the registered script.
@@ -151,6 +202,7 @@ export class MockStream implements StreamHandle, AsyncIterable<unknown> {
     this.record.state = state
     this.settled = settled
     this.sourceSignal.removeEventListener('abort', this.onAbort)
+    this.release()
     this.wakeDrained()
     // A pending read exists only while the queue is empty: push() resolves it directly instead of queueing.
     const waiting = this.waiting
@@ -167,6 +219,7 @@ export class MockStream implements StreamHandle, AsyncIterable<unknown> {
       this.waiting = undefined
       this.queue.length = 0
       this.cancellation.abort(reason)
+      this.release()
       waiting?.resolve({ value: undefined, done: true })
     }
     // Whether cancelled or left after the producer settled, the consumer pulls nothing more: drop what it left.
@@ -186,6 +239,96 @@ export class MockStream implements StreamHandle, AsyncIterable<unknown> {
   }
 }
 
+/**
+ * The uplink a direct handle owns: `send()` pushes, `end()` half-closes, and
+ * `close()` ends it and drops unread items once the stream settles, is
+ * cancelled, or the consumer leaves. The script reads it as `StreamHandle.uplink`.
+ */
+export class HandleUplink implements AsyncIterable<unknown> {
+  private readonly items: unknown[] = []
+  private done = false
+  private waiter: ((result: IteratorResult<unknown>) => void) | undefined
+
+  /**
+   * Queues one uplink item for the script, or completes the read waiting for it.
+   * @param item - the item the handle's `send()` carried.
+   * @throws {Error} after `end()`.
+   */
+  push(item: unknown): void {
+    if (this.done) throw new Error('remote-mock: uplink was ended')
+    const waiter = this.waiter
+    this.waiter = undefined
+    if (waiter === undefined) this.items.push(item)
+    else waiter({ value: item, done: false })
+  }
+
+  /** Half-closes the uplink: pending and later reads complete as done; repeated calls are no-ops. */
+  end(): void {
+    if (this.done) return
+    this.done = true
+    this.waiter?.({ value: undefined, done: true })
+    this.waiter = undefined
+  }
+
+  /** Ends the uplink and drops unread items; the owning stream calls it on settle or cancel, the script's iterator on `return()`. */
+  close(): void {
+    this.items.length = 0
+    this.end()
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return {
+      next: () => {
+        if (this.items.length > 0) return Promise.resolve({ value: this.items.shift(), done: false })
+        if (this.done) return Promise.resolve({ value: undefined, done: true })
+        return new Promise((resolve) => { this.waiter = resolve })
+      },
+      return: () => {
+        this.close()
+        return Promise.resolve({ value: undefined, done: true })
+      },
+    }
+  }
+}
+
+/**
+ * The handle a direct `mock.remote` stream call returns, as a generated method
+ * would: iterate it for the script's downlink, `send()` and `end()` feed
+ * `StreamHandle.uplink`, `dispose()` cancels the stream. `send()` applies the
+ * real handle's check, so a non-lossless JSON item throws and a top-level
+ * `undefined` passes. A stream opened through `rpc.open` reads the carrier's
+ * uplink instead, and this handle owns none.
+ */
+export class MockClientStream implements RemoteStreamHandle<unknown, unknown> {
+  /**
+   * @param stream - the script-side stream.
+   * @param uplink - the uplink this handle feeds; absent when the carrier supplied one.
+   */
+  constructor(private readonly stream: MockStream, private readonly uplink: HandleUplink | undefined) {}
+
+  send(item: unknown): void {
+    if (this.uplink === undefined) {
+      throw new Error(`remote-mock: ${this.stream.record.endpoint} uplink belongs to the carrier that opened the stream`)
+    }
+    if (!isRemoteUplinkItem(item)) {
+      throw new Error(`remote-mock: ${this.stream.record.endpoint} uplink item is not a lossless JSON value`)
+    }
+    this.uplink.push(item)
+  }
+
+  end(): void {
+    this.uplink?.end()
+  }
+
+  dispose(): void {
+    this.stream.dispose()
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<unknown> {
+    return this.stream[Symbol.asyncIterator]()
+  }
+}
+
 /**
  * The `Error` a thrown value stands for: itself, or a new Error carrying its string form.
  * @param reason - thrown value.
diff --git a/packages/test-support/remote-mock/tests/proxy-types.client.spec.ts b/packages/test-support/remote-mock/tests/proxy-types.client.spec.ts
index b1880d313f..081408f4b8 100644
--- a/packages/test-support/remote-mock/tests/proxy-types.client.spec.ts
+++ b/packages/test-support/remote-mock/tests/proxy-types.client.spec.ts
@@ -14,6 +14,7 @@ const artifactPath = resolve(import.meta.dirname, '__remote_proxy_artifact.d.ts'
 const protocolPath = resolve(root, 'packages/typert/protocol/src/types.ts')
 const proxyPath = resolve(import.meta.dirname, '../src/remote-proxy.ts')
 const protocolEntry = resolve(import.meta.dirname, '__remote_protocol.d.ts')
+const brandEntry = resolve(root, 'packages/util/brand/src/index.ts')
 const cordisEntry = resolve(import.meta.dirname, '__remote_cordis.d.ts')
 
 function modulePath(path: string): string {
@@ -40,6 +41,7 @@ function compile(source: string, artifact?: string) {
     types: ['node'],
     paths: {
       '@deepseek-ai/cordis': [cordisEntry],
+      '@deepseek-ai/dsh-brand': [brandEntry],
       '@deepseek-ai/dsh-typert-protocol': [protocolEntry],
       '@deepseek-ai/fixture/remote': [artifactPath],
     },
diff --git a/packages/test-support/remote-mock/tests/proxy.client.spec.ts b/packages/test-support/remote-mock/tests/proxy.client.spec.ts
index ba068d70d2..bef18eb4c8 100644
--- a/packages/test-support/remote-mock/tests/proxy.client.spec.ts
+++ b/packages/test-support/remote-mock/tests/proxy.client.spec.ts
@@ -1,9 +1,9 @@
 /** Native namespace mocks shared by local callers and the Connection carrier. */
 import { describe, expect, it, onTestFinished, vi } from 'vitest'
-import { RemoteMock, frames, ok, openStream, type StreamHandle } from '../src/index.ts'
+import { RemoteMock, frames, ok, openStream, streamHandle, type StreamHandle } from '../src/index.ts'
 
 const describeValue = (hasDocument: boolean) => ok({ writable: true, hasDocument, namespaces: [] })
-const baseline = { type: 'baseline' as const, value: { queues: {}, jobs: {}, projections: {} } }
+const baseline = { type: 'baseline' as const, value: { projections: {} } }
 
 async function drain(source: AsyncIterable<unknown>): Promise<unknown[]> {
   const values: unknown[] = []
@@ -230,8 +230,9 @@ describe('RemoteMock.remote stream proxies', () => {
       consumed = true
       yield baseline
     }
-    const native = response()
-    onTestFinished(async () => { await native.return(undefined) })
+    const generator = response()
+    const native = streamHandle(generator)
+    onTestFinished(async () => { await generator.return(undefined) })
     control.mockReturnValueOnce(native)
     const overridden = mock.open('session/control', [], signal)
     expect(overridden).toBe(native)
diff --git a/packages/test-support/remote-mock/tests/rpc.client.spec.ts b/packages/test-support/remote-mock/tests/rpc.client.spec.ts
index 2eb0a620bc..772a5fa6d8 100644
--- a/packages/test-support/remote-mock/tests/rpc.client.spec.ts
+++ b/packages/test-support/remote-mock/tests/rpc.client.spec.ts
@@ -1,8 +1,13 @@
 /** The Connection carrier face: payload forms, streams, unmatched rejections, and abort. */
 import { describe, expect, it } from 'vitest'
-import { RemoteMock, ok, openStream } from '../src/index.ts'
+import { RemoteMock, ok, openStream, type MockClientStream } from '../src/index.ts'
 
 const idle = (): AbortSignal => new AbortController().signal
+const drain = async (source: AsyncIterable<unknown>): Promise<unknown[]> => {
+  const items: unknown[] = []
+  for await (const item of source) items.push(item)
+  return items
+}
 
 describe('RemoteMock.rpc', () => {
   it('calls and opens by endpoint, taking the proxies\' positional args or the Gateway\'s single object', async () => {
@@ -18,6 +23,84 @@ describe('RemoteMock.rpc', () => {
     expect(mock.log.streams('session/control').map(open => open.args)).toEqual([[{ since: 1 }]])
   })
 
+  it('hands the uplink to the script and keeps it out of the logged args', async () => {
+    const mock = RemoteMock.create().stream('job/attach', async (args, stream) => {
+      for await (const item of stream.uplink) stream.push(`${String(args[0])}:${String(item)}`)
+      stream.end()
+    })
+    const uplink = (values: readonly string[]): AsyncIterable<string> => (async function *() { yield* values })()
+
+    await expect(drain(mock.rpc.open!('/api', 'job/attach', { args: ['job-1'] }, idle(), uplink(['a', 'b']))))
+      .resolves.toEqual(['job-1:a', 'job-1:b'])
+    await expect(drain(mock.open('job/attach', ['job-2'], idle(), uplink(['c'])))).resolves.toEqual(['job-2:c'])
+    // A direct open returns the handle a generated method would: its send/end feed the script's uplink.
+    const direct = mock.open('job/attach', ['job-3'], idle()) as MockClientStream
+    direct.send('d')
+    direct.end()
+    direct.end()
+    await expect(drain(direct)).resolves.toEqual(['job-3:d'])
+    expect(() => { direct.send('late') }).toThrow('remote-mock: uplink was ended')
+    const disposed = mock.open('job/attach', ['job-4'], idle()) as MockClientStream
+    disposed.dispose()
+    await expect(drain(disposed)).resolves.toEqual([])
+    expect(mock.log.streams('job/attach').map(open => [open.args, open.state]))
+      .toEqual([[['job-1'], 'ended'], [['job-2'], 'ended'], [['job-3'], 'ended'], [['job-4'], 'cancelled']])
+    const carried = mock.open('job/attach', ['job-5'], idle(), uplink([])) as MockClientStream
+    expect(() => { carried.send('x') }).toThrow('remote-mock: job/attach uplink belongs to the carrier that opened the stream')
+    await expect(drain(carried)).resolves.toEqual([])
+  })
+
+  it('queues items sent before the script reads and drops the rest once it stops reading', async () => {
+    const mock = RemoteMock.create().stream('job/attach', async (args, stream) => {
+      await Promise.resolve()
+      for await (const item of stream.uplink) {
+        stream.push(`${String(args[0])}:${String(item)}`)
+        break
+      }
+      stream.end()
+    })
+    const direct = mock.open('job/attach', ['job-6'], idle()) as MockClientStream
+    direct.send('first')
+    direct.send('second')
+    await expect(drain(direct)).resolves.toEqual(['job-6:first'])
+    expect(() => { direct.send('late') }).toThrow('remote-mock: uplink was ended')
+  })
+
+  it('applies the real handle checks to send and closes the owned uplink with the stream', async () => {
+    const mock = RemoteMock.create()
+      .stream('job/attach', async (args, stream) => {
+        for await (const item of stream.uplink) stream.push(`${String(args[0])}:${String(item)}`)
+        stream.end()
+      })
+      .stream('job/quiet', (args, stream) => {
+        stream.push(String(args[0]))
+        stream.end()
+      })
+    const absent = mock.open('job/attach', ['job-7'], idle()) as MockClientStream
+    absent.send(undefined)
+    expect(() => { absent.send(1n) }).toThrow('remote-mock: job/attach uplink item is not a lossless JSON value')
+    absent.end()
+    await expect(drain(absent)).resolves.toEqual(['job-7:undefined'])
+    // A script that ends the downlink without reading the uplink closes the owned uplink.
+    const quiet = mock.open('job/quiet', ['job-8'], idle()) as MockClientStream
+    await expect(drain(quiet)).resolves.toEqual(['job-8'])
+    expect(() => { quiet.send('late') }).toThrow('remote-mock: uplink was ended')
+    // A consumer that leaves early closes it too, and a script blocked on the uplink wakes.
+    const unblocked = Promise.withResolvers<undefined>()
+    const blocked = RemoteMock.create().stream('job/attach', async (args, stream) => {
+      stream.push(`${String(args[0])}:first`)
+      for await (const item of stream.uplink) stream.push(String(item))
+      unblocked.resolve(undefined)
+    })
+    const left = blocked.open('job/attach', ['job-9'], idle()) as MockClientStream
+    for await (const item of left) {
+      expect(item).toBe('job-9:first')
+      break
+    }
+    await unblocked.promise
+    expect(() => { left.send('late') }).toThrow('remote-mock: uplink was ended')
+  })
+
   it('rejects malformed payloads and unmatched endpoints, logging the miss', async () => {
     const mock = RemoteMock.create()
     await expect(mock.rpc.call('/api', 'a/b', 'bare')).rejects.toThrow('remote-mock: payload of a/b must be { args: unknown[] | object }')
diff --git a/packages/test-support/remote-mock/tests/streams.client.spec.ts b/packages/test-support/remote-mock/tests/streams.client.spec.ts
index ec41ba902f..8dbdf2b018 100644
--- a/packages/test-support/remote-mock/tests/streams.client.spec.ts
+++ b/packages/test-support/remote-mock/tests/streams.client.spec.ts
@@ -1,6 +1,7 @@
 /** Stream scripts, live stream control, cancellation, and the built-in `$events` opening. */
 import { describe, expect, it } from 'vitest'
-import { RemoteMock, frames, openStream } from '../src/index.ts'
+import type { RemoteStreamHandle } from '@deepseek-ai/dsh-typert-protocol'
+import { RemoteMock, frames, openStream, streamHandle, streamMethod } from '../src/index.ts'
 
 const idle = (): AbortSignal => new AbortController().signal
 
@@ -184,6 +185,24 @@ describe('RemoteMock streams', () => {
     expect(mock.modeOf('s/declared')).toBe('stream')
   })
 
+  it('types a fake stream as the generated handle, with inert uplink members', async () => {
+    const handle = streamHandle<string, string>((async function* () {
+      yield 'a'
+      yield 'b'
+    })())
+    handle.send('ignored')
+    handle.end()
+    handle.dispose()
+    await expect(drain(handle)).resolves.toEqual(['a', 'b'])
+
+    const method = streamMethod<(prefix: string, signal?: AbortSignal) => RemoteStreamHandle<string, never>>(
+      async function* (prefix, signal) {
+        yield `${prefix}:${String(signal?.aborted ?? 'none')}`
+      },
+    )
+    await expect(drain(method('hi'))).resolves.toEqual(['hi:none'])
+  })
+
   it('waits for opens with opened(), and answers $events with one ready frame per generation', async () => {
     const mock = RemoteMock.create({ host: { home: '/home/me' } })
     const second = mock.streams.opened('$events', 2)
diff --git a/packages/typert/generator/README.i18n.yaml b/packages/typert/generator/README.i18n.yaml
index 26eafdb018..7b0c085cd5 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: 399e4fe622a785d68452ffeae79e106246941fa1
-README.zh.md: 1fd19fd76ab804013a8741cb90522e9fd3f608d3
+README.md: 9c207574e9bb576a965ab1a91576a3b5a9db397e
+README.zh.md: 9a6fa9e81d7950efb4d4b76df6921bc5a83b6adf
diff --git a/packages/typert/generator/README.md b/packages/typert/generator/README.md
index 399e4fe622..9c207574e9 100644
--- a/packages/typert/generator/README.md
+++ b/packages/typert/generator/README.md
@@ -79,12 +79,14 @@ The generator is built on one separation: extraction and emission are decoupled
 
 ### Analysis and faces
 
-Host and Client are independent TypeScript programs. Direct project references establish compiler-face membership, while `dsh.client` package subpaths establish runtime-face contribution; `package.json#exports` marks every cross-package public boundary, and imports or re-exports are the only cross-face edges. A relative import that resolves inside the referencing package is followed through that module's re-exports until a package specifier appears, so package-local forwarding modules keep their original declaration references; a relative import that resolves into another package fails. `check` mode fails on syntax or semantic diagnostics, missing public annotations, private cross-package references, and reachable declaration merges the model cannot retain losslessly; `write` mode inserts checker-derived annotations and returns a clean check-mode model. Types owned by NPM dependencies remain `external` references instead of being expanded.
+Host and Client are independent TypeScript programs. Direct project references establish compiler-face membership, while `dsh.client` package subpaths establish runtime-face contribution; `package.json#exports` marks every cross-package public boundary, and imports or re-exports are the only cross-face edges. A relative import that resolves inside the referencing package is followed through that module's re-exports until a package specifier appears, so package-local forwarding modules keep their original declaration references; a relative import that resolves into another package fails. `check` mode fails on syntax or semantic diagnostics, missing public annotations, private cross-package references, and reachable declaration merges the model cannot retain losslessly; `write` mode inserts checker-derived annotations and returns a clean check-mode model. Types owned by NPM dependencies remain `external` references instead of being expanded. A stream method's return type may be `Iterable<Out>`, `AsyncIterable<Out>`, or the protocol's `RemoteStream<Out, In>`, recognized by symbol and declaring package like the standard-library wrappers; a second type argument other than `never` yields the descriptor's uplink codec, and the generated Client signature returns `RemoteStreamHandle<Out, In>`.
 
 ### Emission and publication contract
 
 `FaceModelEmitter` emits executable JavaScript containing success-cached Zod schema factories and the `TYPERT` contribution, plus a declaration file whose factories return `z.ZodType<SourceType>` through the package's public export; unsupported Zod projections fail. The Host face with Remote methods additionally emits `typert.remote-client.*` projections of Host Remote contracts for the Client. `WorkspaceTypertGenerator` validates each contributor's `package.json`: `./typert` and `./client/typert` (and `./remote` when Remote methods exist) must point at the exact generated files, and the `files` list must include them.
 
+[Unary binary results](../protocol/README.md) are recognized after generic type resolution. Their codecs validate the byte-array type and JSON metadata without iterating, copying, or freezing the byte payload; generated Client declarations retain the authored metadata and narrow the byte backing to `ArrayBuffer`.
+
 ### Catalog projection
 
 The runtime type closure indexes exported workspace declarations and referenced framework enums. Vendored declarations stay outside business API discovery; their enums remain available when a public result refers to them.
diff --git a/packages/typert/generator/README.zh.md b/packages/typert/generator/README.zh.md
index 1fd19fd76a..9a6fa9e81d 100644
--- a/packages/typert/generator/README.zh.md
+++ b/packages/typert/generator/README.zh.md
@@ -79,12 +79,14 @@ files:
 
 ### 分析与 face
 
-Host 与 Client 是两个独立的 TypeScript 程序。直接项目引用确定编译器 face 的成员归属，`dsh.client` 包子路径则确定运行时 face 的贡献；`package.json#exports` 划定所有跨包公开边界，跨 face 的边只能来自导入或重新导出。解析到本包内部模块的相对导入会沿该模块的重新导出继续追踪，直到出现包说明符，因此包内转发模块保留原始声明引用；解析到其他包的相对导入会失败。`check` 模式遇到语法或语义诊断、缺失的公开类型标注、跨包私有引用，以及模型无法无损保留的可达声明合并时都会失败；`write` 模式插入类型检查器推导出的标注，并返回无诊断的 check 模式模型。NPM 依赖拥有的类型继续以 `external` 引用表示，不会被展开。
+Host 与 Client 是两个独立的 TypeScript 程序。直接项目引用确定编译器 face 的成员归属，`dsh.client` 包子路径则确定运行时 face 的贡献；`package.json#exports` 划定所有跨包公开边界，跨 face 的边只能来自导入或重新导出。解析到本包内部模块的相对导入会沿该模块的重新导出继续追踪，直到出现包说明符，因此包内转发模块保留原始声明引用；解析到其他包的相对导入会失败。`check` 模式遇到语法或语义诊断、缺失的公开类型标注、跨包私有引用，以及模型无法无损保留的可达声明合并时都会失败；`write` 模式插入类型检查器推导出的标注，并返回无诊断的 check 模式模型。NPM 依赖拥有的类型继续以 `external` 引用表示，不会被展开。流方法的返回类型可以是 `Iterable<Out>`、`AsyncIterable<Out>` 或协议包的 `RemoteStream<Out, In>`，后者与标准库包装器一样按符号名与声明所在包识别；第二个类型参数不为 `never` 时产出描述符的上行编解码器，生成的 Client 签名则返回 `RemoteStreamHandle<Out, In>`。
 
 ### 生成与发布约定
 
 `FaceModelEmitter` 输出包含只缓存成功结果的 Zod schema factory 与 `TYPERT` 贡献的可执行 JavaScript，以及把 factory 通过包的公开导出标注为返回 `z.ZodType<SourceType>` 的声明文件；不支持的 Zod 投影会失败。含 Remote 方法的 Host face 还会额外为 Client 生成 Host Remote 约定的 `typert.remote-client.*` 投影。`WorkspaceTypertGenerator` 校验每个贡献方的 `package.json`：`./typert` 与 `./client/typert`（存在 Remote 方法时还有 `./remote`）必须指向精确的生成文件，且 `files` 清单必须包含它们。
 
+[一元二进制结果](../protocol/README.zh.md)在泛型类型解析后被识别。其 codec 校验字节数组类型与 JSON 元数据，不遍历、复制或冻结字节载荷；生成的 Client 声明保留原有元数据类型，并将字节的底层缓冲区收窄为 `ArrayBuffer`。
+
 ### 目录投影
 
 运行时类型闭包索引导出的 workspace 声明和被引用的框架 enum。Vendor 声明不参与业务 API 发现；公共结果引用其中 enum 时，目录仍提供其定义。
diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts
index eebf7fbc29..726828f0ed 100644
--- a/packages/typert/generator/src/analyzer.ts
+++ b/packages/typert/generator/src/analyzer.ts
@@ -1198,7 +1198,17 @@ class FaceAnalyzer {
     }
 
     const mode = invocation.kind === 'direct' ? invocation.mode : undefined
-    const resultType = this.remoteResultType(method, mode)
+    const { result: resultType, uplink: uplinkType } = this.remoteResultType(method, mode)
+    const uplink: InvocationModel['uplink'] = uplinkType === undefined
+      ? undefined
+      : {
+        boundary: this.remoteBoundary(
+          uplinkType,
+          `${registration.name}#${binding.namespace}/${exportedMethod}:uplink`,
+          false,
+          'undefined',
+        ),
+      }
     return {
       id: `${registration.name}#${binding.namespace}/${exportedMethod}`,
       service: binding.service,
@@ -1209,12 +1219,15 @@ class FaceAnalyzer {
       invocation: receiver,
       ...(scope === undefined ? {} : { scope }),
       parameters,
+      ...(uplink === undefined ? {} : { uplink }),
       ...(cancellation === undefined ? {} : { cancellation }),
       result: this.remoteBoundary(
         resultType,
         `${registration.name}#${binding.namespace}/${exportedMethod}:result`,
         false,
         'undefined-or-void',
+        false,
+        mode === undefined,
       ),
       location: this.location(method.name),
     }
@@ -1337,12 +1350,11 @@ class FaceAnalyzer {
           }
           const [property] = argument.properties
           if (property === undefined) this.fail(argument, 'Remote() options must contain exactly mode: "stream"')
-          if (!ts.isPropertyAssignment(property)
-            || memberName(property.name) !== 'mode'
-            || stringLiteralValue(property.initializer) !== 'stream') {
-            this.fail(property, 'Remote() options must contain exactly mode: "stream"')
-          }
-          marker = { kind: 'direct', mode: 'stream' }
+          const mode = ts.isPropertyAssignment(property) && memberName(property.name) === 'mode'
+            ? stringLiteralValue(property.initializer)
+            : undefined
+          if (mode !== 'stream') this.fail(property, 'Remote() options must contain exactly mode: "stream"')
+          marker = { kind: 'direct', mode }
         }
       } else if (ts.isCallExpression(expression)
         && this.isTypeMetaSymbol(expression.expression, 'RemoteScope')) {
@@ -1368,27 +1380,43 @@ class FaceAnalyzer {
     return found
   }
 
-  private remoteResultType(method: ts.MethodDeclaration, mode?: 'stream'): ts.TypeNode {
+  /**
+   * The item types a Remote method's authored return type declares. Unary
+   * methods unwrap `Promise<T>`; stream methods unwrap `Iterable<Out>`,
+   * `AsyncIterable<Out>`, or the protocol's `RemoteStream<Out, In>`, whose
+   * second type argument is the uplink item type unless it is `never`.
+   */
+  private remoteResultType(
+    method: ts.MethodDeclaration,
+    mode?: 'stream',
+  ): { readonly result: ts.TypeNode; readonly uplink?: ts.TypeNode } {
     const authored = this.requiredType(method, method.type, 'return')
     if (ts.isTypeReferenceNode(authored)) {
       const symbol = this.checker.getSymbolAtLocation(authored.typeName)
       const resolved = symbol === undefined ? undefined : this.resolveSymbol(symbol)
-      const resultType = authored.typeArguments?.[0]
-      const wrappers = mode === 'stream' ? ['Iterable', 'AsyncIterable'] : ['Promise']
       const declaration = resolved === undefined ? undefined : preferredDeclaration(resolved)
-      if (resolved !== undefined
-        && wrappers.includes(resolved.name)
-        && resultType !== undefined
-        && authored.typeArguments?.length === 1
-        && declaration !== undefined
-        && isStandardLibraryFile(declaration.getSourceFile().fileName)) {
-        return resultType
+      const [result, uplink] = authored.typeArguments ?? []
+      const arity = authored.typeArguments?.length ?? 0
+      if (resolved !== undefined && declaration !== undefined && result !== undefined) {
+        const standard = isStandardLibraryFile(declaration.getSourceFile().fileName)
+        const wrappers = mode === undefined ? ['Promise'] : ['Iterable', 'AsyncIterable']
+        if (standard && wrappers.includes(resolved.name) && arity === 1) return { result }
+        if (mode !== undefined
+          && resolved.name === 'RemoteStream'
+          && this.isTypeMetaSymbol(authored.typeName, 'RemoteStream')
+          && arity <= 2) {
+          return uplink === undefined || this.isNeverType(uplink) ? { result } : { result, uplink }
+        }
       }
     }
-    if (mode === 'stream') {
-      this.fail(method, 'stream Remote methods must return Iterable<T> or AsyncIterable<T>')
+    if (mode !== undefined) {
+      this.fail(method, 'stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>')
     }
-    return authored
+    return { result: authored }
+  }
+
+  private isNeverType(type: ts.TypeNode): boolean {
+    return (this.checker.getTypeFromTypeNode(type).flags & ts.TypeFlags.Never) !== 0
   }
 
   private isGlobalAbortSignal(type: ts.TypeNode): boolean {
@@ -1485,6 +1513,7 @@ class FaceAnalyzer {
     requireNamed: boolean,
     topLevelAbsence: 'reject' | 'undefined' | 'undefined-or-void' = 'reject',
     optional = false,
+    allowBytes = false,
   ): RemoteBoundaryModel {
     const type = this.convertType(authoredType)
     const declaredType = this.checker.getTypeFromTypeNode(authoredType)
@@ -1493,7 +1522,7 @@ class FaceAnalyzer {
     const resolvedType = optional
       ? this.checker.getNullableType(declaredType, ts.TypeFlags.Undefined)
       : declaredType
-    const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence)
+    const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence, allowBytes)
     const acceptsUndefined = topLevelAbsence !== 'reject' && this.includesRemoteAbsence(resolvedType)
     const rootSymbol = this.namedWorkspaceType(authoredType)
     const imports = new Map<SymbolId, RemoteTypeImportModel>()
@@ -1549,6 +1578,7 @@ class FaceAnalyzer {
     authoredType: ts.TypeNode,
     resolvedType: ts.Type,
     topLevelAbsence: 'reject' | 'undefined' | 'undefined-or-void',
+    allowBytes: boolean,
   ): TypeNodeId {
     this.assertRemoteJsonType(
       resolvedType,
@@ -1556,6 +1586,7 @@ class FaceAnalyzer {
       new Set(),
       topLevelAbsence !== 'reject',
       topLevelAbsence === 'undefined-or-void',
+      allowBytes,
     )
     const completed = new Map<ts.Type, TypeNodeId>()
     const active = new Map<ts.Type, TypeNodeId>()
@@ -1591,6 +1622,9 @@ class FaceAnalyzer {
           return id
         }
         const flags = type.flags
+        if (this.isRemoteByteArray(type)) {
+          return add({ kind: 'reference', name: 'Uint8Array', target: { kind: 'standard', name: 'Uint8Array' }, arguments: [] })
+        }
         if ((flags & ts.TypeFlags.Any) !== 0) return add({ kind: 'keyword', name: 'any' })
         if ((flags & ts.TypeFlags.Unknown) !== 0) return add({ kind: 'keyword', name: 'unknown' })
         if ((flags & ts.TypeFlags.Never) !== 0) return add({ kind: 'keyword', name: 'never' })
@@ -1628,7 +1662,7 @@ class FaceAnalyzer {
         if ((flags & ts.TypeFlags.TypeParameter) !== 0) {
           this.fail(authoredType, 'Remote codec contains an unresolved type parameter')
         }
-        if ((flags & ts.TypeFlags.Object) === 0) {
+        if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) {
           this.fail(
             authoredType,
             `Remote codec type ${this.checker.typeToString(type, authoredType, ts.TypeFormatFlags.NoTruncation)} has no concrete Zod projection`,
@@ -1643,7 +1677,9 @@ class FaceAnalyzer {
             elements: arguments_.map((argument, index) => {
               const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required
               return {
-                type: convert(argument),
+                type: (elementFlags & ts.ElementFlags.Rest) !== 0
+                  ? this.addNode(authoredType, { kind: 'array', element: convert(argument) })
+                  : convert(argument),
                 optional: (elementFlags & ts.ElementFlags.Optional) !== 0,
                 rest: (elementFlags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0,
               }
@@ -1722,6 +1758,7 @@ class FaceAnalyzer {
     active: Set<ts.Type>,
     allowUndefined: boolean,
     allowVoid: boolean,
+    allowBytes = false,
   ): void {
     const flags = type.flags
     if ((flags & ts.TypeFlags.Undefined) !== 0 && allowUndefined) return
@@ -1737,22 +1774,26 @@ class FaceAnalyzer {
       | ts.TypeFlags.BooleanLike
       | ts.TypeFlags.Null
       | ts.TypeFlags.Never)) !== 0) return
+    if (this.isRemoteByteArray(type)) {
+      if (allowBytes) return
+      this.fail(site, 'Remote Uint8Array is only supported in unary results')
+    }
     if (type.isUnion()) {
       for (const member of type.types) {
-        this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid)
+        this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid, allowBytes)
       }
       return
     }
     if (type.isIntersection()) {
       const material = type.types.filter(member => !this.isRemotePhantomConstraint(member))
       if (material.length === 0) this.fail(site, 'Remote boundary contains a symbol-only object')
-      for (const member of material) this.assertRemoteJsonType(member, site, active, false, false)
+      for (const member of material) this.assertRemoteJsonType(member, site, active, false, false, allowBytes)
       return
     }
     if ((flags & ts.TypeFlags.TypeParameter) !== 0) {
       this.fail(site, 'Remote boundary contains an unresolved type parameter')
     }
-    if ((flags & ts.TypeFlags.Object) === 0) {
+    if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) {
       this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`)
     }
     const symbol = type.getSymbol()
@@ -1778,6 +1819,7 @@ class FaceAnalyzer {
             active,
             (elementFlags & ts.ElementFlags.Optional) !== 0,
             false,
+            allowBytes,
           )
         })
         return
@@ -1785,7 +1827,7 @@ class FaceAnalyzer {
       if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
         const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number)
         if (element === undefined) this.fail(site, 'Remote boundary array has no element type')
-        this.assertRemoteJsonType(element, site, active, false, false)
+        this.assertRemoteJsonType(element, site, active, false, false, allowBytes)
         return
       }
       const properties = this.checker.getPropertiesOfType(type)
@@ -1801,19 +1843,26 @@ class FaceAnalyzer {
           active,
           (property.flags & ts.SymbolFlags.Optional) !== 0,
           false,
+          allowBytes,
         )
       }
       for (const info of this.checker.getIndexInfosOfType(type)) {
         if ((info.keyType.flags & ts.TypeFlags.ESSymbolLike) !== 0) {
           this.fail(site, 'Remote boundary contains a symbol index signature')
         }
-        this.assertRemoteJsonType(info.type, site, active, false, false)
+        this.assertRemoteJsonType(info.type, site, active, false, false, allowBytes)
       }
     } finally {
       active.delete(type)
     }
   }
 
+  private isRemoteByteArray(type: ts.Type): boolean {
+    const symbol = type.getSymbol()
+    return symbol?.name === 'Uint8Array'
+      && symbol.declarations?.some(declaration => isStandardLibraryFile(declaration.getSourceFile().fileName)) === true
+  }
+
   private includesRemoteAbsence(type: ts.Type): boolean {
     if ((type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0) return true
     return type.isUnion() && type.types.some(member => this.includesRemoteAbsence(member))
diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts
index 018184d5b5..78907abd5f 100644
--- a/packages/typert/generator/src/emitter.ts
+++ b/packages/typert/generator/src/emitter.ts
@@ -22,6 +22,7 @@ import type {
   TypeNodeModel,
 } from './model.ts'
 import { TypeGraphRenderer } from './renderer.ts'
+import { childTypeNodeIds } from './model.ts'
 
 /** Failure to project a modeled construct into an emitted artifact. */
 export class TypertEmitError extends Error {
@@ -317,12 +318,21 @@ export class FaceModelEmitter {
       lines.push('    },')
     })
     lines.push('  ],')
+    if (invocation.uplink !== undefined) {
+      lines.push('  uplink: {')
+      lines.push(`    codec: ${indent(strictCodec(
+        invocation.uplink.boundary,
+        schemas.boundary(uplinkBoundaryKey(invocation)),
+      ), 4).trimStart()},`)
+      lines.push('  },')
+    }
     if (invocation.cancellation !== undefined) {
       lines.push("  cancellation: { parameter: 'signal' },")
     }
     lines.push(`  result: ${indent(strictCodec(
       invocation.result,
       schemas.boundary(resultBoundaryKey(invocation)),
+      schemas.encoder(resultBoundaryKey(invocation)),
     ), 2).trimStart()},`)
     lines.push(`  sourceLocation: ${JSON.stringify(invocation.location)},`)
     lines.push('}')
@@ -341,10 +351,13 @@ export class FaceModelEmitter {
       })
       grouped.set(imported.specifier, values)
     }
+    // A stream method's Client signature returns the handle; `RemoteStream` names
+    // what the Host method returns.
     const lines = [
       '/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */',
       'import type {',
       '  RemoteResult,',
+      ...packageModel.invocations.some(invocation => invocation.mode === 'stream') ? ['  RemoteStreamHandle,'] : [],
       '  TypertRemoteContribution,',
       '} from \'@deepseek-ai/dsh-typert-protocol\'',
     ]
@@ -355,6 +368,12 @@ export class FaceModelEmitter {
       lines.push(`import type { ${names.join(', ')} } from ${quote(specifier)}`)
     }
     lines.push('')
+    if (packageModel.invocations.some(invocation => containsBytes(this.renderer, invocation.result.codecType))) {
+      lines.push('type RemoteDecoded<Value> = Value extends Uint8Array ? Uint8Array<ArrayBuffer>')
+      lines.push('  : Value extends string | number | boolean | null | undefined ? Value')
+      lines.push('  : { [Key in keyof Value]: RemoteDecoded<Value[Key]> }')
+      lines.push('')
+    }
     lines.push('declare module \'@deepseek-ai/dsh-typert-protocol\' {')
     const direct = packageModel.invocations.filter(invocation => invocation.invocation.kind === 'direct')
     const scoped = packageModel.invocations.filter(invocation =>
@@ -467,9 +486,15 @@ export class FaceModelEmitter {
       !scoped || invocation.invocation.kind === 'context' || parameter.wire !== invocation.scope?.wire).map(parameter =>
       `${safeIdentifier(parameter.wire)}${parameter.optional === true ? '?' : ''}: ${this.renderer.renderType(parameter.boundary.type, referenceNames)}`)
     if (invocation.cancellation !== undefined) parameters.push('signal?: AbortSignal')
-    const result = this.renderer.renderType(invocation.result.type, referenceNames)
+    const authoredResult = this.renderer.renderType(invocation.result.type, referenceNames)
+    const result = containsBytes(this.renderer, invocation.result.codecType)
+      ? `RemoteDecoded<${authoredResult}>`
+      : authoredResult
     if (invocation.mode === 'stream') {
-      return `(${parameters.join(', ')}) => AsyncIterable<${result}>`
+      const uplink = invocation.uplink === undefined
+        ? 'never'
+        : this.renderer.renderType(invocation.uplink.boundary.type, referenceNames)
+      return `(${parameters.join(', ')}) => RemoteStreamHandle<${result}, ${uplink}>`
     }
     // The unary Client Remote face delivers the carrier's outcome, so every
     // generated consumer signature resolves to a result the caller reads.
@@ -505,6 +530,7 @@ interface SchemaArtifact {
   readonly definitions: readonly string[]
   readonly exports: readonly SchemaExport[]
   boundary(key: string): string
+  encoder(key: string): string | undefined
 }
 
 interface BoundarySchemaRoot {
@@ -512,6 +538,118 @@ interface BoundarySchemaRoot {
   readonly type: TypeNodeId
 }
 
+class ResultEncoderEmitter {
+  private readonly names = new Map<TypeNodeId, string>()
+  private readonly bodies = new Map<TypeNodeId, string>()
+
+  constructor(private readonly renderer: TypeGraphRenderer) {}
+
+  reference(id: TypeNodeId): string | undefined {
+    if (!containsBytes(this.renderer, id)) return undefined
+    const existing = this.names.get(id)
+    if (existing !== undefined) return existing
+    const name = `$encode${this.names.size}`
+    this.names.set(id, name)
+    const node = this.renderer.node(id)
+    const container = node.kind === 'object' || node.kind === 'array' || node.kind === 'tuple'
+    const body = container || node.kind === 'union' || node.kind === 'intersection'
+      ? `return $resultContainer(value, path, ancestors, value => {\n${indent(this.body(id), 2)}\n}, ${container})`
+      : this.body(id)
+    this.bodies.set(id, `const ${name} = (value, writeBytes, path, ancestors) => {\n${indent(body, 2)}\n}`)
+    return name
+  }
+
+  definitions(): string[] {
+    return this.bodies.size === 0 ? [] : [RESULT_SNAPSHOT, ...this.bodies.values()]
+  }
+
+  private call(id: TypeNodeId, value: string, path = 'path'): string {
+    const reference = this.reference(id)
+    return reference === undefined ? value : `${reference}(${value}, writeBytes, ${path}, ancestors)`
+  }
+
+  private body(id: TypeNodeId): string {
+    const node = this.renderer.node(id)
+    switch (node.kind) {
+      case 'reference': {
+        if (node.target.kind === 'standard' && node.target.name === 'Uint8Array') {
+          return 'return value instanceof Uint8Array ? writeBytes(value, path) : value'
+        }
+        if (node.target.kind === 'declaration') {
+          const type = this.renderer.declaration(node.target.symbol).type
+          if (type !== undefined) return `return ${this.call(type, 'value')}`
+        }
+        break
+      }
+      case 'union':
+      case 'intersection': return [
+        ...node.types.filter(type => containsBytes(this.renderer, type)).map(type => `value = ${this.call(type, 'value')}`),
+        'return value',
+      ].join('\n')
+      case 'array': return [
+        'if (!Array.isArray(value)) return value',
+        `for (let index = 0; index < value.length; index++) value[index] = ${this.call(node.element, 'value[index]', '[...path, index]')}`,
+        'return value',
+      ].join('\n')
+      case 'tuple': {
+        const lines = ['if (!Array.isArray(value)) return value']
+        for (const [index, element] of node.elements.entries()) {
+          if (!containsBytes(this.renderer, element.type)) continue
+          if (element.rest) {
+            const rest = this.renderer.node(element.type)
+            if (rest.kind !== 'array') break
+            lines.push(`for (let index = ${index}; index < value.length; index++) value[index] = ${this.call(rest.element, 'value[index]', '[...path, index]')}`)
+          } else {
+            lines.push(`if (value.length > ${index}) value[${index}] = ${this.call(element.type, `value[${index}]`, `[...path, ${index}]`)}`)
+          }
+        }
+        return [...lines, 'return value'].join('\n')
+      }
+      case 'object': {
+        const lines = ["if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Uint8Array) return value"]
+        for (const member of node.members) {
+          if (member.kind === 'property' && containsBytes(this.renderer, member.type)) {
+            const key = quote(member.name)
+            lines.push(`if (Object.hasOwn(value, ${key})) value[${key}] = ${this.call(member.type, `value[${key}]`, `[...path, ${key}]`)}`)
+          } else if (member.kind === 'index' && containsBytes(this.renderer, member.signature.returns)) {
+            lines.push(`for (const key of Object.keys(value)) value[key] = ${this.call(member.signature.returns, 'value[key]', '[...path, key]')}`)
+          }
+        }
+        return [...lines, 'return value'].join('\n')
+      }
+      default: break
+    }
+    throw new TypertEmitError(`typert result encoder: ${node.kind} has no binary field projection`)
+  }
+}
+
+const RESULT_SNAPSHOT = `const $resultSnapshot = (input, path) => {
+  if (input === null || typeof input !== 'object' || input instanceof Uint8Array) return input
+  const toJSON = input.toJSON
+  const value = typeof toJSON === 'function' ? toJSON.call(input, path.at(-1)?.toString() ?? 'value') : input
+  if (value === null || typeof value !== 'object' || value instanceof Uint8Array) return value
+  if (Array.isArray(value)) {
+    const items = []
+    for (let index = 0, length = value.length; index < length; index++) items.push(value[index])
+    return items
+  }
+  const fields = {}
+  for (const key of Object.keys(value)) {
+    const item = key === 'toJSON' && value === input ? toJSON : value[key]
+    if (key === 'toJSON' && typeof item === 'function') continue
+    Object.defineProperty(fields, key, { value: item, enumerable: true, writable: true, configurable: true })
+  }
+  return fields
+}
+const $resultContainer = (input, path, ancestors, project, snapshot) => {
+  if (input === null || typeof input !== 'object') return project(input)
+  const owner = !ancestors.has(input)
+  if (!owner && ancestors.get(input) !== path.length) throw new TypeError('Remote result contains a circular object')
+  if (owner) ancestors.set(input, path.length)
+  try { return project(snapshot ? $resultSnapshot(input, path) : input) }
+  finally { if (owner) ancestors.delete(input) }
+}`
+
 class SchemaEmitter {
   private readonly names = new Map<SymbolId, string>()
   private readonly boundaryNames = new Map<string, string>()
@@ -555,10 +693,15 @@ class SchemaEmitter {
 
   emit(): SchemaArtifact {
     const definitions = this.declarations.map(declaration => this.declarationDefinition(declaration))
+    const encoder = new ResultEncoderEmitter(this.renderer)
+    const encoders = new Map<string, string>()
     for (const boundary of this.boundaries) {
+      const encode = encoder.reference(boundary.type)
+      if (encode !== undefined) encoders.set(boundary.key, encode)
       const name = this.boundaryName(boundary.key)
       definitions.push(`let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.typeSchema(boundary.type)})`)
     }
+    definitions.push(...encoder.definitions())
     const exports = this.schemas.map((model): SchemaExport => ({
       model,
       exportName: safeIdentifier(model.export.name),
@@ -568,6 +711,7 @@ class SchemaEmitter {
       definitions,
       exports,
       boundary: key => this.boundaryName(key),
+      encoder: key => encoders.get(key),
     }
   }
 
@@ -685,6 +829,7 @@ class SchemaEmitter {
           return `z.record(${this.typeSchema(key, substitutions)}, ${this.typeSchema(value, substitutions)})`
         }
         case 'Date': return 'z.date()'
+        case 'Uint8Array': return 'z.instanceof(Uint8Array)'
         default: this.fail(node.name, `standard type ${node.target.name} has no Zod projection`)
       }
     }
@@ -759,8 +904,11 @@ class SchemaEmitter {
         continue
       }
       if (member.kind !== 'property') this.fail(subject, `${member.kind} member ${member.name} is not data-schema projectable`)
+      // Freezing a union may freeze its populated Uint8Array member.
+      const schema = this.readonly(this.typeSchema(member.type, substitutions),
+        member.readonly && !containsBytes(this.renderer, member.type, false))
       const property = this.describe(
-        this.optional(this.readonly(this.typeSchema(member.type, substitutions), member.readonly), member.optional),
+        this.optional(schema, member.optional),
         member,
       )
       properties.push(`${quote(member.jsonName ?? member.name)}: ${property}`)
@@ -852,6 +1000,9 @@ function invocationBoundaryRoots(invocations: readonly InvocationModel[]): Bound
     invocation.parameters.forEach((parameter, index) => {
       result.push({ key: parameterBoundaryKey(invocation, index), type: parameter.boundary.codecType })
     })
+    if (invocation.uplink !== undefined) {
+      result.push({ key: uplinkBoundaryKey(invocation), type: invocation.uplink.boundary.codecType })
+    }
     result.push({ key: resultBoundaryKey(invocation), type: invocation.result.codecType })
   }
   return result
@@ -861,6 +1012,10 @@ function contextBoundaryKey(invocation: InvocationModel): string {
   return `${invocation.id}:context`
 }
 
+function uplinkBoundaryKey(invocation: InvocationModel): string {
+  return `${invocation.id}:uplink`
+}
+
 function parameterBoundaryKey(invocation: InvocationModel, index: number): string {
   return `${invocation.id}:parameter:${String(index)}`
 }
@@ -869,12 +1024,40 @@ function resultBoundaryKey(invocation: InvocationModel): string {
   return `${invocation.id}:result`
 }
 
-function strictCodec(boundary: RemoteBoundaryModel, schema: string): string {
+function containsBytes(
+  renderer: TypeGraphRenderer,
+  id: TypeNodeId,
+  nested = true,
+  visited = new Set<TypeNodeId>(),
+): boolean {
+  if (visited.has(id)) return false
+  visited.add(id)
+  const node = renderer.node(id)
+  if (node.kind === 'reference') {
+    if (node.target.kind === 'standard' && node.target.name === 'Uint8Array') return true
+    if (node.target.kind === 'declaration') {
+      const declaration = renderer.declaration(node.target.symbol)
+      if (declaration.type !== undefined && containsBytes(renderer, declaration.type, nested, visited)) return true
+    }
+    if (!nested) return false
+  }
+  if (!nested && node.kind !== 'reference' && node.kind !== 'parenthesized'
+    && node.kind !== 'union' && node.kind !== 'intersection') return false
+  if (node.kind === 'object' && node.members.some(member =>
+    containsBytes(renderer, member.kind === 'property' ? member.type : member.signature.returns, nested, visited))) return true
+  return childTypeNodeIds(node).some(child => containsBytes(renderer, child, nested, visited))
+}
+
+function strictCodec(boundary: RemoteBoundaryModel, schema: string, encoder?: string): string {
   return [
     '{',
     '  mode: \'strict\',',
     `  typeSymbol: ${quote(boundary.typeSymbol)},`,
     `  create: ${schema},`,
+    ...(encoder === undefined ? [] : [
+      `  decode: value => ${schema}().parse(value),`,
+      `  encode: (value, writeBytes) => ${encoder}(value, writeBytes, [], new Map()),`,
+    ]),
     '}',
   ].join('\n')
 }
@@ -894,6 +1077,7 @@ function remoteImports(invocations: readonly InvocationModel[]): RemoteTypeImpor
   for (const invocation of invocations) {
     if (invocation.invocation.kind === 'context') add(invocation.invocation.boundary)
     for (const parameter of invocation.parameters) add(parameter.boundary)
+    if (invocation.uplink !== undefined) add(invocation.uplink.boundary)
     add(invocation.result)
   }
   return [...imports.values()].sort((left, right) =>
@@ -901,7 +1085,13 @@ function remoteImports(invocations: readonly InvocationModel[]): RemoteTypeImpor
 }
 
 function allocateRemoteImportNames(imports: readonly RemoteTypeImportModel[]): ReadonlyMap<SymbolId, string> {
-  const used = new Set(['TypertRemoteContribution', 'TYPERT_REMOTE'])
+  const used = new Set([
+    'RemoteDecoded',
+    'RemoteResult',
+    'RemoteStreamHandle',
+    'TypertRemoteContribution',
+    'TYPERT_REMOTE',
+  ])
   const names = new Map<SymbolId, string>()
   for (const imported of imports) {
     const base = safeIdentifier(imported.name)
diff --git a/packages/typert/generator/src/model.ts b/packages/typert/generator/src/model.ts
index 477c4368c4..ba88936e26 100644
--- a/packages/typert/generator/src/model.ts
+++ b/packages/typert/generator/src/model.ts
@@ -145,6 +145,10 @@ export interface InvocationModel {
     readonly wire: string
   }
   readonly parameters: readonly InvocationParameterModel[]
+  /** Per-item boundary of the Client uplink, from the `In` type argument of `RemoteStream<Out, In>`; absent when the method reads none. */
+  readonly uplink?: {
+    readonly boundary: RemoteBoundaryModel
+  }
   readonly cancellation?: {
     readonly parameter: 'signal'
   }
diff --git a/packages/typert/generator/tests/fixtures/remote-model/typert-protocol.d.ts b/packages/typert/generator/tests/fixtures/remote-model/typert-protocol.d.ts
index 37c741915c..5bd9db5755 100644
--- a/packages/typert/generator/tests/fixtures/remote-model/typert-protocol.d.ts
+++ b/packages/typert/generator/tests/fixtures/remote-model/typert-protocol.d.ts
@@ -36,6 +36,14 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
     readonly descriptors: readonly unknown[]
   }
 
+  export type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly uplinkItem?: In }
+
+  export interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+    send(item: In): void
+    end(): void
+    dispose(): void
+  }
+
   export abstract class TypertRemoteService {
     readonly typertRemote: {
       readonly service: TypertRemoteService
diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts
index 635e12d334..e8e69be85f 100644
--- a/packages/typert/generator/tests/remote-model.spec.ts
+++ b/packages/typert/generator/tests/remote-model.spec.ts
@@ -15,7 +15,7 @@ function normalizedPath(path: string): string {
 }
 
 interface RuntimeSchema {
-  safeParse(value: unknown): { readonly success: boolean }
+  safeParse(value: unknown): { readonly success: boolean; readonly data?: unknown }
 }
 
 interface RuntimeDescriptor {
@@ -27,7 +27,14 @@ interface RuntimeDescriptor {
     readonly acceptsUndefined?: true
     readonly codec: { readonly create: () => RuntimeSchema }
   }[]
-  readonly result: { readonly create: () => RuntimeSchema }
+  readonly uplink?: {
+    readonly codec: { readonly create: () => RuntimeSchema }
+  }
+  readonly result: {
+    readonly create: () => RuntimeSchema
+    readonly decode?: (value: unknown) => unknown
+    readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown
+  }
 }
 
 interface RuntimeRemoteModule {
@@ -48,6 +55,234 @@ afterEach(() => {
 })
 
 describe('Remote model generation', { timeout: 60_000 }, () => {
+  it('projects a generic binary result without copying or freezing its bytes', async () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/types.ts', source => `${source}\nexport type BinaryFile<Data extends Uint8Array = Uint8Array> = {\n  readonly data: Data\n} & { readonly size: number }\n`)
+    editFile(root, 'packages/remote/src/index.ts', source => `import type { BinaryFile } from './types.ts'\n${source.replace(
+      '\n}\n\nexport type {',
+      '\n  @Remote\n  bytes(): BinaryFile { return { data: new Uint8Array([0, 255]), size: 2 } }\n}\n\nexport type {',
+    )}`)
+    const [artifact] = new WorkspaceTypertGenerator(root).generate()
+    expect(artifact?.js).not.toContain('binaryResult')
+    expect(artifact?.remote?.dts).toContain('Promise<RemoteResult<RemoteDecoded<BinaryFile>>>')
+    const generated = await import(`data:text/javascript,${encodeURIComponent(
+      (artifact?.remote?.js ?? '').replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`),
+    )}`) as RuntimeRemoteModule
+    const descriptor = generated.TYPERT_REMOTE.descriptors.find(invocation => invocation.id.endsWith('/bytes'))
+    expect(descriptor?.result.decode).toBeTypeOf('function')
+    if (descriptor === undefined) throw new Error('binary descriptor missing')
+    const schema = descriptor.result.create()
+    for (const data of [new Uint8Array(), new Uint8Array([0, 128, 255]), new Uint8Array(new SharedArrayBuffer(3))]) {
+      const parsed = schema.safeParse({ data, size: data.length })
+      expect(parsed.success).toBe(true)
+      expect((parsed.data as { readonly data: Uint8Array }).data).toBe(data)
+      expect(Object.isFrozen(data)).toBe(false)
+    }
+    expect(schema.safeParse({ data: 'AP8=', size: 2 }).success).toBe(false)
+    expect(schema.safeParse({ data: [0, 255], size: 2 }).success).toBe(false)
+    expect(schema.safeParse({ data: new Uint8Array(), size: '0' }).success).toBe(false)
+    expect(schema.safeParse({ size: 0 }).success).toBe(false)
+    assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root, `
+async function readBytes() {
+  const result = await ctx.remote.goals.bytes()
+  if (!result.ok) return
+  const data: Uint8Array<ArrayBuffer> = result.value.data
+  new Blob([data])
+  // @ts-expect-error binary results do not carry base64 strings.
+  const base64: string = result.value.data
+  // @ts-expect-error the Client bytes have ordinary ArrayBuffer backing.
+  const shared: Uint8Array<SharedArrayBuffer> = result.value.data
+  void base64
+  void shared
+}
+void readBytes
+`)
+  })
+
+  it.each([
+    ['parameter', '@Remote\n  bytes(data: Uint8Array): number { return data.length }'],
+    ['nested parameter', '@Remote\n  bytes(files: { content: Uint8Array }[]): number { return files.length }'],
+    ['binary stream', "@Remote({ mode: 'stream' })\n  async *bytes(): AsyncIterable<{ data: Uint8Array }> { throw new Error() }"],
+  ])('rejects unsupported binary %s', (_name, method) => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace(
+      '\n}\n\nexport type {', `\n  ${method}\n}\n\nexport type {`,
+    ))
+    expect(() => new WorkspaceTypertGenerator(root).generate())
+      .toThrow('Remote Uint8Array is only supported in unary results')
+  })
+
+  it.each([
+    ['undefined data', '{ data: Uint8Array | undefined }', 'Remote boundary contains non-JSON type undefined'],
+    ['unconstrained metadata', '{ data: Uint8Array; meta: unknown }', 'Remote boundary contains unconstrained unknown data'],
+  ])('rejects binary results with %s', (_name, type, message) => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace(
+      '\n}\n\nexport type {', `\n  @Remote\n  bytes(): ${type} { throw new Error() }\n}\n\nexport type {`,
+    ))
+    expect(() => new WorkspaceTypertGenerator(root).generate()).toThrow(message)
+  })
+
+  it('decodes recursive objects, arrays, tuples, unions and root bytes by their field types', async () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/types.ts', source => `${source}
+declare const fileNameBrand: unique symbol
+export type FileName = string & { readonly [fileNameBrand]: true }
+export type LinkedBytes = { readonly content: Uint8Array } & { readonly next?: LinkedBytes }
+export interface BinaryTree {
+  readonly name: FileName
+  readonly content?: Uint8Array | null
+  readonly files: readonly BinaryTree[]
+  readonly pair: readonly [Uint8Array, { readonly raw: Uint8Array }?]
+  readonly tail: readonly [string, ...Uint8Array[]]
+  readonly choice: Uint8Array | { readonly preview: Uint8Array }
+  readonly variants: ({ readonly content: Uint8Array } & { readonly content: Uint8Array; readonly size: number })[]
+  readonly chunks: Readonly<Record<string, Uint8Array>>
+}
+`)
+    editFile(root, 'packages/remote/src/index.ts', source => `import type { BinaryTree, LinkedBytes } from './types.ts'\n${source.replace(
+      '\n}\n\nexport type {', `
+  @Remote
+  tree(): BinaryTree { throw new Error() }
+  @Remote
+  linked(): LinkedBytes { throw new Error() }
+  @Remote
+  raw(): Uint8Array { throw new Error() }
+  @Remote
+  nullable(): Uint8Array | null { throw new Error() }
+  @Remote
+  maybe(): Uint8Array | void { throw new Error() }
+  @Remote
+  array(): readonly Uint8Array[] { throw new Error() }
+  @Remote
+  envelope(): { readonly content?: Uint8Array; readonly metadata: { readonly title: string } } { throw new Error() }
+  @Remote
+  overlap(): { content: Uint8Array } | { content: Uint8Array; title: string } { throw new Error() }
+  @Remote
+  objectOrBytes(): { content: Uint8Array } | Uint8Array<SharedArrayBuffer> { throw new Error() }
+}\n\nexport type {`,
+    )}`)
+    const [artifact] = new WorkspaceTypertGenerator(root).generate()
+    const generated = await import(`data:text/javascript,${encodeURIComponent(
+      (artifact?.remote?.js ?? '').replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`),
+    )}`) as RuntimeRemoteModule
+    const codec = (method: string) => {
+      const descriptor = generated.TYPERT_REMOTE.descriptors.find(item => item.id.endsWith(`/${method}`))
+      if (descriptor === undefined) throw new Error(`descriptor missing: ${method}`)
+      return descriptor.result
+    }
+    const content = new Uint8Array([128, 255])
+    const leaf = { name: 'leaf', files: [], pair: [content], tail: ['parts', content], choice: content, variants: [], chunks: {} }
+    const value = {
+      ...leaf, content, files: [{ ...leaf, content: null }], pair: [content, { raw: content }],
+      choice: { preview: content }, variants: [{ content, size: 2 }], chunks: { 'a.b/c': content },
+    }
+    expect(codec('tree').decode?.(value)).toEqual(value)
+    const parsed = codec('tree').decode?.(value) as typeof value
+    expect(parsed.content).toBe(content)
+    expect(Object.isFrozen(parsed.files)).toBe(true)
+    expect(Object.isFrozen(parsed.pair)).toBe(true)
+    expect(parsed.pair[0]).toBe(content)
+    expect(parsed.variants[0]?.content).toBe(content)
+    expect(parsed.tail[1]).toBe(content)
+    expect(Object.isFrozen(content)).toBe(false)
+    expect(codec('tree').decode?.(leaf)).toEqual(leaf)
+    expect(() => codec('tree').decode?.({ ...value, files: [{ ...leaf, content: 'base64' }] })).toThrow()
+    expect(() => codec('tree').decode?.({ ...value, variants: [{ content, size: '2' }] })).toThrow()
+    expect(codec('raw').decode?.(content)).toBe(content)
+    expect(codec('nullable').decode?.(null)).toBe(null)
+    expect(codec('nullable').decode?.(content)).toBe(content)
+    expect(codec('maybe').decode?.(undefined)).toBeUndefined()
+    expect(codec('maybe').decode?.(content)).toBe(content)
+    expect(() => codec('raw').decode?.([128, 255])).toThrow()
+    expect(codec('array').decode?.([content])).toEqual([content])
+    expect((codec('array').decode?.([content]) as Uint8Array[])[0]).toBe(content)
+    expect(codec('create').decode).toBeUndefined()
+    expect(codec('create').encode).toBeUndefined()
+    const attachments: { bytes: Uint8Array; path: readonly (string | number)[] }[] = []
+    const writeBytes = (bytes: Uint8Array, path: readonly (string | number)[]): null => {
+      attachments.push({ bytes, path })
+      return null
+    }
+    const metadata = codec('tree').encode?.(value, writeBytes) as typeof value
+    expect(attachments.map(item => item.path)).toEqual([
+      ['content'], ['files', 0, 'pair', 0], ['files', 0, 'tail', 1], ['files', 0, 'choice'],
+      ['pair', 0], ['pair', 1, 'raw'], ['tail', 1], ['choice', 'preview'],
+      ['variants', 0, 'content'], ['chunks', 'a.b/c'],
+    ])
+    expect(attachments.every(item => item.bytes === content)).toBe(true)
+    expect(metadata.content).toBeNull()
+    expect(metadata.files[0]?.content).toBeNull()
+    expect(metadata.variants[0]?.content).toBeNull()
+    expect(value.content).toBe(content)
+    attachments.length = 0
+    expect(codec('overlap').encode?.({ content, title: 'image' }, writeBytes)).toEqual({ content: null, title: 'image' })
+    expect(attachments).toEqual([{ bytes: content, path: ['content'] }])
+    attachments.length = 0
+    const augmented = Object.assign(new Uint8Array(new SharedArrayBuffer(1)).fill(127), { content })
+    expect(codec('objectOrBytes').encode?.(augmented, writeBytes)).toBeNull()
+    expect(augmented.content).toBe(content)
+    expect(attachments).toEqual([{ bytes: augmented, path: [] }])
+    attachments.length = 0
+    expect(codec('raw').encode?.(content, writeBytes)).toBeNull()
+    expect(attachments).toEqual([{ bytes: content, path: [] }])
+    expect(codec('maybe').encode?.(undefined, writeBytes)).toBeUndefined()
+    const circular: { files: unknown[] } = { ...leaf, files: [] }
+    circular.files.push(circular)
+    expect(() => codec('tree').encode?.(circular, writeBytes)).toThrow('circular object')
+    const linked: { content: Uint8Array; next?: unknown } = { content }
+    linked.next = linked
+    expect(() => codec('linked').encode?.(linked, writeBytes)).toThrow('circular object')
+    let metadataReads = 0
+    let contentReads = 0
+    const opaque = { get title() { metadataReads++; return 'image' } }
+    const optional = { get content() { contentReads++; return undefined }, metadata: opaque }
+    const absent = codec('envelope').encode?.(optional, writeBytes) as typeof optional
+    expect(absent.metadata).toBe(opaque)
+    expect(metadataReads).toBe(0)
+    expect(JSON.stringify(absent)).toBe('{"metadata":{"title":"image"}}')
+    expect(contentReads).toBe(1)
+    expect(metadataReads).toBe(1)
+    let jsonCalls = 0
+    const projected = codec('envelope').encode?.({ toJSON(key: string) {
+      jsonCalls++
+      expect(key).toBe('value')
+      return { content, metadata: { title: 'image' } }
+    } }, writeBytes)
+    expect(JSON.stringify(projected)).toBe('{"content":null,"metadata":{"title":"image"}}')
+    expect(jsonCalls).toBe(1)
+    const dictionary = codec('tree').encode?.({
+      ...leaf, chunks: Object.fromEntries([['__proto__', content]]),
+    }, writeBytes) as typeof value
+    expect(Object.hasOwn(dictionary.chunks, '__proto__')).toBe(true)
+    expect((dictionary.chunks as Record<string, unknown>)['__proto__']).toBeNull()
+    assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root, `
+import type { BinaryTree, FileName } from '@fixture/remote/types'
+async function binaryTree() {
+  const result = await ctx.remote.goals.tree()
+  if (!result.ok) return
+  const tree: BinaryTree = result.value
+  const name: FileName = result.value.name
+  const leaf = result.value.files[0]!
+  if (leaf.content) new Blob([leaf.content])
+  const pair: readonly [Uint8Array<ArrayBuffer>, { readonly raw: Uint8Array<ArrayBuffer> }?] = leaf.pair
+  const choice: Uint8Array<ArrayBuffer> | { readonly preview: Uint8Array<ArrayBuffer> } = leaf.choice
+  const chunk: Uint8Array<ArrayBuffer> = leaf.chunks['file']!
+  // @ts-expect-error array readonly modifier is preserved.
+  result.value.files.push(leaf)
+  // @ts-expect-error property readonly modifier is preserved.
+  result.value.name = name
+  const raw = await ctx.remote.goals.raw()
+  if (raw.ok) new Blob([raw.value])
+  const maybe: Promise<RemoteResult<Uint8Array<ArrayBuffer> | void>> = ctx.remote.goals.maybe()
+  const absent = await maybe
+  if (absent.ok && absent.value !== undefined) new Blob([absent.value])
+  void tree; void pair; void choice; void chunk
+}
+void binaryTree
+`)
+  })
+
   it('discovers a Remote-only package and emits strict direct and Context descriptors', async () => {
     const generator = new WorkspaceTypertGenerator(fixtureRoot)
 
@@ -142,7 +377,7 @@ describe('Remote model generation', { timeout: 60_000 }, () => {
       "'agent:goals/rename': (request: RenameGoalRequest) => Promise<RemoteResult<RenameGoalResult>>",
     )
     expect(artifact?.remote?.dts).toContain(
-      "'goals/watch': (agentId: AgentId, signal?: AbortSignal) => AsyncIterable<CreateGoalResult>",
+      "'goals/watch': (agentId: AgentId, signal?: AbortSignal) => RemoteStreamHandle<CreateGoalResult, never>",
     )
 
     const remoteJs = artifact?.remote?.js
@@ -219,6 +454,105 @@ export type {`,
     expect(labelled?.parameters[1]?.codec.create().safeParse(7).success).toBe(false)
   })
 
+  it('models RemoteStream return types with an uplink boundary and renders them on consumers', async () => {
+    const root = copyFixture()
+    editFile(root, 'packages/remote/src/index.ts', source => source
+      .replace(
+        "import { TypertRemoteService, Remote, RemoteScope } from '@deepseek-ai/dsh-typert-protocol'",
+        "import { TypertRemoteService, Remote, RemoteScope, type RemoteStream } from '@deepseek-ai/dsh-typert-protocol'",
+      )
+      .replace(
+        "  @Remote({ mode: 'stream' })\n  async *watch",
+        `  @Remote({ mode: 'stream' })
+  async *attach(agent: Agent, signal: AbortSignal): RemoteStream<CreateGoalResult, CreateGoalRequest> {
+    signal.throwIfAborted()
+    yield { ref: agent.id }
+  }
+
+  @Remote({ mode: 'stream' })
+  async *tail(): RemoteStream<string> {
+    yield 'tail'
+  }
+
+  @Remote({ mode: 'stream' })
+  async *silent(): RemoteStream<string, never> {
+    yield 'silent'
+  }
+
+  @Remote({ mode: 'stream' })
+  async *watch`,
+      ))
+
+    const model = remotePackage(root)
+    const attach = model.invocations.find(invocation => invocation.method === 'attach')
+    expect(attach).toMatchObject({
+      id: '@fixture/remote#goals/attach',
+      mode: 'stream',
+      invocation: { kind: 'direct' },
+      scope: { context: 'agent', wire: 'agentId' },
+      parameters: [{ name: 'agent', wire: 'agentId', source: 'lookup', lookup: 'agent' }],
+      uplink: { boundary: { typeSymbol: '@fixture/remote/types#CreateGoalRequest' } },
+      cancellation: { parameter: 'signal' },
+      result: { typeSymbol: '@fixture/remote/types#CreateGoalResult' },
+    })
+    for (const method of ['tail', 'silent']) {
+      const modeled = model.invocations.find(invocation => invocation.method === method)
+      expect(modeled).toMatchObject({ mode: 'stream', parameters: [] })
+      expect(modeled?.uplink).toBeUndefined()
+      expect(modeled?.cancellation).toBeUndefined()
+    }
+
+    const [artifact] = new WorkspaceTypertGenerator(root).generate()
+    expect(artifact?.remote?.dts).toContain(
+      "  RemoteStreamHandle,\n  TypertRemoteContribution,\n} from '@deepseek-ai/dsh-typert-protocol'",
+    )
+    expect(artifact?.remote?.dts).toContain("declare module '@deepseek-ai/dsh-typert-protocol' {")
+    expect(artifact?.remote?.dts).toContain(
+      "'goals/attach': (agentId: AgentId, signal?: AbortSignal) => RemoteStreamHandle<CreateGoalResult, CreateGoalRequest>",
+    )
+    expect(artifact?.remote?.dts).toContain(
+      "'agent:goals/attach': (signal?: AbortSignal) => RemoteStreamHandle<CreateGoalResult, CreateGoalRequest>",
+    )
+    expect(artifact?.remote?.dts).toContain("'goals/tail': () => RemoteStreamHandle<string, never>")
+    expect(artifact?.remote?.dts).toContain("'goals/silent': () => RemoteStreamHandle<string, never>")
+
+    const remoteJs = artifact?.remote?.js
+    if (remoteJs === undefined) throw new Error('RemoteStream fixture emitted no Host-for-Client JavaScript')
+    const executable = remoteJs.replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`)
+    const generated = await import(`data:text/javascript,${encodeURIComponent(executable)}`) as RuntimeRemoteModule
+    const descriptor = generated.TYPERT_REMOTE.descriptors.find(candidate => candidate.id.endsWith('/attach'))
+    expect(descriptor?.mode).toBe('stream')
+    expect(descriptor?.uplink?.codec.create().safeParse({ title: 'ship' }).success).toBe(true)
+    expect(descriptor?.uplink?.codec.create().safeParse({ title: 1 }).success).toBe(false)
+    expect(descriptor?.cancellation).toEqual({ parameter: 'signal' })
+    expect(generated.TYPERT_REMOTE.descriptors.find(candidate => candidate.id.endsWith('/tail'))?.uplink).toBeUndefined()
+    assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root)
+  })
+
+  it.each([
+    {
+      name: 'a stream method returning a Promise',
+      mode: 'stream',
+      method: 'async attach(agent: Agent, signal: AbortSignal): Promise<CreateGoalResult>',
+      message: 'stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>',
+    },
+    {
+      name: 'an unknown Remote mode',
+      mode: 'duplex',
+      method: 'async *attach(agent: Agent, signal: AbortSignal): AsyncIterable<CreateGoalResult>',
+      message: 'Remote\\(\\) options must contain exactly mode: "stream"',
+    },
+  ])('rejects $name', ({ mode, method, message }) => {
+    const root = copyFixture()
+    const decorator = mode === 'unary' ? '@Remote' : `@Remote({ mode: '${mode}' })`
+    editFile(root, 'packages/remote/src/index.ts', source => source.replace(
+      "  @Remote({ mode: 'stream' })\n  async *watch",
+      `  ${decorator}\n  ${method} {\n    throw new Error('fixture never runs')\n  }\n\n  @Remote({ mode: 'stream' })\n  async *watch`,
+    ))
+
+    expect(() => analyzeRemote(root, false)).toThrow(new RegExp(message))
+  })
+
   it('evaluates declaration-merged mapped and conditional boundaries for codecs without widening consumer types', async () => {
     const root = copyFixture()
     editFile(root, 'packages/remote/src/types.ts', source => `${source}
@@ -638,6 +972,7 @@ function assertRemoteConsumerTypechecks(
   dts: string | undefined,
   dtsMap: string | undefined,
   sourceRoot = fixtureRoot,
+  extraConsumer = '',
 ): void {
   if (dts === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration')
   if (dtsMap === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration map')
@@ -653,6 +988,7 @@ function assertRemoteConsumerTypechecks(
 import remote from '@fixture/remote/remote'
 import type {
   RemoteResult,
+  RemoteStreamHandle,
   TypertRemoteContribution,
   TypertRemoteScopeMap,
   TypertRemoteMap,
@@ -664,10 +1000,12 @@ const contribution: TypertRemoteContribution = remote
 declare const create: TypertRemoteMap['goals/create']
 declare const createScoped: TypertRemoteScopeMap['agent:goals/create']
 declare const rename: TypertRemoteScopeMap['agent:goals/rename']
+declare const watch: TypertRemoteMap['goals/watch']
 const created: Promise<RemoteResult<CreateGoalResult>> = create('agent-1', { title: 'ship' })
 const cancellable: Promise<RemoteResult<CreateGoalResult>> = create('agent-1', { title: 'ship' }, new AbortController().signal)
 const createdScoped: Promise<RemoteResult<CreateGoalResult>> = createScoped({ title: 'ship' })
 const renamed: Promise<RemoteResult<RenameGoalResult>> = rename({ ref: 'goal-1', title: 'land' })
+const watched: RemoteStreamHandle<CreateGoalResult, never> = watch('agent-1')
 declare const ctx: { remote: TypertRemoteNamespaceMap }
 const navigated: Promise<RemoteResult<CreateGoalResult>> = ctx.remote.goals.create('agent-1', { title: 'navigate' })
 void contribution
@@ -675,7 +1013,9 @@ void created
 void cancellable
 void createdScoped
 void renamed
+void watched
 void navigated
+${extraConsumer}
 `
   writeFileSync(consumerPath, consumerSource)
   const configPath = join(consumerRoot, 'tsconfig.consumer.json')
diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts
index 004a2fdc17..50ec19165d 100644
--- a/packages/typert/loader/src/index.ts
+++ b/packages/typert/loader/src/index.ts
@@ -273,6 +273,11 @@ function requireStrictCodec(pkgName: string, value: unknown, subject: string): v
     throw new Error(`typert-loader: ${pkgName} ${subject} must use a strict codec`)
   }
   requireString(pkgName, codec, 'typeSymbol', subject)
+  for (const method of ['decode', 'encode']) {
+    if (codec[method] !== undefined && typeof codec[method] !== 'function') {
+      throw new Error(`typert-loader: ${pkgName} ${subject} ${method} must be a function`)
+    }
+  }
   if (typeof codec.create !== 'function') {
     throw new Error(`typert-loader: ${pkgName} ${subject} has no create() factory`)
   }
diff --git a/packages/typert/loader/tests/loader.spec.ts b/packages/typert/loader/tests/loader.spec.ts
index 748f005d4a..72db60cbae 100644
--- a/packages/typert/loader/tests/loader.spec.ts
+++ b/packages/typert/loader/tests/loader.spec.ts
@@ -535,6 +535,14 @@ describe('validateTypertManifest', () => {
     const descriptor = strictInvocation()
     const manifest = { ...base, invocations: [descriptor] }
     expect(validateTypertManifest('pkg', manifest)).toBe(manifest)
+    const decoded = { ...descriptor, result: { ...descriptor.result, decode: (value: unknown) => value } }
+    expect(validateTypertManifest('pkg', { ...base, invocations: [decoded] }).invocations).toEqual([decoded])
+    expect(() => validateTypertManifest('pkg', {
+      ...base, invocations: [{ ...decoded, result: { ...decoded.result, decode: true } }],
+    })).toThrow('decode must be a function')
+    expect(() => validateTypertManifest('pkg', {
+      ...base, invocations: [{ ...decoded, result: { ...decoded.result, encode: true } }],
+    })).toThrow('encode must be a function')
     const cancellable = { ...descriptor, cancellation: { parameter: 'signal' } }
     expect(validateTypertManifest('pkg', { ...base, invocations: [cancellable] }).invocations)
       .toEqual([cancellable])
diff --git a/packages/typert/protocol/README.i18n.yaml b/packages/typert/protocol/README.i18n.yaml
index fc20a25c24..d1073f7952 100644
--- a/packages/typert/protocol/README.i18n.yaml
+++ b/packages/typert/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/typert/protocol/README.md
-README.md: e41fa9fa305d8f55ce55d3eace647ad5afcea0e3
-README.zh.md: e784e771016ebec0913e0ea847258fe653ae3bd0
+README.md: 8a97bb339d462c8dbea7666c7855a7e51ae9b113
+README.zh.md: 9bb2cae765ee5747bf11a92d44ec2bb201b0285d
diff --git a/packages/typert/protocol/README.md b/packages/typert/protocol/README.md
index e41fa9fa30..8a97bb339d 100644
--- a/packages/typert/protocol/README.md
+++ b/packages/typert/protocol/README.md
@@ -44,6 +44,10 @@ export class GoalService extends TypertRemoteService {
 
 Generation turns the method into a wire endpoint under the service's namespace; Clients call it as a typed method through `ctx.remote` (see the [API Gateway reference](../../../docs/api-gateway.md)). A method opts into cooperative cancellation by declaring `signal: AbortSignal` as its final parameter — the signal is injected, never a JSON parameter or lookup field.
 
+A unary method can return `Uint8Array` directly or within nested objects, arrays, tuples, optional fields, unions, and recursive types. Generation supplies optional result codec `encode()` and `decode()` functions: encoding visits only subtrees whose types can contain bytes, while decoding validates reconstructed values; Client declarations use `Uint8Array<ArrayBuffer>` at every byte position while retaining other field types. Pure JSON results pass through without Host byte detection or Client parsing. Parameters, events, and stream items remain JSON-only; runtime object cycles are unsupported.
+
+A stream method (`@Remote({ mode: 'stream' })`) returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out, In>`. `In` declares the items the Client may send back on the same logical stream; the method reads them through `this.ctx.invocation.uplink<In>()`, and the descriptor carries their codec. `RemoteInvocation` also names the receiving `service`, the calling `peer` (a `PeerScope` the connection layer admitted), and the carrier `signal`; `ctx.invocation` is `undefined` on a Context no Remote call derived: the first `bindTypertRemote()` binding in a tree, which every `TypertRemoteService` constructor makes, registers that accessor on the root. A generated Client stream method returns `RemoteStreamHandle<Out, In>`: the handle with `send`, `end`, and `dispose` beside the downlink iteration. Uplink items are validated one by one at the Host because they arrive from the browser; downlink items are values the Host method produced and pass through.
+
 ### Associating Host objects and Contexts with wire identities
 
 Complex Host objects cannot cross the wire directly. A business package declares the association through the merge-extensible `TypertLookupMap` and `TypertContextMap`. A Host Context adapter owns the stable wire declaration and resolves wire identities to live Contexts. A Client Context adapter maps in both directions because scoped calls originate from a Client Context and forwarded Host events resolve their explicit wire identity there. Host composition may override its synchronous or asynchronous resolver. A resolver that refuses on policy grounds throws `RemoteError` with its own code, which reaches the caller unchanged.
@@ -89,7 +93,7 @@ The package keeps strict reflection in the compiler: decorator initializers reta
 
 ### Protocol maps and descriptors
 
-The merge-extensible protocol maps keep static associations in the type system, while runtime providers register resolution with `ctx.typert`; the map names and shapes live in [`src/types.ts`](src/types.ts). `InvocationDescriptor` is the shared runtime form consumed by the registry, the Gateway, and the Client Remote, covering direct and Context receivers, JSON and lookup parameters, scope projections, cancellation, and result codecs.
+The merge-extensible protocol maps keep static associations in the type system, while runtime providers register resolution with `ctx.typert`; the map names and shapes live in [`src/types.ts`](src/types.ts). `InvocationDescriptor` is the shared runtime form consumed by the registry, the Gateway, and the Client Remote, covering direct and Context receivers, JSON and lookup parameters, scope projections, the uplink codec, cancellation, and result codecs.
 
 ### Wire identity grammar
 
@@ -100,8 +104,9 @@ Every namespace, method, lookup, and Context segment must satisfy `isTypertRemot
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Decorators, Gateway bindings, `remoteMethods`, segment validation |
+| [`src/json-value.ts`](src/json-value.ts) | `isRemoteJsonValue` and `isRemoteUplinkItem`, the lossless JSON checks every carrier shares |
 | [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` and the structural `remoteErrorOf` recognizer |
-| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
+| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `RemoteStream`, `RemoteStreamHandle`, `PeerScope`, `RemoteInvocation`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
 | — | No runtime invariant companion is published; decorators retain private immutable declarations and bindings are frozen values with no independent event stream to cross-check. |
 
 </details>
diff --git a/packages/typert/protocol/README.zh.md b/packages/typert/protocol/README.zh.md
index e784e77101..9bb2cae765 100644
--- a/packages/typert/protocol/README.zh.md
+++ b/packages/typert/protocol/README.zh.md
@@ -44,6 +44,10 @@ export class GoalService extends TypertRemoteService {
 
 生成会把方法变为服务命名空间下的 wire 端点；Client 通过 `ctx.remote` 以类型化方法调用它（见 [API Gateway 参考](../../../docs/api-gateway.zh.md)）。方法把 `signal: AbortSignal` 声明为最后一个参数即可选择协作式取消——该信号是注入的，绝不会成为 JSON 参数或查找字段。
 
+一元方法可以直接返回 `Uint8Array`，也可以将其放在嵌套对象、数组、元组、可选字段、联合类型和递归类型中。生成器提供可选的结果 codec `encode()` 和 `decode()`：编码仅访问类型可能包含字节的子树，解码则校验还原后的值；Client 声明在每个字节位置使用 `Uint8Array<ArrayBuffer>`，同时保留其他字段类型。纯 JSON 结果不经 Host 字节识别或 Client 解析直接传递。参数、事件与流条目仍仅支持 JSON；不支持运行时对象循环。
+
+流方法（`@Remote({ mode: 'stream' })`）返回 `Iterable`、`AsyncIterable` 或 `RemoteStream<Out, In>`。`In` 声明 Client 可以在同一条逻辑流上回送的项；方法通过 `this.ctx.invocation.uplink<In>()` 读取它们，描述符携带其 codec。`RemoteInvocation` 还给出接收服务 `service`、发起调用的 `peer`（连接层接纳的一个 `PeerScope`）与载体 `signal`；非 Remote 调用派生的 Context 上 `ctx.invocation` 为 `undefined`：树中第一个 `bindTypertRemote()` 绑定（每个 `TypertRemoteService` 构造函数都会建立一个）在根上注册该 accessor。生成的 Client 流方法返回 `RemoteStreamHandle<Out, In>`：在下行迭代之外提供 `send`、`end` 与 `dispose` 的句柄。上行项在 Host 逐项校验，因为它们来自浏览器；下行项是 Host 方法产出的值，原样透传。
+
 ### 把 Host 对象与 Context 关联到 wire identity
 
 复杂的 Host 对象不能直接跨 wire 传输。业务包通过可合并扩展的 `TypertLookupMap` 与 `TypertContextMap` 声明关联。Host Context 适配器拥有稳定 wire 声明，并把 wire identity 解析为活跃 Context。Client Context 适配器需要双向映射，因为作用域调用从 Client Context 发起，而转发的 Host 事件要在 Client 侧解析其显式 wire identity。Host 组合可以覆盖其同步或异步解析器。因策略原因拒绝解析的解析器会抛出带有自身错误码的 `RemoteError`，该码原样到达调用方。
@@ -89,7 +93,7 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 
 ### 协议映射与描述符
 
-可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、取消与结果编解码器。
+可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、上行编解码器、取消与结果编解码器。
 
 ### Wire 标识文法
 
@@ -100,8 +104,9 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 装饰器、Gateway 绑定、`remoteMethods`、段校验 |
+| [`src/json-value.ts`](src/json-value.ts) | 各载体共享的无损 JSON 校验 `isRemoteJsonValue` 与 `isRemoteUplinkItem` |
 | [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` 与结构式识别函数 `remoteErrorOf` |
-| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
+| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`RemoteStream`、`RemoteStreamHandle`、`PeerScope`、`RemoteInvocation`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
 | — | 不发布运行时不变量伴生入口；decorator 只保留私有不可变声明，binding 也是冻结值，没有可供交叉核对的独立事件流。 |
 
 </details>
diff --git a/packages/typert/protocol/package.json b/packages/typert/protocol/package.json
index bd0f34482d..0b998c9897 100644
--- a/packages/typert/protocol/package.json
+++ b/packages/typert/protocol/package.json
@@ -31,6 +31,9 @@
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "workspace:^"
   },
diff --git a/packages/typert/protocol/src/index.ts b/packages/typert/protocol/src/index.ts
index 7c3d902b19..f94096beb3 100644
--- a/packages/typert/protocol/src/index.ts
+++ b/packages/typert/protocol/src/index.ts
@@ -5,12 +5,13 @@
  * @module @deepseek-ai/dsh-typert-protocol
  */
 
-import { Service, type Context } from '@deepseek-ai/cordis'
+import { Context, Service } from '@deepseek-ai/cordis'
 import type { TypertContextMap } from './types.ts'
 
 export { RemoteError, remoteErrorOf } from './remote-error.ts'
 export { TYPERT_OWNED_VALUE, isTypertOwnedValue, typertOwnedValue } from './owned-value.ts'
 export type { TypertOwnedValue } from './owned-value.ts'
+export { isRemoteJsonValue, isRemoteUplinkItem } from './json-value.ts'
 
 const TYPERT_REMOTE_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/
 
@@ -27,10 +28,15 @@ export type {
   InvocationDescriptor,
   InvocationParameterDescriptor,
   InvocationSourceLocation,
+  PeerId,
+  PeerScope,
   RemoteErrorCode,
   RemoteErrorDetailsMap,
   RemoteFailure,
+  RemoteInvocation,
   RemoteResult,
+  RemoteStream,
+  RemoteStreamHandle,
   TypertClientEventListener,
   TypertClientRemote,
   TypertClientContextAdapter,
@@ -100,7 +106,7 @@ export interface RemoteMethodMarker {
 
 /** Options for a non-unary Remote method. */
 export interface RemoteMethodOptions {
-  /** Deliver each Iterable item over the shared logical-stream carrier. */
+  /** `stream`: deliver each Iterable item over the shared logical-stream carrier. */
   readonly mode: 'stream'
 }
 
@@ -134,7 +140,10 @@ interface RemoteMethodDescriptorV1 {
 const REMOTE_METHOD_DESCRIPTOR = '@deepseek-ai/dsh-typert-protocol/remote-methods'
 
 /**
- * Bind one visible Service field to a Cordis key and Remote namespace.
+ * Bind one visible Service field to a Cordis key and Remote namespace. A
+ * service that owns a Cordis Context also gives its tree `ctx.invocation`,
+ * `undefined` outside a Remote call, so no `TypertRemoteService` is needed for
+ * a Host composition to read it.
  * @param service - owning Service instance, normally `this`.
  * @param serviceKey - exact Cordis service key.
  * @param options - optional distinct wire namespace.
@@ -148,6 +157,8 @@ export function bindTypertRemote<Service extends object>(
   validateName('service key', serviceKey)
   const namespace = options.namespace ?? serviceKey
   validateName('namespace', namespace)
+  const ctx: unknown = Reflect.get(service, 'ctx')
+  if (ctx instanceof Context) provideInvocationAccessor(ctx)
   return Object.freeze({ service, serviceKey, namespace })
 }
 
@@ -168,6 +179,17 @@ export abstract class TypertRemoteService<out T = never> extends Service<T> {
   }
 }
 
+/**
+ * Make `ctx.invocation` read as `undefined` outside a Remote call instead of the
+ * reflect service's "cannot get property" error; a call-derived Context shadows
+ * the accessor with its own property. The first Remote Service constructed in a
+ * tree registers it on the root, where it outlives any one Service.
+ */
+function provideInvocationAccessor(ctx: Context): void {
+  if (Object.hasOwn(ctx.root.reflect.props, 'invocation')) return
+  ctx.root.accessor('invocation', { get: () => undefined })
+}
+
 /**
  * Mark one public instance method as a direct Remote invocation.
  * @param _method - decorated method; retained only by the class itself.
diff --git a/packages/typert/protocol/src/json-value.ts b/packages/typert/protocol/src/json-value.ts
new file mode 100644
index 0000000000..323cc31ea0
--- /dev/null
+++ b/packages/typert/protocol/src/json-value.ts
@@ -0,0 +1,53 @@
+/**
+ * Lossless JSON checks every Remote carrier shares: the Client handle before it
+ * queues an uplink item, the Gateway at its wire and codec-less uplink
+ * boundaries, and the in-process mock.
+ */
+
+/**
+ * Test whether a value crosses JSON transport without coercion or omission.
+ * @param value - candidate boundary value.
+ * @returns whether the value is losslessly JSON-compatible.
+ */
+export function isRemoteJsonValue(value: unknown): boolean {
+  return visitJsonValue(value, new Set<object>())
+}
+
+/**
+ * Test whether a value may travel as one uplink item: a lossless JSON value, or
+ * a top-level `undefined`, which the wire carries as an `item` frame without
+ * `value`. Nested `undefined`, `NaN`, and infinities stay rejected.
+ * @param value - candidate uplink item.
+ * @returns whether the item crosses every carrier unchanged.
+ */
+export function isRemoteUplinkItem(value: unknown): boolean {
+  return value === undefined || isRemoteJsonValue(value)
+}
+
+function visitJsonValue(value: unknown, ancestors: Set<object>): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') return Number.isFinite(value) && !Object.is(value, -0)
+  if (typeof value !== 'object') return false
+  if (ancestors.has(value)) return false
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype
+        || Reflect.ownKeys(value).length !== value.length + 1) return false
+      for (let index = 0; index < value.length; index++) {
+        if (!Object.hasOwn(value, index) || !visitJsonValue(value[index], ancestors)) return false
+      }
+      return true
+    }
+    const prototype: unknown = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null) return false
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== 'string') return false
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      if (descriptor?.enumerable !== true || !visitJsonValue(Reflect.get(value, key), ancestors)) return false
+    }
+    return true
+  } finally {
+    ancestors.delete(value)
+  }
+}
diff --git a/packages/typert/protocol/src/types.ts b/packages/typert/protocol/src/types.ts
index 358babac9d..ec2a88c4f9 100644
--- a/packages/typert/protocol/src/types.ts
+++ b/packages/typert/protocol/src/types.ts
@@ -5,6 +5,7 @@
  */
 
 import type { Context, Events } from '@deepseek-ai/cordis'
+import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { TypertOwnedValue } from './owned-value.ts'
 
 declare const LOOKUP_HOST: unique symbol
@@ -76,6 +77,52 @@ export type RemoteResult<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly error: RemoteFailure }
 
+declare const STREAM_UPLINK: unique symbol
+
+/**
+ * One Remote stream as a Host method returns it: the items it yields to the
+ * Client, iterated as a plain `AsyncIterable<Out>`. `In` is the type of the
+ * items the Client may send back on the same logical stream, read through
+ * `RemoteInvocation.uplink()`; it is carried only as a type-level marker. The
+ * default `never` declares a method that reads none, and its descriptor
+ * carries no uplink codec. A generated Client stream method returns the same
+ * stream as a `RemoteStreamHandle<Out, In>`.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+export type RemoteStream<Out, In = never> = AsyncIterable<Out> & { readonly [STREAM_UPLINK]?: In }
+
+/**
+ * One open Remote stream as the Client holds it: the downlink items as an
+ * `AsyncIterable`, plus the uplink and cancellation of the same logical
+ * stream. A generated Client stream method returns it, and calling that
+ * method opens the stream: a holder that neither iterates nor disposes the
+ * handle keeps the Host stream alive. A handle stands for one generation:
+ * when the carrier is lost, iteration fails with the carrier error and the
+ * handle is finished.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+export interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+  /**
+   * Send one uplink item. Items sent before the stream has opened are queued
+   * and sent once the `open` frame is on the wire. A top-level `undefined`
+   * travels as an `item` frame without `value`.
+   * @param item - item the Host validates against the method's uplink codec.
+   * @throws {Error} when the item is not a lossless JSON value, when `end()`
+   * was called, or once the stream has terminated.
+   */
+  send(item: In): void
+  /** Half-close the uplink: the Host's `uplink()` iteration ends. Idempotent; ignored after termination. */
+  end(): void
+  /**
+   * Cancel the logical stream: send `cancel` unless a terminal frame has
+   * arrived, and end the downlink iterator quietly. Breaking out of
+   * `for await` early does the same.
+   */
+  dispose(): void
+}
+
 /** Merge-extensible scoped Remote method signatures generated for consumers. */
 export interface TypertRemoteScopeMap {}
 
@@ -226,6 +273,19 @@ export type TypertCodec =
     readonly typeSymbol: string
     /** Materialize and return the process-realm schema on first boundary use. */
     readonly create: () => TypertSchema
+    /**
+     * Decode a unary result whose fields require type-specific handling.
+     * @param value - result reconstructed by the RPC carrier.
+     * @returns the validated result, retaining native byte views.
+     */
+    readonly decode?: (value: unknown) => unknown
+    /**
+     * Project typed binary fields into RPC result attachments.
+     * @param value - native unary result.
+     * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
+     * @returns JSON metadata with untouched JSON subtrees retained.
+     */
+    readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown
   }
   | {
     readonly mode: 'src-json'
@@ -266,7 +326,7 @@ export interface InvocationDescriptor {
   readonly method: string
   /** Service member invoked when the exported method name is an alias. */
   readonly implementation?: string
-  /** Absent for unary calls; stream calls validate and deliver every yielded item. */
+  /** Absent for unary calls; stream calls deliver every yielded item as the Host produced it. */
   readonly mode?: 'stream'
   /** Receiver selection mode. */
   readonly invocation:
@@ -286,6 +346,16 @@ export interface InvocationDescriptor {
   }
   /** Ordered business parameters. */
   readonly parameters: readonly InvocationParameterDescriptor[]
+  /**
+   * Client-to-Host items of the same logical stream, generated from the `In`
+   * type argument of the method's `RemoteStream<Out, In>` return type; absent
+   * when `In` is `never`. The method reads the items through
+   * `RemoteInvocation.uplink()`, so nothing enters the parameter list.
+   */
+  readonly uplink?: {
+    /** Codec validating every uplink item before `uplink()` delivers it. */
+    readonly codec: TypertCodec
+  }
   /** Transport cancellation injected after business parameters instead of entering wire args. */
   readonly cancellation?: {
     /** Reserved final Host method parameter. */
@@ -297,6 +367,59 @@ export interface InvocationDescriptor {
   readonly sourceLocation?: InvocationSourceLocation
 }
 
+/**
+ * Opaque identity of one Peer: a party admitted to this Host by the connection
+ * layer. "Peer" is a connection-layer word; the browser application keeps the
+ * word "Client".
+ */
+export type PeerId = Branded<'PeerId'>
+
+/**
+ * One Peer's session on this Host. Connection owns it: `ctx` is the Cordis
+ * scope that owns connection-lifetime registrations and is disposed with the
+ * Peer. Who the Peer is and what it may do are not recorded here.
+ */
+export interface PeerScope {
+  readonly id: PeerId
+  readonly ctx: Context
+  /**
+   * Tear down every registration made through `ctx`.
+   * @returns settles once the scope has quiesced; racing calls share one completion.
+   */
+  dispose(): Promise<void>
+}
+
+/**
+ * The context of one Remote call, reachable inside the receiving method as
+ * `this.ctx.invocation`. The Gateway derives the receiver from a Context that
+ * carries it, so no parameter is injected and nothing crosses the wire.
+ */
+export interface RemoteInvocation {
+  readonly request: {
+    readonly namespace: string
+    readonly method: string
+    readonly args: Readonly<Record<string, unknown>>
+  }
+  /** Cordis service key of the receiving Service. */
+  readonly service: string
+  /** Peer the call speaks for; an in-process carrier speaks for the operator. */
+  readonly peer: PeerScope
+  /** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
+  readonly signal: AbortSignal
+  /**
+   * The Client's uplink items for this call. Available once; a second call
+   * throws. With an uplink codec on the descriptor every item is decoded to
+   * `In`; without one items arrive as `unknown` after a JSON-safety check.
+   * Iteration ends when the Client ends its uplink; when the method finishes
+   * its downlink the Gateway calls the iterator's `return()` and unread items
+   * are dropped. `In` is the caller's assertion: the runtime decodes by the
+   * descriptor and does not cross-check it.
+   * @template In - item type the caller reads; the descriptor codec decides what arrives.
+   * @returns the single-consumer uplink iterable.
+   */
+  uplink<In = unknown>(): AsyncIterable<In>
+}
+
 /** Generated Host contract selected explicitly by a Client assembly. */
 export interface TypertRemoteContribution {
   /** npm package that owns the Remote methods. */
@@ -569,5 +692,11 @@ export interface TypertRegistryContract {
 declare module '@deepseek-ai/cordis' {
   interface Context {
     typert: TypertRegistryContract
+    /**
+     * The Remote call this Context was derived for, or `undefined` on a
+     * Context no Remote call derived. A Service method reads it as
+     * `this.ctx.invocation`.
+     */
+    readonly invocation: RemoteInvocation | undefined
   }
 }
diff --git a/packages/typert/protocol/tests/protocol.spec.ts b/packages/typert/protocol/tests/protocol.spec.ts
index 09c85316e2..e8e42b0ac0 100644
--- a/packages/typert/protocol/tests/protocol.spec.ts
+++ b/packages/typert/protocol/tests/protocol.spec.ts
@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
-import { Context } from '@deepseek-ai/cordis'
+import { Context, Service } from '@deepseek-ai/cordis'
 import { describe, expect, expectTypeOf, it } from 'vitest'
 import {
   bindTypertRemote,
@@ -240,6 +240,63 @@ describe('typert-protocol Remote declarations', () => {
     expect(remoteMethods(prototypeLess)).toEqual([])
   })
 
+  it('records the stream mode on the Remote marker', () => {
+    class Jobs {
+      follow(): void {}
+    }
+    const initializers: Array<(this: Jobs) => void> = []
+    Remote({ mode: 'stream' })(Reflect.get(Jobs.prototype, 'follow'), methodContext('follow', initializers))
+    const jobs = new Jobs()
+    for (const initialize of initializers) initialize.call(jobs)
+    expect(remoteMethods(jobs)).toEqual([
+      { method: 'follow', mode: 'stream', invocation: { kind: 'direct' } },
+    ])
+  })
+
+  it('registers the invocation accessor once per tree, on the root', async () => {
+    const root = new Context()
+    class First extends TypertRemoteService {
+      constructor(ctx: Context) {
+        super(ctx, 'first')
+      }
+
+      outside(): unknown {
+        return this.ctx.invocation
+      }
+    }
+    class Second extends TypertRemoteService {
+      constructor(ctx: Context) {
+        super(ctx, 'second')
+      }
+    }
+    await root.plugin(First)
+    const second = root.plugin(Second)
+    await second
+    const child = root.plugin(() => {})
+    await child
+    expect(child.ctx.invocation).toBeUndefined()
+    expect((root.get('first') as First).outside()).toBeUndefined()
+    // The accessor belongs to the root, so a Remote Service leaving does not take it along.
+    await second.dispose()
+    expect(child.ctx.invocation).toBeUndefined()
+  })
+
+  it('provides the invocation accessor for a plain Service bound with bindTypertRemote', async () => {
+    const root = new Context()
+    expect(Object.hasOwn(root.reflect.props, 'invocation')).toBe(false)
+    class Plain extends Service {
+      readonly typertRemote = bindTypertRemote(this, 'plain')
+
+      constructor(ctx: Context) {
+        super(ctx, 'plain')
+      }
+    }
+    await root.plugin(Plain)
+    expect(Object.hasOwn(root.reflect.props, 'invocation')).toBe(true)
+    expect(root.invocation).toBeUndefined()
+    expect((root.get('plain') as Plain).typertRemote.namespace).toBe('plain')
+  })
+
   it('rejects malformed decorator calls and targets', () => {
     const method: (this: object) => void = function (this: object): void {}
     expect(() => { (Remote as unknown as (value: typeof method) => void)(method) }).toThrow('context is missing')
@@ -250,6 +307,9 @@ describe('typert-protocol Remote declarations', () => {
     expect(() => Remote('..')).toThrow('export name')
     expect(() => Remote({ mode: 'unary' } as unknown as { mode: 'stream' })).toThrow('exactly mode')
     expect(() => Remote({ mode: 'stream', extra: true } as unknown as { mode: 'stream' })).toThrow('exactly mode')
+    const bogusMode: string = 'duplex'
+    expect(() => Remote({ mode: bogusMode } as { mode: 'stream' }))
+      .toThrow('Remote options must contain exactly mode: "stream"')
     expect(() => RemoteScope('' as 'metaFixture')).toThrow('Scope key')
     expect(() => RemoteScope('metaFixture', 'bad/name')).toThrow('export name')
 
diff --git a/packages/typert/protocol/tsconfig.json b/packages/typert/protocol/tsconfig.json
index 754725418e..342f636170 100644
--- a/packages/typert/protocol/tsconfig.json
+++ b/packages/typert/protocol/tsconfig.json
@@ -13,6 +13,9 @@
     },
     {
       "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../util/brand"
     }
   ]
 }
diff --git a/packages/typert/registry/src/service.ts b/packages/typert/registry/src/service.ts
index 73c772fdd0..93a370e34f 100644
--- a/packages/typert/registry/src/service.ts
+++ b/packages/typert/registry/src/service.ts
@@ -692,6 +692,11 @@ function validateInvocation(descriptor: InvocationDescriptor): void {
   if (cancellation !== undefined && cancellation.parameter !== 'signal') {
     throw new Error(`typert: invocation "${descriptor.id}" cancellation parameter must be "signal"`)
   }
+  const mode = descriptor.mode as string | undefined
+  if (mode !== undefined && mode !== 'stream') {
+    throw new Error(`typert: invocation "${descriptor.id}" mode must be "stream"`)
+  }
+  if (descriptor.uplink !== undefined) validateCodec(descriptor.uplink.codec, `${descriptor.id} uplink`)
   if (descriptor.scope !== undefined) {
     if (descriptor.invocation.kind !== 'direct') {
       throw new Error(`typert: invocation "${descriptor.id}" Context receiver cannot declare a direct scope projection`)
diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts
index 936ed5c279..9df0c730e8 100644
--- a/packages/typert/registry/tests/typert.spec.ts
+++ b/packages/typert/registry/tests/typert.spec.ts
@@ -99,6 +99,18 @@ function scopedInvocation(): InvocationDescriptor {
 }
 
 describe('TypertRegistry', () => {
+  it('retains generated result decoders until the contribution is disposed', async () => {
+    const ctx = await makeCtx()
+    const decode = (value: unknown) => value
+    const descriptor: InvocationDescriptor = {
+      ...invocation(), result: { mode: 'strict', typeSymbol: 'fixture#bytes', create: () => ({ parse: decode }), decode },
+    }
+    const dispose = ctx.typert.register({ ...toolsContribution(), invocations: [descriptor] })
+    expect(ctx.typert.local.get('goals/create')?.result).toBe(descriptor.result)
+    await dispose()
+    expect(ctx.typert.local.get('goals/create')).toBeUndefined()
+  })
+
   it('registers and queries generated schemas separately from package reflection', async () => {
     const ctx = await makeCtx()
     const contribution = toolsContribution()
@@ -500,9 +512,25 @@ describe('TypertRegistry', () => {
     }
     const dispose = ctx.typert.remotes.register({ package: '@fixture/strict', descriptors: [strictInvocation] })
     await dispose()
+    const uplinkInvocation: InvocationDescriptor = {
+      ...strictInvocation,
+      id: '@fixture/remote#attach',
+      method: 'attach',
+      mode: 'stream',
+      uplink: { codec: strict },
+    }
+    const disposeUplink = ctx.typert.remotes.register({ package: '@fixture/uplink', descriptors: [uplinkInvocation] })
+    await disposeUplink()
 
+    const bogusMode: string = 'duplex'
     const malformed: readonly [InvocationDescriptor, string][] = [
       [{ ...invocation(), id: '' }, 'invocation id'],
+      [{ ...invocation(), mode: bogusMode as 'stream' }, 'mode must be "stream"'],
+      [{
+        ...invocation(),
+        mode: 'stream',
+        uplink: { codec: { mode: 'strict', typeSymbol: '', create: () => z.string() } },
+      }, 'uplink type symbol'],
       [{ ...invocation(), namespace: 'bad/name' }, 'namespace'],
       [{ ...invocation(), implementation: 'bad/name' }, 'implementation method'],
       [{
diff --git a/packages/util/native-command/README.i18n.yaml b/packages/util/native-command/README.i18n.yaml
index 8bc90e6e8d..b234b64011 100644
--- a/packages/util/native-command/README.i18n.yaml
+++ b/packages/util/native-command/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/native-command/README.md
-README.md: 9abf4031a915121b6fd2a218473b27c864f8ced8
-README.zh.md: 083318cf4bb37e1c18f016512d58df8bb8f3aec5
+README.md: e17228c694ffb8f69ef694695df54a1fa2f9a21a
+README.zh.md: 68556683ce45bbceb510a4e2fa9227ece033c492
diff --git a/packages/util/native-command/README.md b/packages/util/native-command/README.md
index 9abf4031a9..e17228c694 100644
--- a/packages/util/native-command/README.md
+++ b/packages/util/native-command/README.md
@@ -49,6 +49,8 @@ The `NativeCommandRunner` type is the injectable command boundary for host integ
 
 `revealNativePath(path, signal)` selects the file in Finder or Explorer, including WSL path translation, and opens its parent directory through `xdg-open` on desktop Linux. `nativeFileManager()` identifies that action for Host-derived UI labels; desktop availability remains a separate `canOpenNativePath()` check. Callers must authorize the absolute file path before invoking either operation. Platform dispatch is covered by injected-runner tests; native desktop verification belongs to the corresponding platform. Explorer receives an encoded file URI as a separate argument. Its exit code 1 is accepted as a delegated handoff; cancellation, missing executables, and other exit codes still reject. This acknowledgement does not prove that a desktop window selected the file.
 
+`nativeFileApplications(path, signal)` returns registered applications, localized names, icons, and the current default. macOS 12 and later use LaunchServices; Windows uses Shell association handlers; Linux uses GIO with shared XDG desktop-entry and icon lookup. `openNativeFileApplication(path, application, signal)` revalidates the handler without changing the system default. Windows delegates invocation to the Shell, and Linux delegates argument expansion to `gio launch`. WSL translates the path and uses the Windows adapter. Callers authorize the local file path. Native integration tests use private Windows file associations and Linux XDG roots on their respective platforms.
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -101,10 +103,12 @@ Nothing here enters a request prefix; this package neither assembles nor sends a
 
 <a id="known-limitations-and-deferred-work"></a>
 
+Linux association discovery and explicit launching require GIO. Missing native commands reject the query, and missing artwork returns null; callers can retain file-manager reveal as their fallback.
+
 
 These limits define when this runner is not the right tool. They are current package constraints, not a task backlog.
 
-- **No output bounding** — both streams buffer unbounded in memory; every current caller invokes small native tools whose output is a path or an error line. Adopt `dsh-output-retention` bounding before pointing this at commands with meaningful output volume.
+- Command output uses Node’s `execFile` buffer limit; oversized replies reject. Use the subprocess capability for streaming output.
 
 <a id="dev-note"></a>
 ### Dev Note
diff --git a/packages/util/native-command/README.zh.md b/packages/util/native-command/README.zh.md
index 083318cf4b..68556683ce 100644
--- a/packages/util/native-command/README.zh.md
+++ b/packages/util/native-command/README.zh.md
@@ -49,6 +49,8 @@ const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], s
 
 `revealNativePath(path, signal)` 在 Finder 或文件资源管理器中选中文件，包含 WSL 路径转换；在桌面 Linux 上通过 `xdg-open` 打开上层目录。`nativeFileManager()` 标识该操作，供 UI 根据 Host 选择文案；桌面是否可用仍由独立的 `canOpenNativePath()` 检查决定。调用方必须先授权绝对文件路径，再执行操作。平台分派由注入运行器的测试覆盖；原生桌面验证由对应平台负责。 Explorer 接收独立参数中的编码文件 URI。退出码 1 按已转交请求处理；取消、找不到可执行文件和其他退出码仍然报错。该确认不能证明桌面窗口已选中文件。
 
+`nativeFileApplications(path, signal)` 返回关联应用、本地化名称、图标和当前默认项。macOS 12 及以上版本使用 LaunchServices，Windows 使用 Shell 关联处理器，Linux 使用 GIO，并共用 XDG 桌面文件和图标读取逻辑。`openNativeFileApplication(path, application, signal)` 重新验证关联应用，不修改系统默认值。Windows 交给 Shell 启动应用，Linux 交给 `gio launch` 展开参数。WSL 转换路径后使用 Windows 适配器。调用方负责验证本地文件路径。原生集成测试分别在相应平台使用独立的 Windows 文件关联和 Linux XDG 目录。
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -101,10 +103,12 @@ const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], s
 
 <a id="known-limitations-and-deferred-work"></a>
 
+Linux 的关联查询和指定应用启动需要 GIO。缺少原生命令时查询失败，缺失的图标返回 null；调用方可以保留文件定位作为备用动作。
+
 
 这些限制说明本运行器何时不是合适的工具。它们是当前包约束，不是任务积压。
 
-- **不做输出限量**——两路流在内存中无界缓冲；当前每个调用方只运行输出为一个路径或一行错误的小型原生工具。把它指向输出量可观的命令之前，先接入 `dsh-output-retention` 限量。
+- 命令输出受 Node 的 `execFile` 缓冲上限约束，超过上限时拒绝结果。流式输出由 subprocess 能力处理。
 
 <a id="dev-note"></a>
 ### 开发备注
diff --git a/packages/util/native-command/package.json b/packages/util/native-command/package.json
index 8060a32a2a..9fc16ba0a9 100644
--- a/packages/util/native-command/package.json
+++ b/packages/util/native-command/package.json
@@ -19,10 +19,15 @@
       "default": "./lib/index.js"
     },
     "./src/*": "./src/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    }
   },
   "files": [
     "lib/index.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
diff --git a/packages/util/native-command/src/desktop-entry.ts b/packages/util/native-command/src/desktop-entry.ts
new file mode 100644
index 0000000000..b2589aabb4
--- /dev/null
+++ b/packages/util/native-command/src/desktop-entry.ts
@@ -0,0 +1,76 @@
+/** Shared XDG desktop-entry fields and icon lookup for directory and file application catalogs. */
+import { readFile, stat } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+
+/** Decoded application icon bytes suitable for an image response or data URL. */
+export interface DesktopIcon {
+  readonly bytes: Buffer
+  readonly contentType: 'image/png' | 'image/svg+xml'
+}
+
+/**
+ * Read the main desktop-entry section without interpreting executable commands.
+ * @param text - installed desktop-entry text.
+ * @returns its literal field values; action sections are excluded.
+ */
+export function desktopEntryFields(text: string): Readonly<Record<string, string>> {
+  let main = false
+  const fields = new Map<string, string>()
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith('[')) { main = trimmed === '[Desktop Entry]'; continue }
+    if (!main || trimmed.startsWith('#')) continue
+    const separator = trimmed.indexOf('=')
+    if (separator > 0) fields.set(trimmed.slice(0, separator).trim(), trimmed.slice(separator + 1).trim())
+  }
+  return Object.fromEntries(fields)
+}
+
+/**
+ * Resolve XDG application and icon roots in desktop precedence order.
+ * @param home - user's home directory.
+ * @param env - desktop environment values.
+ * @returns data-home followed by system data directories.
+ */
+export function desktopDataDirectories(home: string, env: Readonly<Record<string, string | undefined>>): readonly string[] {
+  return [env.XDG_DATA_HOME ?? join(home, '.local', 'share'),
+    ...(env.XDG_DATA_DIRS ?? '/usr/local/share:/usr/share').split(':').filter(Boolean)]
+}
+
+/** Read an installed PNG or SVG icon; absent paths and directories have no pixels. */
+async function readIcon(path: string): Promise<DesktopIcon | null> {
+  const contentType = path.endsWith('.png') ? 'image/png' : path.endsWith('.svg') ? 'image/svg+xml' : null
+  if (contentType === null) return null
+  try {
+    if (!(await stat(path)).isFile()) return null
+    return { bytes: await readFile(path), contentType }
+  } catch (_error) {
+    // Missing or unreadable artwork does not remove an otherwise usable application.
+    return null
+  }
+}
+
+/**
+ * Resolve an absolute icon path or an installed hicolor/pixmaps icon name.
+ * @param name - desktop-entry Icon field.
+ * @param directories - XDG data roots in precedence order.
+ * @returns image bytes and media type, or null when artwork is unavailable.
+ */
+export async function desktopApplicationIcon(name: string, directories: readonly string[]): Promise<DesktopIcon | null> {
+  if (isAbsolute(name)) return readIcon(name)
+  for (const directory of directories) {
+    for (const size of ['512x512', '256x256', '128x128', '64x64', '48x48', '32x32']) {
+      for (const extension of ['png', 'svg']) {
+        const icon = await readIcon(join(directory, 'icons', 'hicolor', size, 'apps', `${name}.${extension}`))
+        if (icon !== null) return icon
+      }
+    }
+    const scalable = await readIcon(join(directory, 'icons', 'hicolor', 'scalable', 'apps', `${name}.svg`))
+    if (scalable !== null) return scalable
+    for (const extension of ['png', 'svg']) {
+      const icon = await readIcon(join(directory, 'pixmaps', `${name}.${extension}`))
+      if (icon !== null) return icon
+    }
+  }
+  return null
+}
diff --git a/packages/util/native-command/src/file-applications-linux.ts b/packages/util/native-command/src/file-applications-linux.ts
new file mode 100644
index 0000000000..017473f273
--- /dev/null
+++ b/packages/util/native-command/src/file-applications-linux.ts
@@ -0,0 +1,66 @@
+/** Linux file associations from GIO, with shared XDG metadata and artwork lookup. */
+import { readdir, readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, relative, sep } from 'node:path'
+import { desktopApplicationIcon, desktopDataDirectories, desktopEntryFields } from './desktop-entry.ts'
+import type { NativeCommandRunner } from './runner.ts'
+import type { NativeFileApplication } from './types.ts'
+
+/** Find a desktop id, including ids derived from nested application directories. */
+async function desktopFile(root: string, id: string, directory = root): Promise<string | null> {
+  let entries
+  try { entries = await readdir(directory, { withFileTypes: true }) } catch (_error) {
+    // An absent XDG root contributes no applications.
+    return null
+  }
+  for (const entry of entries) {
+    const path = join(directory, entry.name)
+    if (!entry.isDirectory() && relative(root, path).split(sep).join('-') === id) return path
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const found = await desktopFile(root, id, join(directory, entry.name))
+      if (found !== null) return found
+    }
+  }
+  return null
+}
+
+/**
+ * Query all registered file handlers from GIO without executing desktop-entry command text.
+ * @param path - verified local file path.
+ * @param signal - caller cancellation.
+ * @param run - native command runner.
+ * @param env - XDG and locale settings.
+ * @returns registered applications with the desktop's default marked.
+ */
+export async function linuxFileApplications(
+  path: string, signal: AbortSignal, run: NativeCommandRunner, env: NodeJS.ProcessEnv,
+): Promise<readonly NativeFileApplication[]> {
+  const info = await run('gio', ['info', '-a', 'standard::content-type', path], signal)
+  const mime = /standard::content-type:\s*(\S+)/.exec(info.stdout)?.[1]
+  if (mime === undefined) throw new Error('GIO did not identify the file content type')
+  const result = await run('env', ['LC_ALL=C', 'gio', 'mime', mime], signal)
+  const preferred = /^Default application.*:\s*(.+\.desktop)\s*$/m.exec(result.stdout)?.[1]
+  const ids = [...new Set([...(preferred === undefined ? [] : [preferred]), ...result.stdout.split(/\r?\n/)
+    .filter(line => /^\s+.*\.desktop\s*$/.test(line)).map(line => line.trim())])]
+  const directories = desktopDataDirectories(env.HOME ?? homedir(), env)
+  const locale = (env.LC_ALL ?? env.LC_MESSAGES ?? env.LANG ?? '').replace(/\..*$/, '')
+  const applications: NativeFileApplication[] = []
+  for (const id of ids) {
+    signal.throwIfAborted()
+    let entryPath: string | null = null
+    for (const directory of directories) {
+      entryPath = await desktopFile(join(directory, 'applications'), id)
+      if (entryPath !== null) break
+    }
+    if (entryPath === null) continue
+    const fields = desktopEntryFields(await readFile(entryPath, 'utf8'))
+    const name = fields[`Name[${locale}]`] ?? fields[`Name[${locale.replace(/_.*/, '')}]`] ?? fields.Name
+    if (name === undefined || fields.Hidden === 'true') continue
+    const icon = fields.Icon === undefined ? null : await desktopApplicationIcon(fields.Icon, directories)
+    applications.push({ id: entryPath, name, default: id === preferred,
+      icon: icon === null ? null : `data:${icon.contentType};base64,${icon.bytes.toString('base64')}` })
+  }
+  return applications
+}
diff --git a/packages/util/native-command/src/file-applications-windows.ts b/packages/util/native-command/src/file-applications-windows.ts
new file mode 100644
index 0000000000..a468c9979c
--- /dev/null
+++ b/packages/util/native-command/src/file-applications-windows.ts
@@ -0,0 +1,233 @@
+/** Windows Shell association queries and invocation; paths are encoded data, never PowerShell expressions. */
+import type { NativeCommandRunner } from './runner.ts'
+
+/** Shell interfaces are declared in their native vtable order; Invoke preserves packaged-app and DDE handling. */
+const WINDOWS_ASSOCIATIONS = String.raw`
+using System;
+using System.Collections.Generic;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
+using System.Text;
+
+public static class DshFileAssociations {
+  [ComImport, Guid("973810ae-9599-4b88-9e4d-6ee98c9552da"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface IEnumHandlers {
+    [PreserveSig] int Next(uint count, out IHandler handler, out uint fetched);
+  }
+  [ComImport, Guid("f04061ac-1659-4a3f-a954-775aa57fc083"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface IHandler {
+    void GetName([MarshalAs(UnmanagedType.LPWStr)] out string name);
+    void GetUIName([MarshalAs(UnmanagedType.LPWStr)] out string name);
+    void GetIconLocation([MarshalAs(UnmanagedType.LPWStr)] out string path, out int index);
+    [PreserveSig] int IsRecommended();
+    void MakeDefault([MarshalAs(UnmanagedType.LPWStr)] string description);
+    void Invoke(IDataObject data);
+    void CreateInvoker(IDataObject data, [MarshalAs(UnmanagedType.Interface)] out object invoker);
+  }
+  [ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  public interface IShellItem {
+    void BindToHandler(IntPtr context, ref Guid handler, ref Guid iid, [MarshalAs(UnmanagedType.Interface)] out IDataObject data);
+  }
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  static extern void SHAssocEnumHandlers(string extension, uint filter, out IEnumHandlers handlers);
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  static extern void SHCreateItemFromParsingName(string path, IntPtr context, ref Guid iid, out IShellItem item);
+  [DllImport("shlwapi.dll", CharSet = CharSet.Unicode)]
+  static extern int AssocQueryString(uint flags, uint kind, string association, string extra, StringBuilder output, ref uint size);
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode)]
+  static extern int SHDefExtractIcon(string path, int index, uint flags, out IntPtr large, out IntPtr small, uint size);
+  [DllImport("user32.dll")]
+  static extern bool DestroyIcon(IntPtr icon);
+
+  [DllImport("shlwapi.dll", PreserveSig = false)]
+  static extern void SHCreateThreadRef(IntPtr count, out IntPtr reference);
+  [DllImport("shlwapi.dll", PreserveSig = false)]
+  static extern void SHSetThreadRef(IntPtr reference);
+  [DllImport("shell32.dll")]
+  static extern void SHSetInstanceExplorer(IntPtr reference);
+  [StructLayout(LayoutKind.Sequential)]
+  struct Message {
+    public IntPtr window;
+    public uint message;
+    public UIntPtr wParam;
+    public IntPtr lParam;
+    public uint time;
+    public int x, y;
+    public uint reserved;
+  }
+  [DllImport("user32.dll", SetLastError = true)]
+  static extern UIntPtr SetTimer(IntPtr window, UIntPtr id, uint milliseconds, IntPtr callback);
+  [DllImport("user32.dll")]
+  static extern bool KillTimer(IntPtr window, UIntPtr id);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)]
+  static extern int GetMessage(out Message message, IntPtr window, uint min, uint max);
+  [DllImport("user32.dll")]
+  static extern bool TranslateMessage(ref Message message);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)]
+  static extern IntPtr DispatchMessage(ref Message message);
+
+  // Shell handlers may return before their asynchronous launch work releases the host.
+  // The shared Shell reference, rather than an arbitrary delay, owns that lifetime.
+  static void WithShellLifetime(Action action) {
+    IntPtr count = Marshal.AllocHGlobal(sizeof(int));
+    IntPtr reference = IntPtr.Zero;
+    try {
+      Marshal.WriteInt32(count, 0);
+      SHCreateThreadRef(count, out reference);
+      SHSetThreadRef(reference);
+      SHSetInstanceExplorer(reference);
+      int owned = Marshal.ReadInt32(count);
+      try { action(); }
+      finally {
+        if (Marshal.ReadInt32(count) > owned) {
+          // USER_TIMER_MINIMUM wakes the STA to inspect the reference count while dispatching COM work.
+          UIntPtr timer = SetTimer(IntPtr.Zero, UIntPtr.Zero, 10, IntPtr.Zero);
+          if (timer == UIntPtr.Zero) throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error());
+          try {
+            while (Marshal.ReadInt32(count) > owned) {
+              Message message;
+              if (GetMessage(out message, IntPtr.Zero, 0, 0) <= 0) throw new InvalidOperationException("Shell handoff message loop ended");
+              TranslateMessage(ref message);
+              DispatchMessage(ref message);
+            }
+          } finally { KillTimer(IntPtr.Zero, timer); }
+        }
+      }
+    } finally {
+      SHSetInstanceExplorer(IntPtr.Zero);
+      SHSetThreadRef(IntPtr.Zero);
+      int remaining = reference == IntPtr.Zero ? 0 : Marshal.Release(reference);
+      // An interrupted drain leaves its counter owned by the terminating helper process.
+      if (remaining == 0) Marshal.FreeHGlobal(count);
+    }
+  }
+
+  public sealed class Application {
+    public string id;
+    public string name;
+    public string icon;
+    public bool @default;
+  }
+  static string Associated(string extension, uint kind) {
+    uint size = 0;
+    AssocQueryString(0, kind, extension, null, null, ref size);
+    if (size == 0) return null;
+    var text = new StringBuilder((int)size);
+    return AssocQueryString(0, kind, extension, null, text, ref size) == 0 ? text.ToString() : null;
+  }
+  static string IconData(IHandler handler) {
+    IntPtr large = IntPtr.Zero, small = IntPtr.Zero;
+    try {
+      string source; int index;
+      handler.GetIconLocation(out source, out index);
+      source = Environment.ExpandEnvironmentVariables(source);
+      if (Path.GetExtension(source).Equals(".png", StringComparison.OrdinalIgnoreCase)) {
+        using (var original = Image.FromFile(source))
+        using (var resized = new Bitmap(original, new Size(32, 32)))
+        using (var stream = new MemoryStream()) {
+          resized.Save(stream, ImageFormat.Png);
+          return "data:image/png;base64," + Convert.ToBase64String(stream.ToArray());
+        }
+      }
+      if (SHDefExtractIcon(source, index, 0, out large, out small, 32) != 0 || large == IntPtr.Zero) return null;
+      using (var image = Icon.FromHandle(large))
+      using (var bitmap = image.ToBitmap())
+      using (var stream = new MemoryStream()) {
+        bitmap.Save(stream, ImageFormat.Png);
+        return "data:image/png;base64," + Convert.ToBase64String(stream.ToArray());
+      }
+    } catch (Exception) {
+      // Missing icon resources do not make the application unusable.
+      return null;
+    } finally {
+      if (large != IntPtr.Zero) DestroyIcon(large);
+      if (small != IntPtr.Zero) DestroyIcon(small);
+    }
+  }
+  static void Visit(string path, Action<IHandler> visit) {
+    var extension = Path.GetExtension(path);
+    if (extension.Length == 0) return;
+    IEnumHandlers handlers;
+    SHAssocEnumHandlers(extension, 0, out handlers);
+    try {
+      while (true) {
+        IHandler handler; uint fetched;
+        int result = handlers.Next(1, out handler, out fetched);
+        Marshal.ThrowExceptionForHR(result);
+        if (result != 0 || fetched == 0) break;
+        try { visit(handler); } finally { Marshal.FinalReleaseComObject(handler); }
+      }
+    } finally { Marshal.FinalReleaseComObject(handlers); }
+  }
+  public static Application[] List(string path) {
+    var extension = Path.GetExtension(path);
+    var executable = extension.Length == 0 ? null : Associated(extension, 2);
+    var appId = extension.Length == 0 ? null : Associated(extension, 21);
+    var apps = new List<Application>();
+    var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+    Visit(path, delegate(IHandler handler) {
+      string id, name;
+      handler.GetName(out id); handler.GetUIName(out name);
+      if (!seen.Add(id)) return;
+      apps.Add(new Application { id = id, name = name, icon = IconData(handler),
+        @default = String.Equals(id, executable, StringComparison.OrdinalIgnoreCase) || String.Equals(id, appId, StringComparison.OrdinalIgnoreCase) });
+    });
+    return apps.ToArray();
+  }
+  public static void Open(string path, string application) {
+    WithShellLifetime(delegate { OpenRegistered(path, application); });
+  }
+  static void OpenRegistered(string path, string application) {
+    bool opened = false;
+    Visit(path, delegate(IHandler handler) {
+      string id; handler.GetName(out id);
+      if (opened || !String.Equals(id, application, StringComparison.OrdinalIgnoreCase)) return;
+      var iid = typeof(IShellItem).GUID;
+      IShellItem item;
+      SHCreateItemFromParsingName(path, IntPtr.Zero, ref iid, out item);
+      IDataObject data = null;
+      try {
+        var bhid = new Guid("b8c0bd9f-ed24-455c-83e6-d5390c4fe8c4");
+        var dataIid = typeof(IDataObject).GUID;
+        item.BindToHandler(IntPtr.Zero, ref bhid, ref dataIid, out data);
+        handler.Invoke(data);
+        opened = true;
+      } finally {
+        if (data != null) Marshal.FinalReleaseComObject(data);
+        Marshal.FinalReleaseComObject(item);
+      }
+    });
+    if (!opened) throw new InvalidOperationException("Application is not registered for this file");
+  }
+}`
+
+/**
+ * Execute the Windows Shell adapter in a Unicode STA PowerShell process.
+ * @param path - Windows file path, translated by the caller for WSL.
+ * @param application - registered handler to invoke; null requests the application list.
+ * @param signal - caller cancellation.
+ * @param run - native command runner.
+ * @returns adapter output; query mode emits a JSON array.
+ */
+export async function windowsFileApplications(
+  path: string, application: string | null, signal: AbortSignal, run: NativeCommandRunner,
+): Promise<string> {
+  const encodedPath = Buffer.from(path).toString('base64')
+  const encodedApplication = Buffer.from(application ?? '').toString('base64')
+  const script = `$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+Add-Type -ReferencedAssemblies System,System.Core,System.Drawing -TypeDefinition @'
+${WINDOWS_ASSOCIATIONS}
+'@
+$path = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))
+$application = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedApplication}'))
+${application === null ? 'ConvertTo-Json -InputObject @([DshFileAssociations]::List($path)) -Depth 4 -Compress' : '[DshFileAssociations]::Open($path, $application)'}
+`
+  const result = await run('powershell.exe', [
+    '-NoProfile', '-NonInteractive', '-STA', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64'),
+  ], signal)
+  return result.stdout
+}
diff --git a/packages/util/native-command/src/file-applications.ts b/packages/util/native-command/src/file-applications.ts
new file mode 100644
index 0000000000..7a9b7f9ea8
--- /dev/null
+++ b/packages/util/native-command/src/file-applications.ts
@@ -0,0 +1,110 @@
+/** Native file associations queried from the desktop that owns the path. */
+import { runNativeCommand } from './runner.ts'
+import { linuxFileApplications } from './file-applications-linux.ts'
+import { windowsFileApplications } from './file-applications-windows.ts'
+import { nativeFileManager } from './path-opener.ts'
+import type { PathOpenerInternals } from './path-opener.ts'
+import { parseNativeFileApplications, type NativeFileApplication } from './types.ts'
+
+/** AppKit runs inside the system JXA host; paths arrive as argv, never executable source. */
+const MAC_APPLICATIONS = `
+ObjC.import('AppKit');
+function run(argv) {
+  var workspace = $.NSWorkspace.sharedWorkspace;
+  var file = $.NSURL.fileURLWithPath(argv[0]);
+  var preferred = workspace.URLForApplicationToOpenURL(file);
+  var preferredPath = preferred.isNil() ? null : ObjC.unwrap(preferred.path);
+  var urls = workspace.URLsForApplicationsToOpenURL(file);
+  var apps = [];
+  for (var i = 0; i < urls.count; i++) {
+    var url = urls.objectAtIndex(i);
+    var path = ObjC.unwrap(url.path);
+    var image = null;
+    if (argv[1] === 'icons') {
+      var icon = workspace.iconForFile(path);
+      var thumbnail = $.NSImage.alloc.initWithSize($.NSMakeSize(32, 32));
+      thumbnail.lockFocus;
+      icon.drawInRectFromRectOperationFraction($.NSMakeRect(0, 0, 32, 32), $.NSZeroRect, $.NSCompositingOperationSourceOver, 1);
+      thumbnail.unlockFocus;
+      var bitmap = $.NSBitmapImageRep.imageRepWithData(thumbnail.TIFFRepresentation);
+      var png = bitmap.representationUsingTypeProperties($.NSBitmapImageFileTypePNG, $({}));
+      image = png.isNil() ? null : 'data:image/png;base64,' + ObjC.unwrap(png.base64EncodedStringWithOptions(0));
+    }
+    apps.push({
+      id: path,
+      name: ObjC.unwrap($.NSFileManager.defaultManager.displayNameAtPath(path)),
+      default: path === preferredPath,
+      icon: image
+    });
+  }
+  return JSON.stringify(apps);
+}`
+
+/**
+ * List registered handlers in OS preference order, including the current default and application icons.
+ * @param path - verified absolute local file path.
+ * @param signal - caller lifetime, propagated to the OS query.
+ * @param internals - platform and command adapter for deterministic tests.
+ * @returns current file handlers; an empty list when the platform has no association query.
+ */
+export async function nativeFileApplications(
+  path: string, signal: AbortSignal, internals: PathOpenerInternals = {},
+): Promise<readonly NativeFileApplication[]> {
+  return queryFileApplications(path, signal, internals, true)
+}
+
+/** Query metadata with optional macOS icon rendering for display or launch authorization. */
+async function queryFileApplications(
+  path: string, signal: AbortSignal, internals: PathOpenerInternals, icons: boolean,
+): Promise<readonly NativeFileApplication[]> {
+  signal.throwIfAborted()
+  const target = await desktopTarget(path, signal, internals)
+  const run = internals.run ?? runNativeCommand
+  if (target.platform === 'linux') return linuxFileApplications(path, signal, run, internals.env ?? process.env)
+  let stdout: string
+  if (target.platform === 'darwin') {
+    stdout = (await run('osascript', ['-l', 'JavaScript', '-e', MAC_APPLICATIONS, target.path, icons ? 'icons' : 'handlers'], signal)).stdout
+  } else if (target.platform === 'win32') {
+    stdout = await windowsFileApplications(target.path, null, signal, run)
+  } else return []
+  return parseNativeFileApplications(JSON.parse(stdout))
+}
+
+/**
+ * Open a file in a currently registered handler; stale or arbitrary application identifiers are rejected.
+ * @param path - verified absolute local file path.
+ * @param application - identifier returned by the file association query.
+ * @param signal - caller lifetime, propagated to query and launch.
+ * @param internals - platform and command adapter for deterministic tests.
+ * @returns after the system launcher accepts the file.
+ */
+export async function openNativeFileApplication(
+  path: string, application: string, signal: AbortSignal, internals: PathOpenerInternals = {},
+): Promise<void> {
+  const target = await desktopTarget(path, signal, internals)
+  const run = internals.run ?? runNativeCommand
+  if (target.platform === 'win32') {
+    await windowsFileApplications(target.path, application, signal, run)
+    return
+  }
+  const apps = await queryFileApplications(path, signal, internals, false)
+  if (!apps.some(app => app.id === application)) throw new Error('Application is not registered for this file')
+  if (target.platform === 'linux') await run('gio', ['launch', application, path], signal)
+  else await run('open', ['-a', application, path], signal)
+}
+
+/** Resolve the desktop that owns the file, including Windows applications reached from WSL. */
+async function desktopTarget(
+  path: string, signal: AbortSignal, internals: PathOpenerInternals,
+): Promise<{ platform: NodeJS.Platform; path: string }> {
+  signal.throwIfAborted()
+  const platform = internals.platform ?? process.platform
+  if (platform === 'linux' && nativeFileManager(internals) === 'explorer') {
+    const translated = await (internals.run ?? runNativeCommand)('wslpath', ['-w', path], signal)
+    signal.throwIfAborted()
+    const windowsPath = translated.stdout.replace(/[\r\n]+$/, '')
+    if (windowsPath === '') throw new Error('wslpath returned no Windows path')
+    return { platform: 'win32', path: windowsPath }
+  }
+  return { platform, path }
+}
diff --git a/packages/util/native-command/src/index.ts b/packages/util/native-command/src/index.ts
index 29a0f16c18..9ad8e0883c 100644
--- a/packages/util/native-command/src/index.ts
+++ b/packages/util/native-command/src/index.ts
@@ -18,3 +18,8 @@ export type {
   PathOpenerInternals,
   PathOpenerRunner,
 } from './path-opener.ts'
+
+export { nativeFileApplications, openNativeFileApplication } from './file-applications.ts'
+export type { NativeFileApplication } from './types.ts'
+
+export { desktopEntryFields, desktopDataDirectories, desktopApplicationIcon } from './desktop-entry.ts'
diff --git a/packages/util/native-command/src/types.ts b/packages/util/native-command/src/types.ts
new file mode 100644
index 0000000000..5af42bb996
--- /dev/null
+++ b/packages/util/native-command/src/types.ts
@@ -0,0 +1,34 @@
+/** Browser-safe metadata for native file associations. */
+
+/** One OS-registered application capable of opening the requested file. */
+export interface NativeFileApplication {
+  /** OS application identifier; callers must revalidate it against the file's current handlers before opening. */
+  readonly id: string
+  readonly name: string
+  readonly default: boolean
+  /** PNG or SVG data URL, or null when the desktop supplies no icon. */
+  readonly icon: string | null
+}
+
+/**
+ * Validate file association metadata received from a native process or authenticated Host.
+ * @param value - decoded application list.
+ * @returns validated application metadata.
+ * @throws Error for malformed entries or unsupported icon URLs.
+ */
+export function parseNativeFileApplications(value: unknown): readonly NativeFileApplication[] {
+  if (!Array.isArray(value)) throw new Error('Invalid native application list')
+  const applications: NativeFileApplication[] = []
+  const entries: readonly unknown[] = value
+  for (const entry of entries) {
+    if (typeof entry !== 'object' || entry === null
+      || !('id' in entry) || !('name' in entry) || !('default' in entry) || !('icon' in entry)
+      || typeof entry.id !== 'string' || entry.id.length === 0
+      || typeof entry.name !== 'string' || typeof entry.default !== 'boolean'
+      || !(entry.icon === null || (typeof entry.icon === 'string' && /^data:image\/(?:png|svg\+xml);base64,[A-Za-z0-9+/=]+$/.test(entry.icon)))) {
+      throw new Error('Invalid native application entry')
+    }
+    applications.push({ id: entry.id, name: entry.name, default: entry.default, icon: entry.icon })
+  }
+  return applications
+}
diff --git a/packages/util/native-command/tests/file-applications-linux-native.spec.ts b/packages/util/native-command/tests/file-applications-linux-native.spec.ts
new file mode 100644
index 0000000000..42cc4083cf
--- /dev/null
+++ b/packages/util/native-command/tests/file-applications-linux-native.spec.ts
@@ -0,0 +1,59 @@
+/** Real GIO discovery and desktop-entry launch in private XDG data/config roots. */
+import { execFile, spawnSync } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it, onTestFinished, vi } from 'vitest'
+import { nativeFileApplications, openNativeFileApplication } from '../src/file-applications.ts'
+import type { NativeCommandRunner } from '../src/runner.ts'
+
+const gioAvailable = process.platform === 'linux' && spawnSync('gio', ['help'], { stdio: 'ignore' }).error === undefined
+const execute = promisify(execFile)
+
+/** Desktop Exec quoted-argument syntax; GIO performs its expansion. */
+function quoted(value: string): string {
+  return `"${value.replace(/[\\"`$]/g, match => `\\${match}`)}"`
+}
+
+it.skipIf(!gioAvailable)('queries and launches an installed Linux desktop entry through GIO', async ({ task }) => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-gio-associations-'))
+  const lifetime = new AbortController()
+  const active = new Set<Promise<Awaited<ReturnType<NativeCommandRunner>>>>()
+  onTestFinished(async () => {
+    lifetime.abort()
+    await Promise.allSettled([...active])
+    await rm(root, { recursive: true, force: true })
+  })
+  const data = join(root, 'data')
+  const config = join(root, 'config')
+  const empty = join(root, 'empty')
+  await mkdir(join(data, 'applications'), { recursive: true })
+  await mkdir(config)
+  await mkdir(empty)
+  const path = join(root, "测试 ' file.txt")
+  const script = join(root, 'handler.cjs')
+  const marker = join(root, 'opened.json')
+  await writeFile(path, 'plain text')
+  await writeFile(script, `require('node:fs').writeFileSync(${JSON.stringify(marker)}, JSON.stringify({ path: process.argv[2], pid: process.pid }));\n`)
+  const desktop = join(data, 'applications', 'dsh-test.desktop')
+  await writeFile(desktop, `[Desktop Entry]\nType=Application\nName=DSH Test Handler\nExec=${quoted(process.execPath)} ${quoted(script)} %f\nMimeType=text/plain;\n`)
+  await writeFile(join(data, 'applications', 'mimeinfo.cache'), '[MIME Cache]\ntext/plain=dsh-test.desktop;\n')
+  await writeFile(join(config, 'mimeapps.list'), '[Default Applications]\ntext/plain=dsh-test.desktop;\n')
+  const env = { ...process.env, XDG_DATA_HOME: data, XDG_DATA_DIRS: empty, XDG_CONFIG_HOME: config, XDG_CONFIG_DIRS: empty, LC_ALL: 'C' }
+  const run: NativeCommandRunner = (command, args, signal) => {
+    const task = execute(command, [...args], { signal, env, encoding: 'utf8' })
+    active.add(task)
+    void task.then(() => active.delete(task), () => active.delete(task))
+    return task
+  }
+  const apps = await nativeFileApplications(path, lifetime.signal, { run, env })
+  expect(apps).toContainEqual({ id: desktop, name: 'DSH Test Handler', default: true, icon: null })
+  await openNativeFileApplication(path, desktop, lifetime.signal, { run, env })
+  let opened: { path: string; pid: number } | undefined
+  await vi.waitFor(async () => {
+    opened = JSON.parse(await readFile(marker, 'utf8')) as { path: string; pid: number }
+    expect(opened.path).toBe(path)
+  }, { timeout: task.timeout })
+  await vi.waitFor(() => { expect(() => process.kill(opened!.pid, 0)).toThrow() }, { timeout: task.timeout })
+})
diff --git a/packages/util/native-command/tests/file-applications-linux.spec.ts b/packages/util/native-command/tests/file-applications-linux.spec.ts
new file mode 100644
index 0000000000..7615218f3b
--- /dev/null
+++ b/packages/util/native-command/tests/file-applications-linux.spec.ts
@@ -0,0 +1,64 @@
+/** Linux association parsing over isolated installed-entry fixtures and an injected OS command runner. */
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it, onTestFinished, vi } from 'vitest'
+import { desktopApplicationIcon } from '../src/desktop-entry.ts'
+import { nativeFileApplications, openNativeFileApplication } from '../src/file-applications.ts'
+import type { NativeCommandRunner } from '../src/runner.ts'
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-file-apps-'))
+  onTestFinished(() => rm(root, { recursive: true, force: true }))
+  await mkdir(join(root, 'applications', 'nested'), { recursive: true })
+  await mkdir(join(root, 'pixmaps'))
+  await writeFile(join(root, 'applications', 'player.desktop'), '[Desktop Entry]\nName=Player\nName[zh_CN]=播放器\nIcon=player\nExec=player %f\n[Desktop Action Extra]\nName=Wrong\n')
+  await writeFile(join(root, 'applications', 'nested', 'other.desktop'), '[Desktop Entry]\nName=Other\nExec=other %f\n')
+  await writeFile(join(root, 'pixmaps', 'player.svg'), '<svg xmlns="http://www.w3.org/2000/svg"/>')
+  const run = vi.fn<NativeCommandRunner>(async (command, args) => ({
+    stdout: command === 'gio' && args[0] === 'info' ? '  standard::content-type: audio/mpeg\n'
+      : command === 'env' ? 'Default application for audio/mpeg: player.desktop\nRegistered applications:\n  player.desktop\n  nested-other.desktop\n  missing.desktop\nRecommended applications:\n  player.desktop\n' : '', stderr: '',
+  }))
+  return { root, run, facts: { platform: 'linux' as const, osRelease: 'linux', env: { XDG_DATA_HOME: root, XDG_DATA_DIRS: '', LANG: 'zh_CN.UTF-8' }, run } }
+}
+
+it('deduplicates GIO handlers, resolves nested ids, localizes names, and reuses desktop artwork', async () => {
+  const { root, facts, run } = await fixture()
+  const signal = new AbortController().signal
+  const apps = await nativeFileApplications('/file.mp3', signal, facts)
+  expect(apps).toEqual([
+    { id: join(root, 'applications', 'player.desktop'), name: '播放器', default: true, icon: expect.stringMatching(/^data:image\/svg\+xml;base64,/) as string },
+    { id: join(root, 'applications', 'nested', 'other.desktop'), name: 'Other', default: false, icon: null },
+  ])
+  await openNativeFileApplication('/file.mp3', apps[0]!.id, signal, facts)
+  expect(run).toHaveBeenLastCalledWith('gio', ['launch', apps[0]!.id, '/file.mp3'], signal)
+  await expect(openNativeFileApplication('/file.mp3', '/unregistered.desktop', signal, facts)).rejects.toThrow('not registered')
+})
+
+it('keeps nondefault applications when the desktop has no default and omits hidden or unnamed entries', async () => {
+  const { root, facts, run } = await fixture()
+  await writeFile(join(root, 'applications', 'player.desktop'), '[Desktop Entry]\nHidden=true\nName=Hidden\n')
+  await writeFile(join(root, 'applications', 'unnamed.desktop'), '[Desktop Entry]\nExec=unnamed\n')
+  run.mockImplementation(async command => ({ stdout: command === 'gio' ? 'standard::content-type: audio/mpeg' : 'Registered applications:\n  player.desktop\n  unnamed.desktop\n  nested-other.desktop\n', stderr: '' }))
+  expect(await nativeFileApplications('/file.mp3', new AbortController().signal, facts)).toEqual([
+    { id: join(root, 'applications', 'nested', 'other.desktop'), name: 'Other', default: false, icon: null },
+  ])
+})
+
+it('rejects missing content-type metadata instead of fabricating associations', async () => {
+  const { facts, run } = await fixture()
+  run.mockResolvedValue({ stdout: 'no content type', stderr: '' })
+  await expect(nativeFileApplications('/file.mp3', new AbortController().signal, facts)).rejects.toThrow('content type')
+})
+
+
+it('tolerates absent desktop roots and directory-shaped icon paths without a locale override', async () => {
+  const { root, facts } = await fixture()
+  const icon = join(root, 'folder.png')
+  await mkdir(icon)
+  expect(await desktopApplicationIcon(icon, [])).toBeNull()
+  const apps = await nativeFileApplications('/file.mp3', new AbortController().signal, {
+    ...facts, env: { XDG_DATA_HOME: root, XDG_DATA_DIRS: join(root, 'absent') },
+  })
+  expect(apps[0]?.name).toBe('Player')
+})
diff --git a/packages/util/native-command/tests/file-applications-windows.spec.ts b/packages/util/native-command/tests/file-applications-windows.spec.ts
new file mode 100644
index 0000000000..9f009d0b91
--- /dev/null
+++ b/packages/util/native-command/tests/file-applications-windows.spec.ts
@@ -0,0 +1,111 @@
+/** Real Windows Shell discovery and invocation with a private extension and a private executable. */
+import { randomUUID } from 'node:crypto'
+import { mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it, vi, onTestFinished } from 'vitest'
+import { nativeFileApplications, openNativeFileApplication } from '../src/file-applications.ts'
+import { runNativeCommand, type NativeCommandRunner } from '../src/runner.ts'
+
+/** Encode fixture data without placing its quotes or Unicode in executable PowerShell text. */
+function literal(value: string): string {
+  return `[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${Buffer.from(value).toString('base64')}'))`
+}
+
+it.skipIf(process.platform !== 'win32')('queries and invokes a registered Windows handler through the system Shell', async ({ task, signal: testSignal, onTestFailed }) => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-windows-association-'))
+  const suffix = randomUUID().replaceAll('-', '')
+  const extension = `.dsh${suffix}`
+  const progId = `DSH.Test.${suffix}`
+  const appName = `dsh-handler-${suffix}.exe`
+  const executable = join(root, appName)
+  const path = join(root, `${String.fromCharCode(0x6d4b, 0x8bd5)} ' audio${extension}`)
+  const marker = join(root, 'opened.txt')
+  const lifetime = new AbortController()
+  const signal = AbortSignal.any([testSignal, lifetime.signal])
+  const active = new Set<Promise<Awaited<ReturnType<NativeCommandRunner>>>>()
+  let phase = 'compile fixture'
+  onTestFailed(async () => {
+    const opened = await readFile(marker, 'utf8').catch(() => '(no handoff marker)')
+    console.error('Windows association fixture:', phase, 'active native commands:', active.size, opened)
+  })
+  const run: NativeCommandRunner = (command, args, operationSignal) => {
+    const pending = runNativeCommand(command, args, operationSignal)
+    active.add(pending)
+    void pending.then(() => active.delete(pending), () => active.delete(pending))
+    return pending
+  }
+  const runScript = async (source: string): Promise<void> => {
+    await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(source, 'utf16le').toString('base64')], signal)
+  }
+  onTestFinished(async () => {
+    lifetime.abort()
+    await Promise.allSettled([...active])
+    try {
+      await runNativeCommand('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(`
+$root = [Microsoft.Win32.Registry]::CurrentUser
+$root.DeleteSubKeyTree('Software\\Classes\\${extension}', $false)
+$root.DeleteSubKeyTree('Software\\Classes\\${progId}', $false)
+$root.DeleteSubKeyTree('Software\\Classes\\Applications\\${appName}', $false)
+`, 'utf16le').toString('base64')], new AbortController().signal)
+    } finally { await rm(root, { recursive: true, force: true }) }
+  })
+  await writeFile(path, 'test')
+  // A dedicated executable accepts the file directly; no pre-existing Node association can discard fixture-script arguments.
+  await runScript(`$ErrorActionPreference = 'Stop'
+Add-Type -ReferencedAssemblies System -OutputAssembly (${literal(executable)}) -OutputType ConsoleApplication -TypeDefinition @'
+using System;
+using System.IO;
+using System.Diagnostics;
+public static class Handler {
+  public static void Main(string[] args) {
+    File.WriteAllLines(${JSON.stringify(marker)}, new string[] { args.Length == 0 ? "(no file argument)" : args[0], Process.GetCurrentProcess().Id.ToString() });
+  }
+}
+'@
+`)
+  phase = 'verify fixture executable'
+  await run(executable, [path], signal)
+  expect((await readFile(marker, 'utf8')).split(/\r?\n/)[0]).toBe(path)
+  await rm(marker)
+  phase = 'register association'
+  const command = literal(`"${executable}" "%1"`)
+  await runScript(`$ErrorActionPreference = 'Stop'
+$root = [Microsoft.Win32.Registry]::CurrentUser
+$key = $root.CreateSubKey('Software\\Classes\\${extension}')
+$key.SetValue('', '${progId}'); $key.Dispose()
+$key = $root.CreateSubKey('Software\\Classes\\${extension}\\OpenWithProgids')
+$key.SetValue('${progId}', ''); $key.Dispose()
+$key = $root.CreateSubKey('Software\\Classes\\${progId}\\shell\\open\\command')
+$key.SetValue('', ${command}); $key.Dispose()
+$key = $root.CreateSubKey('Software\\Classes\\Applications\\${appName}\\shell\\open\\command')
+$key.SetValue('', ${command}); $key.Dispose()
+$key = $root.CreateSubKey('Software\\Classes\\Applications\\${appName}\\SupportedTypes')
+$key.SetValue('${extension}', ''); $key.Dispose()
+`)
+  phase = 'query associations'
+  const applications = await nativeFileApplications(path, signal, { run })
+  const expected = applications.find(app => app.id.toLowerCase() === executable.toLowerCase())
+  expect(expected).toMatchObject({ default: true, name: expect.any(String) as string })
+  phase = 'invoke handler'
+  await openNativeFileApplication(path, expected!.id, signal, { run })
+  phase = 'wait for fixture marker'
+  let opened: string[] = []
+  await vi.waitUntil(async () => {
+    signal.throwIfAborted()
+    try { opened = (await readFile(marker, 'utf8')).trim().split(/\r?\n/) } catch (_error) { return false }
+    return true
+  }, { timeout: task.timeout })
+  // Windows Shell can expand an 8.3 input path to its long spelling.
+  expect(await realpath(opened[0]!)).toBe(await realpath(path))
+  const pid = Number(opened[1])
+  expect(pid).toBeGreaterThan(0)
+  phase = 'wait for fixture exit'
+  await vi.waitUntil(() => {
+    signal.throwIfAborted()
+    try { process.kill(pid, 0); return false } catch (error) {
+      if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ESRCH') return true
+      throw error
+    }
+  }, { timeout: task.timeout })
+})
diff --git a/packages/util/native-command/tests/file-applications.spec.ts b/packages/util/native-command/tests/file-applications.spec.ts
new file mode 100644
index 0000000000..2dfe31a9da
--- /dev/null
+++ b/packages/util/native-command/tests/file-applications.spec.ts
@@ -0,0 +1,88 @@
+/** File association results and explicit handler authorization at the native command adapter. */
+import { describe, expect, it, vi, onTestFinished } from 'vitest'
+import * as runner from '../src/runner.ts'
+import { nativeFileApplications, openNativeFileApplication } from '../src/file-applications.ts'
+
+const application = { id: '/Applications/Music.app', name: 'Music', default: true, icon: null }
+const signal = new AbortController().signal
+
+describe('native file associations', () => {
+  it('passes file paths as arguments and preserves the desktop default', async () => {
+    const run = vi.fn(async () => ({ stdout: JSON.stringify([application]), stderr: '' }))
+    const path = '/tmp/中文 $(touch nope).mp3'
+    await expect(nativeFileApplications(path, signal, { platform: 'darwin', run })).resolves.toEqual([application])
+    expect(run).toHaveBeenCalledWith('osascript', ['-l', 'JavaScript', '-e', expect.any(String), path, 'icons'], signal)
+  })
+
+  it.each(['{}', '[null]', '[{"id":1}]', JSON.stringify([{ ...application, icon: 'javascript:alert(1)' }])])('rejects malformed native output %s', async (stdout) => {
+    await expect(nativeFileApplications('/file.mp3', signal, {
+      platform: 'darwin', run: async () => ({ stdout, stderr: '' }),
+    })).rejects.toThrow()
+  })
+
+  it('launches only a currently registered application with argv', async () => {
+    const run = vi.fn(async () => ({ stdout: JSON.stringify([application]), stderr: '' }))
+    await openNativeFileApplication('/file.mp3', application.id, signal, { platform: 'darwin', run })
+    expect(run).toHaveBeenNthCalledWith(1, 'osascript', ['-l', 'JavaScript', '-e', expect.any(String), '/file.mp3', 'handlers'], signal)
+    expect(run).toHaveBeenLastCalledWith('open', ['-a', application.id, '/file.mp3'], signal)
+    run.mockClear()
+    await expect(openNativeFileApplication('/file.mp3', '/arbitrary.app', signal, { platform: 'darwin', run })).rejects.toThrow('not registered')
+    expect(run).toHaveBeenCalledOnce()
+  })
+
+  it('does not query after cancellation or on unsupported platforms', async () => {
+    const run = vi.fn()
+    await expect(nativeFileApplications('/file.mp3', signal, { platform: 'freebsd', run })).resolves.toEqual([])
+    await expect(nativeFileApplications('/file.mp3', AbortSignal.abort(), { platform: 'darwin', run })).rejects.toThrow()
+    expect(run).not.toHaveBeenCalled()
+  })
+})
+
+
+it('uses the production command adapter and current platform when no override is supplied', async () => {
+  const run = vi.spyOn(runner, 'runNativeCommand').mockImplementation(async command => ({
+    stdout: command === 'gio' ? 'standard::content-type: audio/mpeg' : command === 'env' ? 'No applications found' : JSON.stringify([application]), stderr: '',
+  }))
+  onTestFinished(() => { run.mockRestore() })
+  expect(await nativeFileApplications('/file.mp3', signal)).toEqual(process.platform === 'linux' ? [] : [application])
+  await openNativeFileApplication('/file.mp3', application.id, signal, { platform: 'darwin' })
+  expect(run).toHaveBeenLastCalledWith('open', ['-a', application.id, '/file.mp3'], signal)
+})
+
+
+it('encodes Windows query and invocation data separately from native adapter source', async () => {
+  const run = vi.fn<runner.NativeCommandRunner>(async () => ({ stdout: JSON.stringify([application]), stderr: '' }))
+  const path = "C:\\测试\\a'; write-host nope.mp3"
+  expect(await nativeFileApplications(path, signal, { platform: 'win32', run })).toEqual([application])
+  const query = Buffer.from(run.mock.calls[0]![1].at(-1)!, 'base64').toString('utf16le')
+  expect(query).toContain(Buffer.from(path).toString('base64'))
+  expect(query).not.toContain(path)
+  expect(query).toContain('::List($path)')
+  await openNativeFileApplication(path, application.id, signal, { platform: 'win32', run })
+  expect(Buffer.from(run.mock.calls[1]![1].at(-1)!, 'base64').toString('utf16le')).toContain('::Open($path, $application)')
+  expect(run.mock.calls[1]![0]).toBe('powershell.exe')
+})
+
+it('uses the Windows desktop for WSL paths and rejects an empty translation', async () => {
+  const run = vi.fn<runner.NativeCommandRunner>(async command => ({
+    stdout: command === 'wslpath' ? 'C:\\音频.mp3\n' : JSON.stringify([application]), stderr: '',
+  }))
+  const facts = { platform: 'linux' as const, osRelease: 'microsoft', env: {}, run }
+  expect(await nativeFileApplications('/mnt/c/音频.mp3', signal, facts)).toEqual([application])
+  await openNativeFileApplication('/mnt/c/音频.mp3', application.id, signal, facts)
+  expect(run).toHaveBeenCalledWith('wslpath', ['-w', '/mnt/c/音频.mp3'], signal)
+  const empty = async () => ({ stdout: '', stderr: '' })
+  await expect(nativeFileApplications('/a', signal, { ...facts, run: empty })).rejects.toThrow('no Windows path')
+})
+
+
+it('uses production environment and runner defaults for Linux and WSL', async () => {
+  const run = vi.spyOn(runner, 'runNativeCommand').mockImplementation(async command => ({
+    stdout: command === 'gio' ? 'standard::content-type: audio/mpeg'
+      : command === 'env' ? 'No applications found'
+        : command === 'wslpath' ? 'C:\\file.mp3\n' : JSON.stringify([application]), stderr: '',
+  }))
+  onTestFinished(() => { run.mockRestore() })
+  expect(await nativeFileApplications('/file.mp3', signal, { platform: 'linux', osRelease: 'linux' })).toEqual([])
+  expect(await nativeFileApplications('/file.mp3', signal, { platform: 'linux', osRelease: 'microsoft', env: {} })).toEqual([application])
+})
diff --git a/packages/util/package-manifest/README.i18n.yaml b/packages/util/package-manifest/README.i18n.yaml
index dee2ad6293..a83ac511d7 100644
--- a/packages/util/package-manifest/README.i18n.yaml
+++ b/packages/util/package-manifest/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. 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/package-manifest/README.md
-README.md: 86121432ba12329e111f2c796679ae019e403d7e
-README.zh.md: d4d9d8b5b7787ac9531918fb1f7084c7c8a7a8d1
+README.md: 7c4c4935412ca481dc5db2f9c182abf471faf269
+README.zh.md: 58a150ae32a7129c1f213f9268869b99ada99655
diff --git a/packages/util/package-manifest/README.md b/packages/util/package-manifest/README.md
index 86121432ba..7c4c493541 100644
--- a/packages/util/package-manifest/README.md
+++ b/packages/util/package-manifest/README.md
@@ -43,7 +43,7 @@ const manifest: DshPackageManifest = {
 }
 ```
 
-`DshPackageManifest` describes the package.json fields used by DSH, with required `name` and `version`; it is not an exhaustive npm schema. Local profile readers use `Partial<DshPackageManifest>` because profiles need no published version. `DshManifest` describes only public author fields under `dsh`. TypeScript checks the example and erases `import type`; these interfaces do not parse JSON or write a file.
+`DshPackageManifest` describes the package.json fields used by DSH, with required `name` and `version`; it is not an exhaustive npm schema. Local profile readers use `Partial<DshPackageManifest>` because profiles need no published version. `DshManifest` describes only public author fields under `dsh`. `DshBundleManifest.patch` is one patch file path or an ordered list of them, each relative to the package root; the launcher applies a list in order as one bundle layer. TypeScript checks the example and erases `import type`; these interfaces do not parse JSON or write a file.
 
 The following metadata fields are optional. Omitting them leaves the format version or compatible host versions undeclared; readers do not infer defaults.
 
@@ -52,7 +52,7 @@ The following metadata fields are optional. Omitting them leaves the format vers
 | `dsh.manifestVersion` | Manifest format identifier; the declared format is `1`, independent of the npm package version and Session format version. |
 | `engines.dsh` | Author-declared compatible DSH versions as a SemVer range, including exact prerelease versions. This field sits beside `engines.node` and `engines.npm`; an engines object may omit `dsh`. |
 
-`LocalizedText` carries literal text or a language map with a required English fallback. `PluginLocalizedMeta` carries optional display title and description fields, or a metadata diagnostic, for installed plugins. [App boot](../../boot/app-boot/README.md) reads these values; this package only supplies their types.
+`LocalizedText` carries literal text or a language map with a required English fallback. `PluginLocalizedMeta` carries optional display title, description, an image data URL resolved from `package.json.icon`, and metadata diagnostics for installed plugins. [App boot](../../boot/app-boot/README.md) reads these values; this package only supplies their types.
 
 Public composition declarations are defined in [`src/types.ts`](src/types.ts). Internal `configTrees`, `sessionFormatMigration`, and generated `moduleFallback` metadata remain owned by their image-packer, catalog, and launcher readers; the public types do not expose them.
 
diff --git a/packages/util/package-manifest/README.zh.md b/packages/util/package-manifest/README.zh.md
index d4d9d8b5b7..58a150ae32 100644
--- a/packages/util/package-manifest/README.zh.md
+++ b/packages/util/package-manifest/README.zh.md
@@ -43,7 +43,7 @@ const manifest: DshPackageManifest = {
 }
 ```
 
-`DshPackageManifest` 描述 DSH 使用的 package.json 字段，其中 `name` 和 `version` 必填；它不是完整的 npm schema（模式）。本地 profile 读取方使用 `Partial<DshPackageManifest>`，因为 profile 无需发布版本。`DshManifest` 仅描述 `dsh` 下的公共作者字段。TypeScript 检查示例并删除 `import type`；这些接口不解析 JSON，也不写入文件。
+`DshPackageManifest` 描述 DSH 使用的 package.json 字段，其中 `name` 和 `version` 必填；它不是完整的 npm schema（模式）。本地 profile 读取方使用 `Partial<DshPackageManifest>`，因为 profile 无需发布版本。`DshManifest` 仅描述 `dsh` 下的公共作者字段。`DshBundleManifest.patch` 是一个 patch 文件路径，或一个有序的路径列表，均相对于包根目录；launcher 按列表顺序把它们作为同一个组合包层应用。TypeScript 检查示例并删除 `import type`；这些接口不解析 JSON，也不写入文件。
 
 以下元数据字段均可选。省略时，格式版本或兼容的宿主版本保持未声明状态；读取方不推断默认值。
 
@@ -52,7 +52,7 @@ const manifest: DshPackageManifest = {
 | `dsh.manifestVersion` | manifest（元数据清单）格式标识；声明的格式为 `1`，独立于 npm 包版本和 Session 格式版本。 |
 | `engines.dsh` | 作者声明的兼容 DSH 版本，使用 SemVer 范围，也可填写精确的预发布版本。此字段与 `engines.node`、`engines.npm` 并列；engines 对象可省略 `dsh`。 |
 
-`LocalizedText` 携带字面文本或带必需英文回退值的语言映射。`PluginLocalizedMeta` 携带已安装插件的可选展示标题与描述字段，或元信息诊断。[App boot](../../boot/app-boot/README.zh.md) 读取这些值；本包只提供其类型。
+`LocalizedText` 携带字面文本或带必需英文回退值的语言映射。`PluginLocalizedMeta` 携带已安装插件的可选展示标题、描述、从 `package.json.icon` 解析的图片 data URL，以及元信息诊断。[App boot](../../boot/app-boot/README.zh.md) 读取这些值；本包只提供其类型。
 
 公共组合声明定义在 [`src/types.ts`](src/types.ts) 中。内部 `configTrees`、`sessionFormatMigration` 和生成的 `moduleFallback` 元数据分别由镜像打包器、目录生成器和启动器读取方拥有；公共类型不暴露这些字段。
 
diff --git a/packages/util/package-manifest/src/types.ts b/packages/util/package-manifest/src/types.ts
index d6f161f97e..cda212f5a8 100644
--- a/packages/util/package-manifest/src/types.ts
+++ b/packages/util/package-manifest/src/types.ts
@@ -12,6 +12,8 @@ export interface DshPackageManifest {
   version: string
   /** Package summary for discovery and display. */
   description?: string
+  /** SVG, PNG, JPEG, or WebP file relative to this manifest's directory, at most 256 KiB and contained there after realpath resolution. */
+  icon?: string
   /** Prevent npm publication, for example for local profile projects. */
   private?: boolean
   /** Packages installed alongside this package. */
@@ -39,12 +41,14 @@ export interface DshManifest {
 /** Literal text or translations indexed by lowercase language id, with a required English fallback. */
 export type LocalizedText = string | { readonly en: string; readonly [locale: string]: string }
 
-/** Validated plugin display fields or a diagnostic from reading exported locale files. */
+/** Validated plugin display fields and diagnostics from exported locales, manifests, or icon files. */
 export interface PluginLocalizedMeta {
   /** Display title; omission preserves the consumer's technical-name fallback. */
   readonly title?: LocalizedText
   /** Display introduction after locale and package-field fallback. */
   readonly description?: LocalizedText
+  /** Base64 image data URL read from the manifest's icon file; render as an image, not inline markup. */
+  readonly icon?: string
   /** Unmodified local metadata diagnostic; the plugin remains manageable. */
   readonly error?: string
 }
@@ -63,8 +67,8 @@ export interface DshEnginesManifest {
 
 /** The configuration layer exported by a bundle package. */
 export interface DshBundleManifest {
-  /** Patch file path relative to the declaring package root. */
-  patch: string
+  /** One patch file path, or an ordered list applied in sequence, each relative to the declaring package root. */
+  patch: string | string[]
 }
 
 /** The bundle composition declared by a profile directory. */
diff --git a/packages/web/web-search-deepseek/README.i18n.yaml b/packages/web/web-search-deepseek/README.i18n.yaml
index 713c6c7851..f0d546d923 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: 1fa8153b55e40edc869d6d332e3c35a46de0cd1b
-README.zh.md: a38c1e126a23033cd40ef468f98b35d7cc56d869
+README.md: 0617204fdddb9273f75bd9ad4028026c7ffc8060
+README.zh.md: b45b449f2d379f730a6a4f341e8359ed28aaeb0b
diff --git a/packages/web/web-search-deepseek/README.md b/packages/web/web-search-deepseek/README.md
index 1fa8153b55..0617204fdd 100644
--- a/packages/web/web-search-deepseek/README.md
+++ b/packages/web/web-search-deepseek/README.md
@@ -33,7 +33,7 @@ Choose this backend when a deployment wants DeepSeek's native server-side web se
 
 ### Minimal configuration
 
-Load the web service and the provider; the key resolves from `ctx.credentials` when that service is mounted, otherwise from the process environment. The auxiliary search call has its own endpoint setting and uses the Anthropic-compatible base `https://api.deepseek.com/anthropic/v1`, with `/messages` appended. It reads `$DEEPSEEK_SEARCH_BASE_URL`, independently of the conversation adapter’s `$DEEPSEEK_BASE_URL` and protocol.
+Load the web service and the provider; the key resolves from `ctx.credentials` when that service is mounted, otherwise from the process environment. The auxiliary search call has its own endpoint setting and uses the Anthropic-compatible base `https://api.deepseek.com/anthropic/v1`, with `/messages` appended. It reads `$DEEPSEEK_SEARCH_BASE_URL`, independently of the conversation adapter’s `$DEEPSEEK_BASE_URL`.
 
 ```yaml
 - name: '@deepseek-ai/dsh-web'
diff --git a/packages/web/web-search-deepseek/README.zh.md b/packages/web/web-search-deepseek/README.zh.md
index a38c1e126a..b45b449f2d 100644
--- a/packages/web/web-search-deepseek/README.zh.md
+++ b/packages/web/web-search-deepseek/README.zh.md
@@ -33,7 +33,7 @@ kind: "package-reference"
 
 ### 最小配置
 
-加载 web 服务与本提供方；密钥在已挂载 `ctx.credentials` 服务时从其解析，否则从进程环境解析。辅助搜索调用有独立的端点设置，使用 Anthropic 兼容基址 `https://api.deepseek.com/anthropic/v1`，并追加 `/messages`。它读取 `$DEEPSEEK_SEARCH_BASE_URL`，与会话适配器的 `$DEEPSEEK_BASE_URL` 和协议相互独立。
+加载 web 服务与本提供方；密钥在已挂载 `ctx.credentials` 服务时从其解析，否则从进程环境解析。辅助搜索调用有独立的端点设置，使用 Anthropic 兼容基址 `https://api.deepseek.com/anthropic/v1`，并追加 `/messages`。它读取 `$DEEPSEEK_SEARCH_BASE_URL`，与会话适配器的 `$DEEPSEEK_BASE_URL` 相互独立。
 
 ```yaml
 - name: '@deepseek-ai/dsh-web'
diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml
index a58a195684..9b2ed335a8 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: 4cf16a233637da3fb2384ba80cdba8adb0298e5a
-README.zh.md: cfbbdd74f14c1c6f8c8c97b2bb84366ff61bb4d1
+README.md: d34ba156409b5c1cc1d9b3c320af5b8e92082a59
+README.zh.md: ea446f1ddf74a6c118bc2fa6a0f5d77c824b34cc
diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md
index 4cf16a2336..d34ba15640 100644
--- a/packages/workflow/tool-workflow/README.md
+++ b/packages/workflow/tool-workflow/README.md
@@ -68,6 +68,8 @@ The consumer owns the model-facing schema, the `tool:<toolName>` system-prompt g
 
 For a root transport execution (`exec.parent` absent), the tool projects the run into the calling Agent's Session with four log-only events: run-start after `start()` returns, member starts and endings filtered by `run.id`, then run-end only after the result is available and disposal reaches quiescence. Nested transport calls execute normally but write no record. The first failed Session append disables later recording for that run with one warning, leaving either no record or a legal continuous prefix without changing the tool result or cleanup. The package invariant rejects duplicate starts, unpaired members, terminal events with open members, and updates after run-end on both cold load and live append, while accepting missing terminal suffixes.
 
+The engine's `workflow/phase` and `workflow/log` events have no per-line durable or observer surface from this tool: the session log deliberately records run and member lifecycle only, and the Web transcript derives from those records.
+
 ### Render intent
 
 Decided up front per the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md): a `generic` card titled `workflow: <meta.name>`, read directly from `args.meta.name` — presentation is a pure function of args — with the script text carried as `rawInput`. The result keeps the generic card.
diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md
index cfbbdd74f1..ea446f1ddf 100644
--- a/packages/workflow/tool-workflow/README.zh.md
+++ b/packages/workflow/tool-workflow/README.zh.md
@@ -68,6 +68,8 @@ kind: "package-reference"
 
 对于根 transport 执行（`exec.parent` 缺省），工具会用四个 log-only 事件把运行投影到调用方 agent 的会话：`start()` 返回后写 run-start，只记录 `run.id` 匹配的成员开始与结束，并且只在结果可用且 dispose 完全停稳后写 run-end。嵌套 transport 调用照常执行，但不写任何记录。会话追加操作首次失败后，本运行会停止后续记录并只告警一次，留下空记录或合法连续前缀，同时不改变工具结果和清理。包 invariant 会在冷加载与实时追加时拒绝重复 start、未配对成员、仍有开放成员的终点与 run-end 后更新，同时允许缺失终态后缀的连续前缀。
 
+引擎的 `workflow/phase` 与 `workflow/log` 事件在本工具没有逐行的持久或观察面：会话日志刻意只记录 run 与成员生命周期，Web transcript 由这些记录派生。
+
 ### 渲染意图
 
 按[渲染意图 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md)预先确定：使用 `generic` 卡片，标题为 `workflow: <meta.name>`，直接从 `args.meta.name` 读取——呈现是参数的纯函数——脚本文本作为 `rawInput` 携带。结果继续使用 generic 卡片。
diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json
index d75d1e8124..e14338c5f4 100644
--- a/packages/workflow/tool-workflow/package.json
+++ b/packages/workflow/tool-workflow/package.json
@@ -37,19 +37,20 @@
   ],
   "license": "MIT",
   "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-workflow": "workspace:^",
-    "@deepseek-ai/cordis": "workspace:^"
+    "@deepseek-ai/dsh-workflow": "workspace:^"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "workspace:^"
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
diff --git a/packages/workspace/workspace/README.i18n.yaml b/packages/workspace/workspace/README.i18n.yaml
index da38092a17..7f50ab3f55 100644
--- a/packages/workspace/workspace/README.i18n.yaml
+++ b/packages/workspace/workspace/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workspace/workspace/README.md
-README.md: 51fa66d346ffc4027397d8851b0c81ea87269ded
-README.zh.md: 102308d3257ba13d3ec851adcbdb1d4c159abc14
+README.md: 897aca8eb725bc9c3e0808e394e5c976886dd877
+README.zh.md: dc7a81340c9b134110975e700d43d5569fa6f03d
diff --git a/packages/workspace/workspace/README.md b/packages/workspace/workspace/README.md
index 51fa66d346..897aca8eb7 100644
--- a/packages/workspace/workspace/README.md
+++ b/packages/workspace/workspace/README.md
@@ -33,7 +33,7 @@ Use it when the product shows a persistent workspace surface — a sidebar, sess
 
 ### Setting up
 
-The package takes no configuration of its own; it needs a session store, a session persistence backend, and the storage rows that keep its records. A minimal composition:
+The package needs a session store, a session persistence backend, and the storage rows that keep its records. A minimal composition:
 
 ```yaml
 - name: '@deepseek-ai/dsh-session'
@@ -59,6 +59,15 @@ await project.setTitle('Renamed')
 ctx.workspaceRegistry.list() // shows the project, newest first
 ```
 
+<a id="first-use-workspace"></a>
+### First-use Workspace
+
+`initializeDefault(resolveDirectory)` initializes the default Workspace without creating a Session. Initial creation requires an empty Workspace registry and no live, persisted, or archived Session, including Sessions without a working directory. The registry checks persistent history directly; an empty visible sidebar is insufficient.
+
+The directory resolver runs inside the mutation queue only when creation is eligible. It returns an absolute path and initial title; the registry creates missing parent directories, canonicalizes the path, rechecks Session history, and commits the Workspace with its initialization marker. An existing directory is reused; a file conflict or directory failure rejects initialization. The [Host controller](../../api/workspace-controller/README.md#first-use-workspace) supplies the Documents path policy.
+
+The first successful registration records its identity durably. Repeated calls return it without resolving a directory again; renaming keeps that identity, and deleting its registration does not permit another automatic creation. Directory or registration failure leaves initialization unset for retry. Directories created before a later failure remain on disk. Once directory resolution succeeds, caller cancellation does not roll back directory creation or registration. The [first-use decision](../../../.agents/notes/implemented/feature/2026-09-20-default-workspace.md) explains this lifetime.
+
 ### Grouping sessions under a project
 
 A session joins the project of the directory it runs in: create a session in a project's directory and it appears under that project, newest first. A session can only belong to one project. A session whose directory cannot be validated — no recorded directory, or a moved or deleted folder — cannot join and stays ungrouped.
@@ -102,7 +111,7 @@ The API has two owners: `WorkspaceRegistry` creates, orders, and deletes project
 
 ### Durable shape
 
-The registry opens the `workspace` domain (version 2): a `workspaces` table keyed by `WorkspaceId` plus one global state holding `workspaceIds` (the authoritative display order), `archivedSessionIds`, `pinnedSessionIds`, and the optional `pendingMutation` marker. Archive and pin sets contain Session id strings, default to empty, and carry no per-entry objects or timestamps; the pin array keeps the most recently pinned id first. Archiving clears the pin in the same global-state write without changing Workspace membership. Unarchive runs no session-existence probe, because dropping an id from the set cannot introduce an unknown one, while archive verifies the session before adding it.
+The registry opens the `workspace` domain (version 2): a `workspaces` table keyed by `WorkspaceId` plus one global state holding `workspaceIds` (the authoritative display order), `archivedSessionIds`, `pinnedSessionIds`, the optional `defaultWorkspaceId` first-use identity, and the optional `pendingMutation` marker. Archive and pin sets contain Session id strings, default to empty, and carry no per-entry objects or timestamps; the pin array keeps the most recently pinned id first. Archiving clears the pin in the same global-state write without changing Workspace membership. Unarchive runs no session-existence probe, because dropping an id from the set cannot introduce an unknown one, while archive verifies the session before adding it.
 
 ### Lifecycle
 
diff --git a/packages/workspace/workspace/README.zh.md b/packages/workspace/workspace/README.zh.md
index 102308d325..dc7a81340c 100644
--- a/packages/workspace/workspace/README.zh.md
+++ b/packages/workspace/workspace/README.zh.md
@@ -33,7 +33,7 @@ kind: "package-reference"
 
 ### 设置
 
-此包本身不声明任何配置；它需要会话存储、会话持久化后端，以及保存其记录的存储行。最小组合如下：
+此包需要会话存储、会话持久化后端，以及保存其记录的存储行。最小组合如下：
 
 ```yaml
 - name: '@deepseek-ai/dsh-session'
@@ -59,6 +59,15 @@ await project.setTitle('Renamed')
 ctx.workspaceRegistry.list() // shows the project, newest first
 ```
 
+<a id="first-use-workspace"></a>
+### 首次使用工作区
+
+`initializeDefault(resolveDirectory)` 初始化默认 Workspace，不创建 Session。首次创建要求 Workspace 注册表为空，且不存在运行时、持久化或已归档 Session，包括没有工作目录的 Session。注册表直接检查持久化历史；仅凭可见侧边栏为空不足以判断。
+
+目录解析器仅在允许创建时于变更队列内运行。它返回绝对路径和初始标题；注册表创建缺失的父目录、规范化路径、重新检查 Session 历史，再一起提交 Workspace 和初始化标记。已存在的目录直接复用；文件冲突或目录操作失败时拒绝初始化。[Host 控制器](../../api/workspace-controller/README.zh.md#first-use-workspace)提供 Documents 路径策略。
+
+首次成功登记会持久保存工作区身份。重复调用直接返回它，不再解析目录；改名保留该身份，删除登记也不会允许再次自动创建。目录或登记失败时，初始化状态保持未设置，可以重试。后续步骤失败前已创建的目录会保留在磁盘上。目录解析成功后，调用方取消操作不会回滚目录创建或登记。[首次使用决策](../../../.agents/notes/implemented/feature/2026-09-20-default-workspace.zh.md)说明这一生命周期。
+
 ### 将会话归入项目
 
 会话加入它运行目录所在的项目：在项目目录中创建会话，它就会出现在该项目下，新到旧排列。一个会话只能属于一个项目。目录无法校验的会话——没有记录目录，或目录被移动、删除——无法加入，保持 Ungrouped。
@@ -102,7 +111,7 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 
 ### 持久形态
 
-注册表打开 `workspace` 领域（版本 2）：一张以 `WorkspaceId` 为键的 `workspaces` 表，加上一个持有 `workspaceIds`（权威显示顺序）、`archivedSessionIds`、`pinnedSessionIds` 与可选 `pendingMutation` 标记的全局状态。归档与置顶集合存储会话 id 字符串，默认值为空，不包含逐项对象或时间戳；置顶数组把最近置顶的 id 放在前面。归档在同一次全局状态写入中清除置顶，但不改变 Workspace 成员关系。取消归档不做会话存在性探测，因为从集合中移除 id 不可能引入未知 id，而归档会在加入前校验会话。
+注册表打开 `workspace` 领域（版本 2）：一张以 `WorkspaceId` 为键的 `workspaces` 表，加上一个持有 `workspaceIds`（权威显示顺序）、`archivedSessionIds`、`pinnedSessionIds`、可选的首次使用身份 `defaultWorkspaceId` 与可选 `pendingMutation` 标记的全局状态。归档与置顶集合存储会话 id 字符串，默认值为空，不包含逐项对象或时间戳；置顶数组把最近置顶的 id 放在前面。归档在同一次全局状态写入中清除置顶，但不改变 Workspace 成员关系。取消归档不做会话存在性探测，因为从集合中移除 id 不可能引入未知 id，而归档会在加入前校验会话。
 
 ### 生命周期
 
diff --git a/packages/workspace/workspace/src/index.ts b/packages/workspace/workspace/src/index.ts
index ab9ff50409..e2f67d948a 100644
--- a/packages/workspace/workspace/src/index.ts
+++ b/packages/workspace/workspace/src/index.ts
@@ -6,7 +6,7 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { stat } from 'node:fs/promises'
+import { mkdir, stat } from 'node:fs/promises'
 import { Context, Service } from '@deepseek-ai/cordis'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-session-persistence'
@@ -15,7 +15,7 @@ import { WorkspaceEntity } from './entity.ts'
 import type { WorkspaceEntityHost } from './entity.ts'
 
 export { WorkspaceMoveInvalidError } from './entity.ts'
-import { defaultWorkspaceTitle, realpathNormalize } from './paths.ts'
+import { defaultWorkspaceTitle, fullyQualifiedWorkspacePath, realpathNormalize } from './paths.ts'
 import { workspaceDomainSpec } from './spec.ts'
 import type { WorkspaceDomainState, WorkspaceRecord } from './spec.ts'
 import type { Workspace, WorkspaceId as WorkspaceIdBrand } from './types.ts'
@@ -175,6 +175,35 @@ export class WorkspaceRegistry extends Service {
     return await this.enqueueOperation(() => this.createCanonical(canonical, title))
   }
 
+  /**
+   * Initialize the default Workspace only while both the registry and Session
+   * history are empty. Repeated requests reuse its durable identity; deleting
+   * that registration permanently disables automatic creation.
+   * @param resolveDirectory - resolve the absolute directory and initial title;
+   * called only for eligible creation, inside the registry mutation queue.
+   * Missing directories are created recursively before registration.
+   * After resolution, caller cancellation does not roll back creation or registration.
+   * @returns the initialized Workspace, or undefined when automatic creation is ineligible.
+   */
+  initializeDefault(resolveDirectory: () => Promise<{ path: string; title: string }>): Promise<Workspace | undefined> {
+    return this.enqueueOperation(async () => {
+      const state = this.requireState()
+      if (state.defaultWorkspaceId !== undefined) return this.entities.get(state.defaultWorkspaceId)
+      const sessions = this.ctx.get('sessions')
+      if (sessions === undefined) throw new Error('default Workspace initialization requires the Session store')
+      if (state.workspaceIds.length > 0 || state.archivedSessionIds.length > 0
+        || sessions.list().length > 0 || (await this.listStoredHeaders()).length > 0) return undefined
+
+      const { path, title } = await resolveDirectory()
+      if (!fullyQualifiedWorkspacePath(path)) throw new TypeError(`Workspace path is not fully qualified: '${path}'`)
+      await mkdir(path, { recursive: true })
+      const canonical = await realpathNormalize(path)
+      // A Session can start outside the registry queue while directory preparation awaits I/O.
+      if ((await this.listStoredHeaders()).length > 0 || sessions.list().length > 0) return undefined
+      return this.createCanonical(canonical, title, true)
+    })
+  }
+
   /**
    * Look up a workspace by id.
    * @param id - Workspace id.
@@ -379,7 +408,7 @@ export class WorkspaceRegistry extends Service {
     return undefined
   }
 
-  private async createCanonical(canonical: string, title?: string): Promise<WorkspaceEntity> {
+  private async createCanonical(canonical: string, title?: string, firstUse = false): Promise<WorkspaceEntity> {
     for (const entity of this.entities.values()) {
       if (entity.path === canonical) return entity
     }
@@ -425,10 +454,11 @@ export class WorkspaceRegistry extends Service {
 
     try {
       await this.setState({
+        ...state,
+        pendingMutation: undefined,
         initialized: true,
+        ...(firstUse ? { defaultWorkspaceId: id } : {}),
         workspaceIds: [id, ...state.workspaceIds],
-        archivedSessionIds: state.archivedSessionIds,
-        pinnedSessionIds: state.pinnedSessionIds,
       })
     } catch (error) {
       this.entities.delete(id)
@@ -458,10 +488,10 @@ export class WorkspaceRegistry extends Service {
     if (entity === undefined) return false
     const state = this.requireState()
     const nextState = {
+      ...state,
+      pendingMutation: undefined,
       initialized: true,
       workspaceIds: state.workspaceIds.filter(workspaceId => workspaceId !== id),
-      archivedSessionIds: state.archivedSessionIds,
-      pinnedSessionIds: state.pinnedSessionIds,
     }
     await this.setState({
       ...nextState,
@@ -515,12 +545,7 @@ export class WorkspaceRegistry extends Service {
       )
     }
     await this.requireTable().delete(pending.workspaceId)
-    await this.setState({
-      initialized: state.initialized,
-      workspaceIds: state.workspaceIds,
-      archivedSessionIds: state.archivedSessionIds,
-      pinnedSessionIds: state.pinnedSessionIds,
-    })
+    await this.setState({ ...state, pendingMutation: undefined })
   }
 
   private async bootstrap(headers: readonly SessionHeader[]): Promise<void> {
diff --git a/packages/workspace/workspace/src/spec.ts b/packages/workspace/workspace/src/spec.ts
index 165bff34e0..9bd792258a 100644
--- a/packages/workspace/workspace/src/spec.ts
+++ b/packages/workspace/workspace/src/spec.ts
@@ -56,6 +56,8 @@ const workspacePendingMutation = z.discriminatedUnion('operation', [
  */
 export const workspaceDomainState = z.object({
   initialized: z.boolean(),
+  /** First-use Workspace identity, retained after its registration is deleted. */
+  defaultWorkspaceId: workspaceId.optional(),
   workspaceIds: z.array(workspaceId),
   archivedSessionIds: z.array(sessionId).default([]),
   pinnedSessionIds: z.array(sessionId).default([]),
diff --git a/packages/workspace/workspace/tests/workspace.spec.ts b/packages/workspace/workspace/tests/workspace.spec.ts
index f860028d4e..6eafae9f2e 100644
--- a/packages/workspace/workspace/tests/workspace.spec.ts
+++ b/packages/workspace/workspace/tests/workspace.spec.ts
@@ -2,7 +2,7 @@ import type { z } from 'zod'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { basename, join } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
 import Storage from '@deepseek-ai/dsh-storage'
 import type { StorageBackend } from '@deepseek-ai/dsh-storage'
@@ -1156,3 +1156,145 @@ describe('registry-global session unpin', () => {
     expect(result.list.mock.calls.length).toBe(listingsBefore)
   })
 })
+
+describe('first-use Workspace preparation', () => {
+  const contexts: Context[] = []
+
+  afterEach(async () => {
+    for (const ctx of contexts.splice(0)) await ctx.fiber.dispose()
+  })
+
+  async function firstUse(options: HarnessOptions = {}) {
+    const directoryRoot = await makeDir('first-use')
+    const result = await harness({ liveSessions: [], ...options })
+    contexts.push(result.ctx)
+    const resolveDirectory = vi.fn(async () => ({ path: join(directoryRoot, 'nested', 'Workspace'), title: 'Workspace' }))
+    return { ...result, directoryRoot, resolveDirectory }
+  }
+
+  it('creates parent directories and resolves only one directory for concurrent initialization', async () => {
+    const h = await firstUse()
+    const laterDirectory = vi.fn(async () => { throw new Error('directory lookup unavailable') })
+    const [first, repeated] = await Promise.all([
+      h.registry.initializeDefault(h.resolveDirectory), h.registry.initializeDefault(laterDirectory),
+    ])
+    expect(first).toBeDefined()
+    expect(repeated).toBe(first)
+    expect(h.resolveDirectory).toHaveBeenCalledOnce()
+    expect(laterDirectory).not.toHaveBeenCalled()
+    expect(first?.path).toBe(await realpath(join(h.directoryRoot, 'nested', 'Workspace')))
+    expect(first?.title).toBe('Workspace')
+    expect(h.registry.list()).toEqual([first])
+    expect(storedState(h.pool).defaultWorkspaceId).toBe(first?.id)
+    expect(h.ctx.sessions.list()).toEqual([])
+    expect(h.open).not.toHaveBeenCalled()
+  })
+
+  it('reuses an existing directory without changing its contents', async () => {
+    const h = await firstUse()
+    const directory = join(h.directoryRoot, 'nested', 'Workspace')
+    await mkdir(directory, { recursive: true })
+    await writeFile(join(directory, 'keep.txt'), 'keep')
+    expect((await h.registry.initializeDefault(h.resolveDirectory))?.path).toBe(directory)
+    const { readFile } = await import('node:fs/promises')
+    expect(await readFile(join(directory, 'keep.txt'), 'utf8')).toBe('keep')
+  })
+
+  it('leaves initialization retryable when directory resolution fails', async () => {
+    const h = await firstUse()
+    h.resolveDirectory.mockRejectedValueOnce(new Error('lookup unavailable'))
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).rejects.toThrow('lookup unavailable')
+    expect(storedState(h.pool).defaultWorkspaceId).toBeUndefined()
+    expect(await h.registry.initializeDefault(h.resolveDirectory)).toBeDefined()
+  })
+
+  it('rejects a relative candidate before creating its directory', async () => {
+    const h = await firstUse()
+    const candidate = join(h.directoryRoot, 'relative')
+    h.resolveDirectory.mockResolvedValueOnce({ path: relative(process.cwd(), candidate), title: 'Workspace' })
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).rejects.toThrow('fully qualified')
+    await expect(realpath(candidate)).rejects.toMatchObject({ code: 'ENOENT' })
+    expect(h.registry.list()).toEqual([])
+    expect(storedState(h.pool).defaultWorkspaceId).toBeUndefined()
+  })
+
+  it('keeps the initialization marker across deletion and restart', async () => {
+    const h = await firstUse()
+    const workspace = (await h.registry.initializeDefault(h.resolveDirectory))!
+    await workspace.setTitle('Renamed')
+    expect((await h.registry.initializeDefault(h.resolveDirectory))?.title).toBe('Renamed')
+    await h.registry.delete(workspace.id)
+    await h.ctx.fiber.dispose()
+    const restarted = await firstUse({ pool: h.pool })
+    await expect(restarted.registry.initializeDefault(restarted.resolveDirectory)).resolves.toBeUndefined()
+    expect(storedState(h.pool).defaultWorkspaceId).toBe(workspace.id)
+    expect(restarted.registry.list()).toEqual([])
+    expect(restarted.resolveDirectory).not.toHaveBeenCalled()
+  })
+
+  it.each(['persisted', 'live', 'archived'] as const)('refuses automatic creation for a %s cwd-less Session', async (kind) => {
+    const history = header('old')
+    const h = await firstUse(kind === 'persisted' ? { sessions: [history] } : { liveSessions: [history] })
+    if (kind === 'archived') await h.registry.archiveSession(history.id)
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).resolves.toBeUndefined()
+    expect(h.registry.list()).toEqual([])
+    expect(storedState(h.pool).defaultWorkspaceId).toBeUndefined()
+    expect(h.resolveDirectory).not.toHaveBeenCalled()
+  })
+
+  it('refuses a non-empty Workspace list and newly persisted history', async () => {
+    const h = await firstUse()
+    const explicit = await h.registry.create(h.directoryRoot)
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).resolves.toBeUndefined()
+    await h.registry.delete(explicit.id)
+    h.setSessions([header('arrived')])
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).resolves.toBeUndefined()
+  })
+
+  it('fails on a same-path file and remains eligible after it is removed', async () => {
+    const h = await firstUse()
+    const parent = join(h.directoryRoot, 'nested')
+    await mkdir(parent)
+    const path = join(parent, 'Workspace')
+    await writeFile(path, 'occupied')
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).rejects.toThrow()
+    expect(storedState(h.pool).defaultWorkspaceId).toBeUndefined()
+    expect(h.registry.list()).toEqual([])
+    await rm(path)
+    expect((await h.registry.initializeDefault(h.resolveDirectory))?.path).toBe(path)
+  })
+
+  it.each(['persisted', 'live'] as const)('refuses registration when a %s Session appears during directory preparation', async (kind) => {
+    const h = await firstUse()
+    const arrived = header('arrived-during-preparation')
+    if (kind === 'persisted') {
+      h.list.mockResolvedValueOnce([]).mockResolvedValueOnce([
+        { header: arrived, revision: SessionPersistenceRevision('arrived-revision') },
+      ])
+    } else {
+      vi.spyOn(h.ctx.sessions, 'list').mockReturnValueOnce([]).mockReturnValueOnce([{ header: arrived }] as never)
+    }
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).resolves.toBeUndefined()
+    expect(h.registry.list()).toEqual([])
+    expect(storedState(h.pool).defaultWorkspaceId).toBeUndefined()
+  })
+
+  it('does not infer an empty live Session store when the peer is unavailable', async () => {
+    const h = await harness()
+    contexts.push(h.ctx)
+    const resolveDirectory = vi.fn(async () => { throw new Error('unexpected directory lookup') })
+    await expect(h.registry.initializeDefault(resolveDirectory)).rejects.toThrow('Session store')
+    expect(resolveDirectory).not.toHaveBeenCalled()
+    expect(storedState(h.pool).defaultWorkspaceId).toBeUndefined()
+  })
+
+  it('rolls back a failed final marker write and allows a retry', async () => {
+    const pool = new MemoryMediaPool()
+    const h = await firstUse({ pool, backend: selectiveFailureBackend(pool, { globalAt: 3 }) })
+    await expect(h.registry.initializeDefault(h.resolveDirectory)).rejects.toThrow('marker failure')
+    expect(h.registry.list()).toEqual([])
+    expect(storedState(pool).defaultWorkspaceId).toBeUndefined()
+    await expect(realpath(join(h.directoryRoot, 'nested', 'Workspace'))).resolves.toBe(join(h.directoryRoot, 'nested', 'Workspace'))
+    expect(await h.registry.initializeDefault(h.resolveDirectory)).toBeDefined()
+  })
+})
diff --git a/patches/@earendil-works__pi-ai@0.85.1.patch b/patches/@earendil-works__pi-ai@0.85.1.patch
new file mode 100644
index 0000000000..227a183e12
--- /dev/null
+++ b/patches/@earendil-works__pi-ai@0.85.1.patch
@@ -0,0 +1,73 @@
+diff --git a/dist/api/anthropic-messages.js b/dist/api/anthropic-messages.js
+index e1538a5dfcf2225da9dc3ec622576564ee7c8530..abb8f990d680ee247708ca774a467fc5774e28b0 100644
+--- a/dist/api/anthropic-messages.js
++++ b/dist/api/anthropic-messages.js
+@@ -500,7 +500,6 @@ export const stream = (model, context, options) => {
+                         const block = blocks[index];
+                         if (block && block.type === "toolCall") {
+                             block.partialJson += event.delta.partial_json;
+-                            block.arguments = parseStreamingJson(block.partialJson);
+                             stream.push({
+                                 type: "toolcall_delta",
+                                 contentIndex: index,
+diff --git a/dist/api/bedrock-converse-stream.js b/dist/api/bedrock-converse-stream.js
+index 6bc6312906ec3d75f31d190994d21c87f1d0767d..7ff68fb60c3c1d9e3e7d2d2df8d4619593a67335 100644
+--- a/dist/api/bedrock-converse-stream.js
++++ b/dist/api/bedrock-converse-stream.js
+@@ -453,7 +453,6 @@ function handleContentBlockDelta(event, blocks, output, stream) {
+     }
+     else if (delta?.toolUse && block?.type === "toolCall") {
+         block.partialJson = (block.partialJson || "") + (delta.toolUse.input || "");
+-        block.arguments = parseStreamingJson(block.partialJson);
+         stream.push({ type: "toolcall_delta", contentIndex: index, delta: delta.toolUse.input || "", partial: output });
+     }
+     else if (delta?.reasoningContent) {
+diff --git a/dist/api/mistral-conversations.js b/dist/api/mistral-conversations.js
+index 67f9341a6f7d855dce25054fd48cd9077e8e04a1..afdb5c2c873abb72ca8011b7e3f06a230dbe3e8a 100644
+--- a/dist/api/mistral-conversations.js
++++ b/dist/api/mistral-conversations.js
+@@ -543,7 +543,6 @@ async function consumeChatStream(model, output, stream, mistralStream) {
+                 ? toolCall.function.arguments
+                 : JSON.stringify(toolCall.function.arguments || {});
+             block.partialArgs = (block.partialArgs || "") + argsDelta;
+-            block.arguments = parseStreamingJson(block.partialArgs);
+             stream.push({
+                 type: "toolcall_delta",
+                 contentIndex: toolBlocksByKey.get(key),
+diff --git a/dist/api/openai-completions.js b/dist/api/openai-completions.js
+index 48464f2bf56b9369d5c202e4f02fc4f13d35b412..d829f5e8e56e788d96fa7a82c0e3cfaef3fc1f63 100644
+--- a/dist/api/openai-completions.js
++++ b/dist/api/openai-completions.js
+@@ -453,7 +453,6 @@ export const stream = (model, context, options) => {
+                             if (toolCall.function?.arguments) {
+                                 delta = toolCall.function.arguments;
+                                 block.partialArgs = (block.partialArgs ?? "") + toolCall.function.arguments;
+-                                block.arguments = parseStreamingJson(block.partialArgs);
+                             }
+                             else if (toolCall.custom?.input) {
+                                 const nextInput = getCustomToolCallInput(block) + toolCall.custom.input;
+diff --git a/dist/api/openai-responses-shared.js b/dist/api/openai-responses-shared.js
+index 43e463dbfd1e6cc437ebc680468036f47678de26..f4259772e289c326697ea7f2ece25954bfb5a520 100644
+--- a/dist/api/openai-responses-shared.js
++++ b/dist/api/openai-responses-shared.js
+@@ -546,7 +546,6 @@ export async function processResponsesStream(openaiStream, output, stream, model
+             if (!slot || slot.block.partialJson === undefined)
+                 continue;
+             slot.block.partialJson += event.delta;
+-            slot.block.arguments = parseStreamingJson(slot.block.partialJson);
+             pushToolCallDelta(slot, event.delta);
+         }
+         else if (event.type === "response.function_call_arguments.done") {
+diff --git a/dist/api/pi-messages.js b/dist/api/pi-messages.js
+index 5b9cb1680c47083a9a36eefa93124c67c750fd42..dc5a43ebd801fa6d4b7897c3739b588d4d571d3a 100644
+--- a/dist/api/pi-messages.js
++++ b/dist/api/pi-messages.js
+@@ -155,8 +155,6 @@ function createEventConverter(model) {
+             case "toolcall_delta": {
+                 const json = `${toolJson.get(event.contentIndex) ?? ""}${event.delta}`;
+                 toolJson.set(event.contentIndex, json);
+-                partial.content[event.contentIndex].arguments =
+-                    parseStreamingJson(json);
+                 break;
+             }
+             case "toolcall_end":
diff --git a/patches/@yao-pkg__pkg@6.21.0.patch b/patches/@yao-pkg__pkg@6.21.0.patch
index 9f0aa5919d..4facf1f7f2 100644
--- a/patches/@yao-pkg__pkg@6.21.0.patch
+++ b/patches/@yao-pkg__pkg@6.21.0.patch
@@ -1,8 +1,56 @@
 diff --git a/prelude/sea-bootstrap.bundle.js b/prelude/sea-bootstrap.bundle.js
-index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546f232fd23 100644
+index ac14980e953134f2285e326a5111cf52de717cf5..1b1c00d1274cba5f63487898a9d940e8870f4f19 100644
 --- a/prelude/sea-bootstrap.bundle.js
 +++ b/prelude/sea-bootstrap.bundle.js
-@@ -5356,6 +5356,39 @@ var require_sea_vfs_setup = __commonJS({
+@@ -63,6 +63,25 @@ var require_bootstrap_shared = __commonJS({
+           throw new Error("pkg: unknown compression codec id " + compression);
+       }
+     }
++    // Write `content` to `dest` through a same-directory temporary file and an
++    // atomic rename, so a concurrent process never observes a partially written
++    // addon: its existsSync/hash check and dlopen see either no file or a complete
++    // one. A direct writeFileSync truncates a file another process may already
++    // have mapped (SIGBUS on Linux, "Library not loaded" on macOS) and exposes the
++    // half-written bytes to that process's hash comparison.
++    function writeFileAtomic(dest, content) {
++      var tmp = dest + "." + process.pid + "." + Math.random().toString(36).slice(2) + ".tmp";
++      fs.writeFileSync(tmp, content);
++      try {
++        fs.renameSync(tmp, dest);
++      } catch (e) {
++        try {
++          fs.unlinkSync(tmp);
++        } catch (_) {
++        }
++        throw e;
++      }
++    }
+     function cpRecursive(src, dest) {
+       var st = fs.lstatSync(src);
+       if (st.isSymbolicLink()) {
+@@ -100,7 +119,7 @@ var require_bootstrap_shared = __commonJS({
+           return;
+         }
+       }
+-      fs.writeFileSync(dest, srcContent);
++      writeFileAtomic(dest, srcContent);
+     }
+     function patchDlopen(insideSnapshot) {
+       var ancestor = process.dlopen;
+@@ -134,10 +153,10 @@ var require_bootstrap_shared = __commonJS({
+               var dContent = fs.readFileSync(tmpModulePath);
+               var dHash = createHash("sha256").update(dContent).digest("hex");
+               if (hash !== dHash) {
+-                fs.writeFileSync(tmpModulePath, moduleContent);
++                writeFileAtomic(tmpModulePath, moduleContent);
+               }
+             } else {
+-              fs.writeFileSync(tmpModulePath, moduleContent);
++              writeFileAtomic(tmpModulePath, moduleContent);
+             }
+             newPath = tmpModulePath;
+           }
+@@ -5356,6 +5375,39 @@ var require_sea_vfs_setup = __commonJS({
          }
        };
      }
@@ -42,7 +90,7 @@ index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546
      var SEAProvider = class extends MemoryProvider {
        constructor(seaManifest) {
          super();
-@@ -5465,12 +5498,21 @@ var require_sea_vfs_setup = __commonJS({
+@@ -5465,12 +5517,21 @@ var require_sea_vfs_setup = __commonJS({
          }
          return -2;
        }
@@ -67,7 +115,7 @@ index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546
        }
        existsSync(filePath) {
          perf2.count("existsSync calls");
-@@ -5542,7 +5584,7 @@ var require_sea_vfs_setup = __commonJS({
+@@ -5542,7 +5603,7 @@ var require_sea_vfs_setup = __commonJS({
  var require_worker_bootstrap_string = __commonJS({
    "prelude/_worker-bootstrap-string.js"(exports2, module2) {
      "use strict";
@@ -76,7 +124,7 @@ index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546
    }
  });
 
-@@ -5560,7 +5602,6 @@ var require_sea_bootstrap_core = __commonJS({
+@@ -5560,7 +5621,6 @@ var require_sea_bootstrap_core = __commonJS({
      var insideSnapshot = vfs.insideSnapshot;
      var SNAPSHOT_PREFIX = vfs.SNAPSHOT_PREFIX;
      shared.patchDlopen(insideSnapshot);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dc16be7fbf..8663d19a99 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -10,8 +10,9 @@ overrides:
   '@deepseek-ai/schemastery': link:vendor/schemastery
 
 patchedDependencies:
+  '@earendil-works/pi-ai@0.85.1': b9bcce474fb2ac44633dff0fa722816a5bff5451b4575d5874035ea14ba70a4f
   '@electron/osx-sign@1.3.3': 280e7b2816caf01423097d24e79107a66afeb563a348630ce9928ae8499a5861
-  '@yao-pkg/pkg@6.21.0': 07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337
+  '@yao-pkg/pkg@6.21.0': 75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7
   node-pty@1.2.0-beta.15: b40ae545608897914bd25fb009c97eeac478c34e8a910298ddcb01b746534bb0
 
 importers:
@@ -54,6 +55,9 @@ importers:
       '@deepseek-ai/dsh-tool-session-query':
         specifier: workspace:^
         version: link:packages/session-query/tool-session-query
+      '@deepseek-ai/dsh-tool-workspace-dependencies':
+        specifier: workspace:^
+        version: link:packages/skill/tool-workspace-dependencies
       '@deepseek-ai/dsh-web-fetch-http':
         specifier: workspace:^
         version: link:packages/web/web-fetch-http
@@ -86,7 +90,7 @@ importers:
         version: 4.1.8(vitest@4.1.8)
       '@yao-pkg/pkg':
         specifier: 6.21.0
-        version: 6.21.0(patch_hash=07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337)(supports-color@9.4.0)
+        version: 6.21.0(patch_hash=75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7)(supports-color@9.4.0)
       '@yarnpkg/cli-dist':
         specifier: 4.17.1
         version: 4.17.1
@@ -96,9 +100,15 @@ importers:
       execa:
         specifier: ^10.0.0
         version: 10.0.0
+      extract-zip:
+        specifier: ^2.0.1
+        version: 2.0.1(supports-color@9.4.0)
       fast-check:
         specifier: ^4.8.0
         version: 4.8.0
+      fflate:
+        specifier: ^0.8.2
+        version: 0.8.3
       istanbul-lib-report:
         specifier: ^3.0.1
         version: 3.0.1
@@ -135,6 +145,9 @@ importers:
       oxlint-tsgolint:
         specifier: 7.0.2001
         version: 7.0.2001
+      pnpm:
+        specifier: 11.7.0
+        version: 11.7.0
       publint:
         specifier: ^0.3.21
         version: 0.3.21
@@ -144,6 +157,9 @@ importers:
       spdx-expression-parse:
         specifier: ^5.0.0
         version: 5.0.0
+      tar:
+        specifier: ^7.5.0
+        version: 7.5.22
       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)
@@ -294,6 +310,9 @@ importers:
       '@deepseek-ai/dsh-skill-filesystem':
         specifier: workspace:^
         version: link:../../packages/skill/skill-filesystem
+      '@deepseek-ai/dsh-skill-office':
+        specifier: workspace:^
+        version: link:../../packages/skill/skill-office
       '@deepseek-ai/dsh-terminal':
         specifier: workspace:^
         version: link:../../packages/terminal/terminal
@@ -366,6 +385,9 @@ importers:
       '@deepseek-ai/dsh-tool-workflow':
         specifier: workspace:^
         version: link:../../packages/workflow/tool-workflow
+      '@deepseek-ai/dsh-tool-workspace-dependencies':
+        specifier: workspace:^
+        version: link:../../packages/skill/tool-workspace-dependencies
       '@deepseek-ai/dsh-web-app':
         specifier: workspace:^
         version: link:../../packages/bundle/web-app
@@ -536,6 +558,12 @@ importers:
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
         version: link:../../packages/boot/app-boot
+      '@deepseek-ai/dsh-client-ui-settings-general':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-settings-general
+      '@deepseek-ai/dsh-client-ui-sidebar-browser':
+        specifier: workspace:^
+        version: link:../../packages/client/ui-sidebar-browser
       '@deepseek-ai/dsh-home-paths':
         specifier: workspace:^
         version: link:../../packages/util/home-paths
@@ -572,9 +600,6 @@ importers:
       extract-zip:
         specifier: ^2.0.1
         version: 2.0.1(supports-color@9.4.0)
-      fflate:
-        specifier: ^0.8.2
-        version: 0.8.3
       js-yaml:
         specifier: ^4.2.0
         version: 4.3.1
@@ -584,9 +609,6 @@ importers:
       pnpm:
         specifier: 11.7.0
         version: 11.7.0
-      tar:
-        specifier: ^7.5.0
-        version: 7.5.22
       typescript:
         specifier: ^6.0.3
         version: 6.0.3
@@ -620,9 +642,9 @@ importers:
       '@deepseek-ai/dsh-skill-office':
         specifier: workspace:^
         version: link:../../packages/skill/skill-office
-      '@deepseek-ai/dsh-tools':
+      '@deepseek-ai/dsh-tool-workspace-dependencies':
         specifier: workspace:^
-        version: link:../../packages/core/tools
+        version: link:../../packages/skill/tool-workspace-dependencies
 
   apps/web:
     devDependencies:
@@ -949,6 +971,46 @@ importers:
         specifier: ^4.4.3
         version: 4.4.3
 
+  packages/api/job-controller:
+    dependencies:
+      '@deepseek-ai/dsh-typert-protocol':
+        specifier: workspace:^
+        version: link:../../typert/protocol
+      '@deepseek-ai/schemastery':
+        specifier: link:../../../vendor/schemastery
+        version: link:../../../vendor/schemastery
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-api-gateway':
+        specifier: workspace:^
+        version: link:../gateway
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../../client/connection
+      '@deepseek-ai/dsh-client-store':
+        specifier: workspace:^
+        version: link:../../client/store
+      '@deepseek-ai/dsh-jobs':
+        specifier: workspace:^
+        version: link:../../jobs/jobs
+      '@deepseek-ai/dsh-jobs-local':
+        specifier: workspace:^
+        version: link:../../jobs/jobs-local
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-typert-registry':
+        specifier: workspace:^
+        version: link:../../typert/registry
+
   packages/api/remotes:
     dependencies:
       '@deepseek-ai/dsh-deque':
@@ -973,6 +1035,9 @@ importers:
       '@deepseek-ai/dsh-api-gateway':
         specifier: workspace:^
         version: link:../gateway
+      '@deepseek-ai/dsh-api-job-controller':
+        specifier: workspace:^
+        version: link:../job-controller
       '@deepseek-ai/dsh-api-session-controller':
         specifier: workspace:^
         version: link:../session-controller
@@ -1121,9 +1186,6 @@ importers:
       '@deepseek-ai/dsh-fs-local':
         specifier: workspace:^
         version: link:../../fs/fs-local
-      '@deepseek-ai/dsh-jobs':
-        specifier: workspace:^
-        version: link:../../jobs/jobs
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
@@ -1270,6 +1332,9 @@ importers:
       '@deepseek-ai/dsh-fs':
         specifier: workspace:^
         version: link:../../fs/fs
+      '@deepseek-ai/dsh-remote-mock':
+        specifier: workspace:^
+        version: link:../../test-support/remote-mock
       '@deepseek-ai/dsh-sandbox':
         specifier: workspace:^
         version: link:../../sandbox/sandbox
@@ -1297,6 +1362,12 @@ importers:
       '@deepseek-ai/dsh-deque':
         specifier: workspace:^
         version: link:../../util/deque
+      '@deepseek-ai/dsh-native-command':
+        specifier: workspace:^
+        version: link:../../util/native-command
+      '@deepseek-ai/schemastery':
+        specifier: link:../../../vendor/schemastery
+        version: link:../../../vendor/schemastery
       zod:
         specifier: ^4.4.3
         version: 4.4.3
@@ -1356,6 +1427,9 @@ importers:
       '@deepseek-ai/dsh-api-gateway':
         specifier: workspace:^
         version: link:../gateway
+      '@deepseek-ai/dsh-client-connection':
+        specifier: workspace:^
+        version: link:../../client/connection
       '@deepseek-ai/dsh-client-resources':
         specifier: workspace:^
         version: link:../../client/resources
@@ -1365,6 +1439,9 @@ importers:
       '@deepseek-ai/dsh-fs':
         specifier: workspace:^
         version: link:../../fs/fs
+      '@deepseek-ai/dsh-remote-mock':
+        specifier: workspace:^
+        version: link:../../test-support/remote-mock
       '@deepseek-ai/dsh-sandbox-policy':
         specifier: workspace:^
         version: link:../../sandbox/sandbox-policy
@@ -1945,6 +2022,12 @@ importers:
       '@deepseek-ai/dsh-sdk-jsonrpc-server':
         specifier: workspace:^
         version: link:../../sdk/server
+      '@deepseek-ai/dsh-skill-office':
+        specifier: workspace:^
+        version: link:../../skill/skill-office
+      '@deepseek-ai/dsh-tool-workspace-dependencies':
+        specifier: workspace:^
+        version: link:../../skill/tool-workspace-dependencies
       '@deepseek-ai/schemastery':
         specifier: link:../../../vendor/schemastery
         version: link:../../../vendor/schemastery
@@ -2055,6 +2138,9 @@ importers:
       '@deepseek-ai/dsh-agent-presets':
         specifier: workspace:^
         version: link:../../preset/agent-presets
+      '@deepseek-ai/dsh-api-job-controller':
+        specifier: workspace:^
+        version: link:../../api/job-controller
       '@deepseek-ai/dsh-api-remotes':
         specifier: workspace:^
         version: link:../../api/remotes
@@ -2286,6 +2372,9 @@ importers:
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-tool-cordis':
+        specifier: workspace:^
+        version: link:../../extensions/tool-cordis
       '@deepseek-ai/dsh-tool-subagent':
         specifier: workspace:^
         version: link:../../subagent/tool-subagent
@@ -2372,9 +2461,15 @@ importers:
       '@deepseek-ai/dsh-llm':
         specifier: workspace:^
         version: link:../../llm/llm
+      '@deepseek-ai/dsh-scope':
+        specifier: workspace:^
+        version: link:../../core/scope
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-typert-protocol':
+        specifier: workspace:^
+        version: link:../../typert/protocol
 
   packages/client/file-upload:
     dependencies:
@@ -2962,6 +3057,9 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:^
         version: link:../../interaction/commands
+      '@deepseek-ai/dsh-file-reference':
+        specifier: workspace:^
+        version: link:../../context/file-reference
       '@deepseek-ai/dsh-goal':
         specifier: workspace:^
         version: link:../../goal/goal
@@ -3347,9 +3445,9 @@ importers:
       '@deepseek-ai/cordis':
         specifier: workspace:^
         version: link:../../../vendor/cordis
-      '@deepseek-ai/dsh-api-session-controller':
+      '@deepseek-ai/dsh-api-job-controller':
         specifier: workspace:^
-        version: link:../../api/session-controller
+        version: link:../../api/job-controller
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
@@ -3371,6 +3469,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
       '@types/react':
         specifier: ~18.3.1
         version: 18.3.31
@@ -3575,6 +3676,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-conversation':
         specifier: workspace:^
         version: link:../ui-conversation
+      '@deepseek-ai/dsh-client-ui-deliverables':
+        specifier: workspace:^
+        version: link:../ui-deliverables
       '@deepseek-ai/dsh-client-ui-primitives':
         specifier: workspace:^
         version: link:../ui-primitives
@@ -3593,6 +3697,9 @@ importers:
       '@deepseek-ai/dsh-host-open-in-app':
         specifier: workspace:^
         version: link:../../host/open-in-app
+      '@deepseek-ai/dsh-native-command':
+        specifier: workspace:^
+        version: link:../../util/native-command
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -4324,6 +4431,12 @@ importers:
       '@deepseek-ai/cordis':
         specifier: workspace:^
         version: link:../../../vendor/cordis
+      '@deepseek-ai/dsh-api-workspace-controller':
+        specifier: workspace:^
+        version: link:../../api/workspace-controller
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
       '@deepseek-ai/dsh-client-locale':
         specifier: workspace:^
         version: link:../locale
@@ -8272,7 +8385,7 @@ importers:
         version: link:../../../vendor/schemastery
       '@earendil-works/pi-ai':
         specifier: ^0.85.1
-        version: 0.85.1(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)
+        version: 0.85.1(patch_hash=b9bcce474fb2ac44633dff0fa722816a5bff5451b4575d5874035ea14ba70a4f)(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)
     devDependencies:
       '@deepseek-ai/cordis':
         specifier: workspace:^
@@ -10156,6 +10269,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop':
         specifier: workspace:^
         version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-agent-loop-testkit':
+        specifier: workspace:^
+        version: link:../../test-support/agent-loop-testkit
       '@deepseek-ai/dsh-app-boot':
         specifier: workspace:^
         version: link:../../boot/app-boot
@@ -10372,6 +10488,34 @@ importers:
         specifier: workspace:^
         version: link:../../core/tools
 
+  packages/skill/tool-workspace-dependencies:
+    dependencies:
+      '@deepseek-ai/schemastery':
+        specifier: link:../../../vendor/schemastery
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/cordis':
+        specifier: workspace:^
+        version: link:../../../vendor/cordis
+      '@deepseek-ai/cordis-plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@deepseek-ai/cordis-plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+
   packages/spill/spill:
     devDependencies:
       '@deepseek-ai/cordis':
@@ -11838,6 +11982,10 @@ importers:
         version: 4.4.3
 
   packages/typert/protocol:
+    dependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
     devDependencies:
       '@deepseek-ai/cordis':
         specifier: workspace:^
@@ -12688,6 +12836,9 @@ importers:
       '@deepseek-ai/dsh-skill-filesystem':
         specifier: workspace:^
         version: link:../../packages/skill/skill-filesystem
+      '@deepseek-ai/dsh-skill-office':
+        specifier: workspace:^
+        version: link:../../packages/skill/skill-office
       '@deepseek-ai/dsh-spill':
         specifier: workspace:^
         version: link:../../packages/spill/spill
@@ -12787,6 +12938,9 @@ importers:
       '@deepseek-ai/dsh-tool-workflow':
         specifier: workspace:^
         version: link:../../packages/workflow/tool-workflow
+      '@deepseek-ai/dsh-tool-workspace-dependencies':
+        specifier: workspace:^
+        version: link:../../packages/skill/tool-workspace-dependencies
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../packages/core/tools
@@ -12913,6 +13067,9 @@ importers:
       '@deepseek-ai/cosmokit':
         specifier: link:../cosmokit
         version: link:../cosmokit
+      '@deepseek-ai/schemastery':
+        specifier: link:../schemastery
+        version: link:../schemastery
       node-addon-require-builtin:
         specifier: ^0.1.6
         version: 0.1.6
@@ -20728,7 +20885,7 @@ snapshots:
     transitivePeerDependencies:
       - '@algolia/client-search'
 
-  '@earendil-works/pi-ai@0.85.1(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)':
+  '@earendil-works/pi-ai@0.85.1(patch_hash=b9bcce474fb2ac44633dff0fa722816a5bff5451b4575d5874035ea14ba70a4f)(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)':
     dependencies:
       '@anthropic-ai/sdk': 0.123.0(zod@4.4.3)
       '@aws-sdk/client-bedrock-runtime': 3.1048.0
@@ -23016,7 +23173,7 @@ snapshots:
       - bare-buffer
       - react-native-b4a
 
-  '@yao-pkg/pkg@6.21.0(patch_hash=07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337)(supports-color@9.4.0)':
+  '@yao-pkg/pkg@6.21.0(patch_hash=75891fc22b277c145cafeab83e41baf4a70f5b8fe6dc0801c6a0b922d7ee88c7)(supports-color@9.4.0)':
     dependencies:
       '@babel/generator': 7.29.7
       '@babel/parser': 7.29.7
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 05802dbbd7..58172c0252 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -95,6 +95,7 @@ minimumReleaseAgeExclude:
   - '@trycua/cua-driver-win32-x64-msvc@0.28.0'
   - '@trycua/cua-driver@0.28.0'
 patchedDependencies:
+  '@earendil-works/pi-ai@0.85.1': patches/@earendil-works__pi-ai@0.85.1.patch
   '@electron/osx-sign@1.3.3': patches/@electron__osx-sign@1.3.3.patch
   '@yao-pkg/pkg@6.21.0': patches/@yao-pkg__pkg@6.21.0.patch
   node-pty@1.2.0-beta.15: patches/node-pty@1.2.0-beta.15.patch
diff --git a/python/sdk-runtime/README.i18n.yaml b/python/sdk-runtime/README.i18n.yaml
index 6db85a5ee9..3bc7ad7803 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: b2fb0b29c44db0e9e251ce0227e334e08a14e0f1
-README.zh.md: 0f13c0a60c7378cb897ccfa7b7082bb86d722a07
+README.md: 3a27ef586cce3290b13b9cd4517ff5a491f312c2
+README.zh.md: 85bf35f62aa60bdb84e612518e2af740f1e8c708
diff --git a/python/sdk-runtime/README.md b/python/sdk-runtime/README.md
index b2fb0b29c4..3a27ef586c 100644
--- a/python/sdk-runtime/README.md
+++ b/python/sdk-runtime/README.md
@@ -12,6 +12,19 @@ Production executables are named `deepseek-harness-sdk-runtime-<platform>-<arch>
 
 Each target also requires `<executable-stem>-office/`, where the stem excludes `.exe`. This directory contains the complete installed Office packages and their dependencies, preserving engine resources, manifests, licenses, source inventories, and helper permissions. Copy this directory together with the executable. A missing target engine fails the sidecar build with its npm package name and target platform/architecture.
 
+Each wheel also includes `<platform>-<arch>/primary-runtime/` (CPython and the locked Office Python libraries) and sibling `office-skills/` (three default workflows and their shared checker). These are ordinary relocatable files, not bytes embedded in the executable. The shared builder selects target-native archives for all five wheel targets and executes its smoke on the native build host. Packaging and installed-runtime lookup reject missing resources, wrong-platform metadata, and lost Python executable permissions. The short platform directory avoids repeating the executable name in Python DLL paths on Windows.
+
+The packaged bootstrap supplies `DSH_BUNDLED_PRIMARY_RUNTIME` as a carrier default. The `sdk` profile uses it when `DSH_PRIMARY_RUNTIME` is unset; an explicit path overrides it, and an empty string disables the query and Office provider. External payloads retain the `primary-runtime/` plus sibling `office-skills/` layout. The SDK reads Python in place without copying it into `DSH_HOME`. Source and dev-only Node carriers have no bundled default; they use an explicit `DSH_PRIMARY_RUNTIME`.
+
+Skill selection is independent of delivery: project, custom-directory, and user filesystem skills override same-name bundled skills. An SDK patch can disable only the Office provider while retaining the Python query:
+
+```yaml
+- id: skill-office
+  disabled: true
+```
+
+To replace the three Office workflows and shared checker as a set, patch `skill-office.config.assetRoot` to another absolute resource directory. Use the filesystem skill provider for arbitrary skill collections. Configuration patches apply at process startup; changing skills does not require rebuilding the runtime wheel or Python environment.
+
 Repository builds also materialize a dev-only `runtime/node/` carrier. It runs `node runtime/node/node_modules/@deepseek-ai/dsh/lib/bin.js` on system Node 22.19 or newer. It is never selected automatically and is excluded from wheels and sdists.
 
 Both carriers execute the same `dsh` grammar and shipped profiles, including the standalone `sdk-minimal` tree and the full `web` profile with its frontend assets. The private `dsh-python-runtime-closure` manifest defines the packaged dependency closure; there is no Python-specific Node application or checked-in default `cordis.yml`.
diff --git a/python/sdk-runtime/README.zh.md b/python/sdk-runtime/README.zh.md
index 0f13c0a60c..85bf35f62a 100644
--- a/python/sdk-runtime/README.zh.md
+++ b/python/sdk-runtime/README.zh.md
@@ -12,6 +12,19 @@ wheel 包会安装 `dsh` 控制台命令和 `deepseek_harness_runtime` Python 
 
 每个目标还要求 `<executable-stem>-office/`，其中 stem 不含 `.exe`。该目录包含完整的已安装 Office 包及其依赖，保留引擎资源、清单、许可证、源码清单与辅助程序权限。复制可执行文件时必须一并复制此目录。缺少目标引擎会使 sidecar 构建失败，错误会指出其 npm 包名与目标平台／架构。
 
+每个 wheel 还包含 `<platform>-<arch>/primary-runtime/`（CPython 与锁定版本的 Office Python 库）及同级 `office-skills/`（三个默认工作流与共用检查脚本）。它们是可重定位的普通文件，不嵌入可执行文件。共享构建器为全部五个 wheel 目标选择原生归档，并在对应构建主机上执行冒烟检查。打包与已安装运行时定位会拒绝缺失资源、平台不符的元数据及 Python 执行权限丢失。 较短的平台目录避免在 Windows Python DLL 路径中重复可执行文件名称。
+
+打包启动器通过 `DSH_BUNDLED_PRIMARY_RUNTIME` 提供载体默认路径。`sdk` profile 在未设置 `DSH_PRIMARY_RUNTIME` 时使用该路径；显式路径覆盖它，空字符串禁用查询与 Office 提供方。外部 payload 保持 `primary-runtime/` 与同级 `office-skills/` 布局。SDK 原位读取 Python，不复制到 `DSH_HOME`。源码与仅供开发的 Node 载体没有随包默认路径，需显式设置 `DSH_PRIMARY_RUNTIME`。
+
+选择 skills 与交付资源相互独立：项目、自定义目录和用户文件系统 skills 优先于同名随包 skills。SDK patch 可以仅禁用 Office 提供方，同时保留 Python 查询：
+
+```yaml
+- id: skill-office
+  disabled: true
+```
+
+要成套替换三个 Office 工作流与共用检查脚本，可将 `skill-office.config.assetRoot` 配置为另一个绝对资源目录。任意 skill 集合通过文件系统 skill 提供方加载。配置 patch 在进程启动时生效；切换 skills 无需重建 runtime wheel 或 Python 环境。
+
 仓库构建还会物化仅限开发的 `runtime/node/` 载体。它在系统 Node 22.19 或更高版本上运行 `node runtime/node/node_modules/@deepseek-ai/dsh/lib/bin.js`。系统不会自动选择它，而且 wheel 包与 sdist 均不包含它。
 
 两种载体执行相同的 `dsh` 语法与随附 profile，包括独立的 `sdk-minimal` 配置树，以及包含前端产物的完整 `web` profile。私有 `dsh-python-runtime-closure` manifest（元数据清单）定义打包依赖闭包；不存在 Python 专用 Node 应用或检入的默认 `cordis.yml`。
diff --git a/python/sdk-runtime/hatch_build.py b/python/sdk-runtime/hatch_build.py
index 23551b2705..f1357bff52 100644
--- a/python/sdk-runtime/hatch_build.py
+++ b/python/sdk-runtime/hatch_build.py
@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import os
 import platform
+import runpy
 import stat
 from pathlib import Path
 
@@ -76,7 +77,7 @@ class RuntimeBuildHook(BuildHookInterface):
         target = next(name for name, value in _PLATFORMS.items() if value[0] == platform_tag)
         runtime_dir = Path(self.root) / "src" / "deepseek_harness_runtime" / "runtime"
         runtime_files = sorted(
-            runtime_dir.glob("deepseek-harness-sdk-runtime-*") if runtime_dir.is_dir() else []
+            (path for path in runtime_dir.iterdir() if path.name != "node") if runtime_dir.is_dir() else []
         )
         expected_files = (
             [expected_executable, f"{expected_executable.removesuffix('.exe')}-rg.exe"]
@@ -87,6 +88,8 @@ class RuntimeBuildHook(BuildHookInterface):
             expected_files.append(f"{expected_executable}-spawn-helper")
         office = runtime_dir / f"{expected_executable.removesuffix('.exe')}-office"
         expected_files.append(office.name)
+        resources = runtime_dir / target
+        expected_files.append(resources.name)
         expected_files.sort()
         found_files = [path.name for path in runtime_files]
         if found_files != expected_files:
@@ -94,6 +97,10 @@ class RuntimeBuildHook(BuildHookInterface):
                 f"runtime wheel {platform_tag} payload must be {expected_files}; found {found_files}"
             )
         for executable in runtime_files:
+            if executable == resources:
+                validate = runpy.run_path(str(runtime_dir.parent / "_resources.py"))["validate_resources"]
+                validate(resources, target)
+                continue
             if executable == office:
                 adapter = office / "node_modules/@deepseek-ai/libreoffice-kit/package.json"
                 if not adapter.is_file():
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index 244cf218db..16b4ba9886 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -86,6 +86,8 @@
     "@deepseek-ai/dsh-shell-env": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-skill-filesystem": "workspace:^",
+    "@deepseek-ai/dsh-skill-office": "workspace:^",
+    "@deepseek-ai/dsh-tool-workspace-dependencies": "workspace:^",
     "@deepseek-ai/dsh-spill": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-subagent-acp": "workspace:^",
diff --git a/python/sdk-runtime/pyproject.toml b/python/sdk-runtime/pyproject.toml
index 4e1c58fd2d..80c49db937 100644
--- a/python/sdk-runtime/pyproject.toml
+++ b/python/sdk-runtime/pyproject.toml
@@ -22,7 +22,13 @@ dsh = "deepseek_harness_runtime:main"
 
 # Include the injected dsh executable and sidecars; exclude the dev-only node closure.
 [tool.hatch.build]
-artifacts = ["src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*", "src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*/**"]
+artifacts = [
+  "src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*",
+  "src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*/**",
+  "src/deepseek_harness_runtime/runtime/linux-*/**",
+  "src/deepseek_harness_runtime/runtime/macos-*/**",
+  "src/deepseek_harness_runtime/runtime/win-*/**",
+]
 exclude = ["src/deepseek_harness_runtime/runtime/node"]
 
 [tool.hatch.build.targets.wheel]
diff --git a/python/sdk-runtime/runtime-bootstrap.mjs b/python/sdk-runtime/runtime-bootstrap.mjs
index 3db857c0a7..52836d746e 100644
--- a/python/sdk-runtime/runtime-bootstrap.mjs
+++ b/python/sdk-runtime/runtime-bootstrap.mjs
@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /** Private entry owned by the Python single-file runtime packaging. */
 import { registerHooks } from 'node:module'
+import { dirname, join } from 'node:path'
 import { isSea } from 'node:sea'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
@@ -28,6 +29,11 @@ if (aclRunner !== undefined && process.argv[2] === aclRunner) {
   Reflect.deleteProperty(process.env, 'DSH_PTC_RUNTIME_NODE')
   await import('@deepseek-ai/dsh-ptc-runtime-node/process')
 } else if (selection === undefined) {
+  if (isSea()) {
+    // Carrier default stays separate so process/home environment and profile patches can override it.
+    const platform = process.platform === 'darwin' ? 'macos' : process.platform === 'win32' ? 'win' : process.platform
+    process.env.DSH_BUNDLED_PRIMARY_RUNTIME = join(dirname(process.execPath), `${platform}-${process.arch}`, 'primary-runtime')
+  }
   const { runCli } = await import('@deepseek-ai/dsh/lib/bin.js')
   await runCli()
 } else {
diff --git a/python/sdk-runtime/src/deepseek_harness_runtime/__init__.py b/python/sdk-runtime/src/deepseek_harness_runtime/__init__.py
index 48c2b26057..174d629160 100644
--- a/python/sdk-runtime/src/deepseek_harness_runtime/__init__.py
+++ b/python/sdk-runtime/src/deepseek_harness_runtime/__init__.py
@@ -28,6 +28,7 @@ import shutil
 import subprocess
 import sys
 from pathlib import Path
+from ._resources import validate_resources
 
 PACKAGE_METADATA_FILENAME = "deepseek-harness-runtime.json"
 
@@ -59,7 +60,9 @@ def bundled_runtime_path() -> Path:
 
     Raises FileNotFoundError when the platform is unsupported, the executable
     has not been placed into this package, the ripgrep or Office sidecar is
-    missing, or the required macOS spawn helper is missing; the message names
+    missing, the authoring resources are incomplete, or the required macOS
+    spawn helper is missing. Invalid authoring metadata or Python permissions
+    raise ValueError. Missing executable/Office messages name
     the acquisition routes (acquisition strategy is deliberately separate from
     this lookup interface, so an on-demand download can replace it without
     touching callers).
@@ -104,6 +107,7 @@ def bundled_runtime_path() -> Path:
             f"deepseek-harness-runtime-bin is missing the Office sidecar engine {engine} at {office}. "
             + _EXE_ACQUISITION_HINT
         )
+    validate_resources(path.with_name(tag), tag)
     return path
 
 
diff --git a/python/sdk-runtime/src/deepseek_harness_runtime/_resources.py b/python/sdk-runtime/src/deepseek_harness_runtime/_resources.py
new file mode 100644
index 0000000000..df19cb2fa9
--- /dev/null
+++ b/python/sdk-runtime/src/deepseek_harness_runtime/_resources.py
@@ -0,0 +1,41 @@
+"""Validate the authoring resources in staged, installed, or archived runtime wheels."""
+
+from __future__ import annotations
+
+import json
+import re
+import stat
+import zipfile
+from pathlib import Path
+
+
+def validate_resources(root: Path | zipfile.Path, target: str) -> None:
+    """Reject a missing or wrong-target Python environment or bundled Office skill tree."""
+    manifest_path = root / "primary-runtime/runtime.json"
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"runtime authoring resources are missing: {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    platform, arch = target.rsplit("-", 1)
+    platform = {"macos": "darwin", "win": "win32"}.get(platform, platform)
+    if not isinstance(manifest, dict) or (manifest.get("platform"), manifest.get("arch")) != (platform, arch):
+        raise ValueError(f"runtime authoring resources do not match target {target}")
+    version = manifest.get("python")
+    if not isinstance(version, str) or not re.fullmatch(r"\d+\.\d+\.\d+", version):
+        raise ValueError("runtime authoring resources have invalid Python version metadata")
+    if not isinstance(manifest.get("pythonPackages"), dict) or not manifest["pythonPackages"]:
+        raise ValueError("runtime authoring resources have no Python distributions")
+    python_root = root / "primary-runtime/dependencies/python"
+    executable = python_root / ("python.exe" if platform == "win32" else "bin/python3")
+    packages = python_root / ("Lib/site-packages" if platform == "win32" else f"lib/python{version.rsplit('.', 1)[0]}/site-packages")
+    required = [executable, root / "office-skills/scripts/check_office.py"]
+    required.extend(root / f"office-skills/office-{kind}/SKILL.md" for kind in ("docx", "pptx", "xlsx"))
+    for path in required:
+        if not path.is_file():
+            raise FileNotFoundError(f"runtime authoring resource is missing: {path}")
+    if not packages.is_dir():
+        raise FileNotFoundError(f"runtime Python site-packages is missing: {packages}")
+    if platform != "win32":
+        mode = (executable.root.getinfo(executable.at).external_attr >> 16
+                if isinstance(executable, zipfile.Path) else executable.stat().st_mode)
+        if mode & stat.S_IXUSR == 0:
+            raise ValueError(f"runtime Python lost its executable bit: {executable}")
diff --git a/python/sdk/tests/manual_sdk_agent_smoke.py b/python/sdk/tests/manual_sdk_agent_smoke.py
index acadb495be..34c8f5b1f0 100644
--- a/python/sdk/tests/manual_sdk_agent_smoke.py
+++ b/python/sdk/tests/manual_sdk_agent_smoke.py
@@ -26,16 +26,22 @@ class MockCompletionHandler(BaseHTTPRequestHandler):
         body = self.rfile.read(length).decode("utf-8")
         self.requests.append({
             "path": self.path,
-            "authorization": self.headers.get("authorization"),
+            "api_key": self.headers.get("x-api-key"),
             "body": json.loads(body),
         })
         self.send_response(200)
         self.send_header("content-type", "text/event-stream")
         self.end_headers()
-        self.wfile.write(b'data: {"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":""}}]}\n\n')
-        self.wfile.write(b'data: {"choices":[{"delta":{"content":"SDK runtime reached the configured HTTP model endpoint."}}]}\n\n')
-        self.wfile.write(b'data: {"choices":[{"delta":{"content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":7,"completion_tokens":9}}\n\n')
-        self.wfile.write(b"data: [DONE]\n\n")
+        events = [
+            {"type": "message_start", "message": {"id": "sdk-smoke", "model": "sdk-smoke-model", "usage": {"input_tokens": 7, "output_tokens": 0}}},
+            {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}},
+            {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "SDK runtime reached the configured HTTP model endpoint."}},
+            {"type": "content_block_stop", "index": 0},
+            {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 9}},
+            {"type": "message_stop"},
+        ]
+        for event in events:
+            self.wfile.write(f"event: {event['type']}\ndata: {json.dumps(event)}\n\n".encode())
 
     def log_message(self, _format: str, *_args: object) -> None:
         return
@@ -46,7 +52,7 @@ def run_smoke(repo_root: Path, keep_sessions: bool) -> None:
     session_root = dsh_home / "sessions"
     runtime_entry = repo_root / "apps/cli/src/bin.ts"
     server = ThreadingHTTPServer(("127.0.0.1", 0), MockCompletionHandler)
-    thread = threading.Thread(target=server.serve_forever, name="mock-openai-compatible-server", daemon=True)
+    thread = threading.Thread(target=server.serve_forever, name="mock-messages-server", daemon=True)
     thread.start()
     base_url = f"http://127.0.0.1:{server.server_address[1]}"
 
@@ -86,7 +92,8 @@ def run_smoke(repo_root: Path, keep_sessions: bool) -> None:
         assert len(MockCompletionHandler.requests) == 1
         request = MockCompletionHandler.requests[0]
         print(json.dumps(request, ensure_ascii=False, indent=2)[:4000])
-        assert request["authorization"] == "Bearer sdk-smoke-key"
+        assert request["path"] == "/v1/messages"
+        assert request["api_key"] == "sdk-smoke-key"
         assert request["body"]["model"] == "sdk-smoke-model"
 
         jsonl_files = sorted(session_root.rglob("*.jsonl.zstd"))
diff --git a/python/sdk/tests/test_client.py b/python/sdk/tests/test_client.py
index 0d1cc64097..66b9b2665c 100644
--- a/python/sdk/tests/test_client.py
+++ b/python/sdk/tests/test_client.py
@@ -595,6 +595,15 @@ def test_client_keeps_unmatched_notifications_available_globally_while_subscribe
 def test_session_subscription_keeps_descendant_relationships_across_subscriptions() -> None:
     client = HarnessClient()
     with client.subscribe_session_notifications("main") as first:
+        unknown_child = {
+            "type": "subagent/catalog", "seq": 0, "time": 1,
+            "data": {"version": 1, "childId": "unreadable-child", "childCreatedAt": 1, "mode": "unknown"},
+        }
+        client._handle_message({
+            "jsonrpc": "2.0", "method": "session.event",
+            "params": {"sessionId": "main", "event": unknown_child},
+        })
+        assert first.next().payload == {"sessionId": "main", "event": unknown_child}
         client._handle_message({
             "jsonrpc": "2.0",
             "method": "subagent.started",
diff --git a/python/sdk/tests/test_release_version.py b/python/sdk/tests/test_release_version.py
index 39022df00c..b6ddb572e3 100644
--- a/python/sdk/tests/test_release_version.py
+++ b/python/sdk/tests/test_release_version.py
@@ -26,6 +26,18 @@ def test_release_tag_is_optional_for_non_release_builds() -> None:
     build_python_release.validate_release_tag(None, "1.2.3")
 
 
+def test_wheel_verification_uses_distribution_metadata_not_nested_libraries(tmp_path: Path) -> None:
+    wheel = tmp_path / "sdk.whl"
+    with zipfile.ZipFile(wheel, "w") as archive:
+        archive.writestr("nested/library.dist-info/WHEEL", "Tag: cp312-cp312-linux_x86_64\n")
+        archive.writestr("nested/library.dist-info/METADATA", "Name: library\nVersion: 0.0.1\n")
+        archive.writestr("deepseek_harness_sdk-1.2.3.dist-info/WHEEL", "Tag: py3-none-any\n")
+        archive.writestr("deepseek_harness_sdk-1.2.3.dist-info/METADATA",
+                         "Name: deepseek-harness-sdk\nVersion: 1.2.3\nLicense-Expression: MIT\n"
+                         "License-File: LICENSE\nRequires-Dist: deepseek-harness-runtime-bin==1.2.3\n")
+    build_python_release.verify_wheel(wheel, "sdk", "1.2.3", None)
+
+
 def test_release_tag_must_match_repository_version() -> None:
     build_python_release.validate_release_tag("python-v1.2.3", "1.2.3")
 
@@ -96,6 +108,19 @@ def test_stage_sdk_keeps_distribution_module_and_runtime_pin_distinct(tmp_path:
     assert (destination / "src" / "deepseek_harness" / "__init__.py").is_file()
 
 
+def test_copy_package_omits_generated_carriers_before_staging_one_target(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    module = source / "src/deepseek_harness_runtime"
+    for path in ("runtime/macos-arm64/primary-runtime/runtime.json", "runtime/node/package.json",
+                 "runtime/deepseek-harness-sdk-runtime-win-x64.exe", "__init__.py", "_resources.py"):
+        file = module / path
+        file.parent.mkdir(parents=True, exist_ok=True)
+        file.touch()
+    destination = tmp_path / "staged"
+    build_python_release.copy_package(source, destination)
+    assert sorted(path.name for path in (destination / "src/deepseek_harness_runtime").iterdir()) == ["__init__.py", "_resources.py"]
+
+
 @pytest.mark.parametrize(
     ("target", "with_helper"),
     [("linux-x64", False), ("macos-arm64", True), ("macos-x64", True), ("win-x64.exe", False)],
@@ -124,6 +149,10 @@ def test_stage_runtime_copies_platform_payload(
     office_asset = office / "node_modules" / "@deepseek-ai" / "libreoffice-kit-wasm" / "assets" / "soffice.data"
     office_asset.parent.mkdir(parents=True)
     office_asset.write_bytes(b"office data")
+    resources = executable.with_name(executable.name.removeprefix("deepseek-harness-sdk-runtime-").removesuffix(".exe"))
+    resource = resources / "office-skills/scripts/check_office.py"
+    resource.parent.mkdir(parents=True)
+    resource.write_text("checker")
     destination = tmp_path / "staging"
 
     build_python_release.stage_runtime(destination, "1.2.3", executable, executable.name)
@@ -135,6 +164,7 @@ def test_stage_runtime_copies_platform_payload(
         if path.is_file()
     } == expected
     assert (runtime_dir / office.name / office_asset.relative_to(office)).read_bytes() == b"office data"
+    assert (runtime_dir / resources.name / resource.relative_to(resources)).read_text() == "checker"
     pyproject = (destination / "pyproject.toml").read_text()
     assert 'license = "MIT"' in pyproject
     assert 'license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]' in pyproject
diff --git a/python/sdk/tests/test_runtime_resolution.py b/python/sdk/tests/test_runtime_resolution.py
index a1b071e7a0..ecab8a3159 100644
--- a/python/sdk/tests/test_runtime_resolution.py
+++ b/python/sdk/tests/test_runtime_resolution.py
@@ -6,11 +6,13 @@ import json
 import os
 import subprocess
 import sys
+import zipfile
 from pathlib import Path
 from types import SimpleNamespace
 
 import deepseek_harness_runtime as runtime
 import pytest
+from deepseek_harness_runtime._resources import validate_resources
 
 from deepseek_harness_runtime import (
     RUNTIME_MODE_ENV_VAR,
@@ -20,7 +22,7 @@ from deepseek_harness_runtime import (
 )
 
 
-def _office_sidecar(executable: Path, native_targets: tuple[str, ...] = ("darwin-arm64", "darwin-x64", "win32-x64")) -> Path:
+def _resource_sidecars(executable: Path, native_targets: tuple[str, ...] = ("darwin-arm64", "darwin-x64", "win32-x64")) -> Path:
     office = executable.with_name(f"{executable.name.removesuffix('.exe')}-office")
     tag = executable.name.removeprefix("deepseek-harness-sdk-runtime-").removesuffix(".exe")
     native = tag.replace("win-", "win32-").replace("macos-", "darwin-")
@@ -33,6 +35,21 @@ def _office_sidecar(executable: Path, native_targets: tuple[str, ...] = ("darwin
     adapter.write_text(json.dumps({"optionalDependencies": {
         f"@deepseek-ai/libreoffice-kit-{target}": "0.0.1" for target in (*native_targets, "wasm")
     }}), encoding="utf-8")
+    resources = executable.with_name(tag)
+    manifest = resources / "primary-runtime/runtime.json"
+    manifest.parent.mkdir(parents=True)
+    manifest.write_text(json.dumps({"platform": native.rsplit("-", 1)[0], "arch": tag.rsplit("-", 1)[1],
+                                    "python": "3.12.14", "pythonPackages": {"numpy": "2.3.5"}}))
+    python = resources / "primary-runtime/dependencies/python" / ("python.exe" if tag.startswith("win-") else "bin/python3")
+    python.parent.mkdir(parents=True)
+    python.touch()
+    python.chmod(0o755)
+    packages = python.parent if tag.startswith("win-") else python.parent.parent
+    (packages / ("Lib/site-packages" if tag.startswith("win-") else "lib/python3.12/site-packages")).mkdir(parents=True)
+    for file in ["scripts/check_office.py", *(f"office-{kind}/SKILL.md" for kind in ("docx", "pptx", "xlsx"))]:
+        path = resources / "office-skills" / file
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.touch()
     return office
 
 
@@ -41,6 +58,43 @@ def test_unknown_explicit_mode_fails_loud() -> None:
         resolve_bundled_launch_args("bogus")
 
 
+@pytest.mark.parametrize("target", ["linux-x64", "linux-arm64", "macos-arm64", "macos-x64", "win-x64"])
+@pytest.mark.parametrize("invalid", [None, "manifest", "platform", "python", "skills", "packages", "mode"])
+def test_authoring_resources_validate_installed_and_wheel_payloads(tmp_path: Path, target: str, invalid: str | None) -> None:
+    executable = tmp_path / f"deepseek-harness-sdk-runtime-{target}"
+    _resource_sidecars(executable)
+    root = tmp_path / target
+    python = root / "primary-runtime/dependencies/python" / ("python.exe" if target == "win-x64" else "bin/python3")
+    if invalid == "mode" and target == "win-x64":
+        pytest.skip("Windows executables do not require a POSIX executable bit")
+    if invalid == "manifest":
+        (root / "primary-runtime/runtime.json").unlink()
+    elif invalid == "platform":
+        manifest_path = root / "primary-runtime/runtime.json"
+        manifest = json.loads(manifest_path.read_text())
+        manifest["arch"] = "wrong"
+        manifest_path.write_text(json.dumps(manifest))
+    elif invalid == "python":
+        python.unlink()
+    elif invalid == "skills":
+        (root / "office-skills/office-docx/SKILL.md").unlink()
+    elif invalid == "packages":
+        next(root.rglob("site-packages")).rmdir()
+    elif invalid == "mode":
+        python.chmod(0o644)
+    archive_path = tmp_path / "payload.zip"
+    with zipfile.ZipFile(archive_path, "w") as archive:
+        for path in root.rglob("*"):
+            archive.write(path, str(path.relative_to(root)).replace("\\", "/"))
+    with zipfile.ZipFile(archive_path) as archive:
+        for candidate in (root, zipfile.Path(archive)):
+            if invalid is None:
+                validate_resources(candidate, target)
+            else:
+                with pytest.raises((ValueError, FileNotFoundError)):
+                    validate_resources(candidate, target)
+
+
 def test_unknown_env_mode_fails_loud(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv(RUNTIME_MODE_ENV_VAR, "bogus")
     with pytest.raises(ValueError, match="expected 'exe' or 'node'"):
@@ -64,7 +118,7 @@ def test_runtime_requires_spawn_helper_only_on_macos(
     linux = runtime_dir / "deepseek-harness-sdk-runtime-linux-x64"
     linux.touch()
     Path(f"{linux}-rg").touch()
-    _office_sidecar(linux)
+    _resource_sidecars(linux)
     macos = runtime_dir / "deepseek-harness-sdk-runtime-macos-arm64"
     macos.touch()
     Path(f"{macos}-rg").touch()
@@ -85,7 +139,7 @@ def test_windows_runtime_uses_exe_payload_and_exe_sidecar(
     executable = runtime_dir / "deepseek-harness-sdk-runtime-win-x64.exe"
     executable.touch()
     (runtime_dir / "deepseek-harness-sdk-runtime-win-x64-rg.exe").touch()
-    _office_sidecar(executable)
+    _resource_sidecars(executable)
     monkeypatch.setattr(runtime, "bundled_package_dir", lambda: tmp_path)
     monkeypatch.setattr(runtime, "_current_platform_tag", lambda: "win-x64")
 
@@ -122,7 +176,7 @@ def test_runtime_requires_ripgrep_sidecar(
         runtime.bundled_runtime_path()
 
 
-def test_runtime_requires_complete_office_sidecar(
+def test_runtime_requires_complete_resource_sidecars(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     executable = tmp_path / "runtime" / "deepseek-harness-sdk-runtime-linux-x64"
@@ -134,7 +188,7 @@ def test_runtime_requires_complete_office_sidecar(
 
     with pytest.raises(FileNotFoundError, match="Office sidecar"):
         runtime.bundled_runtime_path()
-    office = _office_sidecar(executable)
+    office = _resource_sidecars(executable)
     assert runtime.bundled_runtime_path() == executable
     (office / "node_modules/@deepseek-ai/libreoffice-kit-wasm/prebuilds.json").unlink()
     with pytest.raises(FileNotFoundError, match="Office sidecar"):
@@ -250,7 +304,7 @@ def test_runtime_requires_its_platform_office_engine(
     executable.with_name(f"{executable.stem}-rg{extension}").touch()
     if target.startswith("macos-"):
         Path(f"{executable}-spawn-helper").touch()
-    office = _office_sidecar(executable, native_targets)
+    office = _resource_sidecars(executable, native_targets)
     monkeypatch.setattr(runtime, "bundled_package_dir", lambda: tmp_path)
     monkeypatch.setattr(runtime, "_current_platform_tag", lambda: target)
     assert runtime.bundled_runtime_path() == executable
diff --git a/scripts/build-exe-for-python-sdk.spec.ts b/scripts/build-exe-for-python-sdk.spec.ts
index b0c937a9eb..f2f563fd61 100644
--- a/scripts/build-exe-for-python-sdk.spec.ts
+++ b/scripts/build-exe-for-python-sdk.spec.ts
@@ -101,6 +101,8 @@ describe('Python runtime executable builder CLI', () => {
     expect(result.status).toBe(0)
     expect(result.stdout).toContain('exec pkg')
     expect(result.stdout).toContain('--sea --targets node24-macos-x64')
+    expect(result.stdout).toContain('prepare Python and Office skills for mac-x64')
+    expect(result.stdout).toContain(join(root, 'dist-exe', 'macos-x64'))
   })
 
   it('rejects a Windows arm64 product before any build step', () => {
diff --git a/scripts/build-exe-for-python-sdk.ts b/scripts/build-exe-for-python-sdk.ts
index fc06183c91..341bf95a35 100644
--- a/scripts/build-exe-for-python-sdk.ts
+++ b/scripts/build-exe-for-python-sdk.ts
@@ -9,10 +9,12 @@
 import { spawn } from 'node:child_process'
 import { existsSync, statSync } from 'node:fs'
 import { chmod, copyFile, cp, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { basename, dirname, extname, join, resolve, sep } from 'node:path'
 import { parseArgs } from 'node:util'
 import { resolveLinuxNodePtyAddon, resolveWindowsNodePtyAddons } from './build-exe-for-python-sdk-native-pty.ts'
 import { copyOfficeSidecar, OFFICE_ASSET_IGNORES } from './build-exe-for-python-sdk-office.ts'
+import { preparePrimaryRuntime, smokePrimaryRuntime, type PrimaryRuntimeTarget } from './primary-runtime/prepare.ts'
 
 const root = resolve(import.meta.dirname, '..')
 
@@ -419,7 +421,7 @@ class SingleExeBuild {
   /**
    * Package one target; SEA mode accepts one target per invocation.
    * @param target - the pkg target triple to build.
-   * @returns the executable, Office directory, ripgrep, and required macOS spawn helper paths.
+   * @returns the executable, resource directories, ripgrep, and required macOS spawn helper paths.
    */
   async pack(target: Target): Promise<string[]> {
     const productBase = join(this.outDir, `${OUTPUT_BASENAME}-${target.platform}-${target.arch}`)
@@ -448,7 +450,17 @@ class SingleExeBuild {
       console.log(`build-exe-for-python-sdk: copied ${packages.length} Office packages to ${office}`)
     }
     const ripgrep = await this.copyRipgrepSidecar(target, product)
-    if (target.platform !== 'macos') return [product, ripgrep, office]
+    const resources = join(this.outDir, `${target.platform}-${target.arch}`)
+    const runtimeTarget = `${target.platform === 'macos' ? 'mac' : target.platform}-${target.arch}` as PrimaryRuntimeTarget
+    if (this.cli.dryRun) {
+      console.log(`build-exe-for-python-sdk: [dry-run] prepare Python and Office skills for ${runtimeTarget} in ${resources}`)
+    } else {
+      const { version } = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) as { version: string }
+      await preparePrimaryRuntime({ target: runtimeTarget, output: resources,
+        cache: join(tmpdir(), 'dsh-primary-runtime-downloads'), version, pythonOnly: true })
+      smokePrimaryRuntime(join(resources, 'primary-runtime'))
+    }
+    if (target.platform !== 'macos') return [product, ripgrep, office, resources]
     const spawnHelper = `${product}-spawn-helper`
     const source = join(this.staging, 'node_modules', 'node-pty', 'prebuilds', `darwin-${target.arch}`, 'spawn-helper')
     if (this.cli.dryRun) {
@@ -457,7 +469,7 @@ class SingleExeBuild {
       await copyFile(source, spawnHelper)
       await chmod(spawnHelper, 0o755)
     }
-    return [product, ripgrep, spawnHelper, office]
+    return [product, ripgrep, spawnHelper, office, resources]
   }
 
   /** Copy the target ripgrep binary beside the executable so Node can spawn it outside pkg's virtual filesystem. */
@@ -548,7 +560,7 @@ class SingleExeBuild {
         continue
       }
       if (statSync(path).isDirectory()) {
-        console.log(`  ${path}  (Office dependency directory)`)
+        console.log(`  ${path}  (resource directory)`)
         continue
       }
       const megabytes = statSync(path).size / (1024 * 1024)
diff --git a/scripts/build-python-release.py b/scripts/build-python-release.py
index 4e5bfb4e1e..2918feb380 100644
--- a/scripts/build-python-release.py
+++ b/scripts/build-python-release.py
@@ -8,6 +8,7 @@ import email
 import json
 import os
 import re
+import runpy
 import shutil
 import stat
 import subprocess
@@ -148,18 +149,21 @@ def validate_release_tag(tag: str | None, version: str) -> None:
 
 
 def copy_package(source: Path, destination: Path) -> None:
+    generated_parent = source / "src" / "deepseek_harness_runtime"
+    ignore_files = shutil.ignore_patterns(
+        ".venv", ".pytest_cache", "__pycache__", "*.pyc", "dist", "node_modules",
+    )
+
+    def ignore(directory: str, names: list[str]) -> set[str]:
+        ignored = ignore_files(directory, names)
+        if Path(directory) == generated_parent:
+            ignored.add("runtime")
+        return ignored
+
     shutil.copytree(
         source,
         destination,
-        ignore=shutil.ignore_patterns(
-            ".venv",
-            ".pytest_cache",
-            "__pycache__",
-            "*.pyc",
-            "dist",
-            "node_modules",
-            "deepseek-harness-sdk-runtime-*",
-        ),
+        ignore=ignore,
     )
 
 
@@ -227,6 +231,8 @@ def stage_runtime(destination: Path, version: str, executable: Path, executable_
         shutil.copy2(source_directory / filename, runtime_dir / filename)
     office = office_sidecar_name(executable_name)
     shutil.copytree(source_directory / office, runtime_dir / office)
+    resources = executable_name.removeprefix("deepseek-harness-sdk-runtime-").removesuffix(".exe")
+    shutil.copytree(source_directory / resources, runtime_dir / resources)
 
 
 def verify_office_payload(archive: zipfile.ZipFile, office_modules: str, platform_tag: str) -> None:
@@ -272,16 +278,17 @@ def verify_wheel(
     platform: tuple[str, str] | None,
 ) -> None:
     expected_tag = "py3-none-any" if platform is None else f"py3-none-{platform[0]}"
+    expected_distribution = SDK_DISTRIBUTION if package == "sdk" else RUNTIME_DISTRIBUTION
+    dist_info = f"{expected_distribution.replace('-', '_')}-{version}.dist-info"
     with zipfile.ZipFile(wheel) as archive:
-        wheel_metadata_path = next(name for name in archive.namelist() if name.endswith(".dist-info/WHEEL"))
-        metadata_path = next(name for name in archive.namelist() if name.endswith(".dist-info/METADATA"))
+        wheel_metadata_path = f"{dist_info}/WHEEL"
+        metadata_path = f"{dist_info}/METADATA"
         wheel_metadata = email.message_from_bytes(archive.read(wheel_metadata_path))
         metadata = email.message_from_bytes(archive.read(metadata_path))
         if wheel_metadata.get_all("Tag") != [expected_tag]:
             raise RuntimeError(f"{wheel} has wrong WHEEL tags: {wheel_metadata.get_all('Tag')}")
         if metadata.get("Version") != version:
             raise RuntimeError(f"{wheel} has version {metadata.get('Version')}, expected {version}")
-        expected_distribution = SDK_DISTRIBUTION if package == "sdk" else RUNTIME_DISTRIBUTION
         if metadata.get("Name") != expected_distribution:
             raise RuntimeError(
                 f"{wheel} has distribution name {metadata.get('Name')}, expected {expected_distribution}"
@@ -297,17 +304,21 @@ def verify_wheel(
                 f"{wheel} has license files {license_files}, expected {expected_license_files}"
             )
         runtime_payload = [
-            name for name in archive.namelist() if "/runtime/deepseek-harness-sdk-runtime-" in name
+            name for name in archive.namelist() if name.startswith("deepseek_harness_runtime/runtime/")
         ]
         if package == "runtime":
             assert platform is not None
             office = office_sidecar_name(platform[1])
-            expected_files = sorted((*runtime_filenames(platform[1]), office))
+            resources = platform[1].removeprefix("deepseek-harness-sdk-runtime-").removesuffix(".exe")
+            expected_files = sorted((*runtime_filenames(platform[1]), office, resources))
             found_files = sorted({name.split("/runtime/", 1)[1].split("/", 1)[0] for name in runtime_payload})
             if found_files != expected_files:
                 raise RuntimeError(f"{wheel} runtime payload must be {expected_files}, found {found_files}")
             office_modules = f"deepseek_harness_runtime/runtime/{office}/node_modules"
             verify_office_payload(archive, office_modules, platform[0])
+            validate = runpy.run_path(str(ROOT / "python/sdk-runtime/src/deepseek_harness_runtime/_resources.py"))["validate_resources"]
+            target = next(name for name, value in PLATFORMS.items() if value == platform)
+            validate(zipfile.Path(archive, f"deepseek_harness_runtime/runtime/{resources}/"), target)
             for runtime_file in runtime_payload:
                 if "/" in runtime_file.split("/runtime/", 1)[1]:
                     continue
diff --git a/scripts/check-workspace-constraints.spec.ts b/scripts/check-workspace-constraints.spec.ts
index 0a06641c14..7031e2f9a0 100644
--- a/scripts/check-workspace-constraints.spec.ts
+++ b/scripts/check-workspace-constraints.spec.ts
@@ -164,6 +164,20 @@ describe('dsh family version coherence', () => {
 })
 
 describe('package payload constraints', () => {
+  it.each(['./art/icon.svg', 'art/icon.svg'])('includes declared icon %s in the canonical payload', (icon) => {
+    expect(expectedDshPackageFiles({ icon, exports: { './locale/*.json': './locale/*.json' } })).toEqual([
+      'art/icon.svg', 'locale/*.json', 'lib/index.js', 'lib/types/**/*.d.ts',
+    ])
+  })
+
+  it('accepts the Agent Team icon payload and rejects its omission', () => {
+    const dir = 'packages/experimental/agent-team-profile'
+    const manifest = JSON.parse(readFileSync(new URL(`../${dir}/package.json`, import.meta.url), 'utf8')) as WorkspaceManifest['manifest']
+    expect(checkWorkspaceManifest({ dir, manifest })).toEqual([])
+    expect(checkWorkspaceManifest({ dir, manifest: { ...manifest, files: manifest.files!.filter(file => file !== 'icon.svg') } }))
+      .toEqual([expect.stringContaining('package.json files must be')])
+  })
+
   it.each([
     { exports: { './locale/*.json': './locale/*.json' }, resources: ['locale/*.json'] },
     { exports: { './search/locale/*.json': './resources/search/*.json' }, resources: ['resources/search/*.json'] },
@@ -218,6 +232,15 @@ describe('package payload constraints', () => {
       'cordis.patch.yml',
       'lib/types/**/*.d.ts',
     ])
+    expect(expectedDshPackageFiles({
+      name: '@deepseek-ai/dsh-private-profile',
+      dsh: { bundle: { patch: ['./cordis.patch.yml', './layers/web.patch.yml'] } },
+    })).toEqual([
+      'lib/index.js',
+      'cordis.patch.yml',
+      'layers/web.patch.yml',
+      'lib/types/**/*.d.ts',
+    ])
   })
 
   it.each([
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 2372546421..146db83921 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -13,7 +13,8 @@ import {
   PRIVATE_EXPERIMENTAL_PACKAGE_DIRECTORIES,
 } from './experimental-package-policy.ts'
 import { hasTypertRemoteNavigation, isForbiddenPublicationFile } from './publication-payload.ts'
-import { OPTIONAL_BUNDLES } from '../packages/boot/app-boot/src/profile.ts'
+import type { DshBundleManifest } from '../packages/util/package-manifest/src/types.ts'
+import { OPTIONAL_BUNDLES, bundlePatchFiles } from '../packages/boot/app-boot/src/profile.ts'
 import { collectProjectReferenceFaceViolations } from './project-reference-faces.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -90,6 +91,7 @@ export interface PackageManifest {
     | undefined
   >
   files?: string[]
+  icon?: string
   publishConfig?: { access?: string }
   repository?: { type?: string; url?: string; directory?: string }
   peerDependencies?: Record<string, string>
@@ -97,9 +99,7 @@ export interface PackageManifest {
   dependencies?: Record<string, string>
   optionalDependencies?: Record<string, string>
   dsh?: {
-    bundle?: {
-      patch?: string
-    }
+    bundle?: DshBundleManifest
   }
 }
 
@@ -210,9 +210,9 @@ function sameStringList(actual: readonly string[] | undefined, expected: readonl
 }
 
 /**
- * Compute canonical publication patterns, including explicitly exported locale JSON resources.
+ * Compute canonical publication patterns, including the declared icon and exported locale JSON resources.
  * @param manifest - workspace package manifest.
- * @returns deduplicated locale targets followed by the package's runtime and declaration payloads.
+ * @returns the icon and deduplicated locale targets followed by runtime and declaration payloads.
  */
 export function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
   const localeFiles = new Set<string>()
@@ -221,13 +221,14 @@ export function expectedDshPackageFiles(manifest: PackageManifest): readonly str
     const target = exportDefault(manifest, resource)
     if (target?.startsWith('./') && target.endsWith('.json')) localeFiles.add(target.slice(2))
   }
-  const declaredPatch = manifest.dsh?.bundle?.patch
-  const bundleFiles = declaredPatch === undefined ? [] : [declaredPatch.replace(/^\.\//, '')]
+  const bundle = manifest.dsh?.bundle
+  const bundleFiles = bundle === undefined ? [] : bundlePatchFiles(bundle).map(file => file.replace(/^\.\//, ''))
   const extras = [
     ...bundleFiles,
     ...(manifest.name ? packageFileExtras[manifest.name] ?? [] : []),
   ]
   return [
+    ...typeof manifest.icon === 'string' ? [manifest.icon.replace(/^\.\//u, '')] : [],
     ...[...localeFiles].sort(),
     'lib/index.js',
     // Packages with an invariant export publish its runtime as a separate
diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts
index ed3ca6a0a8..cf706b334c 100644
--- a/scripts/client-bundle-purity.spec.ts
+++ b/scripts/client-bundle-purity.spec.ts
@@ -141,6 +141,8 @@ describe('client bundle purity gate', () => {
     expect(() => resolveId('@deepseek-ai/dsh-token-meter')).toThrow(/purity/)
     expect(() => resolveId('@deepseek-ai/dsh-token-meter/client/internal')).toThrow(/purity/)
     expect(resolveId('@deepseek-ai/dsh-host-open-in-app/shared')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-native-command/types')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-native-command')).toThrow('client bundle purity')
     expect(() => resolveId('@deepseek-ai/dsh-host-open-in-app')).toThrow(/purity/)
     expect(resolveId('@deepseek-ai/dsh-plugin-manager/registry')).toBeNull()
     expect(() => resolveId('@deepseek-ai/dsh-plugin-manager')).toThrow(/purity/)
diff --git a/scripts/dev-web.spec.ts b/scripts/dev-web.spec.ts
index 76dbf82860..df1274c57c 100644
--- a/scripts/dev-web.spec.ts
+++ b/scripts/dev-web.spec.ts
@@ -1,15 +1,112 @@
 import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import type { TsdownBundle } from 'tsdown'
 import { writeClientBuildRecord } from './client-build-environment.ts'
 import {
   devWebBuildEnvironment,
   discoverLibraryDirs,
   discoverPluginDirs,
+  parseDevWebArguments,
+  StageSupervisor,
   watchClientPlugins,
 } from './dev-web.ts'
+import type { StageHandle } from './dev-web.ts'
+
+/** A stage double that exits only on the listed signals or an explicit exit code. */
+function fakeStage(name: string, exitOn: readonly NodeJS.Signals[]): {
+  handle: StageHandle
+  signals: NodeJS.Signals[]
+  exit: (code: number) => void
+} {
+  const exit = Promise.withResolvers<number | null>()
+  const signals: NodeJS.Signals[] = []
+  return {
+    handle: {
+      name,
+      exited: exit.promise,
+      kill(signal) {
+        signals.push(signal)
+        if (exitOn.includes(signal)) exit.resolve(null)
+      },
+    },
+    signals,
+    exit: (code) => { exit.resolve(code) },
+  }
+}
+
+describe('StageSupervisor', () => {
+  it('reports a stage that exits on its own', async () => {
+    const stale: [string, number | null][] = []
+    const supervisor = new StageSupervisor((name, code) => { stale.push([name, code]) })
+    const tsc = fakeStage('tsc', ['SIGTERM'])
+    supervisor.add(tsc.handle)
+    tsc.exit(2)
+    await tsc.handle.exited
+    expect(stale).toEqual([['tsc', 2]])
+  })
+
+  it('forwards one signal, escalates survivors after the grace period, and reports none of them', async () => {
+    const stale: string[] = []
+    const supervisor = new StageSupervisor((name) => { stale.push(name) })
+    const polite = fakeStage('vite', ['SIGTERM'])
+    const stubborn = fakeStage('dsh web', ['SIGKILL'])
+    supervisor.add(polite.handle)
+    supervisor.add(stubborn.handle)
+    await supervisor.stop({ signal: 'SIGTERM', graceMs: 20 })
+    expect(polite.signals).toEqual(['SIGTERM'])
+    expect(stubborn.signals).toEqual(['SIGTERM', 'SIGKILL'])
+    expect(stale).toEqual([])
+  })
+
+  it('waits for stages the terminal already interrupted before signaling survivors', async () => {
+    const supervisor = new StageSupervisor(() => { throw new Error('unexpected stale report') })
+    const interrupted = fakeStage('tsdown', [])
+    const survivor = fakeStage('dsh web', ['SIGTERM'])
+    supervisor.add(interrupted.handle)
+    supervisor.add(survivor.handle)
+    const stopping = supervisor.stop({ graceMs: 20 })
+    interrupted.exit(130)
+    await stopping
+    expect(interrupted.signals).toEqual([])
+    expect(survivor.signals).toEqual(['SIGTERM'])
+  })
+})
+
+describe('parseDevWebArguments', () => {
+  it('builds, serves, and watches natively by default', () => {
+    expect(parseDevWebArguments([])).toEqual({ skipBuild: false, serve: true, pollInterval: undefined, appArgs: [] })
+  })
+
+  it('reads the polling interval with its 500ms default', () => {
+    expect(parseDevWebArguments(['--poll']).pollInterval).toBe(500)
+    expect(parseDevWebArguments(['--poll=250']).pollInterval).toBe(250)
+  })
+
+  it.each(['--poll=abc', '--poll=0', '--poll=-5', '--poll=1.5'])('rejects the polling interval %s', (flag) => {
+    expect(() => parseDevWebArguments([flag])).toThrow(`invalid --poll interval "${flag}"`)
+  })
+
+  it('separates its own flags from the arguments forwarded to dsh web', () => {
+    expect(parseDevWebArguments(['--skip-build', '--poll', '--no-open', '--port', '8080'])).toEqual({
+      skipBuild: true, serve: true, pollInterval: 500, appArgs: ['--no-open', '--port', '8080'],
+    })
+  })
+
+  it('runs only the rebuild watchers with --no-serve', () => {
+    expect(parseDevWebArguments(['--no-serve', '--skip-build'])).toMatchObject({ serve: false, skipBuild: true })
+  })
+
+  it('ignores the separator pnpm run forwards verbatim', () => {
+    expect(parseDevWebArguments(['--', '--no-open']).appArgs).toEqual(['--no-open'])
+    expect(parseDevWebArguments(['--no-serve', '--'])).toMatchObject({ serve: false, appArgs: [] })
+  })
+
+  it('rejects dsh web arguments when no server is started', () => {
+    expect(() => parseDevWebArguments(['--no-serve', '--no-open'])).toThrow('--no-serve leaves no dsh web process for --no-open')
+  })
+})
 
 it('samples one local environment at startup without validating watcher outputs', async () => {
   const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-environment-'))
diff --git a/scripts/dev-web.ts b/scripts/dev-web.ts
index 35500eca13..dd282d773c 100644
--- a/scripts/dev-web.ts
+++ b/scripts/dev-web.ts
@@ -1,28 +1,38 @@
 /**
- * Watch-build for the web dev loop: rebuilds every artifact the browser reads
- * from a source edit. Reload signaling is not this script's business — the host
- * webserver stat-polls the bundles it serves and 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.
+ * The Web development loop: build once, serve through `dsh web`, and keep every
+ * browser-side artifact rebuilt on source edits, in one terminal.
  *
- * Three stages, because the compile shell links built lib products rather than
- * sources: `tsc -b tsconfig.client.json` emits `lib/types` (the tsdown lib
- * entries are that emit, not `src`), tsdown bundles `lib/index.js` and
- * `lib/client.js`, and `vite build` rewrites `apps/web/dist`, which `dsh web`
- * serves. A missing stage does not fail — it silently shows the previous
- * artifact, so an edit appears to do nothing.
+ * Stages, in order: `pnpm run build` (skipped by `--skip-build`), three
+ * long-lived watchers, then `dsh web` (skipped by `--no-serve`). The watchers
+ * exist because the compile shell links built lib products rather than
+ * sources: `tsc -b tsconfig.client.json --watch` emits `lib/types` (the tsdown
+ * lib entries are that emit, not `src`), tsdown watch bundles `lib/index.js`
+ * and `lib/client.js`, and `vite build --watch` rewrites `apps/web/dist`, which
+ * `dsh web` serves. A missing watcher does not fail — it silently shows the
+ * previous artifact, so an edit appears to do nothing; any stage exiting on its
+ * own therefore stops the loop with exit code 1.
  *
- * MUST NOT run concurrently with `pnpm run build`: both write the same
- * `lib/` and `apps/web/dist/` trees.
+ * Reload signaling is not this script's business — the host webserver
+ * stat-polls the bundles it serves and broadcasts `rebuilt` frames itself, so
+ * any process that rewrites `lib/client.js` files triggers reloads.
  *
- * Usage: `pnpm exec tsx scripts/dev-web.ts [--poll[=ms]]`. Requires one prior
- * `pnpm run build`: every stage is incremental over the previous stage's output
- * and none of them bootstraps a missing tree. `--poll` switches the source
- * watchers to polling (default 500ms): network mounts (weka) deliver no inotify
- * events, so native watching sees the initial build only and never a source
- * change. Polling has to reach tsc too — a native-watching tsc never re-emits
- * `lib/types`, which strands the other two stages on stale input.
+ * MUST NOT run beside `pnpm run build`: both write the same `lib/` and
+ * `apps/web/dist/` trees. The build stage here finishes before any watcher starts.
+ *
+ * Usage: `pnpm run dev:web [--skip-build] [--no-serve] [--poll[=ms]] [dsh web arguments]`.
+ * `--skip-build` requires the artifact tree from a prior complete build: every
+ * watcher is incremental over the previous stage's output and none of them
+ * bootstraps a missing tree. `--no-serve` keeps only the watchers, for a
+ * `dsh web` started elsewhere. `--poll` switches the source watchers to polling
+ * (default 500ms): network mounts (weka) deliver no inotify events, so native
+ * watching sees the initial build only and never a source change. Polling has
+ * to reach tsc too — a native-watching tsc never re-emits `lib/types`, which
+ * strands the other two stages on stale input.
+ *
+ * Shutdown: Ctrl+C reaches every stage through the terminal's process group, so
+ * the script only waits for them and escalates survivors; SIGTERM is addressed
+ * to this process alone and is forwarded once. The exit code is 130 after
+ * SIGINT, 0 after SIGTERM, and 1 when a stage exited on its own.
  *
  * Each package keeps its own tsdown.config.ts untouched: this script layers
  * `watch` through API-level inline config (tsdown workspace mode fills inline
@@ -39,6 +49,7 @@ import {
   clientBuildProcessEnvironment,
   repositoryClientBuildEnvironment,
 } from './client-build-environment.ts'
+import { pnpmInvocation } from './pnpm-invocation.ts'
 
 const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 
@@ -67,6 +78,51 @@ export function devWebBuildEnvironment(
   return clientBuildProcessEnvironment(environment, repositoryClientBuildEnvironment(root, environment))
 }
 
+/** Resolved `dev-web` command line: the script's own flags plus the arguments forwarded to `dsh web`. */
+export interface DevWebArguments {
+  /** Skip the complete `pnpm run build` that otherwise precedes the watchers. */
+  readonly skipBuild: boolean
+  /** Start `dsh web`; false keeps only the rebuild watchers beside an already running server. */
+  readonly serve: boolean
+  /** Source-watcher polling interval in milliseconds; undefined selects native watching. */
+  readonly pollInterval: number | undefined
+  /** Arguments forwarded verbatim to `dsh web`, in order. */
+  readonly appArgs: readonly string[]
+}
+
+/** Polling interval selected by a bare `--poll`. */
+const DEFAULT_POLL_INTERVAL = 500
+
+/**
+ * Parse the script's command line. `--skip-build`, `--no-serve`, and `--poll[=ms]`
+ * belong to this script; a bare `--` is dropped; every other token is forwarded
+ * to `dsh web`.
+ * @param argv - arguments after the script path.
+ * @returns the resolved flags and forwarded arguments.
+ * @throws Error when `--poll` carries a non-positive or non-integer interval, or
+ * when `--no-serve` leaves forwarded arguments without a `dsh web` process.
+ */
+export function parseDevWebArguments(argv: readonly string[]): DevWebArguments {
+  let skipBuild = false
+  let serve = true
+  let pollInterval: number | undefined
+  const appArgs: string[] = []
+  for (const arg of argv) {
+    // `pnpm run` forwards a `--` separator verbatim; it carries no meaning here.
+    if (arg === '--') continue
+    if (arg === '--skip-build') skipBuild = true
+    else if (arg === '--no-serve') serve = false
+    else if (arg === '--poll' || arg.startsWith('--poll=')) {
+      pollInterval = arg === '--poll' ? DEFAULT_POLL_INTERVAL : Number(arg.slice('--poll='.length))
+      if (!Number.isInteger(pollInterval) || pollInterval <= 0) throw new Error(`dev-web: invalid --poll interval "${arg}"`)
+    } else appArgs.push(arg)
+  }
+  if (!serve && appArgs.length > 0) {
+    throw new Error(`dev-web: --no-serve leaves no dsh web process for ${appArgs[0] ?? ''}`)
+  }
+  return { skipBuild, serve, pollInterval, appArgs }
+}
+
 /**
  * Discover the watch workspace by declaration: every packages/<group>/<name>
  * whose package.json carries `dsh.client` with platform "web" is a client
@@ -153,46 +209,166 @@ export async function watchClientPlugins(
   return bundles
 }
 
-/**
- * Live watcher processes to terminate when this script is interrupted. Stages
- * register themselves as they start, so the set is complete from the first
- * spawn: an interrupt during a later stage's startup still tears down the
- * earlier ones instead of orphaning them.
- */
-const stages: StageHandle[] = []
+/** One long-lived stage process as the supervisor observes it. */
+export interface StageHandle {
+  /** Command label used in diagnostics. */
+  readonly name: string
+  /** Settles with the exit code, or null when a signal ended the stage. */
+  readonly exited: Promise<number | null>
+  /**
+   * Deliver one signal; a no-op once the stage has exited.
+   * @param signal - the signal to send.
+   */
+  kill(signal: NodeJS.Signals): void
+}
+
+/** How a requested stop reaches the stages. */
+export interface StageStop {
+  /** Signal sent to every live stage first; omitted when the terminal already delivered SIGINT to them. */
+  readonly signal?: NodeJS.Signals | undefined
+  /** Milliseconds to wait for exits before escalating to SIGTERM, and again before SIGKILL. */
+  readonly graceMs: number
+}
 
 /**
- * Spawn one watcher stage, inheriting stdio, registering it for teardown, and
- * failing loud if it ever exits: a dead stage leaves the artifact chain silently
- * stale, which reads as "my edit did nothing" — the one failure this script
- * exists to prevent.
- * @param stage - command label used in the exit diagnostic.
- * @param command - executable, resolved from the workspace bin when local.
+ * Own the live stages: report a stage that exits before a stop was requested,
+ * and on a requested stop signal, wait, and escalate until every stage has exited.
+ */
+export class StageSupervisor {
+  private readonly live = new Set<StageHandle>()
+  private stopping = false
+
+  /**
+   * @param onStale - receives the stage name and exit code when a stage exits before a stop was requested.
+   */
+  constructor(private readonly onStale: (stage: string, code: number | null) => void) {}
+
+  /**
+   * Track one started stage until it exits.
+   * @param stage - the stage to supervise.
+   */
+  add(stage: StageHandle): void {
+    this.live.add(stage)
+    void stage.exited.then((code) => {
+      this.live.delete(stage)
+      if (!this.stopping) this.onStale(stage.name, code)
+    })
+  }
+
+  /**
+   * Stop every live stage and resolve once all of them have exited.
+   * @param stop - initial signal and the grace period between escalation steps.
+   */
+  async stop(stop: StageStop): Promise<void> {
+    this.stopping = true
+    const escalation: (NodeJS.Signals | undefined)[] = [stop.signal]
+    if (stop.signal !== 'SIGTERM') escalation.push('SIGTERM')
+    for (const signal of escalation) {
+      if (this.live.size === 0) return
+      if (signal !== undefined) for (const stage of this.live) stage.kill(signal)
+      await this.settled(stop.graceMs)
+    }
+    for (const stage of this.live) stage.kill('SIGKILL')
+    await Promise.all([...this.live].map(stage => stage.exited))
+  }
+
+  private async settled(graceMs: number): Promise<void> {
+    let timer: NodeJS.Timeout | undefined
+    await Promise.race([
+      Promise.all([...this.live].map(stage => stage.exited)),
+      new Promise<void>((resolve) => { timer = setTimeout(resolve, graceMs) }),
+    ])
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Grace period per escalation step. `dsh web` gives its plugin tree five seconds
+ * to dispose after the first signal; escalating earlier would turn the graceful
+ * drain into a forced exit.
+ */
+const STOP_GRACE_MS = 6_000
+
+/**
+ * Spawn one long-lived stage with inherited stdio and hand it to the supervisor.
+ * @param supervisor - owner that reports an unexpected exit and stops the stage on shutdown.
+ * @param name - command label used in diagnostics.
+ * @param command - executable, resolved from the workspace bins when `local` is set.
  * @param args - command arguments.
  * @param local - whether to resolve `command` from the workspace's installed bins.
  */
-function spawnStage(stage: string, command: string, args: readonly string[], local: boolean): void {
+function spawnStage(
+  supervisor: StageSupervisor,
+  name: string,
+  command: string,
+  args: readonly string[],
+  local: boolean,
+): void {
   const child = execa(command, [...args], {
     cwd: repoRoot,
     stdio: 'inherit',
     preferLocal: local,
     reject: false,
   })
-  stages.push({ kill: () => { child.kill() } })
-  void child.then((result) => {
-    console.error(`dev-web: ${stage} exited (code ${String(result.exitCode)}); the artifact chain is now stale`)
-    process.exit(1)
+  supervisor.add({
+    name,
+    exited: child.then(result => result.exitCode ?? null),
+    kill(signal) { child.kill(signal) },
   })
 }
 
-/** The only capability this script needs from a live watcher process. */
-interface StageHandle {
-  readonly kill: () => void
+/**
+ * Run the complete repository build with the launch environment untouched:
+ * `scripts/build.ts` samples the public client values itself.
+ * @returns the build's exit code, or null when a signal ended it.
+ */
+async function runBuild(): Promise<number | null> {
+  const invocation = pnpmInvocation(['run', 'build'])
+  const result = await execa(invocation.command, invocation.args, { cwd: repoRoot, stdio: 'inherit', reject: false })
+  return result.exitCode ?? null
 }
 
 const invokedPath = process.argv[1]
 const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
 if (isMain) {
+  let options: DevWebArguments
+  try {
+    options = parseDevWebArguments(process.argv.slice(2))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error)
+    console.error('dev-web: usage: pnpm run dev:web [--skip-build] [--no-serve] [--poll[=ms]] [dsh web arguments]')
+    process.exit(1)
+  }
+
+  // Shutdown is requested once, by a terminal signal or by a stage exiting on
+  // its own; `signal` stays unset for SIGINT because the terminal's process
+  // group already delivered it to every stage.
+  const shutdown = Promise.withResolvers<number>()
+  const requested: { code?: number; signal?: NodeJS.Signals } = {}
+  const shutdownRequested = (): boolean => requested.code !== undefined
+  const requestShutdown = (code: number, signal: NodeJS.Signals | undefined): void => {
+    if (shutdownRequested()) return
+    requested.code = code
+    if (signal !== undefined) requested.signal = signal
+    shutdown.resolve(code)
+  }
+  const supervisor = new StageSupervisor((stage, code) => {
+    console.error(`dev-web: ${stage} exited (code ${String(code)}); stopping the other stages`)
+    requestShutdown(1, 'SIGTERM')
+  })
+  // Persistent listeners, not `once`: the tsdown watchers bundle signal-exit,
+  // which re-raises a signal whenever it finds no other listener left and would
+  // terminate this process in the middle of the teardown below.
+  process.on('SIGINT', () => { requestShutdown(130, undefined) })
+  process.on('SIGTERM', () => { requestShutdown(0, 'SIGTERM') })
+
+  const buildExit = options.skipBuild ? 0 : await runBuild()
+  if (shutdownRequested()) process.exit(await shutdown.promise)
+  if (buildExit !== 0) {
+    console.error(`dev-web: pnpm run build exited (code ${String(buildExit)})`)
+    process.exit(1)
+  }
+
   const buildEnvironment = devWebBuildEnvironment(repoRoot, process.env)
   for (const name of Object.keys(process.env)) {
     if (name === CLIENT_BUILD_PROFILE_SELECTOR || name.startsWith('DSH_CLIENT_')) {
@@ -214,32 +390,14 @@ if (isMain) {
     process.exit(1)
   }
 
-  const args = process.argv.slice(2)
-  const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
-  if (args.some(a => a !== pollArg)) {
-    console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
-    process.exit(1)
-  }
-  const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
-  if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
-    console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
-    process.exit(1)
-  }
-
-  // Registered before any stage starts: `stages` is read at signal time, so an
-  // interrupt during tsdown's initial builds still kills whatever is running.
-  const stop = (): void => { for (const stage of stages) stage.kill() }
-  process.once('SIGINT', stop)
-  process.once('SIGTERM', stop)
-
   // tsc has no polling interval flag, so `--poll` selects its fixed-interval
   // watchers rather than an interval. Dropping that translation leaves tsc
   // natively watching on a network mount where inotify never fires: it stops
   // re-emitting lib/types, and the two later stages then rebuild forever from
   // stale input without printing anything.
-  spawnStage(`tsc -b ${CLIENT_TYPE_PROGRAM} --watch`, 'tsc', [
+  spawnStage(supervisor, `tsc -b ${CLIENT_TYPE_PROGRAM} --watch`, 'tsc', [
     '-b', CLIENT_TYPE_PROGRAM, '--watch', '--preserveWatchOutput',
-    ...pollInterval !== undefined
+    ...options.pollInterval !== undefined
       ? ['--watchFile', 'fixedPollingInterval', '--watchDirectory', 'fixedPollingInterval']
       : [],
   ], true)
@@ -248,19 +406,34 @@ if (isMain) {
   // first build reads current lib bundles rather than whatever the last full
   // build left. Its own watch then covers later lib rewrites — those files are
   // in its module graph.
-  await watchClientPlugins(repoRoot, [...pluginDirs, ...libraryDirs], pollInterval)
-  // Through the shell's own `watch` script rather than vite's API: vite is not a
-  // repository-root dependency, and more importantly the vite root is its
-  // working directory — `resolve.dedupe` resolves react from that root, so
-  // running vite from anywhere but apps/web silently switches which react copy
-  // the bundle gets.
-  spawnStage('vite build --watch', 'pnpm', ['--filter', SHELL_PACKAGE, 'run', 'watch'], false)
+  const bundles = await watchClientPlugins(repoRoot, [...pluginDirs, ...libraryDirs], options.pollInterval)
+  if (!shutdownRequested()) {
+    // Through the shell's own `watch` script rather than vite's API: vite is not a
+    // repository-root dependency, and more importantly the vite root is its
+    // working directory — `resolve.dedupe` resolves react from that root, so
+    // running vite from anywhere but apps/web silently switches which react copy
+    // the bundle gets.
+    spawnStage(supervisor, 'vite build --watch', 'pnpm', ['--filter', SHELL_PACKAGE, 'run', 'watch'], false)
+    // The same launch vector as the root `dsh` script, so the served Host runs
+    // from source exactly as `pnpm dsh web` would.
+    if (options.serve) {
+      spawnStage(supervisor, 'dsh web', process.execPath, [
+        '--import', 'tsx/esm', 'apps/cli/src/bin.ts', 'web', ...options.appArgs,
+      ], false)
+    }
+    console.log(
+      `dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
+      + ` and ${String(libraryDirs.length)} statically linked library packages`
+      + (options.pollInterval !== undefined ? ` (polling ${String(options.pollInterval)}ms)` : '')
+      + `, plus tsc -b ${CLIENT_TYPE_PROGRAM} and the ${SHELL_PACKAGE} dist build`
+      + (options.serve ? ', serving through dsh web' : '')
+      + ':\n  '
+      + [...pluginDirs, ...libraryDirs].join('\n  '),
+    )
+  }
 
-  console.log(
-    `dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
-    + ` and ${String(libraryDirs.length)} statically linked library packages`
-    + (pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : '')
-    + `, plus tsc -b ${CLIENT_TYPE_PROGRAM} and the ${SHELL_PACKAGE} dist build:\n  `
-    + [...pluginDirs, ...libraryDirs].join('\n  '),
-  )
+  const exitCode = await shutdown.promise
+  await supervisor.stop({ signal: requested.signal, graceMs: STOP_GRACE_MS })
+  for (const bundle of bundles) await bundle[Symbol.asyncDispose]()
+  process.exit(exitCode)
 }
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index c3a8c6a239..b0d76c28ee 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -119,6 +119,7 @@ export const SERVICE_PAGE: Record<string, string> = {
   subprocess: 'subprocess.md',
   systemPrompt: 'system-prompt.md',
   jobs: 'jobs.md',
+  jobController: 'jobs.md',
   sessionTelemetry: 'session-telemetry.md',
   agentTeams: 'agent-team.md',
   tokenMeter: 'token-meter.md',
@@ -157,6 +158,7 @@ export const SERVICE_PAGE: Record<string, string> = {
  * to a model as `cordis_runtime_inspect what:"client"`).
  */
 export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
+  invocation: 'not a service: per-call accessor (RemoteInvocation | undefined) the Gateway derives for each Remote call — packages/api/gateway/README.md owns the contract',
   webTerminals: 'client-side terminal view models — packages/api/terminal-controller/README.md owns the API',
   appReady: 'not a service: launcher-provided successful-startup signal — packages/boot/cmdline/README.md owns the launcher contract',
   appExit: 'not a service: launcher-provided bounded process-exit callback — packages/boot/cmdline/README.md owns the launcher contract',
@@ -379,6 +381,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ModelCatalog: 'session.md',
   SessionOpenWorkspacePathRequest: 'session.md',
   SessionOpenWorkspacePathValue: 'session.md',
+  SessionWorkspacePathApplication: 'session.md',
   SessionModels: 'session.md',
   SessionModelsRequest: 'session.md',
   SessionPage: 'session.md',
@@ -582,12 +585,28 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   PromptSectionOrderName: 'system-prompt.md',
   SystemPrompt: 'system-prompt.md',
   ToolProviderResult: 'system-prompt.md',
-  JobDoneListener: 'jobs.md',
   JobId: 'jobs.md',
+  JobFollowFrame: 'jobs.md',
+  JobFollowRequest: 'jobs.md',
+  JobListFrame: 'jobs.md',
+  JobListRequest: 'jobs.md',
   JobRead: 'jobs.md',
-  JobSnapshot: 'jobs.md',
-  JobStart: 'jobs.md',
-  JobsChangedListener: 'jobs.md',
+  JobView: 'jobs.md',
+  JobChunk: 'jobs.md',
+  JobSpec: 'jobs.md',
+  JobHandle: 'jobs.md',
+  JobHooks: 'jobs.md',
+  JobOutcome: 'jobs.md',
+  JobOutputSource: 'jobs.md',
+  JobSourceRead: 'jobs.md',
+  JobOutputRead: 'jobs.md',
+  JobAppendOptions: 'jobs.md',
+  JobChannel: 'jobs.md',
+  JobEvent: 'jobs.md',
+  JobEventFilter: 'jobs.md',
+  JobEventListener: 'jobs.md',
+  JobEvents: 'jobs.md',
+  JobSettleCause: 'jobs.md',
   CreateTeamTaskRequest: 'agent-team.md',
   SendTeamMessageRequest: 'agent-team.md',
   SendTeamMessageResult: 'agent-team.md',
@@ -681,6 +700,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   WorkspaceArchiveSessionRequest: 'workspace.md',
   WorkspaceArchiveValue: 'workspace.md',
   WorkspaceCreateRequest: 'workspace.md',
+  WorkspaceInitializeDefaultRequest: 'workspace.md',
   WorkspaceCreateValue: 'workspace.md',
   WorkspaceDeleteRequest: 'workspace.md',
   WorkspaceDeleteValue: 'workspace.md',
@@ -751,6 +771,8 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   ConnectionFetchHandler: 'shared Fetch dispatch is owned by packages/client/connection/src/rpc.ts',
   ConnectionRequestRejection: 'transport rejection status is owned by packages/client/connection/src/rpc.ts',
   ConnectionTrustRequest: 'transport authentication input is owned by packages/client/connection/src/rpc.ts',
+  PeerAdmission: 'Peer admission outcome is owned by packages/client/connection/src/rpc.ts',
+  PeerScope: 'Peer scope contract is owned by packages/typert/protocol/src/types.ts',
   ConnectionIndexRequest: 'frontend authentication request is owned by packages/client/connection/src/rpc.ts',
   ConnectionIndexResponse: 'frontend authentication response is owned by packages/client/connection/src/rpc.ts',
   Profile: 'resolved profile layers are owned by packages/boot/app-boot/README.md',
@@ -833,6 +855,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
   WorkspaceFileScope: 'Host workspace file lookup contract is owned by packages/api/workspace-files/README.md',
+  WorkspaceByteReadOptions: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
   WorkspaceByteRange: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
   WorkspaceDirectoryListing: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
   WorkspaceFileBytes: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md',
@@ -891,19 +914,21 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
     ],
   }],
   inheritedEvents: [
-    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
-    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
-    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
-    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
-    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
-    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
-    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
-    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
-    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
-    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
-    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
-    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
-    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:331' },
+    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:333' },
+    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:341' },
+    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:343' },
+    { name: 'internal/config', summary: 'Waterfall: a fiber config is being resolved before validation.', source: 'vendor/cordis/src/events.ts:339' },
+    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:345' },
+    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:347' },
+    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:349' },
+    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:351' },
+    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:25' },
+    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:26' },
+    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:27' },
+    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:28' },
+    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:41' },
+    { name: 'loader/volatile-update', summary: 'Volatile config values committed into the running fiber without a remount; dispatched to the owning fiber only.', source: 'vendor/loader/src/index.ts:34' },
   ],
   inheritedServices: [
     { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 5b32da720a..6bc2e62bb2 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -243,6 +243,13 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'core',
     note: 'Lists the Session composition\'s user-invocable skills without activating a cold Agent.',
   },
+  {
+    key: 'jobController',
+    pkg: 'api-job-controller',
+    title: 'Host job Remote controller',
+    mode: 'core',
+    note: 'Streams one background job\'s observation record over the generated Remote namespace; the roster stays on the session control stream.',
+  },
   {
     key: 'credentialsController',
     pkg: 'api-settings-controller',
@@ -677,8 +684,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Background job registry',
     mode: 'seam',
     implementations: ['jobs-local'],
-    consumers: ['tool-bash', 'tool-terminal', 'tool-subagent', 'tool-jobs'],
-    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.',
+    consumers: ['tool-bash', 'tool-pwsh', 'tool-terminal', 'tool-subagent', 'tool-jobs', 'api-job-controller'],
+    note: 'Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.',
   },
   {
     key: 'web',
diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts
index 3ab18f9291..8527a0d588 100644
--- a/scripts/gen-third-party-notices.spec.ts
+++ b/scripts/gen-third-party-notices.spec.ts
@@ -2,13 +2,13 @@ import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSyn
 import { join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { describe, expect, it } from 'vitest'
-import desktopRuntimeLock from '../apps/desktop/scripts/primary-runtime-lock.json' with { type: 'json' }
+import primaryRuntimeLock from './primary-runtime/lock.json' with { type: 'json' }
 import {
   CLAUDE_AGENT_SDK_PACKAGE,
   assertRuntimeLicenses,
   claudeDistributionFromManifest,
   collectPythonDependencies,
-  collectDesktopPythonDependencies,
+  collectBundledPythonDependencies,
   isOwnerAuthorizedRuntime,
   isPermissive,
   type Manifest,
@@ -33,7 +33,7 @@ describe('THIRD_PARTY_NOTICES.md', () => {
   }, async () => {
     const generated = await render()
     expect(generated).toContain('It depends on the third-party software listed below.')
-    expect(generated).toContain(`| [\`numpy\`](https://github.com/numpy/numpy) | ${desktopRuntimeLock.pythonPackages.numpy} | BSD-3-Clause |`)
+    expect(generated).toContain(`| [\`numpy\`](https://github.com/numpy/numpy) | ${primaryRuntimeLock.pythonPackages.numpy} | BSD-3-Clause |`)
     expect(generated).toContain('## LibreOffice conversion kit')
     expect(generated).toContain('Recipients must have access to those corresponding sources and notices.')
     expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(generated)
@@ -323,22 +323,22 @@ describe('collectPythonDependencies', () => {
   })
 })
 
-describe('collectDesktopPythonDependencies', () => {
-  it('discloses the committed Desktop closure with its exact locked versions', () => {
-    const dependencies = collectDesktopPythonDependencies(desktopRuntimeLock.pythonPackages)
-    expect(dependencies).toHaveLength(Object.keys(desktopRuntimeLock.pythonPackages).length)
+describe('collectBundledPythonDependencies', () => {
+  it('discloses the committed bundled Python closure with its exact locked versions', () => {
+    const dependencies = collectBundledPythonDependencies(primaryRuntimeLock.pythonPackages)
+    expect(dependencies).toHaveLength(Object.keys(primaryRuntimeLock.pythonPackages).length)
     expect(dependencies).toContainEqual({
-      name: 'pillow', version: desktopRuntimeLock.pythonPackages.Pillow,
+      name: 'pillow', version: primaryRuntimeLock.pythonPackages.Pillow,
       license: 'MIT-CMU', repo: 'https://github.com/python-pillow/Pillow',
     })
     expect(dependencies).toContainEqual({
-      name: 'typing-extensions', version: desktopRuntimeLock.pythonPackages.typing_extensions,
+      name: 'typing-extensions', version: primaryRuntimeLock.pythonPackages.typing_extensions,
       license: 'PSF-2.0', repo: 'https://github.com/python/typing_extensions',
     })
   })
 
   it('normalizes names while preserving pinned version strings', () => {
-    expect(collectDesktopPythonDependencies({ 'typing_extensions': '4.16.0', 'Pillow': '12.3.0' }))
+    expect(collectBundledPythonDependencies({ 'typing_extensions': '4.16.0', 'Pillow': '12.3.0' }))
       .toEqual([
         { name: 'pillow', version: '12.3.0', license: 'MIT-CMU', repo: 'https://github.com/python-pillow/Pillow' },
         { name: 'typing-extensions', version: '4.16.0', license: 'PSF-2.0', repo: 'https://github.com/python/typing_extensions' },
@@ -346,18 +346,18 @@ describe('collectDesktopPythonDependencies', () => {
   })
 
   it('rejects duplicate normalized distribution names with the same locked version', () => {
-    expect(() => collectDesktopPythonDependencies({ typing_extensions: '4.16.0', 'typing.extensions': '4.16.0' }))
+    expect(() => collectBundledPythonDependencies({ typing_extensions: '4.16.0', 'typing.extensions': '4.16.0' }))
       .toThrow('duplicate normalized names')
   })
 
   it('rejects missing distribution metadata and conflicting normalized versions', () => {
-    expect(() => collectDesktopPythonDependencies({ missing: '1.0' })).toThrow('missing from PYTHON_METADATA')
-    expect(() => collectDesktopPythonDependencies({ Pillow: '12.3.0', pillow: '12.4.0' })).toThrow('conflicting locked versions')
+    expect(() => collectBundledPythonDependencies({ missing: '1.0' })).toThrow('missing from PYTHON_METADATA')
+    expect(() => collectBundledPythonDependencies({ Pillow: '12.3.0', pillow: '12.4.0' })).toThrow('conflicting locked versions')
   })
 
   it('applies the runtime license check to bundled Python distributions', () => {
-    expect(() => { assertRuntimeLicenses(collectDesktopPythonDependencies(desktopRuntimeLock.pythonPackages)) }).not.toThrow()
-    const dependencies = collectDesktopPythonDependencies({ 'copyleft-wheel': '1.0' }, {
+    expect(() => { assertRuntimeLicenses(collectBundledPythonDependencies(primaryRuntimeLock.pythonPackages)) }).not.toThrow()
+    const dependencies = collectBundledPythonDependencies({ 'copyleft-wheel': '1.0' }, {
       'copyleft-wheel': { license: 'GPL-3.0-only', repo: 'https://example.com/project' },
     })
     expect(() => { assertRuntimeLicenses(dependencies) }).toThrow('copyleft-wheel (GPL-3.0-only)')
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index c77fbd6b38..6167190367 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -1,7 +1,7 @@
 /**
  * Generate `THIRD_PARTY_NOTICES.md` from the workspace manifests: every
  * external dependency named by a workspace `package.json`, the vendored-package
- * manifest in `vendor/README.md`, the Python `pyproject.toml` files, the Desktop
+ * manifest in `vendor/README.md`, the Python `pyproject.toml` files, the shared
  * Python distribution lock, and the pnpm patch list. npm metadata comes from the installed
  * store, so the tree must be installed. `--check` verifies the committed
  * artifact. Tier policy and ownership live in
@@ -13,7 +13,7 @@ import { dirname, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { parse as parseToml, type TomlTableWithoutBigInt, type TomlValueWithoutBigInt } from 'smol-toml'
 import parseSpdx from 'spdx-expression-parse'
-import desktopRuntimeLock from '../apps/desktop/scripts/primary-runtime-lock.json' with { type: 'json' }
+import primaryRuntimeLock from './primary-runtime/lock.json' with { type: 'json' }
 import { browserBundledExternals } from './browser-bundled-externals.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -93,7 +93,7 @@ const OVERRIDES: Record<string, { license?: string; repo?: string }> = {
 /**
  * Python metadata is recorded from the distributions' license and project
  * fields; generation does not require installing their wheels. Both Python
- * manifests and the Desktop lock reject names absent from this map.
+ * manifests and the shared runtime lock reject names absent from this map.
  */
 const PYTHON_METADATA: Record<string, { license: string; repo: string; role?: string }> = {
   pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness-sdk`' },
@@ -616,12 +616,12 @@ function collectPython(): { name: string; license: string; repo: string; role: s
 }
 
 /**
- * Disclose every Desktop wheel distribution using its locked version, rejecting duplicate normalized names.
- * @param packages - Distribution names and exact versions from the Desktop runtime lock.
+ * Disclose every bundled wheel distribution using its locked version, rejecting duplicate normalized names.
+ * @param packages - Distribution names and exact versions from the shared runtime lock.
  * @param metadata - License and source metadata for every locked distribution.
  * @returns Normalized, sorted distribution identities with versions and licenses.
  */
-export function collectDesktopPythonDependencies(
+export function collectBundledPythonDependencies(
   packages: Readonly<Record<string, string>>,
   metadata: PythonMetadata = PYTHON_METADATA,
 ): { name: string; version: string; license: string; repo: string }[] {
@@ -630,14 +630,14 @@ export function collectDesktopPythonDependencies(
     const name = normalizePythonDistributionName(distribution)
     const previous = normalized.get(name)
     if (previous !== undefined && previous !== version) {
-      throw new Error(`gen-third-party-notices: Desktop python distribution ${name} has conflicting locked versions.`)
+      throw new Error(`gen-third-party-notices: bundled Python distribution ${name} has conflicting locked versions.`)
     }
-    if (previous !== undefined) throw new Error(`gen-third-party-notices: Desktop python distribution ${name} has duplicate normalized names.`)
+    if (previous !== undefined) throw new Error(`gen-third-party-notices: bundled Python distribution ${name} has duplicate normalized names.`)
     normalized.set(name, version)
   }
   return [...normalized].sort(([a], [b]) => a.localeCompare(b)).map(([name, version]) => {
     const entry = metadata[name]
-    if (entry === undefined) throw new Error(`gen-third-party-notices: Desktop python distribution ${name} is missing from PYTHON_METADATA.`)
+    if (entry === undefined) throw new Error(`gen-third-party-notices: bundled Python distribution ${name} is missing from PYTHON_METADATA.`)
     return { name, version, license: entry.license, repo: entry.repo }
   })
 }
@@ -753,7 +753,7 @@ export async function render(): Promise<string> {
   const kitRuntime = runtimeDeps.some(dep => dep.name === LIBREOFFICE_KIT_PACKAGE)
   const vendored = collectVendored()
   const python = collectPython()
-  const desktopPython = collectDesktopPythonDependencies(desktopRuntimeLock.pythonPackages)
+  const bundledPython = collectBundledPythonDependencies(primaryRuntimeLock.pythonPackages)
   const patched = collectPatched()
   const claudeDistribution = runtimeDeps.some(
     dep => dep.name === CLAUDE_AGENT_SDK_PACKAGE,
@@ -762,7 +762,7 @@ export async function render(): Promise<string> {
     : undefined
   const nonPermissiveDev = devDeps.filter(dep => !isPermissive(dep.license))
   assertRuntimeLicenses(runtimeDeps)
-  assertRuntimeLicenses(desktopPython)
+  assertRuntimeLicenses(bundledPython)
   const patchedLines = patched.map(({ spec, patch }) => `- \`${spec}\` — [\`${patch}\`](${patch})`)
 
   return `<!-- Generated by scripts/gen-third-party-notices.ts — do not edit by hand.
@@ -772,7 +772,7 @@ export async function render(): Promise<string> {
 
 DeepSeek Harness is licensed under [MIT](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
 
-This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Desktop bundled Python distributions. It is generated by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
+This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Bundled Python distributions. It is generated by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
 
 The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python SDK closure is recorded separately in [\`python/sdk/uv.lock\`](python/sdk/uv.lock).
 
@@ -817,13 +817,13 @@ Direct dependencies of the \`pyproject.toml\` manifests, plus \`uv\` as the deve
 ${python.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.license} | ${dep.role} |`).join('\n')}
 | [\`uv\`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |
 
-## Desktop bundled Python distributions
+## Bundled Python distributions
 
-The [Desktop runtime lock](apps/desktop/scripts/primary-runtime-lock.json) records each distribution version and the wheel download hashes. The table includes every entry in \`pythonPackages\`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
+The [shared runtime lock](scripts/primary-runtime/lock.json) records each distribution version and the wheel download hashes. The table includes every entry in \`pythonPackages\`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
 
 | Distribution | Locked version | Project license |
 | --- | --- | --- |
-${desktopPython.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.version} | ${dep.license} |`).join('\n')}
+${bundledPython.map(dep => `| [\`${dep.name}\`](${dep.repo}) | ${dep.version} | ${dep.license} |`).join('\n')}
 
 ## First-party native packages
 
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index d2c49aafc3..a301c69a22 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -75,6 +75,7 @@ import WorkflowEngine from '@deepseek-ai/dsh-workflow'
 import type { WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow'
 import * as ToolRalph from '@deepseek-ai/dsh-tool-ralph'
 import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
+import * as ToolWorkspaceDependencies from '@deepseek-ai/dsh-tool-workspace-dependencies'
 import { githubSlug } from './verify-md-links.ts'
 
 /** Attachment seam marker that makes the attachments-conditional `read_image` schema harvestable. */
@@ -637,6 +638,17 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolWorkflow)
     },
   },
+  {
+    pkg: '@deepseek-ai/dsh-tool-workspace-dependencies',
+    dir: 'tool-workspace-dependencies',
+    source: 'packages/skill/tool-workspace-dependencies/src/index.ts',
+    requires: ['ctx.tools'],
+    writes: ['tool/call', 'tool/result'],
+    async mount(ctx) {
+      // Schema harvest never prepares a payload; the directory need not exist.
+      await ctx.plugin(ToolWorkspaceDependencies, { source: resolve(root, '.tmp/tool-catalog/primary-runtime') })
+    },
+  },
   {
     pkg: '@deepseek-ai/dsh-tool-web',
     dir: 'tool-web',
diff --git a/scripts/loader-config-diff.spec.ts b/scripts/loader-config-diff.spec.ts
new file mode 100644
index 0000000000..0cd0a3eb50
--- /dev/null
+++ b/scripts/loader-config-diff.spec.ts
@@ -0,0 +1,109 @@
+/** Raw config comparison reads schema metadata without resolving config or committing references. */
+import { expect, it, vi } from 'vitest'
+import z from '@deepseek-ai/schemastery'
+import { equalExceptVolatile as equal } from '../vendor/loader/src/config/diff.ts'
+
+it('ignores volatile fields in frozen raw inputs without running schema callbacks', () => {
+  const validate = vi.fn((value: string) => value.trim())
+  const schema = z.object({ title: z.transform(z.string(), validate).volatile(), fixed: z.string() })
+  Object.freeze(schema.meta)
+  Object.freeze(schema.dict)
+  const previous = Object.freeze({ title: 'old', fixed: 'same' })
+  const next = Object.freeze({ title: { __jsExpr: 'throw new Error("must not run")' }, fixed: 'same' })
+  expect(equal(previous, next, schema)).toBe(true)
+  expect(equal(previous, next, schema)).toBe(true)
+  expect(validate).not.toHaveBeenCalled()
+  expect(previous.title).toBe('old')
+  expect(next.title).toEqual({ __jsExpr: 'throw new Error("must not run")' })
+})
+
+it('ignores absent, nested and whole-object/array/union volatile fields', () => {
+  const schema = z.object({
+    nested: z.object({ value: z.string().volatile() }),
+    block: z.object({ title: z.string() }).volatile(),
+    list: z.array(z.string()).volatile(),
+    choice: z.union([z.string(), z.number()]).volatile(),
+  })
+  const next = { nested: { value: 'new' }, block: { title: 'new' }, list: ['new'], choice: 1 }
+  expect(equal({}, next, schema)).toBe(true)
+  expect(equal(next, {}, schema)).toBe(true)
+  expect(equal('old', 'new', z.string().volatile())).toBe(true)
+  const restored = new z<unknown>(JSON.parse(JSON.stringify(schema)) as z<unknown>)
+  expect(equal({}, next, restored)).toBe(true)
+})
+
+it('preserves ordinary and unknown fields, object defaults and parent expressions', () => {
+  const schema = z.object({ nested: z.object({ live: z.string().volatile(), fixed: z.string() }).default({ fixed: 'default' }) })
+  expect(equal({}, { nested: { live: 'new', fixed: 'default' } }, schema)).toBe(true)
+  expect(equal({}, { nested: { live: 'new' } }, schema)).toBe(false)
+  expect(equal({}, { unknown: 'new' }, schema)).toBe(false)
+  expect(equal({ nested: { __jsExpr: 'source.a' } }, { nested: { __jsExpr: 'source.b' } }, schema)).toBe(false)
+  expect(equal({ nested: 'invalid' }, { nested: { live: 'new' } }, schema)).toBe(false)
+  expect(equal({ nested: new Date(0) }, { nested: new Date(1) }, schema)).toBe(false)
+  expect(equal({ nested: [] }, { nested: ['new'] }, schema)).toBe(false)
+})
+
+it('keeps ordinary raw changes even if schema validation would normalize them to equal values', () => {
+  const normalize = vi.fn(() => 'same')
+  const schema = z.object({ fixed: z.transform(z.string(), normalize), live: z.string().volatile() })
+  expect(equal({ fixed: 'first' }, { fixed: 'second' }, schema)).toBe(false)
+  expect(normalize).not.toHaveBeenCalled()
+  const other = { '~standard': { version: 1 as const, vendor: 'other', validate: vi.fn() } }
+  expect(equal('first', 'second', other)).toBe(false)
+  expect(other['~standard'].validate).not.toHaveBeenCalled()
+  expect(equal('first', 'second', undefined)).toBe(false)
+})
+
+it('compares raw values strictly without a schema', () => {
+  expect(equal([undefined], [null], undefined)).toBe(false)
+  expect(equal(undefined, null, undefined)).toBe(false)
+  expect(equal({ fixed: 'same' }, { fixed: 'same' }, undefined)).toBe(true)
+  expect(equal({ list: Array(1) }, { list: ['new'] }, undefined)).toBe(false)
+})
+
+it('compares recursive schemas conservatively and visits shared schema nodes at each path', () => {
+  const recursive = z.object({ value: z.string() }).extra('default', undefined)
+  recursive.set('child', recursive)
+  expect(equal({ value: 'old' }, { value: 'new' }, recursive)).toBe(false)
+  const shared = z.object({ value: z.string().volatile() })
+  const schema = z.object({ first: shared, second: shared })
+  expect(equal({}, { first: { value: 'one' }, second: { value: 'two' } }, schema)).toBe(true)
+})
+
+it('equates absent objects with defaults while preserving ordinary field differences', () => {
+  const schema = z.object({ nested: z.object({ fixed: z.string() }).default({ fixed: 'default' }) })
+  for (const absent of [undefined, null]) {
+    expect(equal(absent, {}, schema)).toBe(true)
+    expect(equal({}, absent, schema)).toBe(true)
+    expect(equal({ nested: absent }, { nested: { fixed: 'default' } }, schema)).toBe(true)
+  }
+  expect(equal({}, { nested: { fixed: 'changed' } }, schema)).toBe(false)
+  expect(equal({}, { nested: {} }, schema)).toBe(false)
+})
+
+it('preserves parent expression edits even when their marker matches a volatile field', () => {
+  const schema = z.object({ __jsExpr: z.string().volatile() })
+  expect(equal({ __jsExpr: 'first' }, { __jsExpr: 'second' }, schema)).toBe(false)
+})
+
+it('detects ordinary sparse array edits in both directions', () => {
+  const schema = z.object({ list: z.array(z.string()), live: z.string().volatile() })
+  const before = { list: Array(1), live: 'before' }
+  const after = { list: ['new'], live: 'after' }
+  expect(equal(before, after, schema)).toBe(false)
+  expect(equal(after, before, schema)).toBe(false)
+})
+
+it('compares unknown fields whose names match Object prototype properties', () => {
+  const schema = z.object({ live: z.string().volatile() })
+  for (const key of ['constructor', 'toString', '__proto__']) {
+    const previous = { [key]: 'first', live: 'old' }
+    expect(equal(previous, { [key]: 'second', live: 'new' }, schema)).toBe(false)
+    expect(equal(previous, { [key]: 'first', live: 'new' }, schema)).toBe(true)
+  }
+})
+
+it('compares metadata-free serialized schema nodes', () => {
+  const schema = new z<unknown>(JSON.parse('{"type":"object","dict":{"nested":{"type":"object","dict":{"enabled":{"type":"boolean"}}}}}') as z<unknown>)
+  expect(equal({ nested: { enabled: true } }, { nested: { enabled: false } }, schema)).toBe(false)
+})
diff --git a/scripts/loader-volatile-update.spec.ts b/scripts/loader-volatile-update.spec.ts
new file mode 100644
index 0000000000..16d8f3b0a8
--- /dev/null
+++ b/scripts/loader-volatile-update.spec.ts
@@ -0,0 +1,634 @@
+/** Loader commits volatile config values into running fibers without remounting; ordinary changes keep the update lifecycle. */
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it, onTestFinished, vi } from 'vitest'
+import { Context, type Fiber, type Plugin } from '@deepseek-ai/cordis'
+import Loader, { Group } from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import Timer from '@deepseek-ai/cordis-plugin-timer'
+import z from '@deepseek-ai/schemastery'
+import { Config } from './volatile-config.fixture.ts'
+import Hmr from '@deepseek-ai/dsh-hmr'
+import { boot, reconcileProfilePatches } from '@deepseek-ai/dsh-app-boot'
+
+function context() {
+  const ctx = new Context()
+  onTestFinished(() => ctx.fiber.dispose())
+  return ctx
+}
+
+async function runtimeContext() {
+  const ctx = context()
+  await ctx.plugin(Loader)
+  return ctx
+}
+
+async function mountEntry(ctx: Context, plugin: Plugin, config: unknown = {}): Promise<Fiber> {
+  const name = `consumer-${Object.keys(ctx.loader.builtins).length}`
+  ctx.loader.builtins[name] = plugin
+  const id = await ctx.loader.create({ name: `cordis:${name}`, config })
+  const fiber = ctx.loader.resolve(id).fiber!
+  await fiber.await()
+  return fiber
+}
+
+async function update(fiber: Fiber, config: unknown): Promise<void> {
+  await fiber.entry!.update({ config })
+  await fiber.await()
+}
+
+describe('volatile Loader updates', () => {
+  it('updates a whole-config reference and reports the root path', async () => {
+    const ctx = await runtimeContext()
+    const Config = z.object({ title: z.string() }).volatile()
+    const events = vi.fn()
+    const fiber = await mountEntry(ctx, { Config, apply(owner: Context) {
+      owner.on('loader/volatile-update', events)
+    } }, { title: 'first' })
+    const reference = fiber.config as ReturnType<typeof Config>
+    await update(fiber, { title: 'second' })
+    expect(fiber.config).toBe(reference)
+    expect(reference.get()).toEqual({ title: 'second' })
+    expect(events).toHaveBeenCalledExactlyOnceWith([[]])
+  })
+  it('commits all references before one local event without remounting', async () => {
+    const ctx = await runtimeContext()
+    const configs: ReturnType<typeof Config>[] = []
+    const observed: unknown[] = []
+    const mount = vi.fn(function (owner: Context, config: ReturnType<typeof Config>) {
+      configs.push(config)
+      owner.on('loader/volatile-update', paths => observed.push({ paths, title: config.title.get(), count: config.nested.count.get() }))
+    })
+    const first = await mountEntry(ctx, { Config, apply: mount }, {})
+    await mountEntry(ctx, { Config, apply: mount }, {})
+    const initial = configs[0]!
+    const title = initial.title
+    await update(first, { title: 'hello' })
+    expect(observed).toEqual([])
+    await update(first, { title: 'next', nested: { count: 2 } })
+    await first.await()
+    expect(mount).toHaveBeenCalledTimes(2)
+    expect(first.config).toBe(initial)
+    expect(initial.title).toBe(title)
+    expect(configs[1]!.title.get()).toBe('hello')
+    expect(observed).toEqual([{ paths: [['title'], ['nested', 'count']], title: 'next', count: 2 }])
+    await update(first, { title: 'next', nested: { count: 2 } })
+    expect(observed).toHaveLength(1)
+    await update(first, { optional: 'added' })
+    expect(initial.optional.get()).toBe('added')
+    await update(first, {})
+    expect(initial.optional.get()).toBeUndefined()
+  })
+
+  it('keeps references on invalid updates and replaces them on mixed updates', async () => {
+    const ctx = await runtimeContext()
+    const notifications = vi.fn()
+    const disposed = vi.fn()
+    const configs: ReturnType<typeof Config>[] = []
+    const plugin = { Config, apply(owner: Context, config: ReturnType<typeof Config>) {
+      configs.push(config)
+      owner.on('loader/volatile-update', notifications)
+      owner.effect(() => disposed)
+    } }
+    const fiber = await mountEntry(ctx, plugin, {})
+    const before = configs[0]!
+    await update(fiber, { title: 'invalid candidate', nested: { count: -1 } })
+    expect(before.title.get()).toBe('hello')
+    expect(notifications).not.toHaveBeenCalled()
+    await update(fiber, { title: 'new', fixed: 'restart' })
+    await fiber.await()
+    expect(configs).toHaveLength(2)
+    expect(disposed).toHaveBeenCalledOnce()
+    expect(notifications).not.toHaveBeenCalled()
+    expect(before.title.get()).toBe('hello')
+    expect(configs[1]!.title.get()).toBe('new')
+    expect(configs[1]!.title).not.toBe(before.title)
+  })
+
+  it('bypasses custom update hooks for volatile changes and retains them for mixed changes', async () => {
+    const ctx = await runtimeContext()
+    const hooks: string[] = []
+    const globalHook = vi.fn((_config: unknown, _noSave: boolean, next: () => void) => { next() })
+    ctx.on('internal/update', globalHook, { global: true })
+    const fiber = await mountEntry(ctx, { Config, apply(owner: Context) {
+      owner.on('internal/update', (config: ReturnType<typeof Config>) => {
+        hooks.push(config.title.get())
+      })
+    } }, {})
+    const initial = fiber.config as ReturnType<typeof Config>
+    await update(fiber, { title: 'accepted' })
+    expect(fiber.config).toBe(initial)
+    expect(initial.title.get()).toBe('accepted')
+    await update(fiber, { title: 'accepted' })
+    expect(hooks).toEqual([])
+    expect(globalHook).not.toHaveBeenCalled()
+    await update(fiber, { title: 'custom', fixed: 'changed' })
+    expect(hooks).toEqual(['custom'])
+    expect(initial.title.get()).toBe('accepted')
+  })
+
+  it('compares ordinary dates and arrays and retains the existing nonvolatile restart behavior', async () => {
+    const ctx = await runtimeContext()
+    const schema = z.object({ live: z.string().volatile(), date: z.date(), list: z.array(z.string()) })
+    const apply = vi.fn(function () {})
+    const fiber = await mountEntry(ctx, { Config: schema, apply }, { live: 'a', date: '2026-01-01', list: ['a'] })
+    await update(fiber, { live: 'b', date: '2026-01-01', list: ['a'] })
+    await fiber.await()
+    expect(apply).toHaveBeenCalledOnce()
+    await update(fiber, { live: 'c', date: '2026-01-02', list: ['a'] })
+    await fiber.await()
+    expect(apply).toHaveBeenCalledTimes(2)
+    await update(fiber, { live: 'd', date: '2026-01-02', list: ['b'] })
+    await fiber.await()
+    expect(apply).toHaveBeenCalledTimes(3)
+    const ordinary = await mountEntry(ctx, { Config: z.object({ value: z.string() }), apply() { apply() } }, { value: 'same' })
+    ordinary.update({ value: 'same' })
+    await ordinary.await()
+    expect(apply).toHaveBeenCalledTimes(5)
+  })
+
+  it('resolves pending updates and creates fresh references after dependency replacement', async () => {
+    const ctx = await runtimeContext()
+    const configs: ReturnType<typeof Config>[] = []
+    const consumer = await mountEntry(ctx, { Config, inject: ['volatile-test-provider'], apply(_ctx: Context, config: ReturnType<typeof Config>) {
+      configs.push(config)
+    } }, {})
+    await update(consumer, { title: 'pending' })
+    const provider = await ctx.plugin({ apply(owner: Context) { owner.provide('volatile-test-provider', {}) } })
+    await consumer.await()
+    expect(configs[0]!.title.get()).toBe('pending')
+    await update(consumer, { title: 'live' })
+    await provider.dispose()
+    const before = configs[0]!.title
+    await ctx.plugin({ apply(owner: Context) { owner.provide('volatile-test-provider', {}) } })
+    await consumer.await()
+    expect(configs).toHaveLength(2)
+    expect(configs[1]!.title.get()).toBe('live')
+    expect(configs[1]!.title).not.toBe(before)
+  })
+
+  it('remounts for changed class instances and cyclic ordinary config', async () => {
+    const ctx = await runtimeContext()
+    const schema = z.object({
+      live: z.string().volatile(),
+      url: z.transform(z.string(), value => new URL(value)),
+      data: z.transform(z.string(), () => { const data: Record<string, unknown> = {}; data.self = data; return data }),
+    })
+    const apply = vi.fn(function () {})
+    const oldUrl = 'https://a.example/'
+    const newUrl = 'https://b.example/'
+    const fiber = await mountEntry(ctx, { Config: schema, apply }, { live: 'a', url: oldUrl })
+    const before = fiber.config as ReturnType<typeof schema>
+    await update(fiber, { live: 'b', url: newUrl })
+    await fiber.await()
+    expect(apply).toHaveBeenCalledTimes(2)
+    expect((fiber.config as ReturnType<typeof schema>).url.href).toBe(newUrl)
+    expect(before.live.get()).toBe('a')
+    await update(fiber, { live: 'c', url: newUrl, data: 'first' })
+    await update(fiber, { live: 'd', url: newUrl, data: 'second' })
+    expect(apply).toHaveBeenCalledTimes(4)
+  })
+
+  it('distinguishes undefined from null inside volatile arrays', async () => {
+    const ctx = await runtimeContext()
+    const schema = z.object({ values: z.array(z.any()).volatile() })
+    const events = vi.fn()
+    const fiber = await mountEntry(ctx, { Config: schema, apply(owner: Context) {
+      owner.on('loader/volatile-update', events)
+    } }, { values: [undefined] })
+    await update(fiber, { values: [null] })
+    expect((fiber.config as ReturnType<typeof schema>).values.get()).toEqual([null])
+    expect(events).toHaveBeenCalledExactlyOnceWith([['values']])
+  })
+})
+
+it('reloads real YAML and persists plain values independently of custom update hooks', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-volatile-'))
+  const ctx = new Context()
+  onTestFinished(async () => { await ctx.fiber.dispose(); await rm(root, { recursive: true, force: true }) })
+  ctx.baseUrl = pathToFileURL(root).href + '/'
+  await ctx.plugin(Loader)
+  const configs: ReturnType<typeof Config>[] = []
+  ctx.loader.builtins.include = Include
+  ctx.loader.builtins.group = Group
+  const updates = vi.fn()
+  const consumer = { Config, apply(owner: Context, config: ReturnType<typeof Config>) {
+    configs.push(config)
+    owner.on('internal/update', updates)
+  } }
+  ctx.loader.builtins['volatile-test'] = consumer
+  const filename = join(root, 'cordis.yml')
+  await writeFile(filename, '- id: group\n  name: cordis:group\n  group: true\n  config:\n    - id: consumer\n      name: cordis:volatile-test\n      config:\n        title: initial\n')
+  const rootId = await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(filename).href } })
+  await ctx.loader.await()
+  const include = ctx.loader.resolve(rootId).subtree as Include
+  const group = include.store.group!.fiber!
+  const groupUid = group.uid
+  const entry = [...ctx.loader.entries()].find(entry => entry.options.id === 'consumer')!
+  expect(configs[0]!.title.get()).toBe('initial')
+  await ctx.plugin(Timer)
+  // An exact-file config watch mirrors the HMR root-watch Include path, which packages/boot/hmr covers with a mocked watcher.
+  await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
+  const stopWatching = await ctx.hmr.watchConfig(filename, async () => {
+    await include.refresh()
+    await ctx.loader.await()
+  })
+  await writeFile(filename, '- id: group\n  name: cordis:group\n  group: true\n  config:\n    - id: consumer\n      name: cordis:volatile-test\n      config:\n        title: file-update\n')
+  // The config watcher stabilizes writes for two seconds before publishing a change.
+  await vi.waitFor(() => { expect(configs[0]!.title.get()).toBe('file-update') }, { timeout: 10_000 })
+  await stopWatching()
+  expect(configs).toHaveLength(1)
+  expect(include.store.group!.fiber).toBe(group)
+  expect(group.uid).toBe(groupUid)
+  expect(configs[0]!.title.get()).toBe('file-update')
+  entry.fiber!.update({ title: 'program-update', group: { list: ['item'] } })
+  expect(entry.options.config).toEqual({ title: 'program-update', group: { list: ['item'] } })
+  entry.fiber!.update({ title: 'ephemeral' }, true)
+  expect(entry.options.config).toEqual({ title: 'program-update', group: { list: ['item'] } })
+  await ctx.fiber.dispose()
+  const saved = await readFile(filename, 'utf8')
+  expect(saved).toContain('program-update')
+  expect(saved).not.toContain('get:')
+  expect(saved).not.toContain('ephemeral')
+  expect(updates).toHaveBeenCalledTimes(2)
+  const restored = context()
+  restored.baseUrl = ctx.baseUrl
+  await restored.plugin(Loader)
+  restored.loader.builtins.include = Include
+  restored.loader.builtins.group = Group
+  restored.loader.builtins['volatile-test'] = consumer
+  await restored.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(filename).href } })
+  await restored.loader.await()
+  expect(configs).toHaveLength(2)
+  expect(configs[1]!.title.get()).toBe('program-update')
+  expect(configs[1]!.group.get()).toEqual({ list: ['item'] })
+  await restored.fiber.dispose()
+})
+
+it('updates volatile children through Group and Include custom updates and saves ordinary config', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-volatile-tree-'))
+  const ctx = new Context()
+  onTestFinished(async () => { await ctx.fiber.dispose(); await rm(root, { recursive: true, force: true }) })
+  ctx.baseUrl = pathToFileURL(root).href + '/'
+  await ctx.plugin(Loader)
+  ctx.loader.builtins.include = Include
+  ctx.loader.builtins.group = Group
+  const configs: ReturnType<typeof Config>[] = []
+  const notifications = vi.fn()
+  const childUpdates = vi.fn()
+  ctx.loader.builtins['volatile-test'] = { Config, apply(owner: Context, config: ReturnType<typeof Config>) {
+    configs.push(config)
+    owner.on('loader/volatile-update', notifications)
+    owner.on('internal/update', childUpdates)
+  } }
+  const child = (title: string) => ({ id: 'consumer', name: 'cordis:volatile-test', config: { title } })
+  const filename = join(root, 'tree.json')
+  const includePath = pathToFileURL(filename).href
+  await writeFile(filename, JSON.stringify([{ id: 'group', name: 'cordis:group', group: true, config: [child('initial')] }]))
+  const rootId = await ctx.loader.create({ name: 'cordis:include', config: { path: includePath } })
+  await ctx.loader.await()
+  const includeEntry = ctx.loader.resolve(rootId)
+  const include = includeEntry.subtree as Include
+  const group = include.store.group!
+  const consumer = include.store.consumer!
+  const originalInclude = includeEntry.fiber
+  const originalGroup = group.fiber
+  const originalConsumer = consumer.fiber
+  const initial = configs[0]!
+
+  group.fiber!.update([child('group-update')])
+  await ctx.loader.await()
+  expect(initial.title.get()).toBe('group-update')
+  expect(group.options.config).toEqual([child('group-update')])
+  includeEntry.fiber!.update({ path: includePath, patches: [{ id: 'consumer', config: { title: 'include-update' } }] })
+  await ctx.loader.await()
+  expect(initial.title.get()).toBe('include-update')
+  expect(includeEntry.fiber).toBe(originalInclude)
+  expect(group.fiber).toBe(originalGroup)
+  expect(consumer.fiber).toBe(originalConsumer)
+  expect(consumer.fiber!.config).toBe(initial)
+  expect(configs).toHaveLength(1)
+  expect(notifications).toHaveBeenCalledTimes(2)
+  expect(childUpdates).not.toHaveBeenCalled()
+
+  const ordinary = await ctx.loader.create({ name: 'cordis:volatile-test', config: {} })
+  const entry = ctx.loader.resolve(ordinary)
+  entry.fiber!.update({ title: 'custom-update', fixed: 'ordinary' })
+  expect(childUpdates).toHaveBeenCalledOnce()
+  expect(entry.options.config).toEqual({ title: 'custom-update', fixed: 'ordinary' })
+  expect((entry.fiber!.config as ReturnType<typeof Config>).title.get()).toBe('hello')
+  entry.fiber!.update({ title: 'ephemeral', fixed: 'ordinary' }, true)
+  expect(childUpdates).toHaveBeenCalledTimes(2)
+  expect(entry.options.config).toEqual({ title: 'custom-update', fixed: 'ordinary' })
+  expect(() => { entry.fiber!.update({ nested: { count: -1 } }) }).toThrow()
+  expect(childUpdates).toHaveBeenCalledTimes(2)
+  expect(entry.options.config).toEqual({ title: 'custom-update', fixed: 'ordinary' })
+})
+
+it('commits volatile edits in place and retains direct Fiber updates', async () => {
+  const ctx = await runtimeContext()
+  const notifications = vi.fn()
+  const apply = vi.fn(function (owner: Context) { owner.on('loader/volatile-update', notifications) })
+  const fiber = await mountEntry(ctx, { Config, apply }, {})
+  const original = fiber.config as ReturnType<typeof Config>
+  await ctx.loader.create({ name: 'cordis:disabled', disabled: true })
+  await update(fiber, { title: 'enabled' })
+  expect(apply).toHaveBeenCalledOnce()
+  expect(fiber.config).toBe(original)
+  expect(original.title.get()).toBe('enabled')
+  expect(notifications).toHaveBeenCalledExactlyOnceWith([['title']])
+  await update(fiber, { title: 'invalid', nested: { count: -1 } })
+  expect(original.title.get()).toBe('enabled')
+  await update(fiber, { title: 'mixed', fixed: 'changed' })
+  expect(apply).toHaveBeenCalledTimes(2)
+  expect(original.title.get()).toBe('enabled')
+  const current = fiber.config as ReturnType<typeof Config>
+  expect(current.title.get()).toBe('mixed')
+
+  const hook = vi.fn((_config: unknown, _noSave: boolean, next: () => void) => { next() })
+  fiber.ctx.on('internal/update', hook)
+  fiber.update({ title: 'direct' })
+  await fiber.await()
+  expect(hook).toHaveBeenCalledOnce()
+  expect(apply).toHaveBeenCalledTimes(3)
+  expect(current.title.get()).toBe('mixed')
+  expect(notifications).toHaveBeenCalledOnce()
+})
+
+it('parses a volatile-only update through the config hook without patching the entry context', async () => {
+  const ctx = await runtimeContext()
+  const trace: string[] = []
+  const trim = vi.fn((value: string) => { trace.push('validate'); return value.trim() })
+  const Config = z.object({ block: z.object({ title: z.transform(z.string(), trim, true) }).volatile() })
+  const fiber = await mountEntry(ctx, { Config, apply(owner: Context) {
+    owner.on('loader/volatile-update', () => { trace.push('notify') })
+  } }, { block: { title: 'initial' } })
+  const current = fiber.config as ReturnType<typeof Config>
+  const resolveHook = vi.fn((_raw: unknown, next: () => unknown) => next())
+  fiber.ctx.on('internal/config', resolveHook)
+  const contextPatch = vi.fn((_entry: unknown, next: () => void) => { next() })
+  ctx.on('loader/patch-context', contextPatch)
+  trim.mockClear()
+  trace.length = 0
+  const raw = { block: { title: ' changed ' } }
+  await fiber.entry!.update({ config: raw })
+  expect(contextPatch).not.toHaveBeenCalled()
+  expect(trim).toHaveBeenCalledExactlyOnceWith(' changed ')
+  expect(resolveHook).toHaveBeenCalledOnce()
+  expect(trace).toEqual(['validate', 'notify'])
+  expect(current.block.get()).toEqual({ title: 'changed' })
+  expect(fiber._config).toBe(raw)
+})
+
+it.each([true, false])('keeps old references untouched when isolation replaces a dependency (available: %s)', async (available) => {
+  const ctx = await runtimeContext()
+  const configs: ReturnType<typeof Config>[] = []
+  const notifications = vi.fn()
+  ctx.loader.builtins.provider = { apply(owner: Context) { owner.provide('volatile-isolated-service', {}) } }
+  ctx.loader.builtins.consumer = {
+    inject: ['volatile-isolated-service'], Config,
+    apply(owner: Context, config: ReturnType<typeof Config>) {
+      configs.push(config)
+      owner.on('loader/volatile-update', notifications)
+    },
+  }
+  const provider = (realm: string) => ctx.loader.create({
+    name: 'cordis:provider', isolate: { 'volatile-isolated-service': realm },
+  })
+  await provider('a')
+  if (available) await provider('b')
+  const id = await ctx.loader.create({
+    name: 'cordis:consumer', isolate: { 'volatile-isolated-service': 'a' }, config: { title: 'old' },
+  })
+  await ctx.loader.await()
+  const original = configs[0]!
+  await ctx.loader.resolve(id).update({ isolate: { 'volatile-isolated-service': 'b' }, config: { title: 'new' } })
+  await ctx.loader.await()
+  expect(configs).toHaveLength(available ? 2 : 1)
+  expect(original.title.get()).toBe('old')
+  expect(notifications).not.toHaveBeenCalled()
+  if (!available) {
+    await provider('b')
+    await ctx.loader.await()
+  }
+  expect(configs).toHaveLength(2)
+  expect(configs[1]!.title.get()).toBe('new')
+})
+
+it.each(['group', 'include'] as const)('applies profile patches to a %s subtree without HMR and keeps mixed updates on the normal lifecycle', async (kind) => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-volatile-profile-'))
+  onTestFinished(() => rm(root, { recursive: true, force: true }))
+  const configs: ReturnType<typeof Config>[] = []
+  const events = vi.fn()
+  const dispose = vi.fn()
+  const consumer = { Config, apply(owner: Context, config: ReturnType<typeof Config>) {
+    configs.push(config)
+    owner.on('loader/volatile-update', events)
+    owner.effect(() => dispose)
+  } }
+  const child = (title: string, fixed = 'fixed') => ({ id: 'consumer', name: 'cordis:consumer', config: { title, fixed } })
+  const nested = join(root, 'nested.json')
+  await writeFile(nested, JSON.stringify([child('initial')]))
+  const carrierConfig = (title: string, fixed = 'fixed') => kind === 'group'
+    ? [child(title, fixed)]
+    : { path: pathToFileURL(nested).href, patches: [{ id: 'consumer', config: { title, fixed } }] }
+  const filename = join(root, 'cordis.yml')
+  await writeFile(filename, JSON.stringify([{ id: 'parent', name: `cordis:${kind}`, group: kind === 'group', config: carrierConfig('initial') }]))
+  const ctx = await boot('volatile-test', filename, undefined, async (ctx) => {
+    ctx.loader.builtins.consumer = consumer
+  })
+  onTestFinished(() => ctx.fiber.dispose())
+  expect(ctx.get('hmr')).toBeUndefined()
+  const parent = [...ctx.loader.entries()].find(entry => entry.options.id === 'parent')!
+  const entry = [...ctx.loader.entries()].find(entry => entry.options.id === 'consumer')!
+  const parentFiber = parent.fiber
+  const childFiber = entry.fiber
+  const original = configs[0]!
+  const reference = original.title
+  const patch = (title: string, fixed = 'fixed') => [{ id: 'parent', config: carrierConfig(title, fixed) }]
+  await reconcileProfilePatches(ctx, patch('first'), 'volatile-test')
+  await reconcileProfilePatches(ctx, patch('second'), 'volatile-test')
+  expect(parent.fiber).toBe(parentFiber)
+  expect(entry.fiber).toBe(childFiber)
+  expect(entry.fiber!.config).toBe(original)
+  expect(original.title).toBe(reference)
+  expect(reference.get()).toBe('second')
+  expect(configs).toHaveLength(1)
+  expect(dispose).not.toHaveBeenCalled()
+  expect(events).toHaveBeenCalledTimes(2)
+  expect(events).toHaveBeenLastCalledWith([['title']])
+  await reconcileProfilePatches(ctx, patch('second'), 'volatile-test')
+  expect(events).toHaveBeenCalledTimes(2)
+  await reconcileProfilePatches(ctx, patch('mixed', 'changed'), 'volatile-test')
+  expect(parent.fiber).toBe(parentFiber)
+  expect(configs).toHaveLength(2)
+  expect(dispose).toHaveBeenCalledOnce()
+  expect(reference.get()).toBe('second')
+  expect(configs[1]!.title.get()).toBe('mixed')
+  expect(events).toHaveBeenCalledTimes(2)
+})
+
+it('logs an invalid candidate and keeps its references while other entries commit', async () => {
+  const ctx = await runtimeContext()
+  const events = vi.fn()
+  const plugin = { Config, apply(owner: Context) { owner.on('loader/volatile-update', events) } }
+  const invalid = await mountEntry(ctx, plugin)
+  const healthy = await mountEntry(ctx, plugin)
+  const warning = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+  onTestFinished(() => { warning.mockRestore() })
+  await invalid.entry!.update({ config: { title: 'invalid', nested: { count: -1 } } })
+  await healthy.entry!.update({ config: { title: 'healthy' } })
+  expect(warning).toHaveBeenCalledTimes(2)
+  expect((invalid.config as ReturnType<typeof Config>).title.get()).toBe('hello')
+  expect(invalid._config).toEqual({ title: 'invalid', nested: { count: -1 } })
+  expect((healthy.config as ReturnType<typeof Config>).title.get()).toBe('healthy')
+  expect(events).toHaveBeenCalledExactlyOnceWith([['title']])
+})
+
+it.each([false, true])('retains raw expression edits for dependency restoration (volatile: %s)', async (volatile) => {
+  const ctx = await runtimeContext()
+  const schema = z.object({ value: volatile ? z.string().volatile() : z.string() })
+  const values: unknown[] = []
+  const provide = (a: string, b: string) => ctx.plugin({ apply(owner: Context) { owner.provide('volatile-expression-source', { a, b }) } })
+  const provider = await provide('same', 'same')
+  const fiber = await mountEntry(ctx, { Config: schema, inject: ['volatile-expression-source'], apply(_owner: Context, config: ReturnType<typeof schema>) {
+    values.push(typeof config.value === 'string' ? config.value : config.value.get())
+  } }, { value: { __jsExpr: "ctx.get('volatile-expression-source').a" } })
+  const raw = { value: { __jsExpr: "ctx.get('volatile-expression-source').b" } }
+  await fiber.entry!.update({ config: raw })
+  await fiber.await()
+  expect(values).toEqual(volatile ? ['same'] : ['same', 'same'])
+  expect(fiber._config).toBe(raw)
+  await provider.dispose()
+  await provide('old-route', 'new-route')
+  await fiber.await()
+  expect(values).toEqual(volatile ? ['same', 'new-route'] : ['same', 'same', 'new-route'])
+})
+
+it('remounts when changed expressions resolve to ordinary values different from the live config', async () => {
+  const ctx = await runtimeContext()
+  const source = { a: 'initial', b: 'initial' }
+  ctx.provide('volatile-expression-source', source)
+  const configs: ReturnType<typeof Config>[] = []
+  const events = vi.fn()
+  const fiber = await mountEntry(ctx, { Config, apply(owner: Context, config: ReturnType<typeof Config>) {
+    configs.push(config)
+    owner.on('loader/volatile-update', events)
+  } }, { fixed: { __jsExpr: "ctx.get('volatile-expression-source').a" }, title: 'old' })
+  source.a = source.b = 'changed'
+  await update(fiber, { fixed: { __jsExpr: "ctx.get('volatile-expression-source').b" }, title: 'new' })
+  expect(configs).toHaveLength(2)
+  expect(configs[0]!.title.get()).toBe('old')
+  expect(configs[1]!.fixed).toBe('changed')
+  expect(configs[1]!.title.get()).toBe('new')
+  expect(events).not.toHaveBeenCalled()
+})
+
+it('compares ordinary URL transforms by value and remounts when an expression result changes', async () => {
+  const ctx = await runtimeContext()
+  const source = { value: 'initial' }
+  ctx.provide('volatile-transform-source', source)
+  const schema = z.object({
+    url: z.transform(z.string(), value => new URL(value), true),
+    fixed: z.string(),
+    live: z.string().volatile(),
+  })
+  const events = vi.fn()
+  const mount = vi.fn(function (owner: Context) { owner.on('loader/volatile-update', events) })
+  const fixed = { __jsExpr: "ctx.get('volatile-transform-source').value" }
+  const raw = { url: 'https://example.com/', fixed, live: 'old' }
+  const fiber = await mountEntry(ctx, { Config: schema, apply: mount }, raw)
+  const current = fiber.config as ReturnType<typeof schema>
+  await update(fiber, { ...raw, live: 'new' })
+  expect(mount).toHaveBeenCalledOnce()
+  expect(fiber.config).toBe(current)
+  expect(current.url.href).toBe(raw.url)
+  expect(current.fixed).toBe('initial')
+  expect(current.live.get()).toBe('new')
+  expect(events).toHaveBeenCalledExactlyOnceWith([['live']])
+  source.value = 'changed'
+  await update(fiber, { ...raw, live: 'remounted' })
+  expect(mount).toHaveBeenCalledTimes(2)
+  expect(current.fixed).toBe('initial')
+  expect(current.live.get()).toBe('new')
+  expect(events).toHaveBeenCalledOnce()
+  const replaced = fiber.config as ReturnType<typeof schema>
+  expect(replaced.fixed).toBe('changed')
+  expect(replaced.live.get()).toBe('remounted')
+})
+
+it('remounts when an ordinary parent expression removes a live reference path', async () => {
+  const ctx = await runtimeContext()
+  const source: { block: { value: string } | undefined } = { block: { value: 'old' } }
+  ctx.provide('volatile-path-source', source)
+  const schema = z.object({ block: z.object({ value: z.string().volatile() }).extra('default', undefined), live: z.string().volatile() })
+  const events = vi.fn()
+  const mount = vi.fn(function (owner: Context) { owner.on('loader/volatile-update', events) })
+  const raw = { block: { __jsExpr: "ctx.get('volatile-path-source').block" }, live: 'old' }
+  const fiber = await mountEntry(ctx, { Config: schema, apply: mount }, raw)
+  const current = fiber.config as ReturnType<typeof schema>
+  source.block = undefined
+  await update(fiber, { ...raw, live: 'new' })
+  expect(mount).toHaveBeenCalledTimes(2)
+  expect(current.block.value.get()).toBe('old')
+  expect(events).not.toHaveBeenCalled()
+  expect((fiber.config as ReturnType<typeof schema>).block).toBeUndefined()
+})
+
+it('keeps an ordinary plugin mounted when an absent object becomes its explicit default', async () => {
+  const ctx = await runtimeContext()
+  const Config = z.object({ nested: z.object({ fixed: z.string() }).default({ fixed: 'default' }) })
+  const mount = vi.fn()
+  const fiber = await mountEntry(ctx, { Config, apply: mount }, {})
+  const config: unknown = fiber.config
+  await update(fiber, { nested: { fixed: 'default' } })
+  expect(fiber.config).toBe(config)
+  expect(mount).toHaveBeenCalledTimes(1)
+  await update(fiber, { nested: { fixed: 'changed' } })
+  expect(mount).toHaveBeenCalledTimes(2)
+  expect(fiber.config).toEqual({ nested: { fixed: 'changed' } })
+})
+
+it('keeps a noSave volatile value as the pending raw config across a no-op entry update', async () => {
+  const ctx = await runtimeContext()
+  const fiber = await mountEntry(ctx, { Config, apply() {} }, { title: 'saved' })
+  fiber.update({ title: 'ephemeral' }, true)
+  await fiber.await()
+  expect((fiber.config as ReturnType<typeof Config>).title.get()).toBe('ephemeral')
+  expect(fiber.entry!.options.config).toEqual({ title: 'saved' })
+  await fiber.entry!.update({ config: { title: 'saved' } })
+  expect(fiber._config).toEqual({ title: 'ephemeral' })
+  expect((fiber.config as ReturnType<typeof Config>).title.get()).toBe('ephemeral')
+})
+
+it('isolates a failing notification listener and dispatches with a Context receiver', async () => {
+  const ctx = await runtimeContext()
+  const receivers: unknown[] = []
+  const fiber = await mountEntry(ctx, { Config, apply(owner: Context) {
+    owner.on('loader/volatile-update', function (this: Context) { receivers.push(this.fiber); throw new Error('listener boom') })
+  } }, {})
+  const other = await mountEntry(ctx, { Config, apply() {} }, {})
+  const warning = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+  onTestFinished(() => { warning.mockRestore() })
+  await update(fiber, { title: 'committed' })
+  expect((fiber.config as ReturnType<typeof Config>).title.get()).toBe('committed')
+  expect(receivers).toEqual([fiber])
+  expect(warning).toHaveBeenCalledWith(expect.objectContaining({ message: 'listener boom' }))
+  await update(other, { title: 'unaffected' })
+  expect((other.config as ReturnType<typeof Config>).title.get()).toBe('unaffected')
+})
+
+it('remounts instead of committing when an ordinary field parses into a fresh class instance', async () => {
+  const ctx = await runtimeContext()
+  class Handle { constructor(public readonly name: string) {} }
+  const schema = z.object({ handle: z.transform(z.string(), value => new Handle(value)), live: z.string().volatile() })
+  const mount = vi.fn()
+  const fiber = await mountEntry(ctx, { Config: schema, apply: mount }, { handle: 'h', live: 'old' })
+  const before = fiber.config as ReturnType<typeof schema>
+  await update(fiber, { handle: 'h', live: 'new' })
+  expect(mount).toHaveBeenCalledTimes(2)
+  expect(before.live.get()).toBe('old')
+  expect((fiber.config as ReturnType<typeof schema>).live.get()).toBe('new')
+})
diff --git a/scripts/no-unknown-casts.baseline.json b/scripts/no-unknown-casts.baseline.json
index 132d00b292..38faa69d65 100644
--- a/scripts/no-unknown-casts.baseline.json
+++ b/scripts/no-unknown-casts.baseline.json
@@ -26,9 +26,6 @@
   "apps/desktop-host/tests/office.spec.ts": {
     "3f8653cd87f99ebd70765379dae51ab308ed9c280e831d39e1abd469bfcdc6e3": 1
   },
-  "apps/desktop-host/tests/primary-runtime.spec.ts": {
-    "3f8653cd87f99ebd70765379dae51ab308ed9c280e831d39e1abd469bfcdc6e3": 1
-  },
   "apps/desktop/scripts/installed-update-qualification.ts": {
     "5a8270cf9b1e554ae0cff6eaf7086e44c22f61a08e5f91dc7e1397eccaa726a5": 2
   },
@@ -53,7 +50,6 @@
   },
   "apps/desktop/tests/host-update-tasks.spec.ts": {
     "46197efe57255c9d92d64476470c89d0602c7333bf98ad75509bf43c1b357a3b": 1,
-    "4c5672583f1c38f4fb7dd757e94f8424866a00aa5c9a9d3dfc07d45718fa04c4": 1,
     "f6c86f29edc554d5fda72589a77b006468b174a428a5345ce7e88dec698b9829": 1
   },
   "apps/desktop/tests/main-startup.spec.ts": {
@@ -203,7 +199,6 @@
     "fc16f363fc891dac66e0be8c042da4b1d3f45c35af2d31a03f2214a6c3698379": 1
   },
   "packages/api/gateway/tests/stream-server.host.spec.ts": {
-    "53253a9a650abe4678a5eb411720231ef4a387ed2de78dde44054ff3d72efbbe": 1,
     "c7136804a6f7b829f525135643cb93cc8b3176b1d0036b2ebde5d7b668411658": 1,
     "dd244515f22ccbc14e5872126c3fc405ed6a63bb0390940976e234e3c06fcc2b": 1
   },
@@ -481,10 +476,6 @@
   "packages/client/ui-agent-preset/tests/section-store.client.spec.ts": {
     "23e04af2a900d7a905ff7657de842e9833384a2d4c4afba33964477e43d8ba52": 1
   },
-  "packages/client/ui-agent-preset/tests/section.client.spec.tsx": {
-    "4cc9284f9e4d9df997ed042df717f143f3763130fdfb9e142226da4b5b4c60e6": 1,
-    "67694f8f44eb8347cb38c39d368f4f0ce1b78bd33a6a57a55cf4664f3eaa7f98": 1
-  },
   "packages/client/ui-agent-preset/tests/settings-store.client.spec.ts": {
     "c0e852e6b0e2a8a040b65723f8ab1d650d9cb06c26be7f3a0709ddb9f7525595": 1,
     "d6a04d954aef7a8edd403910851015c0ce1597f6f300292b5158a8bf993fc1d8": 1
@@ -594,10 +585,6 @@
   "packages/client/ui-deliverables/tests/present-open.host.spec.ts": {
     "556e0d31b686cc80ef5c9562dad5534556f1b55ce1ce20491aa39eda98255364": 1
   },
-  "packages/client/ui-deliverables/tests/review-tab.client.spec.tsx": {
-    "52e0f8e51efd9a65974af6ad6868c7e01fff0d6faeb669e9da1bf91de8a2d422": 1,
-    "56f9870142343b23a01725140b72d040d1b9071dd30227271518f50cfa614b6c": 1
-  },
   "packages/client/ui-goal/tests/browser-plugin.client.spec.tsx": {
     "04984a2ce1486250236e638e0197da0a1a840855ed3975c59130a85358c7e5fe": 1,
     "5f1a0867b42cf35dac7fdf5839e3a39c2384c5b3b03142e799a36733ad96b9da": 1,
@@ -611,9 +598,6 @@
   "packages/client/ui-input-trigger/tests/apply.client.spec.ts": {
     "fc590cb703f599e5bb15f23909cedddeb2a77cb2cad0d4b9b8e664a62c46f44e": 1
   },
-  "packages/client/ui-jobs/tests/job-list-action.client.spec.tsx": {
-    "0a7212cab13eacbb983b226949951fc76bad9e2d93dab9fad4639f7c541c2547": 1
-  },
   "packages/client/ui-message-feedback/tests/browser-plugin.client.spec.tsx": {
     "04984a2ce1486250236e638e0197da0a1a840855ed3975c59130a85358c7e5fe": 2
   },
@@ -628,13 +612,6 @@
     "eee35b4d8641824c6eaacfe03ed60d353d81d5257d1111132f34d46a7b13ef35": 2,
     "ff65b54ee69109a8b059fc2a2136c71a5476b47115120c7c92a01171d517f3d7": 1
   },
-  "packages/client/ui-open-in-app/tests/open-in-app-action.client.spec.tsx": {
-    "d6ca469f487b05b19564776f9a8f8288b1f0d9fb5b7fb6681e68f063fb021f38": 1,
-    "fdc0ec545dc17a50bdc1c64102915706cfbfdbb65a2165ae4691f29d577063cd": 1
-  },
-  "packages/client/ui-open-in-app/tests/open-path-action.client.spec.tsx": {
-    "362d9206df82a6d4563c2e5c19457342207b02b246c91656dec01a4b2033fd8e": 1
-  },
   "packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts": {
     "dc36dd8f678695e3b84ce0573968470941c5b6fc5efe529cba17acb1f2799d1c": 1
   },
@@ -736,9 +713,6 @@
     "14a0dc9ccde2879c016f779e0e43f3aa71792759126530b418c9a31a5a2e7a53": 1,
     "ad8886dedfafd8e5f4bf7cb55525bb961822ad0c4fb0ff4a643bfb336fb9d94b": 1
   },
-  "packages/client/ui-sidebar-browser/tests/browser-body.client.spec.tsx": {
-    "dac38a9cc792ab6f3a345802975995e35a48d5a706c26d67cb7dba1c906ee3d5": 1
-  },
   "packages/client/ui-sidebar-documentpreview/tests/document-toolbar.client.spec.tsx": {
     "fb9804cc2774409af6935d5a1369497b433c34cd9305cac88e3400eae0f70936": 1
   },
@@ -831,9 +805,6 @@
   "packages/client/ui-subagent/tests/browser-plugin.client.spec.ts": {
     "810a8e63d34628d25866491b3c6455a51b2d114261b67e62b42728b765370993": 1
   },
-  "packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx": {
-    "92d757187bb2dba986b160c2417c7b4a8b199784d441bfa0777d8077774b932b": 1
-  },
   "packages/client/ui-subagent/tests/sidebar-chat.client.spec.tsx": {
     "024f8748e8908a495117a23a7673046a871f0d8187f8fe561aceba1269aefa31": 1,
     "6f46259a9f4093d68b3fc7859c263f21b6318197b74aba368e8904321ab5c4f9": 1,
@@ -1498,63 +1469,17 @@
   "packages/jobs/jobs-local/tests/loader-composition.spec.ts": {
     "6dc45d44a978dd86bb9ac2c9baf5d31aed699055698709e09bb34e99150e239d": 1
   },
-  "packages/jobs/jobs/tests/invariant.spec.ts": {
-    "2c66826d784c113eaf3f8ae7ac490920b0a9a5a0c8c3540743927379bebdddc9": 1
-  },
   "packages/jobs/tool-jobs/src/index.ts": {
     "64ab5463fdb068e88a33f022baff473b7a0da77854c4ecf8e26412763d6dccf6": 1
   },
   "packages/jobs/tool-jobs/tests/tool-jobs.spec.ts": {
     "0683cfd7f792f1b6333bc8c419d8ce32a7a630179280a31083a8f664e26e0ec0": 1,
     "0cf18056bb99a9f7435d55db31bed426d69b9973f7e15ebbca466f9e08ac9ee3": 1,
-    "284e4fe44c92b2f7e60f312649a22debe743ec6640e3b7b0ff8c9c35b02c24f2": 1,
     "52faf4558fcd91bd27dbdfa7e497843e8eeb75ea5f68ee231335018d5b3f2053": 2
   },
   "packages/llm/deepseek-llm-api-extensions/src/index.ts": {
     "1f519aabb00553384bc9c1c57064a1ed6fcd757032061e1b14e0718d91dd4817": 1
   },
-  "packages/llm/llm-deepseek/src/protocols/chat-completions/adapter.ts": {
-    "598014dcfe77101781e3c6a02709097e3b0151a335e909c44719fac08fdea433": 1
-  },
-  "packages/llm/llm-deepseek/src/protocols/messages/adapter.ts": {
-    "598014dcfe77101781e3c6a02709097e3b0151a335e909c44719fac08fdea433": 1
-  },
-  "packages/llm/llm-deepseek/src/protocols/messages/replay.ts": {
-    "9ebdedf03d9d83739a3d01d1c579242aceca09ea5be1be17f96eacf29e07cdea": 1
-  },
-  "packages/llm/llm-deepseek/tests/adapter.spec.ts": {
-    "34a631902f39d3a40e1baabacdccb986c3a2205cf2a6c8c1880061b87f39609d": 1,
-    "3f65e71f59e11feed30a6ca5bf870cad688d0bd161f6d52fe263a7aaf01bdb19": 2,
-    "b744a3b1ea1021e620ae97ba95bab540b731d7df9634e06fa3830ea7d9e5ebac": 1,
-    "cf2695bf7b16a8d315df73d326e926645d03499422d39f6b97bc569dda04137e": 1,
-    "d09a59b309ad22650abede4b87a64dc6afaf18c08e4313635a22f0121c0a6a92": 1,
-    "eea7d67f2cd0210a9a2d81bce690d485033ea7f120396b8a8b7f2016ea7ae396": 1
-  },
-  "packages/llm/llm-deepseek/tests/loader-composition.spec.ts": {
-    "59c63f734e8bba862325f776e3fcbebd78a84cfb4161f8df41c216950d9bf351": 1
-  },
-  "packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts": {
-    "0dd149237441659d6dc629eb4e30914ac604236cbe023d90693e512b7e300a49": 1
-  },
-  "packages/llm/llm-deepseek/tests/messages/adapter.spec.ts": {
-    "ae6cc7d948e6e78f72fcd1764acabc731e7498c880b7d709710f8bfeee113ef8": 1,
-    "f1f72ca0a6b4cc00365db8c58c0477975b87b4293f0751815e1e971a7191c34d": 1
-  },
-  "packages/llm/llm-deepseek/tests/messages/files.spec.ts": {
-    "65121d4bf51b358c794748d5895b388149f6883d4ae88f6c16b39802813c223f": 1,
-    "eea7d67f2cd0210a9a2d81bce690d485033ea7f120396b8a8b7f2016ea7ae396": 1
-  },
-  "packages/llm/llm-deepseek/tests/messages/serialize.spec.ts": {
-    "02285954262e9d3346a33f080c4aeb89b7f6349014fd23d64e5aeb28a52f1ced": 1,
-    "8c7e2bcfcb534160c7df81de8490cfe4e9891e913c7c429a3f47f603d1129da3": 2,
-    "a394f4cff3c3d3755ffce930afc5cbee43f92de4ae2112a2325b64bdceb74ad2": 1,
-    "ab74fe25dbefba4c45ffa5bab2729b4bb372df0b946711e5d463686e4a0edc02": 2
-  },
-  "packages/llm/llm-deepseek/tests/serialize.spec.ts": {
-    "12712253c43410ab721190981c8b815d102f799ce6942bee3975b035c203dfa8": 1,
-    "98bef9260e144cee077af05112a07d3e9626caa43f06c66ad08f9c024f5469b1": 1,
-    "a394f4cff3c3d3755ffce930afc5cbee43f92de4ae2112a2325b64bdceb74ad2": 1
-  },
   "packages/llm/llm-pi-ai/src/catalog.ts": {
     "5b1064d0195802d24eaa5155c66eb381da6046a8ccd0cacc3d852336475da7ef": 1
   },
@@ -2126,9 +2051,7 @@
     "b50b6842b3565ea7f1441afb3214ab0ccf027df0e44bb485005935849c46f8ea": 1
   },
   "packages/subagent/subagent/src/catalog.ts": {
-    "29a67bf48723006b65c652af8a0ff30a4385bb14d651d91ca3059e1ddcb44fcf": 1,
     "3e704e331ed2fc5d4c0855e2455b31b82924c525f2e267416e393cdbd36c251b": 1,
-    "c3a7c8abe19131a8d98f4fb6a495b590e67a56cbf2e741caccfe730f8261edb0": 1,
     "fdc5fcade0ba1abbc426ccccb07a1ad4998253799b8561815047d95178441cdf": 1
   },
   "packages/subagent/subagent/src/internal.ts": {
diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts
index 98b3bbb051..57903b0e03 100644
--- a/scripts/package-dependency-policy.ts
+++ b/scripts/package-dependency-policy.ts
@@ -55,8 +55,9 @@ const SAFE_HOST_DEPENDENCY_EXPORTS = {
 
 /** Runtime exports that require every consumer to resolve the provider's shared peer instance. */
 const PEER_REQUIRED_HOST_EXPORTS = {
+  '@deepseek-ai/dsh-client-connection': ['OperatorPeer'],
   '@deepseek-ai/dsh-subprocess': ['SubprocessExecutableNotFoundError'],
-  '@deepseek-ai/dsh-scope': ['carrierKeyOf', 'scopeOf', 'scopeTarget'],
+  '@deepseek-ai/dsh-scope': ['carrierKeyOf', 'createScope', 'scopeOf', 'scopeTarget'],
   '@deepseek-ai/dsh-session': ['SESSION_FORMAT_VERSION'],
   '@deepseek-ai/dsh-session-persistence': ['SessionPersistenceNotFoundError'],
 } as const satisfies HostDependencyExports
diff --git a/scripts/persistence-changes.spec.ts b/scripts/persistence-changes.spec.ts
index 54b5a9588f..ab6f0e50e3 100644
--- a/scripts/persistence-changes.spec.ts
+++ b/scripts/persistence-changes.spec.ts
@@ -397,7 +397,63 @@ function unionBody(arms: readonly (readonly SchemaProperty[])[]): PersistenceRoo
   return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
 }
 
+function versionedEvent(variants: readonly { version: number; mode: string; extra?: boolean }[]): PersistenceRoot {
+  const nodes: SchemaNode[] = [
+    { kind: 'object', indices: [], properties: [
+      { name: 'data', type: variants.length === 1 ? 3 : 1, optional: false },
+      { name: 'type', type: 3 + variants.length * 3, optional: false },
+    ] },
+    { kind: 'union', types: variants.map((_, index) => 3 + index * 3) },
+    { kind: 'primitive', type: 'string' },
+  ]
+  for (const variant of variants) {
+    const index = nodes.length
+    nodes.push({ kind: 'object', indices: [], properties: [
+      { name: 'version', type: index + 1, optional: false },
+      { name: 'mode', type: index + 2, optional: false },
+      ...(variant.extra ? [{ name: 'extra', type: 2, optional: false }] : []),
+    ] }, { kind: 'literal', value: variant.version }, { kind: 'literal', value: variant.mode })
+  }
+  nodes.push({ kind: 'literal', value: 'example/value' })
+  const schema = canonicalizeSchema(nodes, 0)
+  return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
+}
+
 describe('persistence change classification', () => {
+  it.each([1, 2])('acknowledges a higher payload version while preserving %s old variant(s) and the V4 checkpoint', (count) => {
+    const root = fixture()
+    const variants = [{ version: 0, mode: 'one-shot' }, { version: 0, mode: 'continuable' }].slice(0, count)
+    const oldEvent = versionedEvent(variants)
+    const nextEvent = versionedEvent([...variants, { version: 1, mode: 'unknown', extra: true }])
+    const before = { ...inventory({}, 4), roots: [...inventory({}, 4).roots.filter(root => root.kind !== 'event'), oldEvent] }
+    finalize(root, before)
+    const after = { ...before, roots: before.roots.map(root => root.kind === 'event' ? nextEvent : root) }
+    expect(classifyPersistenceChange(oldEvent, nextEvent))
+      .toEqual([expect.objectContaining({ kind: 'payload-version-added', requiresVersionBump: false })])
+    runPersistenceChanges(['--record', COMPATIBLE_ID, '--prose', proseFile(root)], root, () => after)
+    verifyPersistenceChanges(root, after)
+  })
+
+  it('rejects changes to old payloads, missing versions, non-increasing versions, and removal of old readers', () => {
+    const variants = [{ version: 0, mode: 'one-shot' }, { version: 0, mode: 'continuable' }]
+    const before = versionedEvent(variants)
+    for (const after of [
+      versionedEvent([...variants, { version: 0, mode: 'unknown' }]),
+      versionedEvent([...variants, { version: -1, mode: 'unknown' }]),
+      versionedEvent([...variants, { version: 0.5, mode: 'unknown' }]),
+      versionedEvent([{ version: 0, mode: 'one-shot', extra: true }, variants[1]!, { version: 1, mode: 'unknown' }]),
+      versionedEvent([{ version: 1, mode: 'unknown' }]),
+    ]) expect(classifyPersistenceChange(before, after).some(change => change.requiresVersionBump)).toBe(true)
+    const expanded = versionedEvent([...variants, { version: 1, mode: 'unknown' }])
+    expect(classifyPersistenceChange(expanded, before).some(change => change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange({ ...before, surface: true }, { ...expanded, surface: true })
+      .some(change => change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange({ ...before, kind: 'header' }, { ...expanded, kind: 'header' })
+      .some(change => change.requiresVersionBump)).toBe(true)
+    const unversioned = unionBody([[{ name: 'mode', type: 2, optional: false }]])
+    expect(classifyPersistenceChange(unversioned, expanded).some(change => change.requiresVersionBump)).toBe(true)
+  })
+
   it('treats a new optional payload subtree as one additive change even with required descendants', () => {
     const before = typeRoot('event:example/value', { value: 'string' })
     const after = typeRoot('event:example/value', { value: 'string', 'details?': { name: 'string', count: 'number' } })
diff --git a/scripts/persistence-changes.ts b/scripts/persistence-changes.ts
index 65f17b279f..d1f38225a9 100644
--- a/scripts/persistence-changes.ts
+++ b/scripts/persistence-changes.ts
@@ -66,6 +66,7 @@ const CHANGE_DESCRIPTIONS = {
   'index-signature-changed': 'index signature changed',
   'tuple-length-changed': 'tuple length changed',
   'tuple-element-cardinality-changed': 'tuple element cardinality changed',
+  'payload-version-added': 'event payload version added',
   'union-variants-changed': 'union variants changed',
   'source-policy-changed': 'source compatibility policy changed',
   'attribution-kind-added': 'attribution-only source kind added',
@@ -405,6 +406,27 @@ export function classifyPersistenceChange(before: PersistenceRoot | null, after:
     }
     const oldNode = oldRoot.schema.nodes[oldIndex] as SchemaNode
     const newNode = newRoot.schema.nodes[newIndex] as SchemaNode
+    if (oldRoot.kind === 'event' && oldRoot.surface === false && scope === 'body' && path === `${key}.data`) {
+      const oldTypes = oldNode.kind === 'union' ? oldNode.types : [oldIndex]
+      const newTypes = newNode.kind === 'union' ? newNode.types : [newIndex]
+      const payloadVersion = (schema: CanonicalSchema, index: number): number | undefined => {
+        const node = schema.nodes[index]
+        if (node?.kind !== 'object') return undefined
+        const property = node.properties.find(property => property.name === 'version' && !property.optional)
+        const version = schema.nodes[property?.type ?? -1]
+        return version?.kind === 'literal' && typeof version.value === 'number'
+          && Number.isSafeInteger(version.value) && version.value >= 0 ? version.value : undefined
+      }
+      const versions = oldTypes.map(index => payloadVersion(oldRoot.schema, index))
+      const oldHashes = new Set(oldTypes.map(index => fingerprint(oldRoot.schema, index, 0)))
+      const newHashes = new Set(newTypes.map(index => fingerprint(newRoot.schema, index, 1)))
+      const added = newTypes.filter(index => !oldHashes.has(fingerprint(newRoot.schema, index, 1)))
+      if (versions.every(version => version !== undefined) && added.length > 0
+        && [...oldHashes].every(hash => newHashes.has(hash))
+        && added.every(index => (payloadVersion(newRoot.schema, index) ?? -1) > Math.max(...versions))) {
+        return [describe(path, 'payload-version-added', false)]
+      }
+    }
     if (oldNode.kind !== newNode.kind) return [describe(path, 'type-changed')]
     if (oldNode.kind === 'object' && newNode.kind === 'object') {
       const oldProps = new Map(oldNode.properties.map(property => [property.name, property]))
diff --git a/apps/desktop/scripts/primary-runtime-lock.json b/scripts/primary-runtime/lock.json
similarity index 69%
rename from apps/desktop/scripts/primary-runtime-lock.json
rename to scripts/primary-runtime/lock.json
index 4dcf73c886..f5b0ada48a 100644
--- a/apps/desktop/scripts/primary-runtime-lock.json
+++ b/scripts/primary-runtime/lock.json
@@ -74,6 +74,54 @@
           "sha256": "623c8799c17128753c65699f1c3aa32402657393a9ad6db09ed8b98ddf76611d"
         }
       ]
+    },
+    "linux-x64": {
+      "nodeArchive": "linux-x64.tar.gz",
+      "nodeSha256": "6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff",
+      "pythonTarget": "x86_64-unknown-linux-gnu",
+      "pythonSha256": "72748da13197c1fb161e3afeef20a6a385ff24f2165e6e2758e47008e7faba4c",
+      "wheels": [
+        {
+          "url": "https://files.pythonhosted.org/packages/b6/23/2a1b231b8ff672b4c450dac27164a8b2ca7d9b7144f9c02d2396518352eb/numpy-2.3.5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
+          "sha256": "0d8163f43acde9a73c2a33605353a4f1bc4798745a8b1d73183b28e5b435ae28"
+        },
+        {
+          "url": "https://files.pythonhosted.org/packages/3d/fe/89d77e424365280b79d99b3e1e7d606f5165af2f2ecfaf0c6d24c799d607/pandas-3.0.1-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl",
+          "sha256": "532527a701281b9dd371e2f582ed9094f4c12dd9ffb82c0c54ee28d8ac9520c4"
+        },
+        {
+          "url": "https://files.pythonhosted.org/packages/84/21/a35af28dcc61f37ed850a2d64c65c701321dfbf25085e469d5559360cbbf/pillow-12.3.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
+          "sha256": "78cb2c6865a35ab8ff8b75fd122f6033b92a62c82801110e48ddd6c936a45d91"
+        },
+        {
+          "url": "https://files.pythonhosted.org/packages/db/36/aa413bc214dc4f785ad2b2ddd8cc99aae7062d49ab155e91e6011af00daf/lxml-6.1.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl",
+          "sha256": "379f8a75cf6eb7eef0af074b55f49ab73b868388a98de14646abcdfa4564bb11"
+        }
+      ]
+    },
+    "linux-arm64": {
+      "nodeArchive": "linux-arm64.tar.gz",
+      "nodeSha256": "724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5",
+      "pythonTarget": "aarch64-unknown-linux-gnu",
+      "pythonSha256": "577b4bec0793ad1ff0cbff9adbd0df078eddde38a4c41bf5d83ad381a85ee39d",
+      "wheels": [
+        {
+          "url": "https://files.pythonhosted.org/packages/74/78/fcd41e5a0ce4f3f7b003da85825acddae6d7ecb60cf25194741b036ca7d6/numpy-2.3.5-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl",
+          "sha256": "8b973c57ff8e184109db042c842423ff4f60446239bd585a5131cc47f06f789d"
+        },
+        {
+          "url": "https://files.pythonhosted.org/packages/d7/39/327802e0b6d693182403c144edacbc27eb82907b57062f23ef5a4c4a5ea7/pandas-3.0.1-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl",
+          "sha256": "b8e36891080b87823aff3640c78649b91b8ff6eea3c0d70aeabd72ea43ab069b"
+        },
+        {
+          "url": "https://files.pythonhosted.org/packages/25/27/ac8f99618ffd3dde21db0f4d4b1d2ab00c0880595bfd17df103f7f39fd0c/pillow-12.3.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl",
+          "sha256": "d9c7f76c0673154f044e9d78c8655fb4213f6ca31a836df48b40fe5d187717b9"
+        },
+        {
+          "url": "https://files.pythonhosted.org/packages/1e/1c/722e88883173097a1a375153e3c2447eba3060d0231522cf6596e99f4195/lxml-6.1.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl",
+          "sha256": "f683dc6300317700025e41d89a43e0276692ded16113a3c43eab704d605c58e5"
+        }
+      ]
     }
   },
   "wheels": [
diff --git a/scripts/primary-runtime/prepare.spec.ts b/scripts/primary-runtime/prepare.spec.ts
new file mode 100644
index 0000000000..6f41ac46b4
--- /dev/null
+++ b/scripts/primary-runtime/prepare.spec.ts
@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { zipSync } from 'fflate'
+import { expect, it } from 'vitest'
+import { downloadPrimaryRuntimeAsset, prepareOfficeSkillAssets, primaryRuntimePayloadDigest, smokePrimaryRuntime, unpackPrimaryRuntimeWheel } from './prepare.ts'
+import lock from './lock.json' with { type: 'json' }
+
+it('covers every SDK wheel target with the shared interpreter lock', () => {
+  const platforms = JSON.parse(readFileSync(new URL('../../python/sdk-runtime/platforms.json', import.meta.url), 'utf8')) as Record<string, unknown>
+  expect(Object.keys(lock.targets).sort()).toEqual(Object.keys(platforms).map(target => target.replace('macos-', 'mac-')).sort())
+})
+
+const libraryWheel = Buffer.from('UEsDBAoAAAAAAASeLl0sYMPjDAAAAAwAAAAJAAAAc2FtcGxlLnB5c2FtcGxlID0gNDIKUEsBAh4DCgAAAAAABJ4uXSxgw+MMAAAADAAAAAkAAAAAAAAAAQAAAKSBAAAAAHNhbXBsZS5weVBLBQYAAAAAAQABADcAAAAzAAAAAAA=', 'base64')
+const relocatedWheel = Buffer.from('UEsDBAoAAAAAAASeLl3x0Nj9FAAAABQAAAAeAAAAc2FtcGxlLTEuMC5kYXRhL3NjcmlwdHMvc2FtcGxlcmVxdWlyZXMgcmVsb2NhdGlvbgpQSwECHgMKAAAAAAAEni5d8dDY/RQAAAAUAAAAHgAAAAAAAAABAAAApIEAAAAAc2FtcGxlLTEuMC5kYXRhL3NjcmlwdHMvc2FtcGxlUEsFBgAAAAABAAEATAAAAFAAAAAAAA==', 'base64')
+const externalLibraryWheel = Buffer.from('UEsDBBQAAAAAAAAAIVyBOE8OHAAAABwAAAAhAAAAc2FtcGxlLTEuMC5kYXRhL3B1cmVsaWIvc2FtcGxlLnB5cmVxdWlyZXMgbGlicmFyeSByZWxvY2F0aW9uClBLAQIUAxQAAAAAAAAAIVyBOE8OHAAAABwAAAAhAAAAAAAAAAAAAACAAQAAAABzYW1wbGUtMS4wLmRhdGEvcHVyZWxpYi9zYW1wbGUucHlQSwUGAAAAAAEAAQBPAAAAWwAAAAAA', 'base64')
+
+it.each(Object.entries(lock.targets))('records every locked wheel distribution and version for %s', (_target, artifact) => {
+  const normalize = (name: string): string => name.toLowerCase().replace(/[-_.]+/gu, '-')
+  const distributions = [...artifact.wheels, ...lock.wheels].map(({ url }) => {
+    const [name, version] = basename(new URL(url).pathname).split('-')
+    return [normalize(name!), version] as const
+  })
+  const declared = Object.entries(lock.pythonPackages).map(([name, version]) => [normalize(name), version] as const)
+  expect(new Set(distributions.map(([name]) => name)).size).toBe(distributions.length)
+  expect(new Set(declared.map(([name]) => name)).size).toBe(declared.length)
+  expect(Object.fromEntries(distributions)).toEqual(Object.fromEntries(declared))
+})
+
+it('keeps a target payload identity independent of other target archives', () => {
+  const changed = structuredClone(lock)
+  changed.targets['win-x64'].wheels[0]!.sha256 = 'a'.repeat(64)
+  expect(primaryRuntimePayloadDigest('mac-arm64', changed, '11.7.0')).toBe(primaryRuntimePayloadDigest('mac-arm64', lock, '11.7.0'))
+  expect(primaryRuntimePayloadDigest('win-x64', changed, '11.7.0')).not.toBe(primaryRuntimePayloadDigest('win-x64', lock, '11.7.0'))
+})
+
+it('invalidates payload identity for shared wheels, package versions and package-manager changes', () => {
+  const wheel = structuredClone(lock), distribution = structuredClone(lock)
+  wheel.wheels[0]!.sha256 = 'a'.repeat(64)
+  distribution.pythonPackages['python-docx'] = '1.2.1'
+  const original = primaryRuntimePayloadDigest('mac-arm64', lock, '11.7.0')
+  expect(primaryRuntimePayloadDigest('mac-arm64', wheel, '11.7.0')).not.toBe(original)
+  expect(primaryRuntimePayloadDigest('mac-arm64', distribution, '11.7.0')).not.toBe(original)
+  expect(primaryRuntimePayloadDigest('mac-arm64', lock, '11.7.1')).not.toBe(original)
+})
+
+it('reports missing distribution metadata before trying to execute a stale native payload', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-stale-runtime-'))
+  try {
+    await writeFile(join(root, 'runtime.json'), JSON.stringify({ desktopVersion: '1.0.0', platform: process.platform, arch: process.arch,
+      components: { python: '3.12.14', numpy: '2.3.5', pandas: '3.0.1' } }))
+    expect(() => { smokePrimaryRuntime(root) }).toThrow('missing Python distribution versions; prepare the payload')
+  } finally { await rm(root, { recursive: true, force: true }) }
+})
+
+it('extracts a hash-verified cached library without a Python installer or network request', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-wheel-'))
+  try {
+    const hash = createHash('sha256').update(libraryWheel).digest('hex')
+    const archive = join(root, hash)
+    await writeFile(archive, libraryWheel)
+    expect(await downloadPrimaryRuntimeAsset('https://unused.invalid/library.whl', hash, root)).toBe(archive)
+    await unpackPrimaryRuntimeWheel(archive, join(root, 'site-packages'))
+    expect(await readFile(join(root, 'site-packages/sample.py'), 'utf8')).toBe('sample = 42\n')
+    await writeFile(archive, 'corrupt archive')
+    await expect(downloadPrimaryRuntimeAsset('https://unused.invalid/library.whl', hash, root)).rejects.toThrow('checksum mismatch')
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+it('fully extracts a large deflate-compressed wheel entry', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-large-wheel-'))
+  try {
+    const expected = Buffer.alloc(1024 * 1024)
+    // Seeded xorshift bytes keep the compressed entry larger than the stream buffers.
+    let state = 26
+    for (let index = 0; index < expected.length; index++) {
+      state ^= state << 13
+      state ^= state >>> 17
+      state ^= state << 5
+      expected[index] = state & 255
+    }
+    const archive = join(root, 'large.whl')
+    await writeFile(archive, zipSync({ 'large.bin': expected }, { level: 6 }))
+    await unpackPrimaryRuntimeWheel(archive, root)
+    expect(await readFile(join(root, 'large.bin'))).toEqual(expected)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+it('retains auxiliary wheel scripts without generating command wrappers', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-wheel-'))
+  try {
+    const archive = join(root, 'relocated.whl')
+    await writeFile(archive, relocatedWheel)
+    await unpackPrimaryRuntimeWheel(archive, join(root, 'site-packages'))
+    expect(await readFile(join(root, 'site-packages/sample-1.0.data/scripts/sample'), 'utf8')).toBe('requires relocation\n')
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+it('rejects library files requiring an unsupported installation scheme', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-wheel-'))
+  try {
+    const archive = join(root, 'relocated.whl')
+    await writeFile(archive, externalLibraryWheel)
+    await expect(unpackPrimaryRuntimeWheel(archive, join(root, 'site-packages'))).rejects.toThrow('unsupported installation paths')
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+it('copies complete Office resources outside the application archive and removes obsolete assets', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'desktop-office-assets-'))
+  try {
+    const source = join(root, 'package', 'assets')
+    const destination = join(root, 'Contents', 'Resources', 'runtime', 'office-skills')
+    await mkdir(join(source, 'scripts'), { recursive: true })
+    await writeFile(join(source, 'scripts', 'check_office.py'), 'print("checker")\n')
+    for (const name of ['office-docx', 'office-pptx', 'office-xlsx']) {
+      await mkdir(join(source, name))
+      await writeFile(join(source, name, 'SKILL.md'), `# ${name}\n`)
+    }
+    await prepareOfficeSkillAssets(source, destination)
+    await writeFile(join(destination, 'obsolete.py'), 'old helper')
+    await prepareOfficeSkillAssets(source, destination)
+    for (const name of ['office-docx', 'office-pptx', 'office-xlsx']) {
+      expect(await readFile(join(destination, name, 'SKILL.md'), 'utf8')).toBe(`# ${name}\n`)
+    }
+    expect(await readFile(join(destination, 'scripts', 'check_office.py'), 'utf8')).toBe('print("checker")\n')
+    await expect(readFile(join(destination, 'obsolete.py'))).rejects.toMatchObject({ code: 'ENOENT' })
+  } finally { await rm(root, { recursive: true, force: true }) }
+})
+
+it('gives Python-only payloads a distinct identity', () => {
+  expect(primaryRuntimePayloadDigest('linux-x64', lock, undefined)).not.toBe(primaryRuntimePayloadDigest('linux-x64', lock, '11.7.0'))
+})
+
+it('keeps carrier pnpm versions aligned with the shared payload build', () => {
+  const root = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as {
+    packageManager: string
+    devDependencies: { pnpm: string }
+  }
+  const desktop = JSON.parse(readFileSync(new URL('../../apps/desktop/package.json', import.meta.url), 'utf8')) as {
+    devDependencies: { pnpm: string }
+  }
+  expect(desktop.devDependencies.pnpm).toBe(root.devDependencies.pnpm)
+  expect(root.packageManager).toBe(`pnpm@${root.devDependencies.pnpm}`)
+})
diff --git a/scripts/primary-runtime/prepare.ts b/scripts/primary-runtime/prepare.ts
new file mode 100644
index 0000000000..a156a7564a
--- /dev/null
+++ b/scripts/primary-runtime/prepare.ts
@@ -0,0 +1,207 @@
+/** Prepare pinned, relocatable script interpreters without installing into the build host. */
+
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { cp } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import extractZip from 'extract-zip'
+import { x as extractTar } from 'tar'
+import { parsePrimaryRuntime, workspaceDependencyPaths, type PrimaryRuntimeManifest } from '../../packages/skill/tool-workspace-dependencies/src/index.ts'
+import lock from './lock.json' with { type: 'json' }
+
+/**
+ * Download or reuse an archive only when its bytes match the release lock.
+ * @param url - Locked archive URL.
+ * @param sha256 - Expected SHA-256 digest.
+ * @param cache - Download cache directory.
+ * @returns Verified local archive path.
+ */
+export async function downloadPrimaryRuntimeAsset(url: string, sha256: string, cache: string): Promise<string> {
+  const destination = join(cache, sha256)
+  let bytes: Buffer
+  try { bytes = readFileSync(destination) } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    const response = await fetch(url)
+    if (!response.ok) throw new Error(`primary runtime download: ${String(response.status)} ${url}`)
+    bytes = Buffer.from(await response.arrayBuffer())
+  }
+  if (createHash('sha256').update(bytes).digest('hex') !== sha256) throw new Error(`primary runtime download: checksum mismatch for ${url}`)
+  writeFileSync(destination, bytes)
+  return destination
+}
+
+async function pythonArchive(target: keyof typeof lock.targets, cache: string): Promise<string> {
+  const artifact = lock.targets[target]
+  const filename = `cpython-${lock.pythonVersion}+${lock.pythonRelease}-${artifact.pythonTarget}-install_only_stripped.tar.gz`
+  return downloadPrimaryRuntimeAsset(`https://github.com/astral-sh/python-build-standalone/releases/download/${lock.pythonRelease}/${encodeURIComponent(filename)}`, artifact.pythonSha256, cache)
+}
+
+/**
+ * Identify the inputs that assemble one target's payload, excluding unrelated target locks.
+ * @param target - Runtime target whose archives are installed.
+ * @param runtimeLock - Locked interpreter and wheel inputs.
+ * @param pnpmVersion - Package-manager version copied into the payload.
+ * @returns SHA-256 payload identity for installation reuse.
+ */
+export function primaryRuntimePayloadDigest(
+  target: keyof typeof lock.targets, runtimeLock: typeof lock, pnpmVersion: string | undefined,
+): string {
+  const { pythonVersion, pythonRelease, nodeVersion, wheels, pythonPackages } = runtimeLock
+  // Identity preserves key order within the selected target, wheel records and distribution map, plus wheel-entry order.
+  // Bump format when extraction or assembly changes payload bytes without changing locked inputs.
+  return createHash('sha256').update(JSON.stringify({
+    format: 4, target, pythonVersion, pythonRelease, nodeVersion: pnpmVersion === undefined ? undefined : nodeVersion,
+    artifact: runtimeLock.targets[target], wheels, pythonPackages, pnpm: pnpmVersion,
+  })).digest('hex')
+}
+
+/**
+ * Unpack a locked library wheel, retaining auxiliary scripts in its distribution data directory.
+ * @param archive - Hash-verified wheel archive.
+ * @param destination - Absolute site-packages directory.
+ * @returns Resolves after extraction without command wrappers; rejects other wheel installation schemes.
+ */
+export async function unpackPrimaryRuntimeWheel(archive: string, destination: string): Promise<void> {
+  await extractZip(archive, {
+    dir: destination,
+    onEntry: (entry) => {
+      const [directory, scheme] = entry.fileName.split('/')
+      if (directory?.endsWith('.data') && scheme !== '' && scheme !== 'scripts') {
+        throw new Error(`primary runtime: wheel requires unsupported installation paths: ${entry.fileName}`)
+      }
+    },
+  })
+}
+
+/**
+ * Copy the skill package's complete asset tree to ordinary filesystem resources.
+ * @param source - The package's assets directory.
+ * @param destination - External Office skill resource directory.
+ * @returns Resolves after replacing the external assets with the complete package tree.
+ */
+export async function prepareOfficeSkillAssets(source: string, destination: string): Promise<void> {
+  rmSync(destination, { recursive: true, force: true })
+  await cp(source, destination, { recursive: true, dereference: true })
+}
+
+/** A locked interpreter and wheel target. */
+export type PrimaryRuntimeTarget = keyof typeof lock.targets
+
+/** Build-only inputs shared by Desktop and SDK carriers. */
+export interface PreparePrimaryRuntimeOptions {
+  /** Target whose archives and wheels are downloaded. */
+  readonly target: PrimaryRuntimeTarget
+  /** Resource directory receiving primary-runtime/ and office-skills/. */
+  readonly output: string
+  /** SHA-256-addressed archive cache. */
+  readonly cache: string
+  /** Carrier release recorded in the legacy desktopVersion manifest field. */
+  readonly version: string
+  /** Omit Node.js and pnpm for carriers providing only Python. */
+  readonly pythonOnly?: boolean
+}
+
+/**
+ * Materialize locked interpreters, libraries and Office resources without executing target code.
+ * @param options - Explicit target and carrier-owned output locations.
+ * @returns Resolves after the complete payload and skills have been copied to the output directory.
+ */
+export async function preparePrimaryRuntime(options: PreparePrimaryRuntimeOptions): Promise<void> {
+  const { target } = options
+  const paths = { runtime: resolve(options.output), downloads: resolve(options.cache) }
+  const artifact = lock.targets[target]
+  mkdirSync(paths.runtime, { recursive: true })
+  mkdirSync(paths.downloads, { recursive: true })
+  const staging = mkdtempSync(join(tmpdir(), 'dsh-primary-'))
+  try {
+    const output = join(staging, 'payload')
+    const dependencies = join(output, 'dependencies')
+    mkdirSync(dependencies, { recursive: true })
+    let pnpmVersion: string | undefined
+    if (!options.pythonOnly) {
+      const nodeFilename = `node-v${lock.nodeVersion}-${artifact.nodeArchive}`
+      const nodeArchive = await downloadPrimaryRuntimeAsset(`https://nodejs.org/dist/v${lock.nodeVersion}/${nodeFilename}`, artifact.nodeSha256, paths.downloads)
+      const unpackedNode = join(staging, 'node')
+      mkdirSync(unpackedNode)
+      if (target === 'win-x64') await extractZip(nodeArchive, { dir: unpackedNode })
+      else await extractTar({ file: nodeArchive, cwd: unpackedNode })
+      const nodeSource = join(unpackedNode, nodeFilename.replace(/\.(?:zip|tar\.gz)$/u, ''))
+      mkdirSync(join(dependencies, 'node', 'bin'), { recursive: true })
+      mkdirSync(join(dependencies, 'node', 'node_modules'))
+      writeFileSync(join(dependencies, 'node', 'node_modules', 'README.txt'), 'Reserved for bundled Node packages. pnpm uses its default installation directories.\n')
+      cpSync(join(nodeSource, ...(target === 'win-x64' ? ['node.exe'] : ['bin', 'node'])),
+        join(dependencies, 'node', 'bin', target === 'win-x64' ? 'node.exe' : 'node'))
+      cpSync(join(nodeSource, 'LICENSE'), join(dependencies, 'node', 'LICENSE'))
+      const require = createRequire(import.meta.url)
+      const pnpmManifest = require.resolve('pnpm')
+      pnpmVersion = (JSON.parse(readFileSync(pnpmManifest, 'utf8')) as { version: string }).version
+      await cp(dirname(pnpmManifest), join(dependencies, 'pnpm'), { recursive: true, dereference: true })
+    }
+    await extractTar({ file: await pythonArchive(target, paths.downloads), cwd: dependencies })
+    const manifest: PrimaryRuntimeManifest = {
+      desktopVersion: options.version,
+      platform: target === 'win-x64' ? 'win32' : target.startsWith('linux-') ? 'linux' : 'darwin',
+      arch: target.endsWith('-arm64') ? 'arm64' : 'x64',
+      payloadDigest: primaryRuntimePayloadDigest(target, lock, pnpmVersion),
+      python: lock.pythonVersion,
+      ...(pnpmVersion === undefined ? {} : { node: lock.nodeVersion, pnpm: pnpmVersion }),
+      pythonPackages: lock.pythonPackages,
+    }
+    const entries = workspaceDependencyPaths(output, manifest)
+    for (const wheel of [...artifact.wheels, ...lock.wheels]) {
+      await unpackPrimaryRuntimeWheel(await downloadPrimaryRuntimeAsset(wheel.url, wheel.sha256, paths.downloads), entries.pythonPackages)
+    }
+    writeFileSync(join(output, 'runtime.json'), `${JSON.stringify(manifest, undefined, 2)}\n`)
+    const destination = join(paths.runtime, 'primary-runtime')
+    rmSync(destination, { recursive: true, force: true })
+    await cp(output, destination, { recursive: true, dereference: true })
+  } finally {
+    rmSync(staging, { recursive: true, force: true })
+  }
+  const require = createRequire(import.meta.url)
+  await prepareOfficeSkillAssets(join(dirname(require.resolve('@deepseek-ai/dsh-skill-office/package.json')), 'assets'),
+    join(paths.runtime, 'office-skills'))
+}
+
+/**
+ * Execute the native payload's interpreters, package manager and Python libraries.
+ * @param root - Final payload directory, including any platform signatures.
+ * @param environment - Scrubbed subprocess environment; defaults to excluding credential-shaped names.
+ */
+export function smokePrimaryRuntime(root: string, environment: NodeJS.ProcessEnv = Object.fromEntries(
+  Object.entries(process.env).filter(([name]) => !/(?:KEY|SECRET|TOKEN|PASSWORD)/iu.test(name)),
+)): void {
+  const manifest = parsePrimaryRuntime(JSON.parse(readFileSync(join(root, 'runtime.json'), 'utf8')))
+  if (manifest.platform !== process.platform || manifest.arch !== process.arch) return
+  if (Object.keys(manifest.pythonPackages).length === 0) throw new Error('primary runtime: missing Python distribution versions; prepare the payload before running its smoke checks.')
+  const entries = workspaceDependencyPaths(root, manifest)
+  const options = { stdio: 'inherit', timeout: 120_000, env: environment } as const
+  execFileSync(entries.python, ['-I', '-B', '-c', 'import decimal, xml.parsers.expat, lzma, uuid, numpy, pandas; assert numpy.arange(4).sum() == 6; assert pandas.DataFrame({"n": [1, 2]}).n.sum() == 3'], options)
+  execFileSync(entries.python, ['-I', '-B', join(import.meta.dirname, 'smoke.py'), JSON.stringify(manifest.pythonPackages),
+    manifest.python, join(dirname(root), 'office-skills', 'scripts', 'check_office.py')], options)
+  execFileSync(entries.python, ['-I', '-B', '-m', 'pip', 'check'], options)
+  if (entries.node !== undefined) execFileSync(entries.node, ['-e', `if (process.versions.node !== ${JSON.stringify(manifest.node)}) process.exit(1)`], options)
+  if (entries.pnpm !== undefined && entries.node !== undefined) execFileSync(entries.node, [entries.pnpm, '--version'], options)
+}
+
+if (import.meta.main) {
+  const { values } = parseArgs({ options: {
+    target: { type: 'string' }, output: { type: 'string' }, cache: { type: 'string' },
+    'python-only': { type: 'boolean', default: false },
+  } })
+  if (!values.target || !Object.hasOwn(lock.targets, values.target) || !values.output) {
+    throw new Error(`Usage: pnpm run prepare:primary-runtime --target <${Object.keys(lock.targets).join('|')}> --output <directory> [--cache <directory>] [--python-only]`)
+  }
+  const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version: string }
+  const output = resolve(values.output)
+  await preparePrimaryRuntime({
+    target: values.target as PrimaryRuntimeTarget, output,
+    cache: values.cache ?? join(tmpdir(), 'dsh-primary-runtime-downloads'), version,
+    pythonOnly: values['python-only'],
+  })
+  smokePrimaryRuntime(join(output, 'primary-runtime'))
+}
diff --git a/apps/desktop/scripts/smoke-primary-runtime.py b/scripts/primary-runtime/smoke.py
similarity index 100%
rename from apps/desktop/scripts/smoke-primary-runtime.py
rename to scripts/primary-runtime/smoke.py
diff --git a/scripts/rescope-vendor.ts b/scripts/rescope-vendor.ts
index 63d887a098..dd281965df 100644
--- a/scripts/rescope-vendor.ts
+++ b/scripts/rescope-vendor.ts
@@ -78,6 +78,8 @@ interface GenericSkip {
 const GENERIC_SKIPS: readonly GenericSkip[] = [
   // `Symbol.for('schemastery')` and the `vendor:` metadata field are upstream identifiers.
   { file: 'vendor/schemastery/src/index.ts', upstream: ['schemastery'] },
+  // Narrows a Standard Schema by the same upstream `vendor:` identifier.
+  { file: 'vendor/loader/src/config/diff.ts', upstream: ['schemastery'] },
   // Asserts the vendored-manifest table, which gains an upstream-name column.
   { file: 'scripts/gen-third-party-notices.spec.ts', upstream: RENAMES.map(rename => rename.upstream) },
   // `cordis` is also an agent-preset id — the directory name under
@@ -172,6 +174,13 @@ const POSTCONDITIONS: readonly PostCondition[] = [
  * quote a neighbouring line the generic pass would rewrite.
  */
 const EXACT_EDITS: readonly ExactEdit[] = [
+  {
+    id: 'loader-diff-schemastery-import',
+    file: 'vendor/loader/src/config/diff.ts',
+    find: "import type Schema from 'schemastery'",
+    replace: "import type Schema from '@deepseek-ai/schemastery'",
+    expect: 1,
+  },
   {
     id: 'cordis-walk-merge-head',
     file: 'scripts/cordis-walk.ts',
diff --git a/scripts/session-snapshot-corpus-policy.spec.ts b/scripts/session-snapshot-corpus-policy.spec.ts
index d1f317db33..0cfe2231b7 100644
--- a/scripts/session-snapshot-corpus-policy.spec.ts
+++ b/scripts/session-snapshot-corpus-policy.spec.ts
@@ -111,12 +111,14 @@ describe('recorded-session corpus policy', () => {
   )
 
   it('bounds explicitly retained roles and requires a baseline/current majority', () => {
+    expect(assertSnapshotCorpusPolicy([
+      baseline, current,
+      { ...completeV0, selectedVersions: Array<number>(9).fill(0) }, ...adjacent,
+    ]).retainedRoles).toBe(11)
     expect(() => assertSnapshotCorpusPolicy([
-      baseline,
-      current,
-      { ...completeV0, selectedVersions: Array<number>(11).fill(0) },
-      ...adjacent,
-    ])).toThrow(`Session corpus retains ${11 + adjacent.length} historical roles; maximum is 10`)
+      baseline, current,
+      { ...completeV0, selectedVersions: Array<number>(10).fill(0) }, ...adjacent,
+    ])).toThrow('Session corpus retains 12 historical roles; maximum is 11')
     expect(() => assertSnapshotCorpusPolicy([
       { ...baseline, selectedVersions: [3] }, completeV0, ...adjacent,
     ])).toThrow(`Session corpus requires a baseline/current majority; baseline=1, current=0, retained=${1 + adjacent.length}`)
diff --git a/scripts/session-snapshot-corpus-policy.ts b/scripts/session-snapshot-corpus-policy.ts
index e10e35506a..0f3b911c4e 100644
--- a/scripts/session-snapshot-corpus-policy.ts
+++ b/scripts/session-snapshot-corpus-policy.ts
@@ -22,7 +22,7 @@ export interface SnapshotCorpusGenerationSummary {
 }
 
 const RETAINED_BASELINE_VERSION = 3
-const MAX_RETAINED_ROLES = 10
+const MAX_RETAINED_ROLES = 11
 const REQUIRED_V0_COVERAGE = new Set([
   'multi-hop',
   'packed-row',
diff --git a/scripts/session-snapshot-corpus.corpus.ts b/scripts/session-snapshot-corpus.corpus.ts
index efa995e839..54d4124ad4 100644
--- a/scripts/session-snapshot-corpus.corpus.ts
+++ b/scripts/session-snapshot-corpus.corpus.ts
@@ -204,7 +204,7 @@ it('keeps V3 replay input plus bounded declared historical migration coverage',
   const summary = assertSnapshotCorpusPolicy(inventory)
   expect(summary.baselineRoles).toBeGreaterThan(0)
   expect(summary).toMatchObject({
-    retainedRoles: 10,
+    retainedRoles: 11,
     retainedScenarios: 8,
   })
 })
diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py
index 7e540f7ef7..d97a733954 100644
--- a/scripts/smoke-python-runtime.py
+++ b/scripts/smoke-python-runtime.py
@@ -44,6 +44,7 @@ MCP_TEXT = "MCP client smoke ok"
 PROFILE_PLUGIN_PROMPT = "Verify the Python-installed dsh profile plugin."
 PROFILE_PLUGIN_TEXT = "profile plugin smoke ok"
 PROFILE_PLUGIN_MARKER = "PYTHON_INSTALLED_DSH_PROFILE_PLUGIN"
+AUTHORING_PROMPT = "Query the packaged Python environment for Office authoring."
 IS_WINDOWS = sys.platform == "win32"
 MINIMAL_SHELL_TOOL = "pwsh" if IS_WINDOWS else "bash"
 MINIMAL_SHELL_COMMAND = (
@@ -77,6 +78,8 @@ LEGACY_CUSTOM_DISABLED_ROWS = (
     "plan-mode",
     "skill",
     "skill-filesystem",
+    "skill-office",
+    "workspace-dependencies",
     "tool-fs",
     "tool-fs-search",
     "tool-goal",
@@ -315,6 +318,10 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
         result = tool_results[-1]
         call_id, tool_name = latest_tool_call(messages, result.get("tool_use_id"))
         tool_text = message_text(result.get("content"))
+        if tool_name == "load_workspace_dependencies":
+            if result.get("is_error") or "python" not in json.loads(tool_text):
+                raise AssertionError(f"packaged Python query failed: {tool_text}")
+            return text_chunks(EXPECTED_TEXT)
         mcp = mcp_tool_followup(call_id, tool_name, tool_text)
         if mcp is not None:
             return mcp
@@ -366,6 +373,7 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
         RESTART_FIRST_PROMPT,
         RESTART_SECOND_PROMPT,
         PROFILE_PLUGIN_PROMPT,
+        AUTHORING_PROMPT,
     }
     prompt = next(
         (candidate for candidate in user_prompts if candidate in scenario_prompts),
@@ -373,6 +381,9 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
     )
     if prompt == SNAPSHOT_DIRECT_CHILD_PROMPT:
         return text_chunks("DIRECT_CHILD_OK")
+    if prompt == AUTHORING_PROMPT:
+        assert_advertised_tool(body, "load_workspace_dependencies")
+        return tool_call_chunks("authoring-runtime", "load_workspace_dependencies", {})
     if prompt == SNAPSHOT_WORKFLOW_CHILD_PROMPT:
         return text_chunks("WORKFLOW_CHILD_OK")
     if prompt == SNAPSHOT_PROMPT:
@@ -709,7 +720,7 @@ def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
         "--scenario",
-        choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-mcp", "sdk-snapshot", "sdk-restart", "sdk-profile-plugin", "sdk-office", "sdk-live", "runner", "direct"),
+        choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-mcp", "sdk-snapshot", "sdk-restart", "sdk-profile-plugin", "sdk-office", "sdk-authoring", "sdk-live", "runner", "direct"),
         default="all",
     )
     parser.add_argument("--exe", type=Path)
@@ -728,10 +739,10 @@ def main() -> None:
         parser.error("--scenario sdk-profile-plugin requires --installed-wheel")
     if args.installed_wheel:
         args.exe = assert_installed_wheel_environment()
-    if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-snapshot", "sdk-restart", "sdk-office", "runner", "direct"} and args.exe is None:
+    if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-minimal-in-history", "sdk-fs-search", "sdk-spawn-node", "sdk-snapshot", "sdk-restart", "sdk-office", "sdk-authoring", "runner", "direct"} and args.exe is None:
         parser.error("--exe is required for custom, minimal, fs-search, spawn-node, snapshot, restart, office, runner, and direct scenarios")
-    if args.update_snapshots and args.scenario not in {"all", "sdk-minimal", "sdk-minimal-in-history", "sdk-snapshot", "sdk-restart"}:
-        parser.error("--update-snapshots requires --scenario sdk-minimal, sdk-minimal-in-history, sdk-snapshot, sdk-restart, or all")
+    if args.update_snapshots and args.scenario not in {"all", "sdk-minimal", "sdk-minimal-in-history", "sdk-snapshot", "sdk-restart", "sdk-authoring"}:
+        parser.error("--update-snapshots requires --scenario sdk-minimal, sdk-minimal-in-history, sdk-snapshot, sdk-restart, sdk-authoring, or all")
     if args.exe is not None and not args.exe.is_file():
         parser.error(f"runtime executable does not exist: {args.exe}")
 
@@ -755,6 +766,9 @@ def main() -> None:
         return
 
     with MockModel() as model:
+        if args.scenario in {"all", "sdk-authoring"}:
+            assert args.exe is not None
+            smoke_sdk_authoring(model.url, args.exe.resolve(), args.update_snapshots)
         if args.scenario in {"all", "sdk-default"}:
             smoke_sdk_default(model.url)
         if args.scenario in {"all", "sdk-custom"}:
@@ -790,6 +804,65 @@ def main() -> None:
     print(f"smoke-python-runtime: {args.scenario} passed")
 
 
+def smoke_sdk_authoring(base_url: str, executable: Path, update_snapshots: bool) -> None:
+    """Query the bundled Python and switch skills without replacing that environment."""
+    from deepseek_harness import DeepSeekHarness
+
+    resources = executable.with_name(executable.name.removeprefix("deepseek-harness-sdk-runtime-").removesuffix(".exe"))
+    manifest = json.loads((resources / "primary-runtime/runtime.json").read_text())
+    for mode in ("default", "replacement", "disabled"):
+        with tempfile.TemporaryDirectory(prefix="dsh-sdk-authoring-") as temporary:
+            root = Path(temporary).resolve()
+            home = root / "home"
+            if mode == "replacement":
+                skill = home / "skills/office-docx/SKILL.md"
+                skill.parent.mkdir(parents=True)
+                skill.write_text("---\nname: office-docx\ndescription: CUSTOM_OFFICE_DOCX\n---\nUse the bundled Python for custom document work.\n")
+            patch = root / "skills.patch.yml"
+            patch.write_text(json.dumps([{"id": "skill-office", "disabled": True}] if mode == "disabled" else []))
+            first = len(MockModelHandler.requests)
+            with DeepSeekHarness(
+                provider="deepseek-official", model="smoke-model", cwd=str(root),
+                dsh_bin=str(executable), dsh_home=str(home), patches=(str(patch),),
+                api_key="sk-keyless-smoke", base_url=base_url,
+                env={"DSH_PERMISSION_MODE": "danger-full-access", "DSH_TELEMETRY_DISABLED": "1"},
+                request_timeout_seconds=60,
+            ) as harness:
+                result = harness.run(AUTHORING_PROMPT, session_id="authoring")
+            assert result.final_response == EXPECTED_TEXT, result.final_response
+            requests = MockModelHandler.requests[first:]
+            assert len(requests) == 2, requests
+            prompt = json.dumps(requests[0], ensure_ascii=False)
+            for name in ("office-docx", "office-pptx", "office-xlsx"):
+                assert (name in prompt) == (mode != "disabled"), (mode, name)
+            assert ("CUSTOM_OFFICE_DOCX" in prompt) == (mode == "replacement"), mode
+            tool_result = next(block for message in requests[1]["messages"]
+                               for block in message.get("content", [])
+                               if isinstance(block, dict) and block.get("tool_use_id") == "authoring-runtime")
+            dependencies = json.loads(message_text(tool_result["content"]))
+            python = Path(dependencies["python"])
+            assert python.is_relative_to(resources), dependencies
+            assert "node" not in dependencies and "pnpm" not in dependencies, dependencies
+            assert dependencies["pythonDistributions"] == manifest["pythonPackages"], dependencies
+            assert not (home / "dsh-runtimes").exists()
+            if mode == "default":
+                subprocess.run([
+                    str(python), "-I", "-B", str(Path(__file__).parent / "primary-runtime/smoke.py"),
+                    json.dumps(manifest["pythonPackages"]), manifest["python"],
+                    str(resources / "office-skills/scripts/check_office.py"),
+                ], check=True, timeout=120,
+                    env={name: value for name, value in os.environ.items()
+                         if not re.search(r"KEY|SECRET|TOKEN|PASSWORD", name, re.I)})
+                schema = next(tool for tool in requests[0]["tools"] if tool.get("name") == "load_workspace_dependencies")
+                visible = {"tool": schema, "result": {**dependencies, "python": "{{python}}", "pythonPackages": "{{site-packages}}"}}
+                compare_snapshot_files(
+                    {"model-visible.json": json.dumps(visible, indent=2, ensure_ascii=False) + "\n"},
+                    update_snapshots, Path(__file__).parent / "snapshots/python-sdk-single-exe/authoring",
+                    ("model-visible.json",),
+                )
+    print("smoke-python-runtime: bundled Python, default skills, replacement and disabled skills passed")
+
+
 def smoke_sdk_office(executable: Path) -> None:
     """Relocate the wheel payload and convert a real DOCX with the target platform engine."""
     from deepseek_harness import DeepSeekHarness
@@ -798,7 +871,8 @@ def smoke_sdk_office(executable: Path) -> None:
         root = Path(temporary).resolve()
         relocated = root / executable.name
         stem = executable.name.removesuffix(".exe")
-        for source in executable.parent.glob(f"{stem}*"):
+        resources = executable.with_name(stem.removeprefix("deepseek-harness-sdk-runtime-"))
+        for source in [*executable.parent.glob(f"{stem}*"), resources]:
             destination = root / source.name
             if source.is_dir():
                 shutil.copytree(source, destination)
@@ -843,6 +917,8 @@ def smoke_sdk_office(executable: Path) -> None:
             api_key="sk-keyless-smoke",
             base_url="http://127.0.0.1:9",
             env={"DSH_PERMISSION_MODE": "danger-full-access", "DSH_TELEMETRY_DISABLED": "1"},
+            # The startup plugin awaits a converter with a 120-second deadline before JSON-RPC is ready.
+            initialize_timeout_seconds=180,
             request_timeout_seconds=180,
         ):
             pass
diff --git a/scripts/snapshots/python-sdk-single-exe/authoring/model-visible.json b/scripts/snapshots/python-sdk-single-exe/authoring/model-visible.json
new file mode 100644
index 0000000000..f7fe317a27
--- /dev/null
+++ b/scripts/snapshots/python-sdk-single-exe/authoring/model-visible.json
@@ -0,0 +1,29 @@
+{
+  "tool": {
+    "name": "load_workspace_dependencies",
+    "description": "Get absolute paths to bundled Python and library directories, plus bundled Python distribution versions. Node.js and pnpm paths are included when the payload provides them. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. When Node.js and pnpm paths are returned, run pnpm with that Node executable and pnpm script path. This does not change PATH or package-manager settings.",
+    "input_schema": {
+      "type": "object",
+      "properties": {}
+    }
+  },
+  "result": {
+    "python": "{{python}}",
+    "pythonPackages": "{{site-packages}}",
+    "pythonDistributions": {
+      "numpy": "2.3.5",
+      "pandas": "3.0.1",
+      "python-dateutil": "2.9.0.post0",
+      "six": "1.17.0",
+      "tzdata": "2025.2",
+      "python-docx": "1.2.0",
+      "python-pptx": "1.0.2",
+      "openpyxl": "3.1.5",
+      "Pillow": "12.3.0",
+      "lxml": "6.1.3",
+      "XlsxWriter": "3.2.9",
+      "typing_extensions": "4.16.0",
+      "et_xmlfile": "2.0.0"
+    }
+  }
+}
diff --git a/scripts/snapshots/translation-prompt-v4/request-response.expected.json b/scripts/snapshots/translation-prompt-v4/request-response.expected.json
index 506a8110b5..9d669c2bfd 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 order and semantic 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 repository-relative document link must keep the source link's semantic target and exact query/fragment suffix. When the target belongs to the active bilingual corpus, English output uses its `.md` path and Chinese output uses its `.zh.md` path; a missing counterpart in that corpus is an error, while targets outside it keep the original path. External URLs, images, and pure in-page fragments stay unchanged. Translate link text.\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 | | | 只指受支持的 Python 与 TypeScript SDK 所使用的 JSON-RPC 客户端／服务器协议；DeepSeek Harness 项目本身不是 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| coding agent | coding agent | coding agent（编程智能体） | | agent 组合词，正文保留英文 |\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/shell` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| Service Provider | Service Provider | | Service provider | 能力 seam 的命名角色；单数固定写作 Service Provider，复数写作 Service Providers。泛指提供服务的 provider 不适用本词条 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| job id | job id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| Typert | Typert | | TypeRT、typeRT、Type RT | DeepSeek Harness 类型图、生成器、loader 与运行时 registry 的产品拼写 |\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| binder | 绑定器 | | | 命名角色：把已声明接口绑定到调用方 context 或生命周期 |\n| config | 配置 | | | 命名角色：一个已解析配置值或边界严格的配置记录 |\n| controller | 控制器 | | | 命名角色：接受意图并改变一项既有领域或展示状态 |\n| directory | 目录 | | | 命名角色：暴露供发现或选择的条目及元数据 |\n| engine | 引擎 | | | 命名角色：实现领域算法或有状态执行模型 |\n| gateway | 网关 | | | 命名角色：适配进程、网络、RPC 或 API 边界 |\n| handle | 句柄 | | | 命名角色：引用并控制或观察一个实时资源 |\n| policy | 策略 | | | 命名角色：决定允许、选择、限制或观察什么 |\n| presenter | 展示转换器 | | | 命名角色：把领域值纯转换为渲染意图 |\n| resolver | 解析器 | | | 命名角色：根据输入计算或定位一个答案 |\n| store | 存储 | | | 命名角色：拥有一组数据并主要提供数据操作 |\n| background job | 后台任务 | | | |\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- Do links preserve their semantic targets and exact query/fragment suffixes while using target-locale paths, and are 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 order and semantic 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 repository-relative document link must keep the source link's semantic target and exact query/fragment suffix. When the target belongs to the active bilingual corpus, English output uses its `.md` path and Chinese output uses its `.zh.md` path; a missing counterpart in that corpus is an error, while targets outside it keep the original path. External URLs, images, and pure in-page fragments stay unchanged. Translate link text.\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 | | | 只指受支持的 Python 与 TypeScript SDK 所使用的 JSON-RPC 客户端／服务器协议；DeepSeek Harness 项目本身不是 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| coding agent | coding agent | coding agent（编程智能体） | | agent 组合词，正文保留英文 |\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/shell` 为范例；Service Definition 是 Cordis `Service`（抽象类或具体 registry 服务），不是 TypeScript interface。任何单一角色、普通边界或扩展点都不能称为 seam。本仓库正文保留英文；与 `extension point` 是不同概念 |\n| Service Provider | Service Provider | | Service provider | 能力 seam 的命名角色；单数固定写作 Service Provider，复数写作 Service Providers。泛指提供服务的 provider 不适用本词条 |\n| skill | skill | skill（技能） | | |\n| slot | slot | | 坑位、孔位 | 客户端架构中的具名可注册位置，保留英文 |\n| spill | spill | | | 工具输出超限落盘机制；组合词写 `spill 文件`、`spill 路径` |\n| spawn | spawn | | | |\n| steering | steering | steering（中途引导） | | |\n| job id | job id | | 任务 id | 保留英文 |\n| subagent | subagent | | | |\n| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |\n| Typert | Typert | | TypeRT、typeRT、Type RT | DeepSeek Harness 类型图、生成器、loader 与运行时 registry 的产品拼写 |\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| binder | 绑定器 | | | 命名角色：把已声明接口绑定到调用方 context 或生命周期 |\n| config | 配置 | | | 命名角色：一个已解析配置值或边界严格的配置记录 |\n| controller | 控制器 | | | 命名角色：接受意图并改变一项既有领域或展示状态 |\n| directory | 目录 | | | 命名角色：暴露供发现或选择的条目及元数据 |\n| engine | 引擎 | | | 命名角色：实现领域算法或有状态执行模型 |\n| gateway | 网关 | | | 命名角色：适配进程、网络、RPC 或 API 边界 |\n| handle | 句柄 | | | 命名角色：引用并控制或观察一个实时资源 |\n| policy | 策略 | | | 命名角色：决定允许、选择、限制或观察什么 |\n| presenter | 展示转换器 | | | 命名角色：把领域值纯转换为渲染意图 |\n| resolver | 解析器 | | | 命名角色：根据输入计算或定位一个答案 |\n| store | 存储 | | | 命名角色：拥有一组数据并主要提供数据操作 |\n| background job | 后台任务 | | | |\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 | 模型提供商 | | | 指为模型提供 API 的厂商或网关：模型设置页文案、用户指南 providers 与 `ui-settings-models` README 用「提供商」；llm seam 的开发者文档（可配置提供方目录、dormant 等）沿用「提供方」 |\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 | 提供方 | | | 泛指的提供方（搜索、检查、settings 文件、subagent 等）；模型厂商或网关见 model 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- Do links preserve their semantic targets and exact query/fragment suffixes while using target-locale paths, and are 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",
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
index 54e2fabc81..1c902d3520 100644
--- a/scripts/translation-pairing.spec.ts
+++ b/scripts/translation-pairing.spec.ts
@@ -319,6 +319,8 @@ describe('translation scope discovery', () => {
     '.agents/notes/proposed/feature.md',
     'docs/guide.md',
     'python/guide.md',
+    'python/sdk-runtime/README.md',
+    'python/sdk-runtime/src/deepseek_harness_runtime/README.md',
   ])('includes %s', (file) => {
     expect(isTranslationScopeFile(file)).toBe(true)
   })
@@ -336,6 +338,7 @@ describe('translation scope discovery', () => {
     'coverage/report/README.md',
     'python/sdk-runtime/src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-macos-arm64/README.md',
     'python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/README.md',
+    'python/sdk-runtime/src/deepseek_harness_runtime/runtime/macos-arm64/office-skills/office-docx/SKILL.md',
   ])('excludes non-source or non-README path %s', (file) => {
     expect(isTranslationScopeFile(file)).toBe(false)
   })
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
index e4c0919a2f..917b912c23 100644
--- a/scripts/translation-pairing.ts
+++ b/scripts/translation-pairing.ts
@@ -165,8 +165,7 @@ export const TRANSLATION_SCOPE_GLOB_EXCLUDES = [
   '**/.pytest_cache/**',
   'apps/web/dist/**',
   '.artifacts/**',
-  'python/sdk-runtime/src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*/**',
-  'python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/**',
+  'python/sdk-runtime/src/deepseek_harness_runtime/runtime/**',
   'vendor/**',
 ]
 
@@ -177,8 +176,7 @@ function isTranslationSourceExcluded(file: string): boolean {
       || segment.startsWith('.doc-typecheck-')
     || segment.startsWith('.node-next-types-'))
     || file.startsWith('apps/web/dist/')
-    || file.startsWith('python/sdk-runtime/src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-')
-    || file.startsWith('python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/')
+    || file.startsWith('python/sdk-runtime/src/deepseek_harness_runtime/runtime/')
 }
 
 /** Whether one discovered Markdown or sidecar path belongs to the bilingual source corpus. */
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 5e4807e188..e36b61fbf7 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1069,11 +1069,16 @@
     {
       "doc": "docs/subsystems/jobs.md",
       "symbol": "JobKindMap",
+      "source": "packages/jobs/jobs/src/view.ts"
+    },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobSpec",
       "source": "packages/jobs/jobs/src/types.ts"
     },
     {
       "doc": "docs/subsystems/jobs.md",
-      "symbol": "JobStart",
+      "symbol": "JobHandle",
       "source": "packages/jobs/jobs/src/types.ts"
     },
     {
@@ -1088,14 +1093,44 @@
     },
     {
       "doc": "docs/subsystems/jobs.md",
-      "symbol": "JobSnapshot",
+      "symbol": "JobOutputSource",
       "source": "packages/jobs/jobs/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobSourceRead",
+      "source": "packages/jobs/jobs/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobChunk",
+      "source": "packages/jobs/jobs/src/view.ts"
+    },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobOutputRead",
+      "source": "packages/jobs/jobs/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobView",
+      "source": "packages/jobs/jobs/src/view.ts"
+    },
     {
       "doc": "docs/subsystems/jobs.md",
       "symbol": "JobRead",
       "source": "packages/jobs/jobs/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobEvent",
+      "source": "packages/jobs/jobs/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/jobs.md",
+      "symbol": "JobEventFilter",
+      "source": "packages/jobs/jobs/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/terminal.md",
       "symbol": "TerminalWaitReason",
@@ -1916,6 +1951,26 @@
       "symbol": "InvocationDescriptor",
       "source": "packages/typert/protocol/src/types.ts"
     },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "RemoteStream",
+      "source": "packages/typert/protocol/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "RemoteStreamHandle",
+      "source": "packages/typert/protocol/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "PeerScope",
+      "source": "packages/typert/protocol/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/typert.md",
+      "symbol": "RemoteInvocation",
+      "source": "packages/typert/protocol/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/typert.md",
       "symbol": "TypertRegistryContract",
diff --git a/scripts/verify-application-entrypoints.spec.ts b/scripts/verify-application-entrypoints.spec.ts
index 0c84043dfc..6ff6cb673a 100644
--- a/scripts/verify-application-entrypoints.spec.ts
+++ b/scripts/verify-application-entrypoints.spec.ts
@@ -99,8 +99,28 @@ describe('application entrypoints', () => {
     write(root, 'scripts/demo-ptc.mjs', "spawn('node', ['packages/example/app/src/bin.ts'])\n")
 
     expect(applicationEntrypointViolations(root)).toEqual([
-      'scripts/demo-ptc.mjs: application demo wrapper must launch apps/cli/src/bin.ts',
-      'scripts/demo-ptc.mjs: application demo wrapper must not launch a package entry directly',
+      'scripts/demo-ptc.mjs: application launcher wrapper must launch apps/cli/src/bin.ts',
+      'scripts/demo-ptc.mjs: application launcher wrapper must not launch a package entry directly',
+    ])
+  })
+
+  it('rejects a start:web script that bypasses the dsh launcher', () => {
+    const root = fixture()
+    write(root, 'package.json', JSON.stringify({ scripts: { 'start:web': 'node packages/example/app/src/bin.ts web' } }))
+
+    expect(applicationEntrypointViolations(root)).toEqual([
+      'package.json scripts.start:web: application launcher script must launch apps/cli/src/bin.ts',
+      'package.json scripts.start:web: application launcher script must not launch a package entry directly',
+    ])
+  })
+
+  it('rejects a dev:web wrapper that serves without the dsh launcher', () => {
+    const root = fixture()
+    write(root, 'package.json', JSON.stringify({ scripts: { 'dev:web': 'tsx scripts/dev-web.ts --poll' } }))
+    write(root, 'scripts/dev-web.ts', "execa('vite', ['build', '--watch'])\n")
+
+    expect(applicationEntrypointViolations(root)).toEqual([
+      'scripts/dev-web.ts: application launcher wrapper must launch apps/cli/src/bin.ts',
     ])
   })
 
diff --git a/scripts/verify-application-entrypoints.ts b/scripts/verify-application-entrypoints.ts
index 728dd0832f..b629e7e9ab 100644
--- a/scripts/verify-application-entrypoints.ts
+++ b/scripts/verify-application-entrypoints.ts
@@ -18,7 +18,7 @@ interface RootManifest {
   readonly scripts?: Record<string, unknown>
 }
 
-interface DemoPolicy {
+interface LauncherPolicy {
   readonly kind: 'dsh-direct' | 'dsh-wrapper'
   readonly wrapper?: string
 }
@@ -48,10 +48,16 @@ const EXECUTABLE_SOURCE_ALLOWLIST = new Map<string, string>([
   ['python/sdk-runtime/runtime-bootstrap.mjs', 'private packaging-only runtime dispatcher'],
 ])
 
-/** Root demos are application wrappers and therefore must visibly select dsh. */
-const ROOT_DEMO_POLICIES = new Map<string, DemoPolicy>([
+/**
+ * Root scripts that start an application must visibly select dsh: every `demo:*`
+ * script needs a row here, and the Web start and development scripts are pinned
+ * by name.
+ */
+const ROOT_LAUNCHER_POLICIES = new Map<string, LauncherPolicy>([
   ['demo:ptc', { kind: 'dsh-wrapper', wrapper: 'scripts/demo-ptc.mjs' }],
   ['demo:inspector', { kind: 'dsh-direct' }],
+  ['start:web', { kind: 'dsh-direct' }],
+  ['dev:web', { kind: 'dsh-wrapper', wrapper: 'scripts/dev-web.ts' }],
 ])
 
 const SOURCE_PATTERNS = [
@@ -131,22 +137,23 @@ function referencesPackageEntry(source: string): boolean {
   return /packages\/[^/\s'"`]+\/[^/\s'"`]+\/(?:src|lib)\/[^\s'"`]+/.test(source)
 }
 
-function rootDemoViolations(root: string): string[] {
+function rootLauncherViolations(root: string): string[] {
   const manifestPath = resolve(root, 'package.json')
   if (!existsSync(manifestPath)) return []
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as RootManifest
   const failures: string[] = []
   for (const [name, commandValue] of Object.entries(manifest.scripts ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
-    if (!name.startsWith('demo:')) continue
-    const command = typeof commandValue === 'string' ? commandValue : ''
-    const policy = ROOT_DEMO_POLICIES.get(name)
+    const policy = ROOT_LAUNCHER_POLICIES.get(name)
     if (policy === undefined) {
-      failures.push(`package.json scripts.${name}: demo launcher has no explicit dsh or in-process classification`)
+      if (name.startsWith('demo:')) {
+        failures.push(`package.json scripts.${name}: demo launcher has no explicit dsh or in-process classification`)
+      }
       continue
     }
+    const command = typeof commandValue === 'string' ? commandValue : ''
     if (policy.kind === 'dsh-direct') {
-      if (!referencesDshCli(command)) failures.push(`package.json scripts.${name}: application demo must launch apps/cli/src/bin.ts`)
-      if (referencesPackageEntry(command)) failures.push(`package.json scripts.${name}: application demo must not launch a package entry directly`)
+      if (!referencesDshCli(command)) failures.push(`package.json scripts.${name}: application launcher script must launch apps/cli/src/bin.ts`)
+      if (referencesPackageEntry(command)) failures.push(`package.json scripts.${name}: application launcher script must not launch a package entry directly`)
       continue
     }
     const wrapper = policy.wrapper
@@ -156,12 +163,12 @@ function rootDemoViolations(root: string): string[] {
     }
     const wrapperPath = resolve(root, wrapper)
     if (!existsSync(wrapperPath)) {
-      failures.push(`${wrapper}: classified demo wrapper is missing`)
+      failures.push(`${wrapper}: classified launcher wrapper is missing`)
       continue
     }
     const source = readFileSync(wrapperPath, 'utf8')
-    if (!referencesDshCli(source)) failures.push(`${wrapper}: application demo wrapper must launch apps/cli/src/bin.ts`)
-    if (referencesPackageEntry(source)) failures.push(`${wrapper}: application demo wrapper must not launch a package entry directly`)
+    if (!referencesDshCli(source)) failures.push(`${wrapper}: application launcher wrapper must launch apps/cli/src/bin.ts`)
+    if (referencesPackageEntry(source)) failures.push(`${wrapper}: application launcher wrapper must not launch a package entry directly`)
   }
   return failures
 }
@@ -175,7 +182,7 @@ export function applicationEntrypointViolations(root: string): string[] {
   return [
     ...manifestBinViolations(root),
     ...executableSourceViolations(root),
-    ...rootDemoViolations(root),
+    ...rootLauncherViolations(root),
   ]
 }
 
diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts
index ffeb8f08f3..d73bce3c22 100644
--- a/scripts/verify-cordis-config.ts
+++ b/scripts/verify-cordis-config.ts
@@ -14,6 +14,8 @@ import { globSync, readFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { Script } from 'node:vm'
 import ts from 'typescript'
+import type { DshBundleManifest } from '../packages/util/package-manifest/src/types.ts'
+import { bundlePatchPaths } from '../packages/boot/app-boot/src/profile.ts'
 import { cordisConfigFiles } from './cordis-config-files.ts'
 import { isCordisGroupEntry, isJsExpr, loadCordisYaml } from './cordis-yaml.ts'
 
@@ -22,7 +24,7 @@ export interface PackageManifest {
   dependencies?: Record<string, string>
   devDependencies?: Record<string, string>
   optionalDependencies?: Record<string, string>
-  dsh?: { bundle?: { patch?: string } }
+  dsh?: { bundle?: DshBundleManifest }
 }
 
 export interface PluginReference {
@@ -257,10 +259,11 @@ function validateAppResolution(): string[] {
   for (const manifestPath of bundleManifests) {
     const bundleDir = manifestPath.replace(/\/package\.json$/, '')
     const manifest = readManifest(manifestPath)
-    const patch = manifest.dsh?.bundle?.patch
-    if (typeof patch !== 'string') continue
-    const patchFile = relative(root, resolve(root, bundleDir, patch)).replaceAll('\\', '/')
-    const references = pluginReferences.filter(reference => reference.file === patchFile)
+    const bundle = manifest.dsh?.bundle
+    if (bundle === undefined) continue
+    const patchFiles = new Set(bundlePatchPaths(resolve(root, bundleDir), bundle)
+      .map(file => relative(root, file).replaceAll('\\', '/')))
+    const references = pluginReferences.filter(reference => patchFiles.has(reference.file))
     violations.push(...bundlePluginDependencyErrors(manifestPath, manifest, references))
   }
   return violations
@@ -362,7 +365,7 @@ function packageTestManifestPath(file: string): string | undefined {
  */
 export function bundleManifestPaths(repoRoot: string = root): string[] {
   return globSync('packages/*/*/package.json', { cwd: repoRoot })
-    .filter(path => typeof readManifest(path, repoRoot).dsh?.bundle?.patch === 'string')
+    .filter(path => readManifest(path, repoRoot).dsh?.bundle?.patch !== undefined)
     .map(path => path.replaceAll('\\', '/'))
     .sort()
 }
diff --git a/scripts/verify-default-product-isolation.ts b/scripts/verify-default-product-isolation.ts
index 5e3acc7fc9..2ce4322e14 100644
--- a/scripts/verify-default-product-isolation.ts
+++ b/scripts/verify-default-product-isolation.ts
@@ -12,7 +12,8 @@ import ts from 'typescript'
 import { applyEntryPatches, type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import { loadOverlayPatches } from '../packages/boot/app-boot/src/index.ts'
-import { composeEntries } from '../packages/boot/app-boot/src/profile.ts'
+import { bundlePatchPaths, composeEntries } from '../packages/boot/app-boot/src/profile.ts'
+import type { DshBundleManifest } from '../packages/util/package-manifest/src/types.ts'
 import { isCordisGroupEntry, loadCordisYaml } from './cordis-yaml.ts'
 import {
   collectRuntimeLocalSourceSpecifiers,
@@ -32,7 +33,7 @@ interface Manifest {
   optionalDependencies?: Record<string, string>
   peerDependencies?: Record<string, string>
   devDependencies?: Record<string, string>
-  dsh?: { bundle?: { patch?: string }; configTrees?: Array<{ path: string }> }
+  dsh?: { bundle?: DshBundleManifest; configTrees?: Array<{ path: string }> }
 }
 
 interface Package {
@@ -238,9 +239,9 @@ export function verifyDefaultProductIsolation(root: string): ProductIsolationRes
     }
     const webLayers = selection.webBundles.flatMap((name) => {
       const pkg = packages.get(name)
-      const patch = pkg?.manifest.dsh?.bundle?.patch
-      if (pkg === undefined || patch === undefined) return []
-      return [loadOverlayPatches('verify-default-product-isolation', resolve(pkg.directory, patch))]
+      const bundle = pkg?.manifest.dsh?.bundle
+      if (pkg === undefined || bundle === undefined) return []
+      return [bundlePatchPaths(pkg.directory, bundle).flatMap(file => loadOverlayPatches('verify-default-product-isolation', file))]
     })
     if (webLayers.length !== selection.webBundles.length) {
       failures.push(`${PROFILE_SOURCE}: default Web bundle layers are incomplete`)
@@ -285,7 +286,7 @@ export function verifyDefaultProductIsolation(root: string): ProductIsolationRes
         dependency(name, range, pkg, `${manifest.name} ${section}`)
       }
     }
-    if (manifest.dsh?.bundle?.patch !== undefined) scanConfig(resolve(pkg.directory, manifest.dsh.bundle.patch))
+    for (const file of manifest.dsh?.bundle === undefined ? [] : bundlePatchPaths(pkg.directory, manifest.dsh.bundle)) scanConfig(file)
     for (const tree of manifest.dsh?.configTrees ?? []) {
       const treePath = resolve(pkg.directory, tree.path)
       const files = existsSync(treePath) && statSync(treePath).isDirectory()
diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts
index 292dccbce9..2c4c147dd7 100644
--- a/scripts/verify-package-dependencies.spec.ts
+++ b/scripts/verify-package-dependencies.spec.ts
@@ -214,7 +214,7 @@ describe('package dependency scope', () => {
     expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/dsh-session/types']).toBeUndefined()
     expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/dsh-typert-protocol']).toBeUndefined()
     expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-scope']).toEqual([
-      'carrierKeyOf', 'scopeOf', 'scopeTarget',
+      'carrierKeyOf', 'createScope', 'scopeOf', 'scopeTarget',
     ])
     expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-typert-protocol']).toBeUndefined()
   })
diff --git a/scripts/verify-package-meta.spec.ts b/scripts/verify-package-meta.spec.ts
index fbdd05daf8..ac82e7e511 100644
--- a/scripts/verify-package-meta.spec.ts
+++ b/scripts/verify-package-meta.spec.ts
@@ -44,6 +44,57 @@ it('does not require locale resources for exported package name and description'
   expect(packageMetaProblems(root)).toEqual([])
 })
 
+it.each([undefined, ['art'], ['art/*.svg'], ['./art/icon.svg']])('accepts a published package icon without locale resources: %j', (files) => {
+  manifest({ icon: './art/icon.svg', files })
+  file('art/icon.svg', '<svg/>')
+  expect(packageMetaProblems(root)).toEqual([])
+})
+
+it.each([{ files: ['lib'] }, { files: ['art', '!art/icon.svg'] }])('rejects an icon omitted from package publication: %j', ({ files }) => {
+  manifest({ icon: './art/icon.svg', files })
+  file('art/icon.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('files must include art/icon.svg')
+})
+
+it.each([null, false, 1, '', './icon.gif', '/tmp/icon.svg', './missing.png', '../outside.svg'])('validates icon declarations without locale resources: %j', (icon) => {
+  manifest({ icon })
+  file('../outside.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('Plugin metadata for @test/plugin:')
+})
+
+it('requires the root icon declaration to be exported', () => {
+  manifest({ icon: './icon.svg', exports: { '.': './entry.js' }, files: ['icon.svg'] })
+  file('icon.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('exports must expose its icon declaration through @test/plugin/package.json')
+})
+
+it.each([
+  { './search/package.json': './resources/search/manifest.json' },
+  { './*/package.json': './resources/*/manifest.json' },
+  { './*': './resources/*' },
+])('validates icons of independent exported manifests: %j', (exports) => {
+  manifest({ exports, files: ['resources'] })
+  const document = './*' in exports ? 'resources/search/package.json' : 'resources/search/manifest.json'
+  json(document, { icon: './icon.webp' })
+  file('resources/search/icon.webp', 'webp')
+  expect(packageMetaProblems(root)).toEqual([])
+  json(document, { icon: './missing.png' })
+  expect(packageMetaProblems(root).join('\n')).toContain('missing.png')
+})
+
+it('requires publication of both an exported icon manifest and its image', () => {
+  manifest({ exports: { './search/package.json': './resources/search.json' }, files: ['resources/icon.svg'] })
+  json('resources/search.json', { icon: './icon.svg' })
+  file('resources/icon.svg', '<svg/>')
+  expect(packageMetaProblems(root).join('\n')).toContain('files must include resources/search.json')
+})
+
+it('ignores icon-like fields in unrelated source JSON', () => {
+  manifest()
+  json('data.json', { icon: false })
+  expect(packageMetaProblems(root)).toEqual([])
+})
+
 it('excludes tests, installed dependencies, and build output from metadata discovery', () => {
   manifest({ exports: { '.': './lib/index.js' }, files: ['lib'] })
   json('tests/fixtures/locale/en.json', { meta: { title: false } })
@@ -91,6 +142,30 @@ it.each(['en', 'zh'])('rejects %s metadata resolved into build output without re
   expect(problems).not.toContain('Plugin metadata for')
 })
 
+it('does not read built locale JSON while checking a source icon declaration', () => {
+  manifest({
+    icon: './icon.svg', files: ['icon.svg'],
+    exports: { './package.json': './package.json', './locale/en.json': './lib/locale/en.json' },
+  })
+  file('icon.svg', '<svg/>')
+  file('lib/locale/en.json', '{')
+  json('locale/en.json', { meta: { title: 'Plugin' } })
+  const problems = packageMetaProblems(root).join('\n')
+  expect(problems).toContain('exports must expose locale/en.json')
+  expect(problems).not.toContain('Plugin metadata for')
+})
+
+it.each(['lib', 'tests'])('rejects an icon declaration when its only locale is excluded source: %s', (directory) => {
+  manifest({
+    icon: './missing.svg', files: ['lib'],
+    exports: { './package.json': './package.json', './locale/en.json': `./${directory}/locale/en.json` },
+  })
+  file(`${directory}/locale/en.json`, '{}')
+  const problems = packageMetaProblems(root).join('\n')
+  expect(problems).toContain('@test/plugin: icon metadata requires locale resources to resolve to source JSON')
+  expect(problems).not.toContain('Plugin metadata for')
+})
+
 it('reads static metadata without evaluating the plugin entry', () => {
   manifest({ exports: { '.': './entry.js', './locale/*.json': './locale/*.json' } })
   file('entry.js', "import { writeFileSync } from 'node:fs'; writeFileSync(new URL('./executed', import.meta.url), 'yes'); throw new Error('plugin entry executed')")
diff --git a/scripts/verify-package-meta.ts b/scripts/verify-package-meta.ts
index f5a486678f..de5720c6db 100644
--- a/scripts/verify-package-meta.ts
+++ b/scripts/verify-package-meta.ts
@@ -9,12 +9,14 @@ interface Manifest {
   name: string
   exports?: unknown
   files?: string[]
+  icon?: unknown
 }
 
 interface SourceJson {
   file: string
   metadata: boolean
   invalid: boolean
+  icon?: unknown
 }
 
 function sourceJsonFiles(dir: string): SourceJson[] {
@@ -29,7 +31,7 @@ function sourceJsonFiles(dir: string): SourceJson[] {
     if (typeof contents !== 'object' || contents === null || Array.isArray(contents)) {
       return { file, metadata: false, invalid: true }
     }
-    return { file, metadata: Object.hasOwn(contents, 'meta'), invalid: false }
+    return { file, metadata: Object.hasOwn(contents, 'meta'), invalid: false, icon: 'icon' in contents ? contents.icon : undefined }
   })
 }
 
@@ -77,7 +79,10 @@ function packageProblems(manifestPath: string): string[] {
   const exported = typeof pkg.exports === 'object' && pkg.exports !== null ? Object.entries(pkg.exports) : []
   for (const [key, target] of exported) {
     if (!key.startsWith('.')) continue
-    if (!key.includes('*')) candidates.add(key)
+    if (!key.includes('*')) {
+      candidates.add(key)
+      if (key.endsWith('/package.json')) candidates.add(key.slice(0, -'/package.json'.length))
+    }
     const plugin = pluginOf(key)
     if (plugin !== undefined && !plugin.includes('*')) candidates.add(plugin)
     for (const pattern of targetsOf(target)) {
@@ -85,6 +90,7 @@ function packageProblems(manifestPath: string): string[] {
         const value = substitution(pattern, `./${document.file}`)
         if (value === undefined) continue
         const request = key.replaceAll('*', value)
+        if (request.endsWith('/package.json')) candidates.add(request.slice(0, -'/package.json'.length))
         const owner = pluginOf(request)
         if (owner === undefined) continue
         candidates.add(owner)
@@ -116,6 +122,26 @@ function packageProblems(manifestPath: string): string[] {
       const file = lookup(resourceOf(filename))
       return file === undefined ? [] : [{ filename, file }]
     })
+    const iconManifest = lookup(`${specifier}/package.json`)
+    const iconDocument = iconManifest === undefined ? undefined : byPath.get(iconManifest)
+    let iconChecked = false
+    if (candidate === '.' && pkg.icon !== undefined && iconManifest !== join(dir, 'package.json')) {
+      problems.push(`${manifestPath}: exports must expose its icon declaration through ${pkg.name}/package.json`)
+    }
+    if (iconDocument?.icon !== undefined && resources.every(({ file }) => byPath.has(file))) {
+      iconChecked = true
+      const meta = readPluginMeta(specifier, parentURL)
+      if (meta?.error !== undefined) problems.push(meta.error)
+      if (meta?.icon !== undefined && typeof iconDocument.icon === 'string') {
+        const iconFile = relative(dir, resolve(dirname(join(dir, iconDocument.file)), iconDocument.icon)).replaceAll('\\', '/')
+        if (pkg.files !== undefined && !published(iconFile, pkg.files)) problems.push(`${manifestPath}: files must include ${iconFile}`)
+        if (iconDocument.file !== 'package.json' && pkg.files !== undefined && !published(iconDocument.file, pkg.files)) {
+          problems.push(`${manifestPath}: files must include ${iconDocument.file}`)
+        }
+      }
+    } else if (iconDocument?.icon !== undefined) {
+      problems.push(`${specifier}: icon metadata requires locale resources to resolve to source JSON`)
+    }
     if (!resources.some(({ file }) => byPath.get(file)?.metadata || byPath.get(file)?.invalid)) continue
     for (const { file } of resources) claimed.add(file)
     const english = lookup(resourceOf('en.json'))
@@ -138,7 +164,7 @@ function packageProblems(manifestPath: string): string[] {
         problems.push(`${resourceOf(filename)}: ${file} must share the English locale directory ${directory}`)
       }
     }
-    if (sourceResources) {
+    if (sourceResources && !iconChecked) {
       const meta = readPluginMeta(specifier, parentURL)
       if (meta?.error !== undefined) problems.push(meta.error)
     }
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 4727164e95..4ca723fe0f 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -56,6 +56,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/document/office-to-pdf': { kind: 'none', reason: 'The provider returns PDF bytes without constructing model input.' },
   '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/client/ui-jobs': { kind: 'none', reason: 'Browser-side presentation of host-observed output; touches no prompt, message, schema, stream, or tool result.' },
   'packages/shell/shell': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' },
   'packages/shell/shell-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/shell/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
@@ -104,7 +105,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/client/ui-chat': { kind: 'none', reason: 'Browser-side Chat presentation; registers nothing model-facing.' },
   'packages/client/ui-message-feedback': { kind: 'none', reason: 'Browser-side controls over log-only message feedback; ratings and notes never enter model context or change model-input tokens.' },
   'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' },
-  'packages/client/ui-jobs': { kind: 'none', reason: 'Browser-side read-only projection of ctx.jobs records; dsh-tool-jobs owns the model-facing behavior.' },
   'packages/client/ui-schedule': { kind: 'none', reason: 'Browser-side read-only projection of active Schedule records; dsh-schedule owns the model-facing tools and delivery.' },
   'packages/client/ui-workflow-run': { kind: 'none', reason: 'Browser-side UI plugin layer; renders durable workflow records without changing model context.' },
   'packages/client/ui-input-trigger': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
@@ -188,6 +188,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/test-support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
   'packages/test-support/remote-mock': { kind: 'none', reason: 'Browser-side test infrastructure (Remote endpoint mock); registers nothing model-facing.' },
   'packages/api/gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },
+  'packages/api/job-controller': { kind: 'none', reason: 'Job observation is browser and Host control state; it registers no prompt, tool, or session event.' },
   'packages/api/session-controller': { kind: 'none', reason: 'Session API and transport owner; invoked Agent commands own any model-visible effect.' },
   'packages/api/settings-controller': { kind: 'none', reason: 'Configuration-surface API owner; it registers no prompt, tool, or session event.' },
   'packages/api/workspace-controller': { kind: 'none', reason: 'Workspace API and state projection owner; it registers no prompt, tool, or session event.' },
diff --git a/scripts/volatile-config.fixture.ts b/scripts/volatile-config.fixture.ts
new file mode 100644
index 0000000000..a10df387fd
--- /dev/null
+++ b/scripts/volatile-config.fixture.ts
@@ -0,0 +1,11 @@
+/** Shared volatile schema fixture for the schema and Loader volatile specs. */
+import z from '@deepseek-ai/schemastery'
+
+/** Mixed ordinary, volatile, nested and whole-object volatile fields. */
+export const Config = z.object({
+  fixed: z.string().default('fixed'),
+  title: z.string().default('hello').volatile(),
+  optional: z.string().volatile(),
+  nested: z.object({ count: z.number().min(0).volatile().default(1) }).default({}),
+  group: z.object({ list: z.array(z.string()) }).default({ list: [] }).volatile(),
+})
diff --git a/scripts/volatile-config.spec.ts b/scripts/volatile-config.spec.ts
new file mode 100644
index 0000000000..75d2a5f1f6
--- /dev/null
+++ b/scripts/volatile-config.spec.ts
@@ -0,0 +1,151 @@
+/** Schemastery and Cordis config reference behavior through direct and Loader updates. */
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { type Volatile } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { Config } from './volatile-config.fixture.ts'
+import { createVolatile, deepEqual, volatileEntries } from '@deepseek-ai/cosmokit'
+import { redactSecrets } from '../packages/settings/settings/src/redact.ts'
+
+describe('volatile schemas', () => {
+  it('parses references with defaults and absent values while preserving schema metadata', () => {
+    const parsed = Config({})
+    expect(parsed.title.get()).toBe('hello')
+    expect(parsed.optional.get()).toBeUndefined()
+    expect(parsed.nested.count.get()).toBe(1)
+    expectTypeOf(parsed.title).toEqualTypeOf<Volatile<string>>()
+    expectTypeOf(parsed.optional).toEqualTypeOf<Volatile<string | undefined>>()
+    expectTypeOf(parsed.nested.count).toEqualTypeOf<Volatile<number>>()
+    expectTypeOf(z.string().volatile().description('Live text').default('text')().get()).toEqualTypeOf<string>()
+    expectTypeOf(z.string().required().volatile()('text').get()).toEqualTypeOf<string>()
+    expect(Config.dict?.title?.type).toBe('string')
+    expect(Config.dict?.title?.meta.default).toBe('hello')
+    expect(Config.simplify(parsed)).toBeNull()
+    const reconstructed = new z<unknown>(JSON.parse(JSON.stringify(Config.toJSON())) as z<unknown>)
+    expect((reconstructed({ title: 'changed' }) as ReturnType<typeof Config>).title.get()).toBe('changed')
+    expect(reconstructed.simplify(reconstructed({ title: 'changed' }))).toEqual({ title: 'changed' })
+    expect(z.string().volatile().required()('present').get()).toBe('present')
+    expect(() => z.string().volatile().required()()).toThrow('missing required value')
+    expect(() => Config({ nested: { count: -1 } })).toThrow()
+    expect(Config({ nested: { count: -1 } }, { autofix: true }).nested.count.get()).toBe(1)
+  })
+
+  it('copies and freezes data snapshots without freezing the input', () => {
+    const input = { group: { list: ['a'] } }
+    const parsed = Config(input)
+    input.group.list.push('b')
+    expect(parsed.group.get()).toEqual({ list: ['a'] })
+    expect(Object.isFrozen(parsed.group.get())).toBe(true)
+    expect(Object.isFrozen(parsed.group.get().list)).toBe(true)
+    expect(() => (parsed.group.get().list as string[]).push('c')).toThrow()
+    expect(Object.keys(parsed.group)).toEqual(['get'])
+    expect(() => z.any().volatile()(new Date())).toThrow('plain objects')
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    expect(() => z.any().volatile()(cyclic)).toThrow('cycles')
+  })
+
+  it.each([
+    ['array', () => z.object({ items: z.array(z.string().volatile()) }), 'items'],
+    ['dict', () => z.object({ items: z.dict(z.string().volatile()) }), 'items'],
+    ['union', () => z.union([z.object({ title: z.string().volatile() }), z.string()]), 'title'],
+    ['tuple', () => z.object({ items: z.tuple([z.string().volatile()]) }), 'items'],
+    ['intersect', () => z.intersect([z.object({ title: z.string().volatile() })]), 'title'],
+    ['transform', () => z.transform(z.object({ title: z.string().volatile() }), value => value), 'title'],
+    ['nested', () => z.object({ block: z.object({ title: z.string().volatile() }).volatile() }), 'block'],
+  ])('rejects %s placements even when input omits the field', (_name, schema, path) => {
+    expect(() => schema()({})).toThrow(path)
+  })
+
+  it('rejects repeat wrapping and supports an entire array or union as a value', () => {
+    expect(() => z.string().volatile().volatile()).toThrow('already wrapped')
+    expect(z.array(z.string()).volatile()(['a']).get()).toEqual(['a'])
+    expect(z.union([z.string(), z.number()]).volatile()(1).get()).toBe(1)
+    const schema = z.string().volatile()
+    expect(schema('first')).not.toBe(schema('first'))
+  })
+
+  it('retains ordinary fields and secret traversal in serialized schemas', () => {
+    const schema = z.object({ block: z.object({ apiKey: z.string().role('secret'), title: z.string() }).volatile() })
+    const restored = new z<unknown>(JSON.parse(JSON.stringify(schema.toJSON())) as z<unknown>)
+    expect(restored.dict?.block?.type).toBe('object')
+    expect(restored.dict?.block?.dict?.apiKey?.meta.role).toBe('secret')
+    expect(redactSecrets(restored as z<never>, { block: { apiKey: 'secret', title: 'public' } }).value)
+      .toEqual({ block: { title: 'public' } })
+  })
+
+  it('accepts metadata-free serialized nodes and checks their nested volatile declarations', () => {
+    const schema = new z<{ enabled: boolean }>(JSON.parse('{"type":"object","dict":{"enabled":{"type":"boolean"}}}') as z<{ enabled: boolean }>)
+    expect(schema({ enabled: true })).toEqual({ enabled: true })
+    const dynamic = new z<unknown>(JSON.parse(
+      '{"type":"object","dict":{"items":{"type":"array","inner":{"type":"string","meta":{"volatile":true}}}}}',
+    ) as z<unknown>)
+    expect(() => dynamic({ items: [] })).toThrow('items')
+  })
+
+  it('resolves recursive lazy schemas only for the supplied data', () => {
+    interface Tree { name: string; children?: Tree[] }
+    function tree(): z<Tree> {
+      return z.object({ name: z.string(), children: z.array(z.lazy(tree)).default([]) })
+    }
+    expect(tree()({ name: 'root' })).toEqual({ name: 'root', children: [] })
+    expect(tree()({ name: 'root', children: [{ name: 'leaf' }] }))
+      .toEqual({ name: 'root', children: [{ name: 'leaf', children: [] }] })
+    const schema = z.object({ lazy: z.lazy(() => z.object({ live: z.string().volatile() })) })
+    expect(() => schema({ lazy: { live: 'value' } })).toThrow('lazy')
+  })
+})
+
+describe('volatile comparison semantics', () => {
+  it('ignores reference contents while retaining ordinary differences', () => {
+    const first = Config({ title: 'a' })
+    const second = Config({ title: 'b' })
+    expect(deepEqual(first, second, true)).toBe(true)
+    expect(deepEqual(first, Config({ fixed: 'changed' }), true)).toBe(false)
+    expect(deepEqual(first.title, 'a', true)).toBe(false)
+    expect(deepEqual('a', first.title, true)).toBe(false)
+    expect(deepEqual([undefined], [null], true)).toBe(false)
+    expect(deepEqual([undefined], [null])).toBe(true)
+    expect(deepEqual(new Date(0), new Date(0), true)).toBe(true)
+    expect(deepEqual(/a/g, /a/i, true)).toBe(false)
+    expect(deepEqual(new URL('https://a.example'), new URL('https://b.example'), true)).toBe(false)
+    expect(deepEqual(new URL('https://EXAMPLE.com:443/'), new URL('https://example.com'), true)).toBe(true)
+    expect(deepEqual(new URL('https://example.com'), {}, true)).toBe(false)
+    expect(deepEqual({}, new URL('https://example.com'), true)).toBe(false)
+    expect(deepEqual(new Uint8Array([1]).buffer, new Uint8Array([2]).buffer, true)).toBe(false)
+    const firstCycle: Record<string, unknown> = {}; firstCycle.self = firstCycle
+    const secondCycle: Record<string, unknown> = {}; secondCycle.self = secondCycle
+    expect(deepEqual(firstCycle, secondCycle, true)).toBe(false)
+  })
+})
+
+it('enumerates references through shared config containers without descending into snapshots or cycles', () => {
+  const ref = createVolatile({ nested: 'value' })
+  const shared = Object.assign(Object.create(null), { live: ref }) as Record<string, unknown>
+  const config: Record<string, unknown> = { list: [shared, shared], opaque: new URL('https://example.com'), plain: 'value' }
+  config.self = config
+  expect(volatileEntries(config)).toEqual([
+    { path: ['list', '0', 'live'], ref },
+    { path: ['list', '1', 'live'], ref },
+  ])
+  expect(volatileEntries(ref)).toEqual([{ path: [], ref }])
+})
+
+it('compares sparse array slots as undefined in both directions', () => {
+  for (const strict of [true, false]) {
+    expect(deepEqual(Array(1), [undefined], strict)).toBe(true)
+    expect(deepEqual([undefined], Array(1), strict)).toBe(true)
+    expect(deepEqual(Array(1), ['new'], strict)).toBe(false)
+    expect(deepEqual(['new'], Array(1), strict)).toBe(false)
+    expect(deepEqual(Array(1), [], strict)).toBe(false)
+    expect(deepEqual([], Array(1), strict)).toBe(false)
+  }
+  expect(deepEqual(Array(1), [null], true)).toBe(false)
+  expect(deepEqual([null], Array(1), true)).toBe(false)
+})
+
+it('reports unsupported volatile values as validation issues with their path', () => {
+  const schema = z.object({ block: z.object({ when: z.date().volatile() }) })
+  expect(() => schema({ block: { when: new Date(0) } })).toThrow(z.ValidationError)
+  expect(() => schema({ block: { when: new Date(0) } })).toThrow('$.block.when')
+  expect(schema({ block: {} }).block.when.get()).toBeUndefined()
+})
diff --git a/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml b/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml
index 05682eb693..1119ac8f98 100644
--- a/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml
+++ b/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml
@@ -36,6 +36,8 @@
 - insert:
     - id: cordis-host-runner
       name: '@deepseek-ai/dsh-cordis-host-runner'
+    - id: cordis-inspect-providers
+      name: '@deepseek-ai/dsh-tool-cordis/host'
     - id: tool-cordis
       name: '@deepseek-ai/dsh-tool-cordis'
     - id: llm-replay
diff --git a/snapshots/session/cordis-inspect-jsdoc/cordis.yml b/snapshots/session/cordis-inspect-jsdoc/cordis.yml
index 1f92269096..9c8e871aea 100644
--- a/snapshots/session/cordis-inspect-jsdoc/cordis.yml
+++ b/snapshots/session/cordis-inspect-jsdoc/cordis.yml
@@ -33,5 +33,7 @@
 - insert:
     - id: cordis-host-runner
       name: '@deepseek-ai/dsh-cordis-host-runner'
+    - id: cordis-inspect-providers
+      name: '@deepseek-ai/dsh-tool-cordis/host'
     - id: tool-cordis
       name: '@deepseek-ai/dsh-tool-cordis'
diff --git a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
index 158f24c1af..ac4c592e35 100644
--- a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
+++ b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md
@@ -25,10 +25,6 @@ Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for ex
 
 Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked.
 
-# Harness runtime inspection
-
-Use cordis_inspect_list to discover Host and Client providers, then cordis_inspect_query to read exact Service, Event, Tool, Theme or Slot APIs. These tools are read-only; queries do not invoke business methods.
-
 Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.
 
 Use subagent in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set `run_in_background: false` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.
@@ -71,7 +67,7 @@ interface ToolArgsMap {
   } & Record<string, JsonValue>;
   /** List every Cordis Inspect Provider currently known to the Host, including local Host Providers and the latest manifests synchronized from the Client. Each entry includes its platform, purpose, read-only methods, and input/output schemas. Call this Tool before writing or configuring a plugin, then select the provider and method for cordis_inspect_query from its result. Do not guess names or treat an Inspect method as a business Service that Plugin code can call. */
   cordis_inspect_list: Record<string, JsonValue>;
-  /** Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant. */
+  /** Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. */
   cordis_inspect_query: {
     /** Runtime platform that owns the Provider. */
     platform: "host" | "client";
diff --git a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
index a48efa53bf..532e048e81 100644
--- a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
+++ b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json
@@ -55,7 +55,7 @@
     },
     {
       "name": "cordis_inspect_query",
-      "description": "Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant.",
+      "description": "Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/session/deepseek-messages-input-history/cordis.snapshot.yml b/snapshots/session/deepseek-messages-input-history/cordis.snapshot.yml
index 93ac7431eb..23c2d736c9 100644
--- a/snapshots/session/deepseek-messages-input-history/cordis.snapshot.yml
+++ b/snapshots/session/deepseek-messages-input-history/cordis.snapshot.yml
@@ -44,4 +44,4 @@
               - id: deepseek-v4-flash
               - id: deepseek-v4-pro
     - id: messages-input-history-snapshot
-      name: '../../../packages/llm/llm-deepseek/tests/messages/fixtures/input-history.ts'
+      name: '../../../packages/llm/llm-deepseek/tests/fixtures/input-history.ts'
diff --git a/snapshots/session/deepseek-messages-input-history/cordis.yml b/snapshots/session/deepseek-messages-input-history/cordis.yml
index d143031868..019b755c26 100644
--- a/snapshots/session/deepseek-messages-input-history/cordis.yml
+++ b/snapshots/session/deepseek-messages-input-history/cordis.yml
@@ -1,3 +1,3 @@
 - insert:
     - id: messages-input-history-snapshot
-      name: '../../../packages/llm/llm-deepseek/tests/messages/fixtures/input-history.ts'
+      name: '../../../packages/llm/llm-deepseek/tests/fixtures/input-history.ts'
diff --git a/snapshots/session/deepseek-messages-invalid-tool-history/cordis.snapshot.yml b/snapshots/session/deepseek-messages-invalid-tool-history/cordis.snapshot.yml
index 92bac46628..0ae3966b64 100644
--- a/snapshots/session/deepseek-messages-invalid-tool-history/cordis.snapshot.yml
+++ b/snapshots/session/deepseek-messages-invalid-tool-history/cordis.snapshot.yml
@@ -44,4 +44,4 @@
               - id: deepseek-v4-flash
               - id: deepseek-v4-pro
     - id: messages-history-snapshot
-      name: '../../../packages/llm/llm-deepseek/tests/messages/fixtures/history.ts'
+      name: '../../../packages/llm/llm-deepseek/tests/fixtures/history.ts'
diff --git a/snapshots/session/deepseek-messages-invalid-tool-history/cordis.yml b/snapshots/session/deepseek-messages-invalid-tool-history/cordis.yml
index 55b26d1e56..6a4ad74520 100644
--- a/snapshots/session/deepseek-messages-invalid-tool-history/cordis.yml
+++ b/snapshots/session/deepseek-messages-invalid-tool-history/cordis.yml
@@ -1,3 +1,3 @@
 - insert:
     - id: messages-history-snapshot
-      name: '../../../packages/llm/llm-deepseek/tests/messages/fixtures/history.ts'
+      name: '../../../packages/llm/llm-deepseek/tests/fixtures/history.ts'
diff --git a/snapshots/session/office-skills-no-renderer/cordis.yml b/snapshots/session/office-skills-no-renderer/cordis.yml
index 4c963015fe..c4d3987921 100644
--- a/snapshots/session/office-skills-no-renderer/cordis.yml
+++ b/snapshots/session/office-skills-no-renderer/cordis.yml
@@ -6,7 +6,6 @@
 
 - id: llm-deepseek
   config:
-    protocol: chat-completions
     thinking: enabled
     reasoningEffort: high
     maxTokens: 8192
diff --git a/snapshots/session/skill-load/session.v4.jsonl b/snapshots/session/skill-load/session.v4.jsonl
new file mode 100644
index 0000000000..62c83cec58
--- /dev/null
+++ b/snapshots/session/skill-load/session.v4.jsonl
@@ -0,0 +1,23 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1783654655599,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
+{"type":"permission/preset","data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Load the editing-cordis-compositions skill with the skill tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Load the editing-cordis-compositions skill with the skill tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"<system-reminder>\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n<available_skills>\n- `editing-cordis-compositions`: Use when creating, changing, or validating an agent preset or other Cordis composition for this harness, including deciding host versus preset placement and checking that an authored preset mounts.\n- `model-only-skill`: Prove user-disabled skills remain available to the model.\n- `snapshot-skill`: Exercise project skill discovery and loading in snapshot tests.\n</available_skills>\n\nIf the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.\nA user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.\n</system-reminder>"}],"source":{"kind":"skill-catalog","form":"catalog","entries":[{"name":"editing-cordis-compositions","description":"Use when creating, changing, or validating an agent preset or other Cordis composition for this harness, including deciding host versus preset placement and checking that an authored preset mounts."},{"name":"model-only-skill","description":"Prove user-disabled skills remain available to the model."},{"name":"snapshot-skill","description":"Exercise project skill discovery and loading in snapshot tests."}]},"role":"user","id":"{{message:4}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"session/title","data":{"title":"Load the editing-cordis-compositions ski","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"Load the requested skill."},{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"editing-cordis-compositions\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5},"stream":[{"type":"chunk","time":1788699430688,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699430688,"index":0,"dt":[],"texts":["Load the requested skill."]},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699430688,"index":1,"dt":[],"id":"call_skill_load","name":"skill","args":["{\"name\":\"editing-cordis-compositions\"}"]},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Load the requested skill."}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"editing-cordis-compositions\"}"}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"usage","usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_skill_load","name":"skill","arguments":"{\"name\":\"editing-cordis-compositions\"}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_skill_load"},"toolCallId":"call_skill_load","content":[{"type":"text","text":"<skill_content name=\"editing-cordis-compositions\">\n<skill_resources>\nBase directory for this skill: {{cwd}}/.dsh/skills/editing-cordis-compositions\nResolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.\n</skill_resources>\n\n<skill_instructions>\n# Editing Cordis compositions\n\nEvery capability in this harness is a plugin row in a `cordis.yml`. There is no separate configuration language: changing what an agent can do means changing which rows are composed for it.\n\n## Off-limits\n\n**Never edit, delete, or overwrite a preset that ships with the deployment** — the `agent-presets` directory beside the deployment's own config, which supplies `standard`, `ptc`, `minimal`, and `cordis`. Never escalate the sandbox to reach it, even when a change there looks quicker. An upgrade overwrites that install, and corrupting `cordis` disables preset authoring itself. Reading a shipped composition is the intended way to start; writing to one is not, and neither is editing the host composition to work around a preset limitation.\n\nTo change what a shipped preset does, copy it and edit the copy. Locally authored presets under the user root are yours to create, edit, and delete.\n\n## Decide the plane first\n\nTwo planes, and the choice is not about how \"agent-related\" something feels — it is about whether the thing must be shared.\n\n**Host composition.** The registries themselves (`tools`, `systemPrompt`, `agents`, `agent-loop`, `sessions`), anything crossing sessions (persistence, session query, storage, settings, credentials, telemetry), the sandbox and approval stack, the model route, and the subagent registry with its spawn/fork backends. One instance for the process.\n\n**Agent preset.** What one session contributes to those registries: its tool plugins, its persona and prompt sections, its compaction policy. One instance per session, mounted under that session's scope and unwound with it.\n\n**A service with a consumer outside the agent plane cannot move into a preset.** `subagents` is the worked example: the registry answers cross-session queries for the host api-proxy, so a per-session copy both starves that host row — it waits forever for a service nothing provides — and collides on the second session, since a provider name registers once. The preset contributes the delegation *tools*; the registry and its backends stay host-side.\n\nA preset is a directory holding one `agent.cordis.yml`, optionally beside a `preset.yml` carrying display metadata — `name` and `description` (and, for shipped presets, a roster `order`). Write the metadata too: a preset without it shows up in every picker as its bare directory name.\n\nLocally authored presets live one directory per preset under `${DSH_HOME:-$HOME/.dsh}/.agent-presets/`, and the shipped set sits beside the deployment's own config. Use those when the user asks where to look. For deployment overrides, read `${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/cordis.patch.yml`, `${DSH_HOME:-$HOME/.dsh}/cordis.patch.yml`, and any launch `--patch` files for the `agent-presets` row's `roots` and `includeUserRoot`. Obtain the active profile and extra patch paths from the user when they are not in the task context; do not guess a different profile.\n\n## Authoring a preset\n\nUse shell and file tools to locate the installed `@deepseek-ai/dsh-agent-presets` package under the active profile's `node_modules` or the deployment installation. Its `presets/<id>/` directory contains each shipped preset. If those files are unavailable, ask the user to copy the preset through the Web preset picker and provide the copied directory; runtime API inspection does not execute Remote methods.\n\nCopy the complete source directory, including skills and assets, into a new `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<new-id>/` directory (or the explicitly configured writable root). Refuse an existing destination. Set `name` and `description` in `preset.yml` and remove the copied roster `order`. Never overwrite the installed source.\n\nEdit the copy's `agent.cordis.yml` with the normal file tools. Writes outside the workspace follow the active filesystem approval policy. For profile-wide capabilities, author a workspace bundle and install it with `plugin_manager`; load `cordis-plugin-development` for packaging guidance.\n\n## Service isolation\n\nA preset row that publishes a service needs an `isolate` realm containing both the provider and all its consumers. A tool that only consumes a host service remains outside that realm. Copy the shipped preset's existing groups rather than introducing service instances into the process-global realm.\n\n```yaml\n- id: delegation\n  name: cordis:group\n  group: true\n  isolate:\n    workflowEngine: true\n  config:\n    - id: workflow-ptc\n      name: '@deepseek-ai/dsh-workflow-ptc'\n      config:\n        provider: spawn\n    - id: tool-workflow\n      name: '@deepseek-ai/dsh-tool-workflow'\n```\n\n## Verify a preset\n\nCheck the edited YAML and referenced local files with file tools. Ask the user to select the new preset in the Web picker and start a session; this authoring agent cannot invoke the preset Remote API or start a Web session through inspection. Once the user provides a running session or browser control, inspect the visible tools and any activation diagnostic. File validation alone does not verify imports, service dependencies, or isolation. Report which checks ran and leave activation unverified until that session check succeeds.\n\n## Native product subagents\n\nCodex and Claude Code providers are independent optional Profile Bundles. Install only the products a Profile needs, then restart the Profile so its Host registers those providers:\n\n```sh\ndsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex\ndsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code\ndsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-codex\ndsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-claude-code\n```\n\nEach Bundle owns its Host availability; the preset separately grants one Agent its ordinary delegation tool. Never move a product provider into the preset and never add a product-specific settings field. Removing one package withdraws only that provider on the next Profile start.\n\nCopy these disabled templates from a shipped full preset and remove `disabled` only for the products the user requested:\n\n```yaml\n- id: tool-subagent-codex\n  name: '@deepseek-ai/dsh-tool-subagent'\n  disabled: true\n  config:\n    provider: codex\n    toolName: subagent_codex\n    backgroundMode: one-shot\n    maxDepth: provider-managed\n\n- id: tool-subagent-claude-code\n  name: '@deepseek-ai/dsh-tool-subagent'\n  disabled: true\n  config:\n    provider: claude-code\n    toolName: subagent_claude_code\n    backgroundMode: one-shot\n    maxDepth: provider-managed\n```\n\nFor additional named Codex or Claude Code instances, mount a separate host-plane provider row for each instance with a unique `providerName`, then add a separate preset tool row whose `provider` exactly matches that name and whose `toolName` is also unique. Keep the shipped rows for the default `codex` and `claude-code` names; do not reuse one tool row for several providers or derive either name from permission or environment settings.\n\nThe two rows are independent. Leaving both disabled preserves the copied preset, enabling one exposes only that product tool, and enabling both exposes both. Production `dsh` does not install either optional provider: before enabling a row, install the matching `@deepseek-ai/dsh-subagent-codex` or `@deepseek-ai/dsh-subagent-claude-code` Bundle in the Profile and restart it. Each Bundle registers its dormant default provider and exclusively uses its pinned package-local platform CLI; additional named instances use extra host-plane rows from the same installed package. A preset cannot provide that host dependency. `backgroundMode: one-shot` keeps omitted or `false` calls in the foreground and lets explicit `run_in_background: true` return a generic Job id. Full presets already carry `tool-jobs`, while the base host carries the job registry; retain both so `job_output`, `job_list`, `job_kill`, cancellation, and completion notices stay available. Installing a Bundle or composing a preset row does not start a product, authenticate an account, select a model, probe credentials, or manage native product settings.\n\n## What not to move into a preset\n\n`agent-loop` registers the one agent factory and throws on a second. The registries own the per-session layering and cannot themselves be per-session. Session persistence must stay host-side or the session list fragments. The sandbox, approval, and permission rows are a deliberate boundary: a preset is exactly as privileged as the plugins it names, so letting one relax its own confinement would defeat the confinement.\n</skill_instructions>\n</skill_content>"}],"isError":false,"id":"{{message:6}}"}},"sourceEventSeqs":[15],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The skill is loaded."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4},"stream":[{"type":"chunk","time":1788699430709,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699430709,"index":0,"dt":[],"texts":["The skill is loaded."]},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788699430709,"index":1,"dt":[],"texts":["DONE"]},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The skill is loaded."}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"usage","usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/session/workspace-dependencies/cordis.snapshot.yml b/snapshots/session/workspace-dependencies/cordis.snapshot.yml
index 0c8ada9cd0..6b88b3b3fe 100644
--- a/snapshots/session/workspace-dependencies/cordis.snapshot.yml
+++ b/snapshots/session/workspace-dependencies/cordis.snapshot.yml
@@ -46,7 +46,7 @@
 
 - insert:
     - id: workspace-dependencies
-      name: ../../../apps/desktop-host/src/workspace-dependencies.ts
+      name: '@deepseek-ai/dsh-tool-workspace-dependencies'
       config:
         source: !!js process.cwd() + "/runtime-source"
         root: !!js process.cwd() + "/runtime-installed"
diff --git a/snapshots/session/workspace-dependencies/cordis.yml b/snapshots/session/workspace-dependencies/cordis.yml
index 00aae51666..295a5cc683 100644
--- a/snapshots/session/workspace-dependencies/cordis.yml
+++ b/snapshots/session/workspace-dependencies/cordis.yml
@@ -1,6 +1,6 @@
 - insert:
     - id: workspace-dependencies
-      name: ../../../apps/desktop-host/src/workspace-dependencies.ts
+      name: '@deepseek-ai/dsh-tool-workspace-dependencies'
       config:
         source: !!js process.cwd() + '/runtime-source'
         root: !!js process.cwd() + '/runtime-installed'
diff --git a/snapshots/session/workspace-dependencies/tool-schemas.expected.json b/snapshots/session/workspace-dependencies/tool-schemas.expected.json
index 7697c3522f..3906d70183 100644
--- a/snapshots/session/workspace-dependencies/tool-schemas.expected.json
+++ b/snapshots/session/workspace-dependencies/tool-schemas.expected.json
@@ -217,7 +217,7 @@
     },
     {
       "name": "load_workspace_dependencies",
-      "description": "Get absolute paths to bundled Python, Node.js, pnpm, and library directories, plus bundled Python distribution versions. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. Run pnpm with the returned Node executable and pnpm script path. This does not change PATH or package-manager settings.",
+      "description": "Get absolute paths to bundled Python and library directories, plus bundled Python distribution versions. Node.js and pnpm paths are included when the payload provides them. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml, and XlsxWriter. Use these libraries for Office files unless the user or workspace instructions select another environment. When Node.js and pnpm paths are returned, run pnpm with that Node executable and pnpm script path. This does not change PATH or package-manager settings.",
       "parameters": {
         "type": "object",
         "properties": {}
diff --git a/snapshots/web/background-job-list/running.expected.md b/snapshots/web/background-job-list/running.expected.md
index 62a413bf4c..d8e1552658 100644
--- a/snapshots/web/background-job-list/running.expected.md
+++ b/snapshots/web/background-job-list/running.expected.md
@@ -1,2 +1,3 @@
 - list "Background jobs":
-  - listitem: bash sleep 45 running {{duration}}
+  - listitem:
+    - button "Show live output of for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done": for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done {{duration}} bash running
diff --git a/snapshots/web/background-job-list/settled.expected.md b/snapshots/web/background-job-list/settled.expected.md
index cc4bcfef74..d9776370c6 100644
--- a/snapshots/web/background-job-list/settled.expected.md
+++ b/snapshots/web/background-job-list/settled.expected.md
@@ -1,2 +1,2 @@
 - list "Background jobs":
-  - listitem: "bash sleep 45 signal: SIGTERM {{duration}}"
+  - listitem: "bash for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done signal: SIGTERM; web e2e cancellation {{duration}}"
diff --git a/snapshots/web/bash-abort-row/ui.expected.md b/snapshots/web/bash-abort-row/ui.expected.md
index d6188dfffa..911bf72973 100644
--- a/snapshots/web/bash-abort-row/ui.expected.md
+++ b/snapshots/web/bash-abort-row/ui.expected.md
@@ -5,7 +5,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Run two shell commands: wait for cancellation, then write skipped.txt. {{clock}}"
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/changed-files-turn/ui.expected.md b/snapshots/web/changed-files-turn/ui.expected.md
index 197e8c92f5..cfefec17db 100644
--- a/snapshots/web/changed-files-turn/ui.expected.md
+++ b/snapshots/web/changed-files-turn/ui.expected.md
@@ -1,14 +1,13 @@
-- button "系统提示词"
 - text: 不用先查看目录，直接做四件事：把 intro.md 里的标题「示例项目」改成「项目说明」，新建 src/util.ts 导出一个两数相加的 add 函数，新建 app.local 写一行 mode=demo，最后用 bash 在 notes.txt 末尾追加一行 done。 {{clock}}
 - button "复制"
 - button "7 次工具调用" [expanded]
 - button "上下文注入 runtime-context"
-- button "思考 The user wants four things done directly. But I need to read intro.md before editing (fs-observation-policy requires reading existing file first). The user says don't look at the directory first, but reading intro.md is needed for the edit tool. Let me just do it."
+- button "思考"
 - button "读取 intro.md":
   - text: 读取
   - button "intro.md"
-- button "Bash List files and show notes.txt"
-- button "思考 Now do all four actions. Edit intro.md, write src/util.ts, write app.local, bash append."
+- button "运行命令 List files and show notes.txt"
+- button "思考"
 - button "编辑 intro.md +1 -1":
   - text: 编辑
   - button "intro.md"
@@ -21,8 +20,8 @@
   - text: 写入
   - button "app.local"
   - text: +1 -0
-- button "Bash Append done to notes.txt"
-- 'button "思考 All four done. Present the files? The user asked to create files. I should call present for the deliverables. Files: intro.md, src/util.ts, app.local, notes.txt. All are outputs. Let me present them."'
+- button "运行命令 Append done to notes.txt"
+- button "思考"
 - button "交付文件 已交付 intro.md, src/util.ts, app.local, notes.txt"
 - paragraph: 四件事全部完成：
 - list:
@@ -81,20 +80,12 @@
 - text: 此主机没有可用的桌面，无法使用外部程序打开文件或文件夹；文件仍可在侧边栏预览
 - button "在侧边栏预览 intro.md"
 - text: intro.md 标题已改为「项目说明」
-- button "在侧边栏打开 intro.md": 打开
-- button "intro.md 的更多文件操作" [disabled]
 - button "在侧边栏预览 src/util.ts"
 - text: util.ts 新增 add 两数相加函数
-- button "在侧边栏打开 src/util.ts": 打开
-- button "src/util.ts 的更多文件操作" [disabled]
 - button "在侧边栏预览 app.local"
 - text: app.local 新增配置文件，内容 mode=demo
-- button "在侧边栏打开 app.local": 打开
-- button "app.local 的更多文件操作" [disabled]
 - button "在侧边栏预览 notes.txt"
 - text: notes.txt 末尾追加了 done 一行
-- button "在侧边栏打开 notes.txt": 打开
-- button "notes.txt 的更多文件操作" [disabled]
 - button "复制"
 - button "好的回答"
 - button "有问题的回答"
diff --git a/snapshots/web/cordis-tool-round/system-prompt.expected.md b/snapshots/web/cordis-tool-round/system-prompt.expected.md
index a6bd84f32d..187a1abeef 100644
--- a/snapshots/web/cordis-tool-round/system-prompt.expected.md
+++ b/snapshots/web/cordis-tool-round/system-prompt.expected.md
@@ -2,7 +2,7 @@ You are an AI agent powered by DeepSeek Harness.
 
 You are a coding agent powered by the deepseek-v4-flash model.
 
-Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
+Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 
 Check the [exit code: N] marker on every bash result; investigate failures before moving on.
 
diff --git a/snapshots/web/cordis-tool-round/tool-schemas.expected.json b/snapshots/web/cordis-tool-round/tool-schemas.expected.json
index ca7afe0add..bb6f987d5a 100644
--- a/snapshots/web/cordis-tool-round/tool-schemas.expected.json
+++ b/snapshots/web/cordis-tool-round/tool-schemas.expected.json
@@ -195,7 +195,7 @@
     },
     {
       "name": "cordis_inspect_query",
-      "description": "Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before cordis_define to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant.",
+      "description": "Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/snapshots/web/deepseek-messages-chat/ui.expected.md b/snapshots/web/deepseek-messages-chat/ui.expected.md
index 9a790ba8ea..9704a35af6 100644
--- a/snapshots/web/deepseek-messages-chat/ui.expected.md
+++ b/snapshots/web/deepseek-messages-chat/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "对话" [selected]
     - tab "轨迹"
-- button "系统提示词"
 - text: 只回复 MESSAGES_WEB_READY，不调用工具。 {{clock}}
 - button "复制"
 - button "已思考"
diff --git a/snapshots/web/default-workspace/snapshot.yml b/snapshots/web/default-workspace/snapshot.yml
new file mode 100644
index 0000000000..b9efb8a8b7
--- /dev/null
+++ b/snapshots/web/default-workspace/snapshot.yml
@@ -0,0 +1,11 @@
+version: 1
+scenario: default-workspace
+profile: web
+composition: web-default
+recording: authored
+workspace:
+  final: true
+header:
+  class: web-default
+session:
+  source: ../fresh-round-trip/session.v3.jsonl
diff --git a/snapshots/web/default-workspace/ui.expected.md b/snapshots/web/default-workspace/ui.expected.md
new file mode 100644
index 0000000000..7988d45c0c
--- /dev/null
+++ b/snapshots/web/default-workspace/ui.expected.md
@@ -0,0 +1,25 @@
+- banner:
+  - navigation "Session hierarchy": Use the bash tool to
+  - text: Standard mode
+  - button "More actions"
+  - button "Open right sidebar"
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: "Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop. {{clock}}"
+- button "Copy"
+- button "1 tool call"
+- paragraph: DONE
+- button "Copy"
+- button "Good response"
+- button "Bad response"
+- button "Branch into a new conversation"
+- text: {{clock}}
+- textbox "Message or run a task, / commands, @ files or sessions"
+- button "Add files or run commands"
+- 'button "Access mode, current: Workspace Write"': Workspace Write
+- button "Select model, current DeepSeek-V4-Flash": DeepSeek-V4-Flash
+- button "Send message" [disabled]
+- button "1 turns 2 steps · {{throughput}} tok/s": 1 turns 2 steps{{throughput}} tok/s
+- button "15.8K tok · Cache hit 99%": 15.8K tokCache hit 99%
+- button "6% of context used": 6%
diff --git a/snapshots/web/default-workspace/workspace.expected/.empty b/snapshots/web/default-workspace/workspace.expected/.empty
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/snapshots/web/default-workspace/workspace.expected/.empty
@@ -0,0 +1 @@
+
diff --git a/snapshots/web/details-session-lifecycle/sidebar.expected.md b/snapshots/web/details-session-lifecycle/sidebar.expected.md
index 2a8b1d5955..9ae98ff006 100644
--- a/snapshots/web/details-session-lifecycle/sidebar.expected.md
+++ b/snapshots/web/details-session-lifecycle/sidebar.expected.md
@@ -17,7 +17,7 @@
   "expanded": true,
   "mode": "push",
   "panelContentWidth": 756,
-  "panelOuterWidth": 757,
+  "panelOuterWidth": 756,
   "coversViewport": false,
   "resizeHandleWidth": 8,
   "expandedDirectories": [],
@@ -246,7 +246,7 @@
   "expanded": true,
   "mode": "push",
   "panelContentWidth": 756,
-  "panelOuterWidth": 757,
+  "panelOuterWidth": 756,
   "coversViewport": false,
   "resizeHandleWidth": 8,
   "expandedDirectories": [],
@@ -281,7 +281,7 @@
   "expanded": true,
   "mode": "push",
   "panelContentWidth": 756,
-  "panelOuterWidth": 757,
+  "panelOuterWidth": 756,
   "coversViewport": false,
   "resizeHandleWidth": 8,
   "expandedDirectories": [],
diff --git a/snapshots/web/document-preview/applications.expected.md b/snapshots/web/document-preview/applications.expected.md
new file mode 100644
index 0000000000..d70632d545
--- /dev/null
+++ b/snapshots/web/document-preview/applications.expected.md
@@ -0,0 +1,4 @@
+- menu:
+  - menuitem "Test Player (default)"
+  - menuitem "Other Player"
+  - menuitem "Show file location"
diff --git a/snapshots/web/document-preview/document.expected.md b/snapshots/web/document-preview/document.expected.md
index e92c8cf01f..a2489ba886 100644
--- a/snapshots/web/document-preview/document.expected.md
+++ b/snapshots/web/document-preview/document.expected.md
@@ -17,7 +17,7 @@
 
 ## Basic HTML
 
-- Developer tools: off by default on Web and desktop
+- Developer tools: disabled for this scenario
 - Sandbox: no permissions
 - Inline script: pending
 - Local script: pending
@@ -67,11 +67,16 @@
 
 ## Office unavailable
 
-- DOC, DOCX, XLS, XLSX, PPT, PPTX viewer menus: 0 | 0 | 0 | 0 | 0 | 0
+- DOC, DOCX, PPT, PPTX viewer menus: 0 | 0 | 0 | 0
 - Guidance: Read failed: Office previews are unavailable. Enable the document preview service on the computer running DeepSeek Harness.
 - Binary text shown: false
 - Plain-text option and viewer picker: hidden
 
+## Spreadsheet preview
+
+- XLS: unsupported / Open in default app
+- XLSX: unsupported / Open in default app
+
 ## Unknown suffix
 
 - Viewer menu hidden: true
@@ -81,5 +86,5 @@
 
 - State: unsupported
 - Line: Preview is not available for this file type yet.
-- Header control: Open
-- Empty-state control: Open in default app
+- Header control has no text: true
+- Empty-state control has text: true
diff --git a/snapshots/web/feedback-command/ack-expanded.expected.md b/snapshots/web/feedback-command/ack-expanded.expected.md
index 50bc047607..d9c09956cf 100644
--- a/snapshots/web/feedback-command/ack-expanded.expected.md
+++ b/snapshots/web/feedback-command/ack-expanded.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with the single word LIGHTHOUSE and stop. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to reply with a single word. Let me comply."
+- button "Think"
 - paragraph: LIGHTHOUSE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/feedback-command/ack.expected.md b/snapshots/web/feedback-command/ack.expected.md
index d553156708..b5060084a4 100644
--- a/snapshots/web/feedback-command/ack.expected.md
+++ b/snapshots/web/feedback-command/ack.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with the single word LIGHTHOUSE and stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/feedback-release/ack-expanded.expected.md b/snapshots/web/feedback-release/ack-expanded.expected.md
index 50bc047607..d9c09956cf 100644
--- a/snapshots/web/feedback-release/ack-expanded.expected.md
+++ b/snapshots/web/feedback-release/ack-expanded.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with the single word LIGHTHOUSE and stop. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to reply with a single word. Let me comply."
+- button "Think"
 - paragraph: LIGHTHOUSE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/feedback-release/ack.expected.md b/snapshots/web/feedback-release/ack.expected.md
index d553156708..b5060084a4 100644
--- a/snapshots/web/feedback-release/ack.expected.md
+++ b/snapshots/web/feedback-release/ack.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with the single word LIGHTHOUSE and stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/file-upload-round/ui.expected.md b/snapshots/web/file-upload-round/ui.expected.md
index 6435e7d5bf..fc6a0cf362 100644
--- a/snapshots/web/file-upload-round/ui.expected.md
+++ b/snapshots/web/file-upload-round/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: poem.txt TXT 16B
 - button "reference-1.png, click to view original":
   - img "reference-1.png"
diff --git a/snapshots/web/fresh-round-trip/accepted-reconnect.expected.md b/snapshots/web/fresh-round-trip/accepted-reconnect.expected.md
new file mode 100644
index 0000000000..dca0e7be05
--- /dev/null
+++ b/snapshots/web/fresh-round-trip/accepted-reconnect.expected.md
@@ -0,0 +1,6 @@
+selected sidebar rows: 1
+new-session labels: 0
+row draggable: true
+host history blank: true
+composer: ""
+contenteditable: true
diff --git a/snapshots/web/fresh-round-trip/system-prompt.expected.md b/snapshots/web/fresh-round-trip/system-prompt.expected.md
index cc5a4013c4..e05a41da44 100644
--- a/snapshots/web/fresh-round-trip/system-prompt.expected.md
+++ b/snapshots/web/fresh-round-trip/system-prompt.expected.md
@@ -2,7 +2,7 @@ You are an AI agent powered by DeepSeek Harness.
 
 You are a coding agent powered by the deepseek-v4-flash model.
 
-Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
+Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 
 Check the [exit code: N] marker on every bash result; investigate failures before moving on.
 
diff --git a/snapshots/web/fresh-round-trip/ui-expanded.expected.md b/snapshots/web/fresh-round-trip/ui-expanded.expected.md
index 0b593347b8..1bbd83f0d9 100644
--- a/snapshots/web/fresh-round-trip/ui-expanded.expected.md
+++ b/snapshots/web/fresh-round-trip/ui-expanded.expected.md
@@ -6,14 +6,13 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to run a simple bash command and reply with \"DONE\"."
+- button "Think"
 - button "Bash Echo the test string"
-- button "Think The command executed successfully and output \"WEB_E2E_OK\". I just need to reply with \"DONE\"."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/fresh-round-trip/ui.expected.md b/snapshots/web/fresh-round-trip/ui.expected.md
index 425343834b..7988d45c0c 100644
--- a/snapshots/web/fresh-round-trip/ui.expected.md
+++ b/snapshots/web/fresh-round-trip/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use the bash tool to run exactly: echo WEB_E2E_OK. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call"
diff --git a/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md b/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md
index ffd5ea6805..7c9f533f8c 100644
--- a/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md
+++ b/snapshots/web/goal-multi-turn-actions/ui-expanded.expected.md
@@ -11,22 +11,21 @@
   - button "Jump to turn 2"
 - 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"'
-- button "System prompt"
 - button "6 tool calls" [expanded]
 - button "Context injection goal"
 - button "Context injection runtime-context"
-- 'button "Think The user''s goal is: \"做两个turn，每个turn输出随机一个包的文件结构。注意你做完一个turn之后，直接输出内容，停止，我们的系统会帮你再开一个turn，你看着做一个类似的\" — which translates to: \"Do two turns, each turn output the file structure of a random package. Note that after you finish one turn, directly output the content and stop; our system will help you open another turn, and you just do something similar.\""'
+- button "Think"
 - button "Bash List package directories deterministically"
 - button "View goal 做两个turn，每个turn输出随机一个包的文件结构。注意你做完一个turn之后，直接输出内容，停止，我们的系统会帮你再开一个turn，你看着做一个类似的"
-- 'button "Think There''s a `packages` directory. Let me look inside to see what packages are available."'
+- button "Think"
 - button "Bash List packages directory contents"
-- button "Think There are 4 packages:"
+- button "Think"
 - button "Failed Bash Randomly pick one package directory"
-- 'button "Think shuf is not available on macOS. I''ll use a different approach for random selection. Let me use $RANDOM in bash or use `sort -R` or Python."'
+- button "Think"
 - button "Bash Randomly select one package with Python"
-- 'button "Think The random pick for turn 1 is `packages/context/session-reference`. Now I''ll output its file structure. Let me get the file tree."'
+- button "Think"
 - button "Bash List all files in session-reference package"
-- 'button "Think Turn 1 is done. Per the objective: \"你做完一个turn之后，直接输出内容，停止\" — after finishing a turn, directly output the content and stop. The system will open another turn."'
+- button "Think"
 - paragraph:
   - strong: Turn 1 / 2
   - text: — 随机选中的包：
@@ -42,15 +41,14 @@
 - button "Bad response"
 - button "Branch into a new conversation"
 - text: {{clock}}
-- button "System prompt"
 - button "5 tool calls · 2 messages" [expanded]
 - button "Context injection goal"
-- 'button "Think This is turn 2 of 2. I need to randomly pick another package and output its file structure. In the first turn I picked `packages/context/session-reference`. Let me pick a different one randomly this time."'
+- button "Think"
 - button "Bash Randomly select another package with Python"
-- 'button "Think The random pick returned the same package as turn 1. Since turn 1 already covered `session-reference`, it would be better to pick a different one for variety. Let me re-roll, excluding the already-covered package."'
+- button "Think"
 - button "Bash Re-roll excluding the package from turn 1"
 - button "Bash List all files in token-meter package"
-- 'button "Think This is turn 2 of 2. I''ve output the file structure for `packages/llm/token-meter`. Both turns are done. I should output the content, stop, and then mark the goal as complete since both turns are finished."'
+- button "Think"
 - paragraph:
   - strong: Turn 2 / 2
   - text: — 随机选中的包：
diff --git a/snapshots/web/goal-multi-turn-actions/ui.expected.md b/snapshots/web/goal-multi-turn-actions/ui.expected.md
index 59dc395da6..2d7d6a5d24 100644
--- a/snapshots/web/goal-multi-turn-actions/ui.expected.md
+++ b/snapshots/web/goal-multi-turn-actions/ui.expected.md
@@ -11,7 +11,6 @@
   - button "Jump to turn 2"
 - 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"'
-- button "System prompt"
 - button "6 tool calls"
 - paragraph:
   - strong: Turn 1 / 2
@@ -28,7 +27,6 @@
 - button "Bad response"
 - button "Branch into a new conversation"
 - text: {{clock}}
-- button "System prompt"
 - button "5 tool calls · 2 messages"
 - paragraph: 两个 turn 都完成了 ✅
 - paragraph:
diff --git a/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md b/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md
index 8e1c4db5cc..8b6f7eae5f 100644
--- a/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md
+++ b/snapshots/web/lifecycle-chrome/reloaded-expanded.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with the single word LIGHTHOUSE and stop. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to reply with a single word. Let me comply."
+- button "Think"
 - paragraph: LIGHTHOUSE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/lifecycle-chrome/reloaded.expected.md b/snapshots/web/lifecycle-chrome/reloaded.expected.md
index c4bf010378..a760c82371 100644
--- a/snapshots/web/lifecycle-chrome/reloaded.expected.md
+++ b/snapshots/web/lifecycle-chrome/reloaded.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with the single word LIGHTHOUSE and stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/live-interactions/cancel-expanded.expected.md b/snapshots/web/live-interactions/cancel-expanded.expected.md
index 1cbe13209e..3813c500b7 100644
--- a/snapshots/web/live-interactions/cancel-expanded.expected.md
+++ b/snapshots/web/live-interactions/cancel-expanded.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
diff --git a/snapshots/web/live-interactions/cancel.expected.md b/snapshots/web/live-interactions/cancel.expected.md
index b30b140798..8b64580291 100644
--- a/snapshots/web/live-interactions/cancel.expected.md
+++ b/snapshots/web/live-interactions/cancel.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/live-interactions/error-auth.expected.md b/snapshots/web/live-interactions/error-auth.expected.md
index aa423c09dc..4a5dd961fe 100644
--- a/snapshots/web/live-interactions/error-auth.expected.md
+++ b/snapshots/web/live-interactions/error-auth.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/live-interactions/loading.expected.md b/snapshots/web/live-interactions/loading.expected.md
index 67b4bf71a4..4635768121 100644
--- a/snapshots/web/live-interactions/loading.expected.md
+++ b/snapshots/web/live-interactions/loading.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/live-interactions/retry-exhausted.expected.md b/snapshots/web/live-interactions/retry-exhausted.expected.md
index 0f9f0503c1..2433cb613f 100644
--- a/snapshots/web/live-interactions/retry-exhausted.expected.md
+++ b/snapshots/web/live-interactions/retry-exhausted.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/live-interactions/retry-expanded.expected.md b/snapshots/web/live-interactions/retry-expanded.expected.md
index d201eba408..5ea5441f23 100644
--- a/snapshots/web/live-interactions/retry-expanded.expected.md
+++ b/snapshots/web/live-interactions/retry-expanded.expected.md
@@ -6,14 +6,13 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
 - button "Context injection runtime-context"
 - group:
   - status: Retried model request (1/5) · {{duration}}
-- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls."
+- button "Think"
 - paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures.
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/live-interactions/retry.expected.md b/snapshots/web/live-interactions/retry.expected.md
index 435a2aac62..a122990338 100644
--- a/snapshots/web/live-interactions/retry.expected.md
+++ b/snapshots/web/live-interactions/retry.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/live-interactions/running-draft.expected.md b/snapshots/web/live-interactions/running-draft.expected.md
index 6518e42770..92ddaed171 100644
--- a/snapshots/web/live-interactions/running-draft.expected.md
+++ b/snapshots/web/live-interactions/running-draft.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/message-actions/ui.expected.md b/snapshots/web/message-actions/ui.expected.md
index df127b9b31..f4776040f5 100644
--- a/snapshots/web/message-actions/ui.expected.md
+++ b/snapshots/web/message-actions/ui.expected.md
@@ -9,11 +9,10 @@
   - button "Jump to turn 1"
   - button "Jump to turn 2"
   - button "Jump to turn 3"
-- button "System prompt"
 - text: "Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - tooltip "Copy"
-- button "Think The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."
+- button "Think"
 - paragraph: I will read both files before answering.
 - button "Copy"
 - button "Good response"
@@ -26,7 +25,6 @@
 - button "Read b.txt":
   - text: Read
   - button "b.txt"
-- button "System prompt"
 - text: Now give the final answer. {{clock}}
 - button "Copy"
 - paragraph: DONE
diff --git a/snapshots/web/minimal-preset/ui.expected.md b/snapshots/web/minimal-preset/ui.expected.md
index 3567494649..e7e695c43c 100644
--- a/snapshots/web/minimal-preset/ui.expected.md
+++ b/snapshots/web/minimal-preset/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use the bash tool to run exactly: printf 'MINIMAL_BASH_CARD_OK\\n'. Then reply exactly MINIMAL_PRESET_REQUEST_OK and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call" [expanded]
diff --git a/snapshots/web/plan-review/approved-expanded.expected.md b/snapshots/web/plan-review/approved-expanded.expected.md
index 71a77be2f5..602b7120f8 100644
--- a/snapshots/web/plan-review/approved-expanded.expected.md
+++ b/snapshots/web/plan-review/approved-expanded.expected.md
@@ -5,20 +5,17 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- text: plan Plan mode on. Use /plan off to leave.
-- button "System prompt"
-- text: "Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop. {{clock}}"
+- text: "plan Plan mode on. Use /plan off to leave. Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call · 1 message" [expanded]
 - button "Context injection runtime-context"
-- 'button "Think The user wants me to plan a small change to add a `--greeting` flag to a CLI. They explicitly told me not to read or write any files, and to call exit_plan_mode with a short plan. Let me do that directly."'
+- button "Think"
 - paragraph:
   - text: Since the user has explicitly asked me not to read or write any files and to go straight to planning, I'll proceed with
   - code: exit_plan_mode
   - text: .
 - 'button "Tool call exit_plan_mode · # Add `--greeting` flag to CLI"'
-- button "System prompt"
-- 'button "Think The plan was approved. The user''s last instruction says: \"Once the plan is approved, reply with the single word DONE and stop.\" So I should just reply with DONE and stop."'
+- button "Think"
 - paragraph: DONE
 - 'button "Open plan: Add `--greeting` flag to CLI"': "Add `--greeting` flag to CLI Plan · Markdown Open"
 - button "Copy"
diff --git a/snapshots/web/plan-review/approved.expected.md b/snapshots/web/plan-review/approved.expected.md
index 94ba2c08b5..fe52ec9268 100644
--- a/snapshots/web/plan-review/approved.expected.md
+++ b/snapshots/web/plan-review/approved.expected.md
@@ -5,12 +5,9 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- text: plan Plan mode on. Use /plan off to leave.
-- button "System prompt"
-- text: "Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop. {{clock}}"
+- text: "plan Plan mode on. Use /plan off to leave. Plan a small change: add a --greeting flag to a CLI. Do not read or write any files. Call exit_plan_mode with a short plan of at most five bullet points. Once the plan is approved, reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call · 1 message"
-- button "System prompt"
 - paragraph: DONE
 - 'button "Open plan: Add `--greeting` flag to CLI"': "Add `--greeting` flag to CLI Plan · Markdown Open"
 - button "Copy"
diff --git a/snapshots/web/present-svg/session.v4.jsonl b/snapshots/web/present-svg/session.v4.jsonl
new file mode 100644
index 0000000000..d844e49889
--- /dev/null
+++ b/snapshots/web/present-svg/session.v4.jsonl
@@ -0,0 +1,29 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1788926678903,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0,"agentPreset":"standard"}
+{"type":"permission/preset","data":{"preset":"workspace-write"}}
+{"type":"sandbox/mode","data":{"mode":"workspace-write"}}
+{"type":"approval/policy","data":{"policy":"ask"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"简单画一个 SVG 表示冯诺依曼架构, 保存为 von-neumann.svg"}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"简单画一个 SVG 表示冯诺依曼架构, 保存为 von-neumann.svg"}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}
+{"type":"session/title","data":{"title":"简单画一个 SVG 表示冯诺依曼","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants a simple SVG diagram of the von Neumann architecture, saved as von-neumann.svg. Let me create a clean SVG showing CPU (control unit, ALU), memory, input, and output with bidirectional data/control buses.\n\nLet me write the file."},{"type":"text","text":"我来创建一个冯诺依曼架构的 SVG 示意图。"},{"type":"tool-call","id":"call_00_yxav8LdZ9iwWpgkUnspF6361","name":"write","arguments":"{\"file_path\": \"{{cwd}}/von-neumann.svg\", \"content\": \"<svg xmlns=\\\"http://www.w3.org/2000/svg\\\" viewBox=\\\"0 0 900 560\\\" width=\\\"900\\\" height=\\\"560\\\" font-family=\\\"Helvetica, Arial, sans-serif\\\">\\n  <title>冯诺依曼架构</title>\\n\\n  <defs>\\n    <marker id=\\\"arrow\\\" markerWidth=\\\"10\\\" markerHeight=\\\"10\\\" refX=\\\"8\\\" refY=\\\"3\\\" orient=\\\"auto\\\">\\n      <path d=\\\"M0,0 L8,3 L0,6 Z\\\" fill=\\\"#555\\\"/>\\n    </marker>\\n  </defs>\\n\\n  <!-- Background -->\\n  <rect x=\\\"0\\\" y=\\\"0\\\" width=\\\"900\\\" height=\\\"560\\\" fill=\\\"#fafbfc\\\"/>\\n  <text x=\\\"450\\\" y=\\\"34\\\" text-anchor=\\\"middle\\\" font-size=\\\"22\\\" font-weight=\\\"bold\\\" fill=\\\"#222\\\">冯诺依曼体系结构 (Von Neumann Architecture)</text>\\n\\n  <!-- ===== CPU ===== -->\\n  <rect x=\\\"300\\\" y=\\\"70\\\" width=\\\"300\\\" height=\\\"240\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#1f6feb\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"450\\\" y=\\\"98\\\" text-anchor=\\\"middle\\\" font-size=\\\"17\\\" font-weight=\\\"bold\\\" fill=\\\"#1f6feb\\\">中央处理器 CPU</text>\\n\\n  <!-- Control Unit -->\\n  <rect x=\\\"325\\\" y=\\\"118\\\" width=\\\"120\\\" height=\\\"160\\\" rx=\\\"8\\\" fill=\\\"#ddf4ff\\\" stroke=\\\"#54aeff\\\" stroke-width=\\\"1.5\\\"/>\\n  <text x=\\\"385\\\" y=\\\"142\\\" text-anchor=\\\"middle\\\" font-size=\\\"12.5\\\" font-weight=\\\"bold\\\" fill=\\\"#0969da\\\">控制单元</text>\\n  <text x=\\\"385\\\" y=\\\"158\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#0b5394\\\">CU</text>\\n  <text x=\\\"385\\\" y=\\\"262\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">指令译码 · 时序控制</text>\\n\\n  <!-- ALU -->\\n  <rect x=\\\"455\\\" y=\\\"118\\\" width=\\\"120\\\" height=\\\"160\\\" rx=\\\"8\\\" fill=\\\"#fff8c5\\\" stroke=\\\"#d4a72c\\\" stroke-width=\\\"1.5\\\"/>\\n  <text x=\\\"515\\\" y=\\\"142\\\" text-anchor=\\\"middle\\\" font-size=\\\"12.5\\\" font-weight=\\\"bold\\\" fill=\\\"#9a6700\\\">算术逻辑单元</text>\\n  <text x=\\\"515\\\" y=\\\"158\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#7a5200\\\">ALU</text>\\n  <text x=\\\"515\\\" y=\\\"262\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">算术运算 · 逻辑运算</text>\\n\\n  <!-- Registers -->\\n  <rect x=\\\"330\\\" y=\\\"186\\\" width=\\\"110\\\" height=\\\"56\\\" rx=\\\"6\\\" fill=\\\"#fff\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.2\\\" stroke-dasharray=\\\"4,3\\\"/>\\n  <text x=\\\"385\\\" y=\\\"208\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">寄存器组</text>\\n  <text x=\\\"385\\\" y=\\\"224\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">Registers / 缓存</text>\\n\\n  <!-- ===== Memory ===== -->\\n  <rect x=\\\"300\\\" y=\\\"400\\\" width=\\\"300\\\" height=\\\"110\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#cf222e\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"450\\\" y=\\\"428\\\" text-anchor=\\\"middle\\\" font-size=\\\"17\\\" font-weight=\\\"bold\\\" fill=\\\"#cf222e\\\">内存储器 Memory</text>\\n  <text x=\\\"450\\\" y=\\\"452\\\" text-anchor=\\\"middle\\\" font-size=\\\"12\\\" fill=\\\"#444\\\">存储单元: 指令和数据</text>\\n  <text x=\\\"450\\\" y=\\\"470\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#666\\\">(存放程序与数据，同一总线存取)</text>\\n\\n  <!-- ===== Input ===== -->\\n  <rect x=\\\"40\\\" y=\\\"150\\\" width=\\\"170\\\" height=\\\"120\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#1a7f37\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"125\\\" y=\\\"186\\\" text-anchor=\\\"middle\\\" font-size=\\\"15\\\" font-weight=\\\"bold\\\" fill=\\\"#1a7f37\\\">输入设备</text>\\n  <text x=\\\"125\\\" y=\\\"206\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">Input</text>\\n  <text x=\\\"125\\\" y=\\\"238\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">键盘 · 鼠标 · 磁盘</text>\\n\\n  <!-- ===== Output ===== -->\\n  <rect x=\\\"690\\\" y=\\\"150\\\" width=\\\"170\\\" height=\\\"120\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#bf3989\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"775\\\" y=\\\"186\\\" text-anchor=\\\"middle\\\" font-size=\\\"15\\\" font-weight=\\\"bold\\\" fill=\\\"#bf3989\\\">输出设备</text>\\n  <text x=\\\"775\\\" y=\\\"206\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">Output</text>\\n  <text x=\\\"775\\\" y=\\\"238\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">显示器 · 打印机</text>\\n\\n  <!-- ===== Bus lines ===== -->\\n  <!-- Address bus CPU <-> Memory (red) -->\\n  <path d=\\\"M450,320 L450,398\\\" fill=\\\"none\\\" stroke=\\\"#cf222e\\\" stroke-width=\\\"3\\\"/>\\n  <text x=\\\"420\\\" y=\\\"362\\\" text-anchor=\\\"end\\\" font-size=\\\"11\\\" fill=\\\"#cf222e\\\" transform=\\\"rotate(-90 420 362)\\\">地址总线</text>\\n\\n  <!-- Data/control bus label along the bottom -->\\n  <line x1=\\\"300\\\" y1=\\\"355\\\" x2=\\\"600\\\" y2=\\\"355\\\" stroke=\\\"#555\\\" stroke-width=\\\"1\\\" stroke-dasharray=\\\"2,3\\\" opacity=\\\"0.0\\\"/>\\n  <text x=\\\"450\\\" y=\\\"353\\\" text-anchor=\\\"middle\\\" font-size=\\\"12\\\" font-weight=\\\"bold\\\" fill=\\\"#555\\\">← 数据总线 / 控制总线 →</text>\\n\\n  <!-- CPU <-> Input (bidirectional-ish: input data in + control out) -->\\n  <path d=\\\"M212,210 L298,210\\\" fill=\\\"none\\\" stroke=\\\"#1a7f37\\\" stroke-width=\\\"3\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <path d=\\\"M212,196 L298,196\\\" fill=\\\"none\\\" stroke=\\\"#555\\\" stroke-width=\\\"2\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"255\\\" y=\\\"184\\\" text-anchor=\\\"middle\\\" font-size=\\\"10.5\\\" fill=\\\"#1a7f37\\\">数据(输入)</text>\\n  <text x=\\\"255\\\" y=\\\"236\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">控制</text>\\n\\n  <!-- CPU <-> Output -->\\n  <path d=\\\"M602,210 L688,210\\\" fill=\\\"none\\\" stroke=\\\"#bf3989\\\" stroke-width=\\\"3\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <path d=\\\"M602,196 L688,196\\\" fill=\\\"none\\\" stroke=\\\"#555\\\" stroke-width=\\\"2\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"645\\\" y=\\\"184\\\" text-anchor=\\\"middle\\\" font-size=\\\"10.5\\\" fill=\\\"#bf3989\\\">数据(输出)</text>\\n  <text x=\\\"645\\\" y=\\\"236\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">控制</text>\\n\\n  <!-- Memory <-> Input/Output hints: 存储器与 I/O 也通过总线交换 -->\\n  <path d=\\\"M125,272 L125,300 Q125,340 175,340 L298,340\\\" fill=\\\"none\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.8\\\" stroke-dasharray=\\\"6,4\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"160\\\" y=\\\"328\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\" transform=\\\"rotate(-8 160 328)\\\">总线</text>\\n\\n  <path d=\\\"M775,272 L775,300 Q775,340 725,340 L602,340\\\" fill=\\\"none\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.8\\\" stroke-dasharray=\\\"6,4\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"740\\\" y=\\\"328\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\" transform=\\\"rotate(8 740 328)\\\">总线</text>\\n\\n  <!-- Stored-program note -->\\n  <text x=\\\"450\\\" y=\\\"530\\\" text-anchor=\\\"middle\\\" font-size=\\\"11.5\\\" fill=\\\"#666\\\">核心思想: 指令与数据以二进制形式统一存放在存储器中 —— “存储程序”</text>\\n</svg>\\n\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":7197,"outputTokens":2153,"totalTokens":10502,"cacheReadTokens":1152,"reasoningTokens":55},"stream":[{"type":"chunk","time":1789457782571,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789457782571,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," a"," simple"," SVG"," diagram"," of"," the"," von"," Neumann"," architecture",","," saved"," as"," von","-","neum","ann",".svg","."," Let"," me"," create"," a"," clean"," SVG"," showing"," CPU"," (","control"," unit",","," AL","U","),"," memory",","," input",","," and"," output"," with"," bidirectional"," data","/","control"," buses",".\n\n","Let"," me"," write"," the"," file","."]},{"type":"chunk","time":1789457782572,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1789457782572,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0],"texts":["我来","创建一个","冯","诺","依","曼","架构","的"," SVG"," ","示意图","。"]},{"type":"chunk","time":1789457782572,"chunk":{"type":"block-start","index":2,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789457782572,"index":2,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_yxav8LdZ9iwWpgkUnspF6361","name":"write","args":["","{","\"","file","_path","\"",": ","\"","/","private","/","var","/f","old","ers","/n","5","/f","339","h","wh","15","_g","f","4","gk","8","ns","rt","9","qm","400","00","gn","/T","/d","sh","-web","-e","2","e","-w","s","-g","Ou","Z","JC","/","works","pace","/v","on","-","neum","ann",".svg","\"",", ","\"","content","\"",": ","\"","<","svg"," xmlns","=\\\"","http","://","www",".w","3",".org","/","200","0","/s","vg","\\\""," view","Box","=\\\"","0"," ","0"," ","900"," ","560","\\\""," width","=\\\"","900","\\\""," height","=\\\"","560","\\\""," font","-family","=\\\"","Hel","vetica",","," A","rial",","," sans","-serif","\\\">\\n"," "," <","title",">","冯","诺","依","曼","架构","</","title",">\\n\\n"," "," <","def","s",">\\n","   "," <","mark","er"," id","=\\\"","arrow","\\\""," marker","Width","=\\\"","10","\\\""," marker","Height","=\\\"","10","\\\""," ref","X","=\\\"","8","\\\""," ref","Y","=\\\"","3","\\\""," orient","=\\\"","auto","\\\">\\n","     "," <","path"," d","=\\\"","M","0",",","0"," L","8",",","3"," L","0",",","6"," Z","\\\""," fill","=\\\"#","555","\\\"/>\\n","   "," </","mark","er",">\\n"," "," </","def","s",">\\n\\n"," "," <!--"," Background"," -->\\n"," "," <","rect"," x","=\\\"","0","\\\""," y","=\\\"","0","\\\""," width","=\\\"","900","\\\""," height","=\\\"","560","\\\""," fill","=\\\"#","f","af","bf","c","\\\"/>\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","34","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","22","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","222","\\\">","冯","诺","依","曼","体系","结构"," (","Von"," Neumann"," Architecture",")</","text",">\\n\\n"," "," <!--"," =","===="," CPU"," =","===="," -->\\n"," "," <","rect"," x","=\\\"","300","\\\""," y","=\\\"","70","\\\""," width","=\\\"","300","\\\""," height","=\\\"","240","\\\""," rx","=\\\"","10","\\\""," fill","=\\\"#","fff","\\\""," stroke","=\\\"#","1","f","6","f","eb","\\\""," stroke","-width","=\\\"","2",".","5","\\\"/>\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","98","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","17","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","1","f","6","f","eb","\\\">","中央","处理器"," CPU","</","text",">\\n\\n"," "," <!--"," Control"," Unit"," -->\\n"," "," <","rect"," x","=\\\"","325","\\\""," y","=\\\"","118","\\\""," width","=\\\"","120","\\\""," height","=\\\"","160","\\\""," rx","=\\\"","8","\\\""," fill","=\\\"#","d","df","4","ff","\\\""," stroke","=\\\"#","54","ae","ff","\\\""," stroke","-width","=\\\"","1",".","5","\\\"/>\\n"," "," <","text"," x","=\\\"","385","\\\""," y","=\\\"","142","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","12",".","5","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","096","9","da","\\\">","控制","单元","</","text",">\\n"," "," <","text"," x","=\\\"","385","\\\""," y","=\\\"","158","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","0","b","539","4","\\\">","CU","</","text",">\\n"," "," <","text"," x","=\\\"","385","\\\""," y","=\\\"","262","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","555","\\\">","指令","译","码"," ·"," ","时序","控制","</","text",">\\n\\n"," "," <!--"," AL","U"," -->\\n"," "," <","rect"," x","=\\\"","455","\\\""," y","=\\\"","118","\\\""," width","=\\\"","120","\\\""," height","=\\\"","160","\\\""," rx","=\\\"","8","\\\""," fill","=\\\"#","fff","8","c","5","\\\""," stroke","=\\\"#","d","4","a","72","c","\\\""," stroke","-width","=\\\"","1",".","5","\\\"/>\\n"," "," <","text"," x","=\\\"","515","\\\""," y","=\\\"","142","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","12",".","5","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","9","a","670","0","\\\">","算术","逻辑","单元","</","text",">\\n"," "," <","text"," x","=\\\"","515","\\\""," y","=\\\"","158","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","7","a","520","0","\\\">","ALU","</","text",">\\n"," "," <","text"," x","=\\\"","515","\\\""," y","=\\\"","262","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","555","\\\">","算术","运算"," ·"," ","逻辑","运算","</","text",">\\n\\n"," "," <!--"," Reg","isters"," -->\\n"," "," <","rect"," x","=\\\"","330","\\\""," y","=\\\"","186","\\\""," width","=\\\"","110","\\\""," height","=\\\"","56","\\\""," rx","=\\\"","6","\\\""," fill","=\\\"#","fff","\\\""," stroke","=\\\"#","8","c","959","f","\\\""," stroke","-width","=\\\"","1",".","2","\\\""," stroke","-d","ash","array","=\\\"","4",",","3","\\\"/>\\n"," "," <","text"," x","=\\\"","385","\\\""," y","=\\\"","208","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","444","\\\">","寄存器","组","</","text",">\\n"," "," <","text"," x","=\\\"","385","\\\""," y","=\\\"","224","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","666","\\\">","Reg","isters"," /"," ","缓存","</","text",">\\n\\n"," "," <!--"," =","===="," Memory"," =","===="," -->\\n"," "," <","rect"," x","=\\\"","300","\\\""," y","=\\\"","400","\\\""," width","=\\\"","300","\\\""," height","=\\\"","110","\\\""," rx","=\\\"","10","\\\""," fill","=\\\"#","fff","\\\""," stroke","=\\\"#","cf","222","e","\\\""," stroke","-width","=\\\"","2",".","5","\\\"/>\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","428","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","17","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","cf","222","e","\\\">","内","存储器"," Memory","</","text",">\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","452","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","12","\\\""," fill","=\\\"#","444","\\\">","存储","单元",":"," ","指令","和数据","</","text",">\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","470","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","666","\\\">","(","存放","程序","与","数据","，","同一","总线","存取",")</","text",">\\n\\n"," "," <!--"," =","===="," Input"," =","===="," -->\\n"," "," <","rect"," x","=\\\"","40","\\\""," y","=\\\"","150","\\\""," width","=\\\"","170","\\\""," height","=\\\"","120","\\\""," rx","=\\\"","10","\\\""," fill","=\\\"#","fff","\\\""," stroke","=\\\"#","1","a","7","f","37","\\\""," stroke","-width","=\\\"","2",".","5","\\\"/>\\n"," "," <","text"," x","=\\\"","125","\\\""," y","=\\\"","186","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","15","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","1","a","7","f","37","\\\">","输入","设备","</","text",">\\n"," "," <","text"," x","=\\\"","125","\\\""," y","=\\\"","206","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","444","\\\">","Input","</","text",">\\n"," "," <","text"," x","=\\\"","125","\\\""," y","=\\\"","238","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","666","\\\">","键盘"," ·"," ","鼠标"," ·"," ","磁盘","</","text",">\\n\\n"," "," <!--"," =","===="," Output"," =","===="," -->\\n"," "," <","rect"," x","=\\\"","690","\\\""," y","=\\\"","150","\\\""," width","=\\\"","170","\\\""," height","=\\\"","120","\\\""," rx","=\\\"","10","\\\""," fill","=\\\"#","fff","\\\""," stroke","=\\\"#","bf","398","9","\\\""," stroke","-width","=\\\"","2",".","5","\\\"/>\\n"," "," <","text"," x","=\\\"","775","\\\""," y","=\\\"","186","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","15","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","bf","398","9","\\\">","输出","设备","</","text",">\\n"," "," <","text"," x","=\\\"","775","\\\""," y","=\\\"","206","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","444","\\\">","Output","</","text",">\\n"," "," <","text"," x","=\\\"","775","\\\""," y","=\\\"","238","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","666","\\\">","显示器"," ·"," ","打印机","</","text",">\\n\\n"," "," <!--"," =","===="," Bus"," lines"," =","===="," -->\\n"," "," <!--"," Address"," bus"," CPU"," <","->"," Memory"," (","red",")"," -->\\n"," "," <","path"," d","=\\\"","M","450",",","320"," L","450",",","398","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","cf","222","e","\\\""," stroke","-width","=\\\"","3","\\\"/>\\n"," "," <","text"," x","=\\\"","420","\\\""," y","=\\\"","362","\\\""," text","-an","chor","=\\\"","end","\\\""," font","-size","=\\\"","11","\\\""," fill","=\\\"#","cf","222","e","\\\""," transform","=\\\"","rotate","(-","90"," ","420"," ","362",")","\\\">","地址","总线","</","text",">\\n\\n"," "," <!--"," Data","/","control"," bus"," label"," along"," the"," bottom"," -->\\n"," "," <","line"," x","1","=\\\"","300","\\\""," y","1","=\\\"","355","\\\""," x","2","=\\\"","600","\\\""," y","2","=\\\"","355","\\\""," stroke","=\\\"#","555","\\\""," stroke","-width","=\\\"","1","\\\""," stroke","-d","ash","array","=\\\"","2",",","3","\\\""," opacity","=\\\"","0",".","0","\\\"/>\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","353","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","12","\\\""," font","-weight","=\\\"","bold","\\\""," fill","=\\\"#","555","\\\">","←"," ","数据","总线"," /"," ","控制","总线"," →","</","text",">\\n\\n"," "," <!--"," CPU"," <","->"," Input"," (","bid","irectional","-ish",":"," input"," data"," in"," +"," control"," out",")"," -->\\n"," "," <","path"," d","=\\\"","M","212",",","210"," L","298",",","210","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","1","a","7","f","37","\\\""," stroke","-width","=\\\"","3","\\\""," marker","-end","=\\\"","url","(#","arrow",")","\\\"/>\\n"," "," <","path"," d","=\\\"","M","212",",","196"," L","298",",","196","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","555","\\\""," stroke","-width","=\\\"","2","\\\""," marker","-end","=\\\"","url","(#","arrow",")","\\\"/>\\n"," "," <","text"," x","=\\\"","255","\\\""," y","=\\\"","184","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10",".","5","\\\""," fill","=\\\"#","1","a","7","f","37","\\\">","数据","(","输入",")</","text",">\\n"," "," <","text"," x","=\\\"","255","\\\""," y","=\\\"","236","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","555","\\\">","控制","</","text",">\\n\\n"," "," <!--"," CPU"," <","->"," Output"," -->\\n"," "," <","path"," d","=\\\"","M","602",",","210"," L","688",",","210","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","bf","398","9","\\\""," stroke","-width","=\\\"","3","\\\""," marker","-end","=\\\"","url","(#","arrow",")","\\\"/>\\n"," "," <","path"," d","=\\\"","M","602",",","196"," L","688",",","196","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","555","\\\""," stroke","-width","=\\\"","2","\\\""," marker","-end","=\\\"","url","(#","arrow",")","\\\"/>\\n"," "," <","text"," x","=\\\"","645","\\\""," y","=\\\"","184","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10",".","5","\\\""," fill","=\\\"#","bf","398","9","\\\">","数据","(","输出",")</","text",">\\n"," "," <","text"," x","=\\\"","645","\\\""," y","=\\\"","236","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","555","\\\">","控制","</","text",">\\n\\n"," "," <!--"," Memory"," <","->"," Input","/","Output"," hints",":"," ","存储器","与"," I","/O"," ","也","通过","总线","交换"," -->\\n"," "," <","path"," d","=\\\"","M","125",",","272"," L","125",",","300"," Q","125",",","340"," ","175",",","340"," L","298",",","340","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","8","c","959","f","\\\""," stroke","-width","=\\\"","1",".","8","\\\""," stroke","-d","ash","array","=\\\"","6",",","4","\\\""," marker","-end","=\\\"","url","(#","arrow",")","\\\"/>\\n"," "," <","text"," x","=\\\"","160","\\\""," y","=\\\"","328","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","666","\\\""," transform","=\\\"","rotate","(-","8"," ","160"," ","328",")","\\\">","总线","</","text",">\\n\\n"," "," <","path"," d","=\\\"","M","775",",","272"," L","775",",","300"," Q","775",",","340"," ","725",",","340"," L","602",",","340","\\\""," fill","=\\\"","none","\\\""," stroke","=\\\"#","8","c","959","f","\\\""," stroke","-width","=\\\"","1",".","8","\\\""," stroke","-d","ash","array","=\\\"","6",",","4","\\\""," marker","-end","=\\\"","url","(#","arrow",")","\\\"/>\\n"," "," <","text"," x","=\\\"","740","\\\""," y","=\\\"","328","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","10","\\\""," fill","=\\\"#","666","\\\""," transform","=\\\"","rotate","(","8"," ","740"," ","328",")","\\\">","总线","</","text",">\\n\\n"," "," <!--"," St","ored","-program"," note"," -->\\n"," "," <","text"," x","=\\\"","450","\\\""," y","=\\\"","530","\\\""," text","-an","chor","=\\\"","middle","\\\""," font","-size","=\\\"","11",".","5","\\\""," fill","=\\\"#","666","\\\">","核心","思想",":"," ","指令","与","数据","以","二进制","形式","统一","存放在","存储器","中"," ——"," “","存储","程序","”","</","text",">\\n","</","svg",">\\n","\"","}"]},{"type":"chunk","time":1789457782585,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants a simple SVG diagram of the von Neumann architecture, saved as von-neumann.svg. Let me create a clean SVG showing CPU (control unit, ALU), memory, input, and output with bidirectional data/control buses.\n\nLet me write the file."}}},{"type":"chunk","time":1789457782585,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"我来创建一个冯诺依曼架构的 SVG 示意图。"}}},{"type":"chunk","time":1789457782585,"chunk":{"type":"block-end","index":2,"block":{"type":"tool-call","id":"call_00_yxav8LdZ9iwWpgkUnspF6361","name":"write","arguments":"{\"file_path\": \"{{cwd}}/von-neumann.svg\", \"content\": \"<svg xmlns=\\\"http://www.w3.org/2000/svg\\\" viewBox=\\\"0 0 900 560\\\" width=\\\"900\\\" height=\\\"560\\\" font-family=\\\"Helvetica, Arial, sans-serif\\\">\\n  <title>冯诺依曼架构</title>\\n\\n  <defs>\\n    <marker id=\\\"arrow\\\" markerWidth=\\\"10\\\" markerHeight=\\\"10\\\" refX=\\\"8\\\" refY=\\\"3\\\" orient=\\\"auto\\\">\\n      <path d=\\\"M0,0 L8,3 L0,6 Z\\\" fill=\\\"#555\\\"/>\\n    </marker>\\n  </defs>\\n\\n  <!-- Background -->\\n  <rect x=\\\"0\\\" y=\\\"0\\\" width=\\\"900\\\" height=\\\"560\\\" fill=\\\"#fafbfc\\\"/>\\n  <text x=\\\"450\\\" y=\\\"34\\\" text-anchor=\\\"middle\\\" font-size=\\\"22\\\" font-weight=\\\"bold\\\" fill=\\\"#222\\\">冯诺依曼体系结构 (Von Neumann Architecture)</text>\\n\\n  <!-- ===== CPU ===== -->\\n  <rect x=\\\"300\\\" y=\\\"70\\\" width=\\\"300\\\" height=\\\"240\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#1f6feb\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"450\\\" y=\\\"98\\\" text-anchor=\\\"middle\\\" font-size=\\\"17\\\" font-weight=\\\"bold\\\" fill=\\\"#1f6feb\\\">中央处理器 CPU</text>\\n\\n  <!-- Control Unit -->\\n  <rect x=\\\"325\\\" y=\\\"118\\\" width=\\\"120\\\" height=\\\"160\\\" rx=\\\"8\\\" fill=\\\"#ddf4ff\\\" stroke=\\\"#54aeff\\\" stroke-width=\\\"1.5\\\"/>\\n  <text x=\\\"385\\\" y=\\\"142\\\" text-anchor=\\\"middle\\\" font-size=\\\"12.5\\\" font-weight=\\\"bold\\\" fill=\\\"#0969da\\\">控制单元</text>\\n  <text x=\\\"385\\\" y=\\\"158\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#0b5394\\\">CU</text>\\n  <text x=\\\"385\\\" y=\\\"262\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">指令译码 · 时序控制</text>\\n\\n  <!-- ALU -->\\n  <rect x=\\\"455\\\" y=\\\"118\\\" width=\\\"120\\\" height=\\\"160\\\" rx=\\\"8\\\" fill=\\\"#fff8c5\\\" stroke=\\\"#d4a72c\\\" stroke-width=\\\"1.5\\\"/>\\n  <text x=\\\"515\\\" y=\\\"142\\\" text-anchor=\\\"middle\\\" font-size=\\\"12.5\\\" font-weight=\\\"bold\\\" fill=\\\"#9a6700\\\">算术逻辑单元</text>\\n  <text x=\\\"515\\\" y=\\\"158\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#7a5200\\\">ALU</text>\\n  <text x=\\\"515\\\" y=\\\"262\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">算术运算 · 逻辑运算</text>\\n\\n  <!-- Registers -->\\n  <rect x=\\\"330\\\" y=\\\"186\\\" width=\\\"110\\\" height=\\\"56\\\" rx=\\\"6\\\" fill=\\\"#fff\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.2\\\" stroke-dasharray=\\\"4,3\\\"/>\\n  <text x=\\\"385\\\" y=\\\"208\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">寄存器组</text>\\n  <text x=\\\"385\\\" y=\\\"224\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">Registers / 缓存</text>\\n\\n  <!-- ===== Memory ===== -->\\n  <rect x=\\\"300\\\" y=\\\"400\\\" width=\\\"300\\\" height=\\\"110\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#cf222e\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"450\\\" y=\\\"428\\\" text-anchor=\\\"middle\\\" font-size=\\\"17\\\" font-weight=\\\"bold\\\" fill=\\\"#cf222e\\\">内存储器 Memory</text>\\n  <text x=\\\"450\\\" y=\\\"452\\\" text-anchor=\\\"middle\\\" font-size=\\\"12\\\" fill=\\\"#444\\\">存储单元: 指令和数据</text>\\n  <text x=\\\"450\\\" y=\\\"470\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#666\\\">(存放程序与数据，同一总线存取)</text>\\n\\n  <!-- ===== Input ===== -->\\n  <rect x=\\\"40\\\" y=\\\"150\\\" width=\\\"170\\\" height=\\\"120\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#1a7f37\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"125\\\" y=\\\"186\\\" text-anchor=\\\"middle\\\" font-size=\\\"15\\\" font-weight=\\\"bold\\\" fill=\\\"#1a7f37\\\">输入设备</text>\\n  <text x=\\\"125\\\" y=\\\"206\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">Input</text>\\n  <text x=\\\"125\\\" y=\\\"238\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">键盘 · 鼠标 · 磁盘</text>\\n\\n  <!-- ===== Output ===== -->\\n  <rect x=\\\"690\\\" y=\\\"150\\\" width=\\\"170\\\" height=\\\"120\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#bf3989\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"775\\\" y=\\\"186\\\" text-anchor=\\\"middle\\\" font-size=\\\"15\\\" font-weight=\\\"bold\\\" fill=\\\"#bf3989\\\">输出设备</text>\\n  <text x=\\\"775\\\" y=\\\"206\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">Output</text>\\n  <text x=\\\"775\\\" y=\\\"238\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">显示器 · 打印机</text>\\n\\n  <!-- ===== Bus lines ===== -->\\n  <!-- Address bus CPU <-> Memory (red) -->\\n  <path d=\\\"M450,320 L450,398\\\" fill=\\\"none\\\" stroke=\\\"#cf222e\\\" stroke-width=\\\"3\\\"/>\\n  <text x=\\\"420\\\" y=\\\"362\\\" text-anchor=\\\"end\\\" font-size=\\\"11\\\" fill=\\\"#cf222e\\\" transform=\\\"rotate(-90 420 362)\\\">地址总线</text>\\n\\n  <!-- Data/control bus label along the bottom -->\\n  <line x1=\\\"300\\\" y1=\\\"355\\\" x2=\\\"600\\\" y2=\\\"355\\\" stroke=\\\"#555\\\" stroke-width=\\\"1\\\" stroke-dasharray=\\\"2,3\\\" opacity=\\\"0.0\\\"/>\\n  <text x=\\\"450\\\" y=\\\"353\\\" text-anchor=\\\"middle\\\" font-size=\\\"12\\\" font-weight=\\\"bold\\\" fill=\\\"#555\\\">← 数据总线 / 控制总线 →</text>\\n\\n  <!-- CPU <-> Input (bidirectional-ish: input data in + control out) -->\\n  <path d=\\\"M212,210 L298,210\\\" fill=\\\"none\\\" stroke=\\\"#1a7f37\\\" stroke-width=\\\"3\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <path d=\\\"M212,196 L298,196\\\" fill=\\\"none\\\" stroke=\\\"#555\\\" stroke-width=\\\"2\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"255\\\" y=\\\"184\\\" text-anchor=\\\"middle\\\" font-size=\\\"10.5\\\" fill=\\\"#1a7f37\\\">数据(输入)</text>\\n  <text x=\\\"255\\\" y=\\\"236\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">控制</text>\\n\\n  <!-- CPU <-> Output -->\\n  <path d=\\\"M602,210 L688,210\\\" fill=\\\"none\\\" stroke=\\\"#bf3989\\\" stroke-width=\\\"3\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <path d=\\\"M602,196 L688,196\\\" fill=\\\"none\\\" stroke=\\\"#555\\\" stroke-width=\\\"2\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"645\\\" y=\\\"184\\\" text-anchor=\\\"middle\\\" font-size=\\\"10.5\\\" fill=\\\"#bf3989\\\">数据(输出)</text>\\n  <text x=\\\"645\\\" y=\\\"236\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">控制</text>\\n\\n  <!-- Memory <-> Input/Output hints: 存储器与 I/O 也通过总线交换 -->\\n  <path d=\\\"M125,272 L125,300 Q125,340 175,340 L298,340\\\" fill=\\\"none\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.8\\\" stroke-dasharray=\\\"6,4\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"160\\\" y=\\\"328\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\" transform=\\\"rotate(-8 160 328)\\\">总线</text>\\n\\n  <path d=\\\"M775,272 L775,300 Q775,340 725,340 L602,340\\\" fill=\\\"none\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.8\\\" stroke-dasharray=\\\"6,4\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"740\\\" y=\\\"328\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\" transform=\\\"rotate(8 740 328)\\\">总线</text>\\n\\n  <!-- Stored-program note -->\\n  <text x=\\\"450\\\" y=\\\"530\\\" text-anchor=\\\"middle\\\" font-size=\\\"11.5\\\" fill=\\\"#666\\\">核心思想: 指令与数据以二进制形式统一存放在存储器中 —— “存储程序”</text>\\n</svg>\\n\"}"}}},{"type":"chunk","time":1789457782585,"chunk":{"type":"usage","usage":{"inputTokens":7197,"outputTokens":2153,"totalTokens":10502,"cacheReadTokens":1152,"reasoningTokens":55}}},{"type":"chunk","time":1789457782585,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_yxav8LdZ9iwWpgkUnspF6361","name":"write","arguments":"{\"file_path\": \"{{cwd}}/von-neumann.svg\", \"content\": \"<svg xmlns=\\\"http://www.w3.org/2000/svg\\\" viewBox=\\\"0 0 900 560\\\" width=\\\"900\\\" height=\\\"560\\\" font-family=\\\"Helvetica, Arial, sans-serif\\\">\\n  <title>冯诺依曼架构</title>\\n\\n  <defs>\\n    <marker id=\\\"arrow\\\" markerWidth=\\\"10\\\" markerHeight=\\\"10\\\" refX=\\\"8\\\" refY=\\\"3\\\" orient=\\\"auto\\\">\\n      <path d=\\\"M0,0 L8,3 L0,6 Z\\\" fill=\\\"#555\\\"/>\\n    </marker>\\n  </defs>\\n\\n  <!-- Background -->\\n  <rect x=\\\"0\\\" y=\\\"0\\\" width=\\\"900\\\" height=\\\"560\\\" fill=\\\"#fafbfc\\\"/>\\n  <text x=\\\"450\\\" y=\\\"34\\\" text-anchor=\\\"middle\\\" font-size=\\\"22\\\" font-weight=\\\"bold\\\" fill=\\\"#222\\\">冯诺依曼体系结构 (Von Neumann Architecture)</text>\\n\\n  <!-- ===== CPU ===== -->\\n  <rect x=\\\"300\\\" y=\\\"70\\\" width=\\\"300\\\" height=\\\"240\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#1f6feb\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"450\\\" y=\\\"98\\\" text-anchor=\\\"middle\\\" font-size=\\\"17\\\" font-weight=\\\"bold\\\" fill=\\\"#1f6feb\\\">中央处理器 CPU</text>\\n\\n  <!-- Control Unit -->\\n  <rect x=\\\"325\\\" y=\\\"118\\\" width=\\\"120\\\" height=\\\"160\\\" rx=\\\"8\\\" fill=\\\"#ddf4ff\\\" stroke=\\\"#54aeff\\\" stroke-width=\\\"1.5\\\"/>\\n  <text x=\\\"385\\\" y=\\\"142\\\" text-anchor=\\\"middle\\\" font-size=\\\"12.5\\\" font-weight=\\\"bold\\\" fill=\\\"#0969da\\\">控制单元</text>\\n  <text x=\\\"385\\\" y=\\\"158\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#0b5394\\\">CU</text>\\n  <text x=\\\"385\\\" y=\\\"262\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">指令译码 · 时序控制</text>\\n\\n  <!-- ALU -->\\n  <rect x=\\\"455\\\" y=\\\"118\\\" width=\\\"120\\\" height=\\\"160\\\" rx=\\\"8\\\" fill=\\\"#fff8c5\\\" stroke=\\\"#d4a72c\\\" stroke-width=\\\"1.5\\\"/>\\n  <text x=\\\"515\\\" y=\\\"142\\\" text-anchor=\\\"middle\\\" font-size=\\\"12.5\\\" font-weight=\\\"bold\\\" fill=\\\"#9a6700\\\">算术逻辑单元</text>\\n  <text x=\\\"515\\\" y=\\\"158\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#7a5200\\\">ALU</text>\\n  <text x=\\\"515\\\" y=\\\"262\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">算术运算 · 逻辑运算</text>\\n\\n  <!-- Registers -->\\n  <rect x=\\\"330\\\" y=\\\"186\\\" width=\\\"110\\\" height=\\\"56\\\" rx=\\\"6\\\" fill=\\\"#fff\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.2\\\" stroke-dasharray=\\\"4,3\\\"/>\\n  <text x=\\\"385\\\" y=\\\"208\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">寄存器组</text>\\n  <text x=\\\"385\\\" y=\\\"224\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">Registers / 缓存</text>\\n\\n  <!-- ===== Memory ===== -->\\n  <rect x=\\\"300\\\" y=\\\"400\\\" width=\\\"300\\\" height=\\\"110\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#cf222e\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"450\\\" y=\\\"428\\\" text-anchor=\\\"middle\\\" font-size=\\\"17\\\" font-weight=\\\"bold\\\" fill=\\\"#cf222e\\\">内存储器 Memory</text>\\n  <text x=\\\"450\\\" y=\\\"452\\\" text-anchor=\\\"middle\\\" font-size=\\\"12\\\" fill=\\\"#444\\\">存储单元: 指令和数据</text>\\n  <text x=\\\"450\\\" y=\\\"470\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#666\\\">(存放程序与数据，同一总线存取)</text>\\n\\n  <!-- ===== Input ===== -->\\n  <rect x=\\\"40\\\" y=\\\"150\\\" width=\\\"170\\\" height=\\\"120\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#1a7f37\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"125\\\" y=\\\"186\\\" text-anchor=\\\"middle\\\" font-size=\\\"15\\\" font-weight=\\\"bold\\\" fill=\\\"#1a7f37\\\">输入设备</text>\\n  <text x=\\\"125\\\" y=\\\"206\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">Input</text>\\n  <text x=\\\"125\\\" y=\\\"238\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">键盘 · 鼠标 · 磁盘</text>\\n\\n  <!-- ===== Output ===== -->\\n  <rect x=\\\"690\\\" y=\\\"150\\\" width=\\\"170\\\" height=\\\"120\\\" rx=\\\"10\\\" fill=\\\"#fff\\\" stroke=\\\"#bf3989\\\" stroke-width=\\\"2.5\\\"/>\\n  <text x=\\\"775\\\" y=\\\"186\\\" text-anchor=\\\"middle\\\" font-size=\\\"15\\\" font-weight=\\\"bold\\\" fill=\\\"#bf3989\\\">输出设备</text>\\n  <text x=\\\"775\\\" y=\\\"206\\\" text-anchor=\\\"middle\\\" font-size=\\\"11\\\" fill=\\\"#444\\\">Output</text>\\n  <text x=\\\"775\\\" y=\\\"238\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\">显示器 · 打印机</text>\\n\\n  <!-- ===== Bus lines ===== -->\\n  <!-- Address bus CPU <-> Memory (red) -->\\n  <path d=\\\"M450,320 L450,398\\\" fill=\\\"none\\\" stroke=\\\"#cf222e\\\" stroke-width=\\\"3\\\"/>\\n  <text x=\\\"420\\\" y=\\\"362\\\" text-anchor=\\\"end\\\" font-size=\\\"11\\\" fill=\\\"#cf222e\\\" transform=\\\"rotate(-90 420 362)\\\">地址总线</text>\\n\\n  <!-- Data/control bus label along the bottom -->\\n  <line x1=\\\"300\\\" y1=\\\"355\\\" x2=\\\"600\\\" y2=\\\"355\\\" stroke=\\\"#555\\\" stroke-width=\\\"1\\\" stroke-dasharray=\\\"2,3\\\" opacity=\\\"0.0\\\"/>\\n  <text x=\\\"450\\\" y=\\\"353\\\" text-anchor=\\\"middle\\\" font-size=\\\"12\\\" font-weight=\\\"bold\\\" fill=\\\"#555\\\">← 数据总线 / 控制总线 →</text>\\n\\n  <!-- CPU <-> Input (bidirectional-ish: input data in + control out) -->\\n  <path d=\\\"M212,210 L298,210\\\" fill=\\\"none\\\" stroke=\\\"#1a7f37\\\" stroke-width=\\\"3\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <path d=\\\"M212,196 L298,196\\\" fill=\\\"none\\\" stroke=\\\"#555\\\" stroke-width=\\\"2\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"255\\\" y=\\\"184\\\" text-anchor=\\\"middle\\\" font-size=\\\"10.5\\\" fill=\\\"#1a7f37\\\">数据(输入)</text>\\n  <text x=\\\"255\\\" y=\\\"236\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">控制</text>\\n\\n  <!-- CPU <-> Output -->\\n  <path d=\\\"M602,210 L688,210\\\" fill=\\\"none\\\" stroke=\\\"#bf3989\\\" stroke-width=\\\"3\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <path d=\\\"M602,196 L688,196\\\" fill=\\\"none\\\" stroke=\\\"#555\\\" stroke-width=\\\"2\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"645\\\" y=\\\"184\\\" text-anchor=\\\"middle\\\" font-size=\\\"10.5\\\" fill=\\\"#bf3989\\\">数据(输出)</text>\\n  <text x=\\\"645\\\" y=\\\"236\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#555\\\">控制</text>\\n\\n  <!-- Memory <-> Input/Output hints: 存储器与 I/O 也通过总线交换 -->\\n  <path d=\\\"M125,272 L125,300 Q125,340 175,340 L298,340\\\" fill=\\\"none\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.8\\\" stroke-dasharray=\\\"6,4\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"160\\\" y=\\\"328\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\" transform=\\\"rotate(-8 160 328)\\\">总线</text>\\n\\n  <path d=\\\"M775,272 L775,300 Q775,340 725,340 L602,340\\\" fill=\\\"none\\\" stroke=\\\"#8c959f\\\" stroke-width=\\\"1.8\\\" stroke-dasharray=\\\"6,4\\\" marker-end=\\\"url(#arrow)\\\"/>\\n  <text x=\\\"740\\\" y=\\\"328\\\" text-anchor=\\\"middle\\\" font-size=\\\"10\\\" fill=\\\"#666\\\" transform=\\\"rotate(8 740 328)\\\">总线</text>\\n\\n  <!-- Stored-program note -->\\n  <text x=\\\"450\\\" y=\\\"530\\\" text-anchor=\\\"middle\\\" font-size=\\\"11.5\\\" fill=\\\"#666\\\">核心思想: 指令与数据以二进制形式统一存放在存储器中 —— “存储程序”</text>\\n</svg>\\n\"}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_yxav8LdZ9iwWpgkUnspF6361"},"toolCallId":"call_00_yxav8LdZ9iwWpgkUnspF6361","content":[{"type":"text","text":"<path>{{cwd}}/von-neumann.svg</path>\n<type>file</type>\n<content>\nCreated file\n</content>"}],"isError":false,"id":"{{message:5}}"},"meta":{"operation":"create","diffs":[]}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The file is created. Let me present it as a deliverable."},{"type":"tool-call","id":"call_00_otuUentgajQb2RkFVoKT3699","name":"present","arguments":"{\"files\": [{\"path\": \"von-neumann.svg\", \"description\": \"冯诺依曼架构示意图 SVG\"}]}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":85,"outputTokens":80,"totalTokens":10661,"cacheReadTokens":10496,"reasoningTokens":14},"stream":[{"type":"chunk","time":1789457782632,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1789457782632,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," file"," is"," created","."," Let"," me"," present"," it"," as"," a"," deliver","able","."]},{"type":"chunk","time":1789457782632,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789457782632,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_otuUentgajQb2RkFVoKT3699","name":"present","args":["","{","\"","files","\"",": ","[","{\"","path","\":"," \"","von","-","neum","ann",".svg","\","," \"","description","\":"," \"","冯","诺","依","曼","架构","示意图"," SVG","\"","}]","}"]},{"type":"chunk","time":1789457782632,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The file is created. Let me present it as a deliverable."}}},{"type":"chunk","time":1789457782632,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_otuUentgajQb2RkFVoKT3699","name":"present","arguments":"{\"files\": [{\"path\": \"von-neumann.svg\", \"description\": \"冯诺依曼架构示意图 SVG\"}]}"}}},{"type":"chunk","time":1789457782632,"chunk":{"type":"usage","usage":{"inputTokens":85,"outputTokens":80,"totalTokens":10661,"cacheReadTokens":10496,"reasoningTokens":14}}},{"type":"chunk","time":1789457782632,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":2,"callId":"call_00_otuUentgajQb2RkFVoKT3699","name":"present","arguments":"{\"files\": [{\"path\": \"von-neumann.svg\", \"description\": \"冯诺依曼架构示意图 SVG\"}]}"}}
+{"type":"deliverables/presented","data":{"turn":1,"callId":"call_00_otuUentgajQb2RkFVoKT3699","files":[{"path":"von-neumann.svg","description":"冯诺依曼架构示意图 SVG"}]}}
+{"type":"tool/result","data":{"turn":1,"step":2,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_otuUentgajQb2RkFVoKT3699"},"toolCallId":"call_00_otuUentgajQb2RkFVoKT3699","content":[{"type":"text","text":"Presented von-neumann.svg"}],"isError":false,"id":"{{message:7}}"}},"sourceEventSeqs":[19],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"step/start","data":{"turn":1,"step":3}}
+{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"已创建 `von-neumann.svg`，一个简洁的冯诺依曼架构示意图，包含：\n\n- **CPU（中央处理器）**：内含控制单元 CU、算术逻辑单元 ALU 和寄存器组\n- **内存储器 Memory**：标注\"指令和数据统一存放\"（存储程序思想）\n- **输入设备 / 输出设备**：分别用绿色和粉色表示数据流向\n- **总线连接**：CPU 与内存间的地址总线，以及 CPU 与 I/O 设备间的数据/控制线，箭头标明数据流向\n\n下方附一行核心思想说明：指令与数据以二进制统一存储在存储器中。用浏览器打开该 SVG 文件即可查看。"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:8}}"},"usage":{"inputTokens":56,"outputTokens":145,"totalTokens":10825,"cacheReadTokens":10624,"reasoningTokens":0},"stream":[{"type":"chunk","time":1789457782649,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1789457782649,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["已","创建"," `","von","-","neum","ann",".svg","`","，","一个","简洁","的","冯","诺","依","曼","架构","示意图","，","包含","：\n\n","-"," **","CPU","（","中央","处理器","）","**","：","内含","控制","单元"," CU","、","算术","逻辑","单元"," AL","U"," ","和","寄存器","组","\n","-"," **","内","存储器"," Memory","**","：","标注","\"","指令","和数据","统一","存放","\"","（","存储","程序","思想","）\n","-"," **","输入","设备"," /"," ","输出","设备","**","：","分别","用","绿色","和","粉色","表示","数据","流向","\n","-"," **","总线","连接","**","：","CPU"," ","与","内存","间的","地址","总线","，","以及"," CPU"," ","与"," I","/O"," ","设备","间的","数据","/","控制","线","，","箭头","标明","数据","流向","\n\n","下方","附","一行","核心","思想","说明","：","指令","与","数据","以","二进制","统一","存储在","存储器","中","。","用","浏览器","打开","该"," SVG"," ","文件","即可","查看","。"]},{"type":"chunk","time":1789457782650,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"已创建 `von-neumann.svg`，一个简洁的冯诺依曼架构示意图，包含：\n\n- **CPU（中央处理器）**：内含控制单元 CU、算术逻辑单元 ALU 和寄存器组\n- **内存储器 Memory**：标注\"指令和数据统一存放\"（存储程序思想）\n- **输入设备 / 输出设备**：分别用绿色和粉色表示数据流向\n- **总线连接**：CPU 与内存间的地址总线，以及 CPU 与 I/O 设备间的数据/控制线，箭头标明数据流向\n\n下方附一行核心思想说明：指令与数据以二进制统一存储在存储器中。用浏览器打开该 SVG 文件即可查看。"}}},{"type":"chunk","time":1789457782650,"chunk":{"type":"usage","usage":{"inputTokens":56,"outputTokens":145,"totalTokens":10825,"cacheReadTokens":10624,"reasoningTokens":0}}},{"type":"chunk","time":1789457782650,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":3}}
+{"type":"workspace/changes","data":{"turn":1}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/present-svg/ui.expected.md b/snapshots/web/present-svg/ui.expected.md
index c867d85c45..9920928bed 100644
--- a/snapshots/web/present-svg/ui.expected.md
+++ b/snapshots/web/present-svg/ui.expected.md
@@ -1,15 +1,14 @@
-- button "系统提示词"
 - text: 简单画一个 SVG 表示冯诺依曼架构, 保存为 von-neumann.svg {{clock}}
 - button "复制"
 - button "2 次工具调用 · 1 条消息" [expanded]
 - button "上下文注入 runtime-context"
-- button "思考 The user wants a simple SVG diagram of the von Neumann architecture, saved as von-neumann.svg. Let me create a clean SVG showing CPU (control unit, ALU), memory, input, and output with bidirectional data/control buses."
+- button "思考"
 - paragraph: 我来创建一个冯诺依曼架构的 SVG 示意图。
 - button "写入 von-neumann.svg +83 -0":
   - text: 写入
   - button "von-neumann.svg"
   - text: +83 -0
-- button "思考 The file is created. Let me present it as a deliverable."
+- button "思考"
 - button "交付文件 已交付 von-neumann.svg"
 - paragraph:
   - text: 已创建
@@ -37,8 +36,6 @@
 - text: 此主机没有可用的桌面，无法使用外部程序打开文件或文件夹；文件仍可在侧边栏预览
 - button "在侧边栏预览 von-neumann.svg"
 - text: von-neumann.svg 冯诺依曼架构示意图 SVG
-- button "在侧边栏打开 von-neumann.svg": 打开
-- button "von-neumann.svg 的更多文件操作" [disabled]
 - button "复制"
 - button "好的回答"
 - button "有问题的回答"
diff --git a/snapshots/web/present/session.v4.jsonl b/snapshots/web/present/session.v4.jsonl
new file mode 100644
index 0000000000..442cd7b022
--- /dev/null
+++ b/snapshots/web/present/session.v4.jsonl
@@ -0,0 +1,29 @@
+{"type":"session","version":4,"id":"{{session:1}}","createdAt":1788883598275,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0,"agentPreset":"ptc"}
+{"type":"permission/preset","data":{"preset":"workspace-write"}}
+{"type":"sandbox/mode","data":{"mode":"workspace-write"}}
+{"type":"approval/policy","data":{"policy":"ask"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use one run_code program to do the following in order. Call present for missing.txt and catch its error without creating that file. Use bash to run exactly `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`. Call present for report.txt and 说明.txt. After present succeeds, deliberately throw the string \"AFTER_PRESENT\" (not an Error object) from that same run_code program. Do not retry the program or create any other files. Finish by mentioning `report.txt` and `说明.txt` in inline code, and put PRESENT_DONE in a separate paragraph."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Use one run_code program to do the following in order. Call present for missing.txt and catch its error without creating that file. Use bash to run exactly `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`. Call present for report.txt and 说明.txt. After present succeeds, deliberately throw the string \"AFTER_PRESENT\" (not an Error object) from that same run_code program. Do not retry the program or create any other files. Finish by mentioning `report.txt` and `说明.txt` in inline code, and put PRESENT_DONE in a separate paragraph."}],"source":{"kind":"user","rpcId":"{{rpc:1}}","clientTimeZone":"{{clientTimeZone}}"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}}
+{"type":"session/title","data":{"title":"Use one run_code program to","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants one run_code program that:\n1. Calls present for missing.txt and catches its error without creating that file.\n2. Uses bash to run exactly `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`.\n3. Calls present for report.txt and 说明.txt.\n4. After present succeeds, deliberately throws the string \"AFTER_PRESENT\" (not an Error object) from that same run_code program.\n5. Does not retry the program or create other files.\n6. Finishes by mentioning report.txt and 说明.txt in inline code, and put PRESENT_DONE in a separate paragraph.\n\nLet me write the program.\n\npresent tool args: { files: [{ path, description? }] }.\n\nSo first: try present for missing.txt — catch error. It should error because the file doesn't exist (present requires existing workspace file).\n\nThen bash run exact command. Note the command uses `;` inside a single string. Run as a single command string: `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`.\n\nWait — printf interprets the arguments... In bash, `printf \"DELIVERED_REPORT\\n\"` with the format string containing \\n — printf will interpret \\n as newline. Good.\n\nThen present for report.txt and 说明.txt.\n\nThen throw \"AFTER_PRESENT\" string. In TS async function body, `throw \"AFTER_PRESENT\"` works.\n\nLet me write it."},{"type":"tool-call","id":"call_00_GgvYPol45qxGf6GezK3L3590","name":"run_code","arguments":"{\"code\": \"// Step 1: present for missing.txt — must fail, catch the error, don't create the file\\ntry {\\n  await tools.present({ files: [{ path: \\\"missing.txt\\\", description: \\\"must not exist\\\" }] });\\n  console.log(\\\"UNEXPECTED: present succeeded for missing.txt\\\");\\n} catch (err) {\\n  console.log(\\\"Caught present error for missing.txt:\\\", typeof err, String(err).slice(0, 200));\\n}\\n\\n// Step 2: run the exact bash command to create the two report files\\nconst res = await tools.bash({\\n  command: 'printf \\\"DELIVERED_REPORT\\\\n\\\" > report.txt; printf \\\"DELIVERED_NOTE\\\\n\\\" > 说明.txt',\\n  description: \\\"Write DELIVERED_REPORT and DELIVERED_NOTE to files\\\",\\n});\\nconsole.log(\\\"bash exit:\\\", res.exitCode);\\n\\n// Step 3: present for report.txt and 说明.txt (must succeed)\\nconst p2 = await tools.present({\\n  files: [\\n    { path: \\\"report.txt\\\", description: \\\"delivered report\\\" },\\n    { path: \\\"说明.txt\\\", description: \\\"delivered note\\\" },\\n  ],\\n});\\nconsole.log(\\\"present ok, files:\\\", p2.files.map((f) => f.path).join(\\\", \\\"));\\n\\n// Step 4: deliberately throw a plain string AFTER_PRESENT (not an Error)\\nthrow \\\"AFTER_PRESENT\\\";\", \"description\": \"Present files then deliberately throw AFTER_PRESENT\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":981,"outputTokens":695,"totalTokens":9356,"cacheReadTokens":7680,"reasoningTokens":329},"stream":[{"type":"chunk","time":1788883599120,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788883599120,"index":0,"dt":[0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," one"," run","_code"," program"," that",":\n","1","."," Calls"," present"," for"," missing",".txt"," and"," catches"," its"," error"," without"," creating"," that"," file",".\n","2","."," Uses"," bash"," to"," run"," exactly"," `","printf"," \"","DEL","IVER","ED","_RE","PORT","\\n","\""," >"," report",".txt",";"," printf"," \"","DEL","IVER","ED","_N","OTE","\\n","\""," >"," ","说明",".txt","`.\n","3","."," Calls"," present"," for"," report",".txt"," and"," ","说明",".txt",".\n","4","."," After"," present"," succeeds",","," deliberately"," throws"," the"," string"," \"","AF","TER","_P","RES","ENT","\""," (","not"," an"," Error"," object",")"," from"," that"," same"," run","_code"," program",".\n","5","."," Does"," not"," ret","ry"," the"," program"," or"," create"," other"," files",".\n","6","."," Fin","ishes"," by"," mentioning"," report",".txt"," and"," ","说明",".txt"," in"," inline"," code",","," and"," put"," PRES","ENT","_D","ONE"," in"," a"," separate"," paragraph",".\n\n","Let"," me"," write"," the"," program",".\n\n","present"," tool"," args",":"," {"," files",":"," [{"," path",","," description","?"," }","]"," }",".\n\n","So"," first",":"," try"," present"," for"," missing",".txt"," —"," catch"," error","."," It"," should"," error"," because"," the"," file"," doesn","'t"," exist"," (","present"," requires"," existing"," workspace"," file",").\n\n","Then"," bash"," run"," exact"," command","."," Note"," the"," command"," uses"," `",";","`"," inside"," a"," single"," string","."," Run"," as"," a"," single"," command"," string",":"," `","printf"," \"","DEL","IVER","ED","_RE","PORT","\\n","\""," >"," report",".txt",";"," printf"," \"","DEL","IVER","ED","_N","OTE","\\n","\""," >"," ","说明",".txt","`.\n\n","Wait"," —"," printf"," interprets"," the"," arguments","..."," In"," bash",","," `","printf"," \"","DEL","IVER","ED","_RE","PORT","\\n","\"","`"," with"," the"," format"," string"," containing"," \\","n"," —"," printf"," will"," interpret"," \\","n"," as"," new","line","."," Good",".\n\n","Then"," present"," for"," report",".txt"," and"," ","说明",".txt",".\n\n","Then"," throw"," \"","AF","TER","_P","RES","ENT","\""," string","."," In"," TS"," async"," function"," body",","," `","throw"," \"","AF","TER","_P","RES","ENT","\"","`"," works",".\n\n","Let"," me"," write"," it","."]},{"type":"chunk","time":1788883599123,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788883599123,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_GgvYPol45qxGf6GezK3L3590","name":"run_code","args":["","{","\"","code","\"",": ","\"","//"," Step"," ","1",":"," present"," for"," missing",".txt"," —"," must"," fail",","," catch"," the"," error",","," don","'t"," create"," the"," file","\\n","try"," {\\n"," "," await"," tools",".p","resent","({"," files",":"," [{"," path",":"," \\\"","missing",".txt","\\\","," description",":"," \\\"","must"," not"," exist","\\\""," }","]"," });\\n"," "," console",".log","(\\\"","UN","EXP","ECT","ED",":"," present"," succeeded"," for"," missing",".txt","\\\");\\n","}"," catch"," (","err",")"," {\\n"," "," console",".log","(\\\"","Ca","ught"," present"," error"," for"," missing",".txt",":\\\","," typeof"," err",","," String","(err",").","slice","(","0",","," ","200","));\\n","}\\n\\n","//"," Step"," ","2",":"," run"," the"," exact"," bash"," command"," to"," create"," the"," two"," report"," files","\\n","const"," res"," ="," await"," tools",".b","ash","({\\n"," "," command",":"," '","printf"," \\\"","DEL","IVER","ED","_RE","PORT","\\\\n","\\\""," >"," report",".txt",";"," printf"," \\\"","DEL","IVER","ED","_N","OTE","\\\\n","\\\""," >"," ","说明",".txt","',\\n"," "," description",":"," \\\"","Write"," DEL","IVER","ED","_RE","PORT"," and"," DEL","IVER","ED","_N","OTE"," to"," files","\\\",\\n","});\\n","console",".log","(\\\"","bash"," exit",":\\\","," res",".exit","Code",");\\n\\n","//"," Step"," ","3",":"," present"," for"," report",".txt"," and"," ","说明",".txt"," (","must"," succeed",")\\n","const"," p","2"," ="," await"," tools",".p","resent","({\\n"," "," files",":"," [\\n","   "," {"," path",":"," \\\"","report",".txt","\\\","," description",":"," \\\"","del","ivered"," report","\\\""," },\\n","   "," {"," path",":"," \\\"","说明",".txt","\\\","," description",":"," \\\"","del","ivered"," note","\\\""," },\\n"," "," ],\\n","});\\n","console",".log","(\\\"","present"," ok",","," files",":\\\","," p","2",".f","iles",".map","((","f",")"," =>"," f",".path",").","join","(\\\","," \\\"","));\\n\\n","//"," Step"," ","4",":"," deliberately"," throw"," a"," plain"," string"," AFTER","_P","RES","ENT"," (","not"," an"," Error",")\\n","throw"," \\\"","AF","TER","_P","RES","ENT","\\\";","\"",", ","\"","description","\"",": ","\"","Present"," files"," then"," deliberately"," throw"," AFTER","_P","RES","ENT","\"","}"]},{"type":"chunk","time":1788883599125,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants one run_code program that:\n1. Calls present for missing.txt and catches its error without creating that file.\n2. Uses bash to run exactly `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`.\n3. Calls present for report.txt and 说明.txt.\n4. After present succeeds, deliberately throws the string \"AFTER_PRESENT\" (not an Error object) from that same run_code program.\n5. Does not retry the program or create other files.\n6. Finishes by mentioning report.txt and 说明.txt in inline code, and put PRESENT_DONE in a separate paragraph.\n\nLet me write the program.\n\npresent tool args: { files: [{ path, description? }] }.\n\nSo first: try present for missing.txt — catch error. It should error because the file doesn't exist (present requires existing workspace file).\n\nThen bash run exact command. Note the command uses `;` inside a single string. Run as a single command string: `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`.\n\nWait — printf interprets the arguments... In bash, `printf \"DELIVERED_REPORT\\n\"` with the format string containing \\n — printf will interpret \\n as newline. Good.\n\nThen present for report.txt and 说明.txt.\n\nThen throw \"AFTER_PRESENT\" string. In TS async function body, `throw \"AFTER_PRESENT\"` works.\n\nLet me write it."}}},{"type":"chunk","time":1788883599125,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_GgvYPol45qxGf6GezK3L3590","name":"run_code","arguments":"{\"code\": \"// Step 1: present for missing.txt — must fail, catch the error, don't create the file\\ntry {\\n  await tools.present({ files: [{ path: \\\"missing.txt\\\", description: \\\"must not exist\\\" }] });\\n  console.log(\\\"UNEXPECTED: present succeeded for missing.txt\\\");\\n} catch (err) {\\n  console.log(\\\"Caught present error for missing.txt:\\\", typeof err, String(err).slice(0, 200));\\n}\\n\\n// Step 2: run the exact bash command to create the two report files\\nconst res = await tools.bash({\\n  command: 'printf \\\"DELIVERED_REPORT\\\\n\\\" > report.txt; printf \\\"DELIVERED_NOTE\\\\n\\\" > 说明.txt',\\n  description: \\\"Write DELIVERED_REPORT and DELIVERED_NOTE to files\\\",\\n});\\nconsole.log(\\\"bash exit:\\\", res.exitCode);\\n\\n// Step 3: present for report.txt and 说明.txt (must succeed)\\nconst p2 = await tools.present({\\n  files: [\\n    { path: \\\"report.txt\\\", description: \\\"delivered report\\\" },\\n    { path: \\\"说明.txt\\\", description: \\\"delivered note\\\" },\\n  ],\\n});\\nconsole.log(\\\"present ok, files:\\\", p2.files.map((f) => f.path).join(\\\", \\\"));\\n\\n// Step 4: deliberately throw a plain string AFTER_PRESENT (not an Error)\\nthrow \\\"AFTER_PRESENT\\\";\", \"description\": \"Present files then deliberately throw AFTER_PRESENT\"}"}}},{"type":"chunk","time":1788883599125,"chunk":{"type":"usage","usage":{"inputTokens":981,"outputTokens":695,"totalTokens":9356,"cacheReadTokens":7680,"reasoningTokens":329}}},{"type":"chunk","time":1788883599125,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_GgvYPol45qxGf6GezK3L3590","name":"run_code","arguments":"{\"code\": \"// Step 1: present for missing.txt — must fail, catch the error, don't create the file\\ntry {\\n  await tools.present({ files: [{ path: \\\"missing.txt\\\", description: \\\"must not exist\\\" }] });\\n  console.log(\\\"UNEXPECTED: present succeeded for missing.txt\\\");\\n} catch (err) {\\n  console.log(\\\"Caught present error for missing.txt:\\\", typeof err, String(err).slice(0, 200));\\n}\\n\\n// Step 2: run the exact bash command to create the two report files\\nconst res = await tools.bash({\\n  command: 'printf \\\"DELIVERED_REPORT\\\\n\\\" > report.txt; printf \\\"DELIVERED_NOTE\\\\n\\\" > 说明.txt',\\n  description: \\\"Write DELIVERED_REPORT and DELIVERED_NOTE to files\\\",\\n});\\nconsole.log(\\\"bash exit:\\\", res.exitCode);\\n\\n// Step 3: present for report.txt and 说明.txt (must succeed)\\nconst p2 = await tools.present({\\n  files: [\\n    { path: \\\"report.txt\\\", description: \\\"delivered report\\\" },\\n    { path: \\\"说明.txt\\\", description: \\\"delivered note\\\" },\\n  ],\\n});\\nconsole.log(\\\"present ok, files:\\\", p2.files.map((f) => f.path).join(\\\", \\\"));\\n\\n// Step 4: deliberately throw a plain string AFTER_PRESENT (not an Error)\\nthrow \\\"AFTER_PRESENT\\\";\", \"description\": \"Present files then deliberately throw AFTER_PRESENT\"}"}}
+{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"call_00_GgvYPol45qxGf6GezK3L3590","parentCallId":"call_00_GgvYPol45qxGf6GezK3L3590","subCallId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:1","name":"present","arguments":{"files":[{"path":"missing.txt","description":"must not exist"}]}}}
+{"type":"tool/ptc-dispatch","data":{"rootCallId":"call_00_GgvYPol45qxGf6GezK3L3590","parentCallId":"call_00_GgvYPol45qxGf6GezK3L3590","subCallId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:1","name":"present","arguments":{"files":[{"path":"missing.txt","description":"must not exist"}]},"isError":true,"error":{"name":"FsError","code":"FS_NOT_FOUND"},"content":[{"type":"text","text":"Error: Cannot present missing.txt: file not found. Check the path, create the file if needed, and retry."}]}}
+{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"call_00_GgvYPol45qxGf6GezK3L3590","parentCallId":"call_00_GgvYPol45qxGf6GezK3L3590","subCallId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:2","name":"bash","arguments":{"command":"printf \"DELIVERED_REPORT\n\" > report.txt; printf \"DELIVERED_NOTE\n\" > 说明.txt","description":"Write DELIVERED_REPORT and DELIVERED_NOTE to files"}}}
+{"type":"tool/ptc-dispatch","data":{"rootCallId":"call_00_GgvYPol45qxGf6GezK3L3590","parentCallId":"call_00_GgvYPol45qxGf6GezK3L3590","subCallId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:2","name":"bash","arguments":{"command":"printf \"DELIVERED_REPORT\n\" > report.txt; printf \"DELIVERED_NOTE\n\" > 说明.txt","description":"Write DELIVERED_REPORT and DELIVERED_NOTE to files"},"isError":false,"content":[{"type":"text","text":"(no output)"}]}}
+{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"call_00_GgvYPol45qxGf6GezK3L3590","parentCallId":"call_00_GgvYPol45qxGf6GezK3L3590","subCallId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:3","name":"present","arguments":{"files":[{"path":"report.txt","description":"delivered report"},{"path":"说明.txt","description":"delivered note"}]}}}
+{"type":"deliverables/presented","data":{"turn":1,"callId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:3","files":[{"path":"report.txt","description":"delivered report"},{"path":"说明.txt","description":"delivered note"}]}}
+{"type":"tool/ptc-dispatch","data":{"rootCallId":"call_00_GgvYPol45qxGf6GezK3L3590","parentCallId":"call_00_GgvYPol45qxGf6GezK3L3590","subCallId":"call_00_GgvYPol45qxGf6GezK3L3590:ptc:3","name":"present","arguments":{"files":[{"path":"report.txt","description":"delivered report"},{"path":"说明.txt","description":"delivered note"}]},"isError":false,"content":[{"type":"text","text":"Presented report.txt\nPresented 说明.txt"}]}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_GgvYPol45qxGf6GezK3L3590"},"toolCallId":"call_00_GgvYPol45qxGf6GezK3L3590","content":[{"type":"text","text":"Error: code run failed (exception): AFTER_PRESENT\nCaptured output:\nCaught present error for missing.txt: object ToolCallError: Cannot present missing.txt: file not found. Check the path, create the file if needed, and retry.\nbash exit: 0\npresent ok, files: report.txt, 说明.txt\nFile sandbox: workspace-write; enforcement: full."}],"isError":true,"id":"{{message:5}}"},"error":{"name":"CodeRunFailedError","code":"CODE_RUN_FAILED"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The program ran as intended:\n1. present for missing.txt failed with a ToolCallError, caught and logged — missing.txt was not created.\n2. bash ran exactly the given command, exit 0.\n3. present succeeded for report.txt and 说明.txt.\n4. Then threw the plain string \"AFTER_PRESENT\" (program failed with that exception, as expected — not an Error object).\n\nI did not retry the program or create other files. Now finish mentioning `report.txt` and `说明.txt` in inline code, with PRESENT_DONE in a separate paragraph."},{"type":"text","text":"The single program ran exactly as ordered: `present` for `missing.txt` failed and was caught (no file created), bash ran the exact command successfully, then `present` succeeded for `report.txt` and `说明.txt`, after which the program deliberately threw the string `AFTER_PRESENT` — no retries, no extra files.\n\nPRESENT_DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":94,"outputTokens":198,"totalTokens":9636,"cacheReadTokens":9344,"reasoningTokens":121},"stream":[{"type":"chunk","time":1788883599242,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788883599242,"index":0,"dt":[1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," program"," ran"," as"," intended",":\n","1","."," present"," for"," missing",".txt"," failed"," with"," a"," Tool","Call","Error",","," caught"," and"," logged"," —"," missing",".txt"," was"," not"," created",".\n","2","."," bash"," ran"," exactly"," the"," given"," command",","," exit"," ","0",".\n","3","."," present"," succeeded"," for"," report",".txt"," and"," ","说明",".txt",".\n","4","."," Then"," threw"," the"," plain"," string"," \"","AF","TER","_P","RES","ENT","\""," (","program"," failed"," with"," that"," exception",","," as"," expected"," —"," not"," an"," Error"," object",").\n\n","I"," did"," not"," ret","ry"," the"," program"," or"," create"," other"," files","."," Now"," finish"," mentioning"," `","report",".txt","`"," and"," `","说明",".txt","`"," in"," inline"," code",","," with"," PRES","ENT","_D","ONE"," in"," a"," separate"," paragraph","."]},{"type":"chunk","time":1788883599244,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788883599244,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," single"," program"," ran"," exactly"," as"," ordered",":"," `","present","`"," for"," `","missing",".txt","`"," failed"," and"," was"," caught"," (","no"," file"," created","),"," bash"," ran"," the"," exact"," command"," successfully",","," then"," `","present","`"," succeeded"," for"," `","report",".txt","`"," and"," `","说明",".txt","`,"," after"," which"," the"," program"," deliberately"," threw"," the"," string"," `","AF","TER","_P","RES","ENT","`"," —"," no"," ret","ries",","," no"," extra"," files",".\n\n","PR","ES","ENT","_D","ONE"]},{"type":"chunk","time":1788883599244,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The program ran as intended:\n1. present for missing.txt failed with a ToolCallError, caught and logged — missing.txt was not created.\n2. bash ran exactly the given command, exit 0.\n3. present succeeded for report.txt and 说明.txt.\n4. Then threw the plain string \"AFTER_PRESENT\" (program failed with that exception, as expected — not an Error object).\n\nI did not retry the program or create other files. Now finish mentioning `report.txt` and `说明.txt` in inline code, with PRESENT_DONE in a separate paragraph."}}},{"type":"chunk","time":1788883599244,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"The single program ran exactly as ordered: `present` for `missing.txt` failed and was caught (no file created), bash ran the exact command successfully, then `present` succeeded for `report.txt` and `说明.txt`, after which the program deliberately threw the string `AFTER_PRESENT` — no retries, no extra files.\n\nPRESENT_DONE"}}},{"type":"chunk","time":1788883599244,"chunk":{"type":"usage","usage":{"inputTokens":94,"outputTokens":198,"totalTokens":9636,"cacheReadTokens":9344,"reasoningTokens":121}}},{"type":"chunk","time":1788883599244,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/present/ui.expected.md b/snapshots/web/present/ui.expected.md
index ad3780520c..2892aa7897 100644
--- a/snapshots/web/present/ui.expected.md
+++ b/snapshots/web/present/ui.expected.md
@@ -6,18 +6,17 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use one run_code program to do the following in order. Call present for missing.txt and catch its error without creating that file. Use bash to run exactly `printf \"DELIVERED_REPORT\\n\" > report.txt; printf \"DELIVERED_NOTE\\n\" > 说明.txt`. Call present for report.txt and 说明.txt. After present succeeds, deliberately throw the string \"AFTER_PRESENT\" (not an Error object) from that same run_code program. Do not retry the program or create any other files. Finish by mentioning `report.txt` and `说明.txt` in inline code, and put PRESENT_DONE in a separate paragraph. {{clock}}"
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants one run_code program that:"
+- button "Think"
 - text: Failed
 - 'button "Code Error: code run failed (exception): AFTER_PRESENT"'
 - button "Present files Delivery failed missing.txt"
 - button "Bash Write DELIVERED_REPORT and DELIVERED_NOTE to files"
 - button "Present files Delivered report.txt, 说明.txt"
-- button "Think The program ran as intended:"
+- button "Think"
 - paragraph:
   - text: "The single program ran exactly as ordered:"
   - code: present
@@ -36,15 +35,13 @@
   - text: — no retries, no extra files.
 - paragraph: PRESENT_DONE
 - button "Preview report.txt in sidebar"
-- text: report.txt
-- status: Opened in default app
-- button "Open report.txt in sidebar": Open
-- button "More file actions for report.txt"
+- text: report.txt delivered report
+- button "Open in Test Editor"
+- button "More ways to open"
 - button "Preview 说明.txt in sidebar"
-- text: 说明.txt
-- status: Opened in default app
-- button "Open 说明.txt in sidebar": Open
-- button "More file actions for 说明.txt"
+- text: 说明.txt delivered note
+- button "Open in Test Editor"
+- button "More ways to open"
 - button "Copy"
 - button "Good response"
 - button "Bad response"
diff --git a/snapshots/web/preset-migration/session.1.v2.jsonl b/snapshots/web/preset-migration/session.1.v2.jsonl
new file mode 100644
index 0000000000..47ef5e21a9
--- /dev/null
+++ b/snapshots/web/preset-migration/session.1.v2.jsonl
@@ -0,0 +1,3 @@
+{"type":"session","version":2,"id":"{{session:2}}","createdAt":2,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":1,"agentPreset":"code","origin":"subagent","parentSession":"{{session:1}}"}
+{"type":"subagent/descriptor","data":{"version":3,"provider":"spawn","mode":"one-shot","label":"historical child"}}
+{"type":"feedback/record","data":{"text":"Child history remains readable independently."}}
diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md
index 8787372c8f..107c581adc 100644
--- a/snapshots/web/ptc-round/system-prompt.expected.md
+++ b/snapshots/web/ptc-round/system-prompt.expected.md
@@ -4,7 +4,7 @@ You are a coding agent powered by the deepseek-v4-flash model.
 
 `run_code` is the only tool you can call directly — a tool call naming any other tool fails. Reach every tool the SDK declares below from inside the program.
 
-Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
+Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 
 Check the [exit code: N] marker on every bash result; investigate failures before moving on.
 
diff --git a/snapshots/web/ptc-round/ui.expected.md b/snapshots/web/ptc-round/ui.expected.md
index c62860982b..9e68c8604a 100644
--- a/snapshots/web/ptc-round/ui.expected.md
+++ b/snapshots/web/ptc-round/ui.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt catching its error in the program. Return an object with both outcomes. Then reply DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
-- 'button "Think The user wants me to write a single `run_code` program that:"'
+- button "Think"
 - button "Code Run bash echo and catch missing file read"
 - button "Bash Echo CODE_ROUND_OK" [expanded]
 - text: Done workspace echo CODE_ROUND_OK
@@ -20,7 +19,7 @@
 - button "Inspect"
 - text: Failed
 - 'button "Read Error: cannot read \"{{cwd}}/workspace/missing.txt\": not found"'
-- button "Think The program ran successfully. Let me now reply DONE as instructed."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/question-composer/answered-expanded.expected.md b/snapshots/web/question-composer/answered-expanded.expected.md
index 1e5e5a39cb..488e8b8029 100644
--- a/snapshots/web/question-composer/answered-expanded.expected.md
+++ b/snapshots/web/question-composer/answered-expanded.expected.md
@@ -6,17 +6,16 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."
+- button "Think"
 - button "Ask question 1/1 answered" [expanded]
 - term: Which color do you prefer?
 - definition: Blue Include accessibility notes
 - button "Inspect"
-- button "Think The user answered \"Blue\". I should now reply with the single word DONE and stop."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/question-composer/answered.expected.md b/snapshots/web/question-composer/answered.expected.md
index dd494fb614..fa8b822467 100644
--- a/snapshots/web/question-composer/answered.expected.md
+++ b/snapshots/web/question-composer/answered.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "1 tool call"
diff --git a/snapshots/web/question-composer/cancelled.expected.md b/snapshots/web/question-composer/cancelled.expected.md
index 15af0b5cc7..7238215d90 100644
--- a/snapshots/web/question-composer/cancelled.expected.md
+++ b/snapshots/web/question-composer/cancelled.expected.md
@@ -5,11 +5,10 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Use the ask_user_question tool to ask me exactly one multi-select question with id \"color\", question \"Which color do you prefer?\", header \"Pick one\", and two options: label \"Blue\" with description \"A cool recessive hue that reads as calm and trustworthy in long reading sessions and dense dashboards.\", and label \"Green\" with description \"A restful mid-spectrum hue with the highest perceived brightness, easiest on the eye over long sessions.\" Set multi_select to true. After I answer, reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "Context injection runtime-context"
-- button "Think The user wants me to use the ask_user_question tool with specific parameters. Let me do exactly that."
+- button "Think"
 - button "Ask question cancelled" [expanded]
 - paragraph: This question set was cancelled before answers were submitted.
 - list:
diff --git a/snapshots/web/queue-actions/collapsed.expected.md b/snapshots/web/queue-actions/collapsed.expected.md
index 765e045f17..bcb7ecf753 100644
--- a/snapshots/web/queue-actions/collapsed.expected.md
+++ b/snapshots/web/queue-actions/collapsed.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/queue-actions/editing.expected.md b/snapshots/web/queue-actions/editing.expected.md
index 96eff6022d..13925614bf 100644
--- a/snapshots/web/queue-actions/editing.expected.md
+++ b/snapshots/web/queue-actions/editing.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/queue-actions/layout.expected.md b/snapshots/web/queue-actions/layout.expected.md
index 0d5d2ce2b1..4ca4469eed 100644
--- a/snapshots/web/queue-actions/layout.expected.md
+++ b/snapshots/web/queue-actions/layout.expected.md
@@ -8,7 +8,6 @@
     - 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"'
-- button "System prompt"
 - button "Context injection goal"
 - button "Context injection runtime-context"
 - paragraph: partial
diff --git a/snapshots/web/queue-actions/preserved-expanded.expected.md b/snapshots/web/queue-actions/preserved-expanded.expected.md
index fe66236496..e95a3f6fb3 100644
--- a/snapshots/web/queue-actions/preserved-expanded.expected.md
+++ b/snapshots/web/queue-actions/preserved-expanded.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
diff --git a/snapshots/web/queue-actions/preserved.expected.md b/snapshots/web/queue-actions/preserved.expected.md
index 66052f1522..3f186da354 100644
--- a/snapshots/web/queue-actions/preserved.expected.md
+++ b/snapshots/web/queue-actions/preserved.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/queue-actions/sending.expected.md b/snapshots/web/queue-actions/sending.expected.md
index 07dd357aba..02e60e5f77 100644
--- a/snapshots/web/queue-actions/sending.expected.md
+++ b/snapshots/web/queue-actions/sending.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/queue-actions/ui.expected.md b/snapshots/web/queue-actions/ui.expected.md
index 9e43a41140..fcc1477d43 100644
--- a/snapshots/web/queue-actions/ui.expected.md
+++ b/snapshots/web/queue-actions/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/queued-image/delivered.expected.md b/snapshots/web/queued-image/delivered.expected.md
index 289963776b..a77a5d3547 100644
--- a/snapshots/web/queued-image/delivered.expected.md
+++ b/snapshots/web/queued-image/delivered.expected.md
@@ -10,7 +10,6 @@
   - button "Jump to turn 1"
   - button "Jump to turn 2"
   - button "Jump to turn 3"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/queued-image/queued.expected.md b/snapshots/web/queued-image/queued.expected.md
index e28d8df980..95b98d26cd 100644
--- a/snapshots/web/queued-image/queued.expected.md
+++ b/snapshots/web/queued-image/queued.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/schedule-catalog/system-prompt.expected.md b/snapshots/web/schedule-catalog/system-prompt.expected.md
index 0c5f3c77cc..01b43eca97 100644
--- a/snapshots/web/schedule-catalog/system-prompt.expected.md
+++ b/snapshots/web/schedule-catalog/system-prompt.expected.md
@@ -6,7 +6,7 @@ You are interacting with the user through the DeepSeek Harness Web GUI at {{webU
 
 You are a coding agent powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.
 
-Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
+Tokens prefixed with @ are paths the user explicitly referenced. Relative paths resolve from the workspace root; absolute paths identify files or directories on the host. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.
 
 Check the [exit code: N] marker on every bash result; investigate failures before moving on.
 
diff --git a/snapshots/web/seeded-history/command-row.expected.md b/snapshots/web/seeded-history/command-row.expected.md
index 727368f383..bcebaccbe0 100644
--- a/snapshots/web/seeded-history/command-row.expected.md
+++ b/snapshots/web/seeded-history/command-row.expected.md
@@ -8,18 +8,17 @@
 - navigation "Turn navigation":
   - button "Jump to turn 1"
   - button "Jump to turn 2"
-- button "System prompt"
 - text: "Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "2 tool calls" [expanded]
-- button "Think The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."
+- button "Think"
 - button "Read a.txt":
   - text: Read
   - button "a.txt"
 - button "Read b.txt":
   - text: Read
   - button "b.txt"
-- button "Think Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
@@ -28,7 +27,6 @@
 - text: {{clock}}
 - button "compact Compacted 5 history items (~{{tokens}} tokens)"
 - button "Context injection AGENTS.md"
-- text: permission preset read-only
 - textbox "Message or run a task, / commands, @ files or sessions"
 - button "Add files or run commands"
 - 'button "Access mode, current: Read Only"': Read Only
diff --git a/snapshots/web/seeded-history/feedback-row.expected.md b/snapshots/web/seeded-history/feedback-row.expected.md
index 2b26bde0d6..cb0bde06e7 100644
--- a/snapshots/web/seeded-history/feedback-row.expected.md
+++ b/snapshots/web/seeded-history/feedback-row.expected.md
@@ -8,18 +8,17 @@
 - navigation "Turn navigation":
   - button "Jump to turn 1"
   - button "Jump to turn 2"
-- button "System prompt"
 - text: "Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "2 tool calls" [expanded]
-- button "Think The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."
+- button "Think"
 - button "Read a.txt":
   - text: Read
   - button "a.txt"
 - button "Read b.txt":
   - text: Read
   - button "b.txt"
-- button "Think Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
@@ -28,7 +27,6 @@
 - text: {{clock}}
 - button "compact Compacted 5 history items (~{{tokens}} tokens)"
 - button "Context injection AGENTS.md"
-- text: permission preset read-only
 - 'button "feedback Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}." [expanded]'
 - text: "Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}."
 - textbox "Message or run a task, / commands, @ files or sessions"
diff --git a/snapshots/web/seeded-history/file-preview.expected.md b/snapshots/web/seeded-history/file-preview.expected.md
index 197bb3c9cf..64d5ce902f 100644
--- a/snapshots/web/seeded-history/file-preview.expected.md
+++ b/snapshots/web/seeded-history/file-preview.expected.md
@@ -1,6 +1,5 @@
 - text: {{cwd}}/a.txt
 - button "Line wrap" [pressed]
 - button "Read the file again"
-- button "Open"
-- button "More ways to open"
+- button "Show file location"
 - text: alpha
diff --git a/snapshots/web/seeded-history/ui-expanded.expected.md b/snapshots/web/seeded-history/ui-expanded.expected.md
index bd687552fd..4f6ac15000 100644
--- a/snapshots/web/seeded-history/ui-expanded.expected.md
+++ b/snapshots/web/seeded-history/ui-expanded.expected.md
@@ -8,18 +8,17 @@
 - navigation "Turn navigation":
   - button "Jump to turn 1"
   - button "Jump to turn 2"
-- button "System prompt"
 - text: "Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "2 tool calls" [expanded]
-- button "Think The user wants me to read a.txt and b.txt, then reply with \"DONE\". Let me do both reads in parallel."
+- button "Think"
 - button "Read a.txt":
   - text: Read
   - button "a.txt"
 - button "Read b.txt":
   - text: Read
   - button "b.txt"
-- button "Think Both files have been read. a.txt contains \"alpha\" and b.txt contains \"beta\". I'll now reply with DONE as instructed."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/seeded-history/ui.expected.md b/snapshots/web/seeded-history/ui.expected.md
index 0a26ac4c88..4f703e11d9 100644
--- a/snapshots/web/seeded-history/ui.expected.md
+++ b/snapshots/web/seeded-history/ui.expected.md
@@ -8,7 +8,6 @@
 - navigation "Turn navigation":
   - button "Jump to turn 1"
   - button "Jump to turn 2"
-- button "System prompt"
 - text: "Use the read tool twice in one assistant message: read a.txt and b.txt. Then reply with the single word DONE and stop. {{clock}}"
 - button "Copy"
 - button "2 tool calls"
diff --git a/snapshots/web/skill-tool-row/snapshot.yml b/snapshots/web/skill-tool-row/snapshot.yml
index 4c82c05edb..8b01149257 100644
--- a/snapshots/web/skill-tool-row/snapshot.yml
+++ b/snapshots/web/skill-tool-row/snapshot.yml
@@ -6,4 +6,4 @@ recording: authored
 header:
   class: skill
 session:
-  source: ../../session/skill-load/session.v3.jsonl
+  source: ../../session/skill-load/session.v4.jsonl
diff --git a/snapshots/web/skill-tool-row/ui.expected.md b/snapshots/web/skill-tool-row/ui.expected.md
index aa014bd9e0..816b680d6e 100644
--- a/snapshots/web/skill-tool-row/ui.expected.md
+++ b/snapshots/web/skill-tool-row/ui.expected.md
@@ -5,17 +5,16 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Load the editing-cordis-compositions skill with the skill tool, then reply DONE. {{date}} {{clock}}
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
 - button "Context injection skill-catalog"
-- button "Think Load the requested skill."
+- button "Think"
 - button "Skill editing-cordis-compositions" [expanded]
 - region "Instructions": "Instructions <skill_content name=\"editing-cordis-compositions\"> <skill_resources> Base directory for this skill: {{cwd}}/.dsh/skills/editing-cordis-compositions Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed. </skill_resources> <skill_instructions> # Editing Cordis compositions Every capability in this harness is a plugin row in a `cordis.yml`. There is no separate configuration language: changing what an agent can do means changing which rows are composed for it. ## Off-limits **Never edit, delete, or overwrite a preset that ships with the deployment** — the `agent-presets` directory beside the deployment's own config, which supplies `standard`, `ptc`, `minimal`, and `cordis`. Never escalate the sandbox to reach it, even when a change there looks quicker. An upgrade overwrites that install, and corrupting `cordis` disables preset authoring itself. Reading a shipped composition is the intended way to start; writing to one is not, and neither is editing the host composition to work around a preset limitation. To change what a shipped preset does, copy it and edit the copy. Locally authored presets under the user root are yours to create, edit, and delete. ## Decide the plane first Two planes, and the choice is not about how \"agent-related\" something feels — it is about whether the thing must be shared. **Host composition.** The registries themselves (`tools`, `systemPrompt`, `agents`, `agent-loop`, `sessions`), anything crossing sessions (persistence, session query, storage, settings, credentials, telemetry), the sandbox and approval stack, the model route, and the subagent registry with its spawn/fork backends. One instance for the process. **Agent preset.** What one session contributes to those registries: its tool plugins, its persona and prompt sections, its compaction policy. One instance per session, mounted under that session's scope and unwound with it. **A service with a consumer outside the agent plane cannot move into a preset.** `subagents` is the worked example: the registry answers cross-session queries for the host api-proxy, so a per-session copy both starves that host row — it waits forever for a service nothing provides — and collides on the second session, since a provider name registers once. The preset contributes the delegation *tools*; the registry and its backends stay host-side. A preset is a directory holding one `agent.cordis.yml`, optionally beside a `preset.yml` carrying display metadata — `name` and `description` (and, for shipped presets, a roster `order`). Write the metadata too: a preset without it shows up in every picker as its bare directory name. Locally authored presets live one directory per preset under `${DSH_HOME:-$HOME/.dsh}/.agent-presets/`, and the shipped set sits beside the deployment's own config. Use those when the user asks where to look. For deployment overrides, read `${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/cordis.patch.yml`, `${DSH_HOME:-$HOME/.dsh}/cordis.patch.yml`, and any launch `--patch` files for the `agent-presets` row's `roots` and `includeUserRoot`. Obtain the active profile and extra patch paths from the user when they are not in the task context; do not guess a different profile. ## Authoring a preset Use shell and file tools to locate the installed `@deepseek-ai/dsh-agent-presets` package under the active profile's `node_modules` or the deployment installation. Its `presets/<id>/` directory contains each shipped preset. If those files are unavailable, ask the user to copy the preset through the Web preset picker and provide the copied directory; runtime API inspection does not execute Remote methods. Copy the complete source directory, including skills and assets, into a new `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<new-id>/` directory (or the explicitly configured writable root). Refuse an existing destination. Set `name` and `description` in `preset.yml` and remove the copied roster `order`. Never overwrite the installed source. Edit the copy's `agent.cordis.yml` with the normal file tools. Writes outside the workspace follow the active filesystem approval policy. For profile-wide capabilities, author a workspace bundle and install it with `plugin_manager`; load `cordis-plugin-development` for packaging guidance. ## Service isolation A preset row that publishes a service needs an `isolate` realm containing both the provider and all its consumers. A tool that only consumes a host service remains outside that realm. Copy the shipped preset's existing groups rather than introducing service instances into the process-global realm. ```yaml - id: delegation name: cordis:group group: true isolate: workflowEngine: true config: - id: workflow-ptc name: '@deepseek-ai/dsh-workflow-ptc' config: provider: spawn - id: tool-workflow name: '@deepseek-ai/dsh-tool-workflow' ``` ## Verify a preset Check the edited YAML and referenced local files with file tools. Ask the user to select the new preset in the Web picker and start a session; this authoring agent cannot invoke the preset Remote API or start a Web session through inspection. Once the user provides a running session or browser control, inspect the visible tools and any activation diagnostic. File validation alone does not verify imports, service dependencies, or isolation. Report which checks ran and leave activation unverified until that session check succeeds. ## Native product subagents Codex and Claude Code providers are independent optional Profile Bundles. Install only the products a Profile needs, then restart the Profile so its Host registers those providers: ```sh dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-codex dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-claude-code ``` Each Bundle owns its Host availability; the preset separately grants one Agent its ordinary delegation tool. Never move a product provider into the preset and never add a product-specific settings field. Removing one package withdraws only that provider on the next Profile start. Copy these disabled templates from a shipped full preset and remove `disabled` only for the products the user requested: ```yaml - id: tool-subagent-codex name: '@deepseek-ai/dsh-tool-subagent' disabled: true config: provider: codex toolName: subagent_codex backgroundMode: one-shot maxDepth: provider-managed - id: tool-subagent-claude-code name: '@deepseek-ai/dsh-tool-subagent' disabled: true config: provider: claude-code toolName: subagent_claude_code backgroundMode: one-shot maxDepth: provider-managed ``` For additional named Codex or Claude Code instances, mount a separate host-plane provider row for each instance with a unique `providerName`, then add a separate preset tool row whose `provider` exactly matches that name and whose `toolName` is also unique. Keep the shipped rows for the default `codex` and `claude-code` names; do not reuse one tool row for several providers or derive either name from permission or environment settings. The two rows are independent. Leaving both disabled preserves the copied preset, enabling one exposes only that product tool, and enabling both exposes both. Production `dsh` does not install either optional provider: before enabling a row, install the matching `@deepseek-ai/dsh-subagent-codex` or `@deepseek-ai/dsh-subagent-claude-code` Bundle in the Profile and restart it. Each Bundle registers its dormant default provider and exclusively uses its pinned package-local platform CLI; additional named instances use extra host-plane rows from the same installed package. A preset cannot provide that host dependency. `backgroundMode: one-shot` keeps omitted or `false` calls in the foreground and lets explicit `run_in_background: true` return a generic Job id. Full presets already carry `tool-jobs`, while the base host carries the job registry; retain both so `job_output`, `job_list`, `job_kill`, cancellation, and completion notices stay available. Installing a Bundle or composing a preset row does not start a product, authenticate an account, select a model, probe credentials, or manage native product settings. ## What not to move into a preset `agent-loop` registers the one agent factory and throws on a second. The registries own the per-session layering and cannot themselves be per-session. Session persistence must stay host-side or the session list fragments. The sandbox, approval, and permission rows are a deliberate boundary: a preset is exactly as privileged as the plugins it names, so letting one relax its own confinement would defeat the confinement. </skill_instructions> </skill_content>"
 - button "Inspect"
-- button "Think The skill is loaded."
+- button "Think"
 - paragraph: DONE
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/steering/mid-steer.expected.md b/snapshots/web/steering/mid-steer.expected.md
index 18b8b2bda0..f8b2fc5561 100644
--- a/snapshots/web/steering/mid-steer.expected.md
+++ b/snapshots/web/steering/mid-steer.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use the ask_user_question tool to ask me exactly one question with id "checkpoint", question "Ready to continue?", header "Checkpoint", and options labeled "Yes" and "No". After I answer, reply with one short sentence acknowledging my answer and stop. {{clock}}
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/steering/settled-expanded.expected.md b/snapshots/web/steering/settled-expanded.expected.md
index 558a2cbccd..037a6f71da 100644
--- a/snapshots/web/steering/settled-expanded.expected.md
+++ b/snapshots/web/steering/settled-expanded.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use the ask_user_question tool to ask me exactly one question with id "checkpoint", question "Ready to continue?", header "Checkpoint", and options labeled "Yes" and "No". After I answer, reply with one short sentence acknowledging my answer and stop. {{clock}}
 - button "Copy"
 - button "1 tool call" [expanded]
diff --git a/snapshots/web/steering/settled.expected.md b/snapshots/web/steering/settled.expected.md
index 9d5e8bbdc5..b1cb14742e 100644
--- a/snapshots/web/steering/settled.expected.md
+++ b/snapshots/web/steering/settled.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use the ask_user_question tool to ask me exactly one question with id "checkpoint", question "Ready to continue?", header "Checkpoint", and options labeled "Yes" and "No". After I answer, reply with one short sentence acknowledging my answer and stop. {{clock}}
 - button "Copy"
 - button "1 tool call"
diff --git a/snapshots/web/subagent-conversation/sidebar-chat.expected.md b/snapshots/web/subagent-conversation/sidebar-chat.expected.md
index 588d7bc778..2563dc0d92 100644
--- a/snapshots/web/subagent-conversation/sidebar-chat.expected.md
+++ b/snapshots/web/subagent-conversation/sidebar-chat.expected.md
@@ -1,4 +1,3 @@
-- button "System prompt"
 - text: "Explain event sourcing in one sentence.Your parent agent id is \"session-{{uuid}}\". Before you finish, send your result to that agent with send_message({ agent_id: \"session-{{uuid}}\", message: \"<self-contained result>\" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn. {{clock}}"
 - button "Copy"
 - button "Thought for a while"
diff --git a/snapshots/web/subagent-conversation/ui-expanded.expected.md b/snapshots/web/subagent-conversation/ui-expanded.expected.md
index 958a6e5041..c4a77f1285 100644
--- a/snapshots/web/subagent-conversation/ui-expanded.expected.md
+++ b/snapshots/web/subagent-conversation/ui-expanded.expected.md
@@ -13,23 +13,20 @@
 - navigation "Turn navigation":
   - button "Jump to turn 1"
   - button "Jump to turn 2"
-- button "System prompt"
 - text: "Explain event sourcing in one sentence.Your parent agent id is \"session-{{uuid}}\". Before you finish, send your result to that agent with send_message({ agent_id: \"session-{{uuid}}\", message: \"<self-contained result>\" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn. {{clock}}"
 - button "Copy"
 - button "Thought for a while" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls."
+- button "Think"
 - paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures.
 - button "Copy"
 - button "Good response"
 - button "Bad response"
 - button "Branch into a new conversation"
-- text: {{clock}}
-- button "System prompt"
-- text: Now give the same explanation to a human reader. {{clock}}
+- text: {{clock}} Now give the same explanation to a human reader. {{clock}}
 - button "Copy"
 - button "Thought for a while" [expanded]
-- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls."
+- button "Think"
 - paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures.
 - button "Copy"
 - button "Good response"
diff --git a/snapshots/web/subagent-conversation/ui.expected.md b/snapshots/web/subagent-conversation/ui.expected.md
index 62af856938..5e1ccfc3fa 100644
--- a/snapshots/web/subagent-conversation/ui.expected.md
+++ b/snapshots/web/subagent-conversation/ui.expected.md
@@ -13,7 +13,6 @@
 - navigation "Turn navigation":
   - button "Jump to turn 1"
   - button "Jump to turn 2"
-- button "System prompt"
 - text: "Explain event sourcing in one sentence.Your parent agent id is \"session-{{uuid}}\". Before you finish, send your result to that agent with send_message({ agent_id: \"session-{{uuid}}\", message: \"<self-contained result>\" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn. {{clock}}"
 - button "Copy"
 - button "Thought for a while"
@@ -22,9 +21,7 @@
 - button "Good response"
 - button "Bad response"
 - button "Branch into a new conversation"
-- text: {{clock}}
-- button "System prompt"
-- text: Now give the same explanation to a human reader. {{clock}}
+- text: {{clock}} Now give the same explanation to a human reader. {{clock}}
 - button "Copy"
 - button "Thought for a while"
 - paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures.
diff --git a/snapshots/web/subagent-interrupt/offline-composer.expected.md b/snapshots/web/subagent-interrupt/offline-composer.expected.md
index 32ef6d7bd7..7c67669374 100644
--- a/snapshots/web/subagent-interrupt/offline-composer.expected.md
+++ b/snapshots/web/subagent-interrupt/offline-composer.expected.md
@@ -9,7 +9,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: "Explain event sourcing in one sentence.Your parent agent id is \"session-{{uuid}}\". Before you finish, send your result to that agent with send_message({ agent_id: \"session-{{uuid}}\", message: \"<self-contained result>\" }). The parent shares your workspace but does not automatically receive your transcript, tool output, or reasoning. Send earlier messages as well when a finding changes what the parent should do next; sending a message does not end your turn. {{clock}}"
 - button "Copy"
 - button "Context injection runtime-context"
diff --git a/snapshots/web/turn-tail-actions/completed.expected.md b/snapshots/web/turn-tail-actions/completed.expected.md
index 88cbf864a8..52872ef7db 100644
--- a/snapshots/web/turn-tail-actions/completed.expected.md
+++ b/snapshots/web/turn-tail-actions/completed.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Begin your reply with the plain sentence "Reading the workspace now." as text, and in that same message call the bash tool with the command "echo alpha". After the tool result, reply with the single word DONE and stop. {{clock}}
 - button "Copy"
 - button "1 tool call · 1 message"
diff --git a/snapshots/web/turn-tail-actions/focused.expected.md b/snapshots/web/turn-tail-actions/focused.expected.md
index 97ce445aef..cd8c64c32e 100644
--- a/snapshots/web/turn-tail-actions/focused.expected.md
+++ b/snapshots/web/turn-tail-actions/focused.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Begin your reply with the plain sentence "Reading the workspace now." as text, and in that same message call the bash tool with the command "echo alpha". After the tool result, reply with the single word DONE and stop. {{clock}}
 - button "Copy"
 - button "1 tool call · 1 message" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to begin with \"Reading the workspace now.\" and call bash with \"echo alpha\" in the same message. Then after the tool result, reply with the single word DONE and stop."
+- button "Think"
 - paragraph: Reading the workspace now.
 - button "Bash Print alpha to stdout"
 - paragraph: DONE
diff --git a/snapshots/web/turn-tail-actions/running.expected.md b/snapshots/web/turn-tail-actions/running.expected.md
index 0aad69b556..ce077f8d64 100644
--- a/snapshots/web/turn-tail-actions/running.expected.md
+++ b/snapshots/web/turn-tail-actions/running.expected.md
@@ -6,12 +6,11 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Begin your reply with the plain sentence "Reading the workspace now." as text, and in that same message call the bash tool with the command "echo alpha". After the tool result, reply with the single word DONE and stop. {{clock}}
 - button "Copy"
 - tooltip "Copy"
 - button "Context injection runtime-context"
-- button "Think The user wants me to begin with \"Reading the workspace now.\" and call bash with \"echo alpha\" in the same message. Then after the tool result, reply with the single word DONE and stop."
+- button "Think"
 - paragraph: Reading the workspace now.
 - button "Bash Print alpha to stdout"
 - paragraph: partial
diff --git a/snapshots/web/turn-tail-actions/settled.expected.md b/snapshots/web/turn-tail-actions/settled.expected.md
index 33ff59bd2a..df291fa049 100644
--- a/snapshots/web/turn-tail-actions/settled.expected.md
+++ b/snapshots/web/turn-tail-actions/settled.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Begin your reply with the plain sentence "Reading the workspace now." as text, and in that same message call the bash tool with the command "echo alpha". After the tool result, reply with the single word DONE and stop. {{clock}}
 - button "Copy"
 - button "1 tool call · 1 message"
diff --git a/snapshots/web/turn-tail-actions/usage-expanded.expected.md b/snapshots/web/turn-tail-actions/usage-expanded.expected.md
index ea6ffa712d..19a3319879 100644
--- a/snapshots/web/turn-tail-actions/usage-expanded.expected.md
+++ b/snapshots/web/turn-tail-actions/usage-expanded.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Begin your reply with the plain sentence "Reading the workspace now." as text, and in that same message call the bash tool with the command "echo alpha". After the tool result, reply with the single word DONE and stop. {{clock}}
 - button "Copy"
 - button "1 tool call · 1 message"
diff --git a/snapshots/web/web-search-round/ui.expected.md b/snapshots/web/web-search-round/ui.expected.md
index a843fffa55..b769848c9f 100644
--- a/snapshots/web/web-search-round/ui.expected.md
+++ b/snapshots/web/web-search-round/ui.expected.md
@@ -6,7 +6,6 @@
   - tablist:
     - tab "Chat" [selected]
     - tab "Trajectory"
-- button "System prompt"
 - text: Use web_search once with queries ["DeepSeek Harness snapshot search","DeepSeek Harness multi-query search"]. Then reply exactly SEARCH_DONE and stop. {{clock}}
 - button "Copy"
 - button "1 tool call" [expanded]
diff --git a/snapshots/web/workflow-run/ui.expected.md b/snapshots/web/workflow-run/ui.expected.md
index da34c06fd8..cd0ee5f743 100644
--- a/snapshots/web/workflow-run/ui.expected.md
+++ b/snapshots/web/workflow-run/ui.expected.md
@@ -1,12 +1,11 @@
-- button "System prompt"
 - text: "Use the workflow tool exactly once, with args omitted, meta set to { \"name\": \"snapshot-flow\", \"description\": \"one child for the snapshot\" }, and this EXACT script body (copy it verbatim): phase('Run') const reply = await agent('Reply with exactly the word WF_CHILD_OK and nothing else.') return { reply } After the workflow returns, reply with the single word WORKFLOW_DONE and stop. Do not use any other tool. {{clock}}"
 - button "Copy"
 - button "1 tool call" [expanded]
 - button "Context injection runtime-context"
-- button "Think The user wants me to use the workflow tool exactly once with specific parameters. Let me carefully follow the instructions:"
+- button "Think"
 - button "Run workflow snapshot-flow"
 - button "snapshot-flow 1 member Completed"
-- button "Think The workflow returned successfully with the reply \"WF_CHILD_OK\". Now I need to reply with exactly \"WORKFLOW_DONE\" and stop."
+- button "Think"
 - paragraph: WORKFLOW_DONE
 - button "Copy"
 - button "Good response"
diff --git a/tsconfig.base.json b/tsconfig.base.json
index cc1b65cc78..313fd9eeff 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -71,6 +71,9 @@
       "@deepseek-ai/dsh-api-gateway": ["./packages/api/gateway/src/index.ts"],
       "@deepseek-ai/dsh-api-gateway/client": ["./packages/api/gateway/src/client/index.ts"],
       "@deepseek-ai/dsh-api-gateway/types": ["./packages/api/gateway/src/types.ts"],
+      "@deepseek-ai/dsh-api-job-controller": ["./packages/api/job-controller/src/index.ts"],
+      "@deepseek-ai/dsh-api-job-controller/client": ["./packages/api/job-controller/src/client/index.ts"],
+      "@deepseek-ai/dsh-api-job-controller/types": ["./packages/api/job-controller/src/types.ts"],
       "@deepseek-ai/dsh-api-session-controller": ["./packages/api/session-controller/src/index.ts"],
       "@deepseek-ai/dsh-api-session-controller/client": ["./packages/api/session-controller/src/client/index.ts"],
       "@deepseek-ai/dsh-api-session-controller/types": ["./packages/api/session-controller/src/types.ts"],
@@ -128,6 +131,7 @@
       "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"],
       "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"],
       "@deepseek-ai/dsh-jobs/brand": ["./packages/jobs/jobs/src/brand.ts"],
+      "@deepseek-ai/dsh-jobs/view": ["./packages/jobs/jobs/src/view.ts"],
       "@deepseek-ai/dsh-credentials/types": ["./packages/credentials/credentials/src/types.ts"],
       "@deepseek-ai/dsh-authorization/types": ["./packages/credentials/authorization/src/types.ts"],
       "@deepseek-ai/dsh-settings/types": ["./packages/settings/settings/src/types.ts"],
@@ -181,6 +185,7 @@
       "@deepseek-ai/dsh-plugin-manager/registry": ["./packages/boot/plugin-manager/src/registry.ts"],
       "@deepseek-ai/dsh-plugin-manager/operations": ["./packages/boot/plugin-manager/src/operations.ts"],
       "@deepseek-ai/dsh-plugin-manager/tools": ["./packages/boot/plugin-manager/src/tools.ts"],
+      "@deepseek-ai/dsh-tool-cordis/host": ["./packages/extensions/tool-cordis/src/host.ts"],
       "@deepseek-ai/dsh-host-plugin-inventory": ["./packages/host/plugin-inventory/src"],
       "@deepseek-ai/dsh-host-plugin-inventory/types": ["./packages/host/plugin-inventory/src/types.ts"],
       "@deepseek-ai/dsh-client-ui-slots": ["./packages/client/ui-slots/src"],
@@ -193,6 +198,7 @@
       "@deepseek-ai/dsh-client-ui-sidebar-documentpreview/client": ["./packages/client/ui-sidebar-documentpreview/src/client"],
       "@deepseek-ai/dsh-client-ui-sidebar-browser": ["./packages/client/ui-sidebar-browser/src"],
       "@deepseek-ai/dsh-client-ui-sidebar-browser/client": ["./packages/client/ui-sidebar-browser/src/client"],
+      "@deepseek-ai/dsh-client-ui-sidebar-browser/types": ["./packages/client/ui-sidebar-browser/src/types.ts"],
       "@deepseek-ai/dsh-api-workspace-files": ["./packages/api/workspace-files/src"],
       "@deepseek-ai/dsh-api-workspace-files/types": ["./packages/api/workspace-files/src/types.ts"],
       "@deepseek-ai/dsh-api-workspace-files/client": ["./packages/api/workspace-files/src/client/index.ts"],
@@ -245,6 +251,8 @@
       "@deepseek-ai/dsh-experimental-client-ui-agent-team": ["./packages/experimental/client-ui-agent-team/src"],
       "@deepseek-ai/dsh-client-ui-settings-plugins": ["./packages/client/ui-settings-plugins/src"],
       "@deepseek-ai/dsh-client-ui-jobs": ["./packages/client/ui-jobs/src"],
+      "@deepseek-ai/dsh-client-ui-jobs/client": ["./packages/client/ui-jobs/src/client/index.ts"],
+      "@deepseek-ai/dsh-client-ui-jobs/invariant": ["./packages/client/ui-jobs/src/invariant.ts"],
       "@deepseek-ai/dsh-client-ui-schedule": ["./packages/client/ui-schedule/src"],
       "@deepseek-ai/dsh-client-ui-schedule/client": ["./packages/client/ui-schedule/src/client/index.ts"],
       "@deepseek-ai/dsh-client-ui-plan": ["./packages/client/ui-plan/src"],
@@ -254,6 +262,7 @@
       "@deepseek-ai/dsh-client-ui-theme": ["./packages/client/ui-theme/src"],
       "@deepseek-ai/dsh-client-ui-settings": ["./packages/client/ui-settings/src"],
       "@deepseek-ai/dsh-client-ui-settings-general": ["./packages/client/ui-settings-general/src"],
+      "@deepseek-ai/dsh-client-ui-settings-general/types": ["./packages/client/ui-settings-general/src/types.ts"],
       "@deepseek-ai/dsh-client-ui-settings-models": ["./packages/client/ui-settings-models/src"],
       "@deepseek-ai/dsh-client-ui-plugin-manager": ["./packages/client/ui-plugin-manager/src"],
       "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": ["./packages/client/ui-settings-plugin-inventory/src"],
@@ -289,6 +298,7 @@
       "@deepseek-ai/dsh-session-log-export/client": ["./packages/session-query/session-log-export/src/client"],
       "@deepseek-ai/dsh-compaction-image-offload/projection": ["./packages/compaction/compaction-image-offload/src/projection.ts"],
       "@deepseek-ai/dsh-session-format-catalog/message-projections": ["./packages/session/session-format-catalog/src/message-projections.ts"],
+      "@deepseek-ai/dsh-native-command/types": ["./packages/util/native-command/src/types.ts"],
       // BEGIN generated package aliases — pnpm run gen-tsconfig-paths
       "@deepseek-ai/dsh-acp": ["./packages/acp/acp/src"],
       "@deepseek-ai/dsh-acp-app": ["./packages/bundle/acp-app/src"],
@@ -482,6 +492,7 @@
       "@deepseek-ai/dsh-tool-web": ["./packages/web/tool-web/src"],
       "@deepseek-ai/dsh-tool-workflow": ["./packages/workflow/tool-workflow/src"],
       "@deepseek-ai/dsh-tool-workflow/invariant": ["./packages/workflow/tool-workflow/src/invariant.ts"],
+      "@deepseek-ai/dsh-tool-workspace-dependencies": ["./packages/skill/tool-workspace-dependencies/src"],
       "@deepseek-ai/dsh-tools": ["./packages/core/tools/src"],
       "@deepseek-ai/dsh-tools/invariant": ["./packages/core/tools/src/invariant.ts"],
       "@deepseek-ai/dsh-user-approval": ["./packages/interaction/user-approval/src"],
diff --git a/tsconfig.client.json b/tsconfig.client.json
index 08538a0e76..d6b4de5dc2 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -91,7 +91,7 @@
     { "path": "./packages/client/ui-dockkit" },
     { "path": "./packages/client/ui-sidebar-right" },
     { "path": "./packages/client/ui-sidebar-documentpreview/tsconfig.client.json" },
-    { "path": "./packages/client/ui-sidebar-browser" },
+    { "path": "./packages/client/ui-sidebar-browser/tsconfig.client.json" },
     { "path": "./packages/client/ui-sidebar-files" },
     { "path": "./packages/client/ui-jobs" },
     { "path": "./packages/client/ui-schedule" },
@@ -110,7 +110,7 @@
     { "path": "./packages/client/ui-open-in-app" },
     { "path": "./packages/client/ui-theme" },
     { "path": "./packages/client/ui-settings" },
-    { "path": "./packages/client/ui-settings-general" },
+    { "path": "./packages/client/ui-settings-general/tsconfig.client.json" },
     { "path": "./packages/client/ui-settings-models" },
     { "path": "./packages/client/ui-plugin-manager" },
     { "path": "./packages/client/ui-settings-plugin-inventory" },
diff --git a/tsconfig.host.json b/tsconfig.host.json
index c1088e0ae8..30dc0ea0bf 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -7,9 +7,7 @@
     "noEmit": true,
     "rewriteRelativeImportExtensions": false
   },
-  "files": [
-    "packages/client/ui-settings-general/src/client/desktop-update-bridge.ts"
-  ],
+  "files": [],
   "include": [
     "apps/web/product-isolation.ts",
     "apps/web/tests/default-product-isolation.e2e.ts",
@@ -41,12 +39,14 @@
     "apps/web/tests/chat-scroll-fixture.ts",
     "apps/web/tests/trajectory-virtualization.e2e.ts",
     "apps/web/tests/lifecycle-chrome.e2e.ts",
+    "apps/web/tests/reasoning-preview.e2e.ts",
     "apps/web/tests/details-session-lifecycle.e2e.ts",
     "apps/web/tests/sessionless-header.e2e.ts",
     "apps/web/tests/document-preview.e2e.ts",
     "apps/web/tests/office-fixture.ts",
     "apps/web/tests/sidebar-browser.e2e.ts",
     "apps/web/tests/plugin-config.e2e.ts",
+    "apps/web/tests/input-plugin-extensions.e2e.ts",
     "apps/web/tests/plugin-manager.e2e.ts",
     "apps/web/tests/plugin-install-cancel.e2e.ts",
     "apps/web/tests/plugin-install-approve.e2e.ts",
@@ -63,6 +63,8 @@
     "apps/web/tests/public-mount.e2e.ts",
     "apps/web/tests/workspace-new-session-folding.e2e.ts",
     "apps/web/tests/workspace-management.e2e.ts",
+    "apps/web/tests/default-workspace.e2e.ts",
+    "apps/web/tests/new-session-refused.e2e.ts",
     "apps/web/tests/workspace-recency.e2e.ts",
     "apps/web/tests/session-unarchive.e2e.ts",
     "apps/web/tests/replay-round-trip.e2e.ts",
@@ -121,6 +123,7 @@
     "apps/web/tests/subagent-interrupt-ui.e2e.ts",
     "apps/web/tests/sidebar-subagent-activity.e2e.ts",
     "apps/web/tests/background-job-list.e2e.ts",
+    "apps/web/tests/live-job-stream.e2e.ts",
     "apps/web/tests/bash-abort-row.e2e.ts",
     "apps/web/tests/skill-tool-row.e2e.ts",
     "apps/web/tests/tool-details.e2e.ts",
@@ -169,6 +172,7 @@
   "references": [
     { "path": "./packages/client/connection/tsconfig.host.json" },
     { "path": "./packages/skill/skill-office" },
+    { "path": "./packages/skill/tool-workspace-dependencies" },
     { "path": "./packages/browser-use/browser-use" },
     { "path": "./packages/experimental/browser-use-runtime" },
     { "path": "./packages/experimental/browser-use-playwright-mcp" },
@@ -179,6 +183,8 @@
     { "path": "./packages/experimental/computer-use-cua-driver-mcp" },
     { "path": "./packages/experimental/computer-use-cua-driver-native" },
     { "path": "./packages/client/ui-sidebar-documentpreview/tsconfig.host.json" },
+    { "path": "./packages/client/ui-sidebar-browser/tsconfig.host.json" },
+    { "path": "./packages/client/ui-settings-general/tsconfig.host.json" },
     { "path": "./packages/document/office-to-pdf" },
     { "path": "./packages/client/ui-deliverables/tsconfig.host.json" },
     { "path": "./vendor/cosmokit" },
@@ -219,6 +225,7 @@
     { "path": "./packages/typert/registry" },
     { "path": "./packages/api/gateway/tsconfig.host.json" },
     { "path": "./packages/api/remotes/tsconfig.host.json" },
+    { "path": "./packages/api/job-controller/tsconfig.host.json" },
     { "path": "./packages/api/session-controller/tsconfig.host.json" },
     { "path": "./packages/api/workspace-files/tsconfig.host.json" },
     { "path": "./packages/api/settings-controller" },
diff --git a/vendor/README.md b/vendor/README.md
index 4c9e1832ae..f6e31b6617 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -54,6 +54,8 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 
 21. **`cordis/src/logger.ts` exporter disposal**: each disposer retains its registration id, so removing an earlier exporter cannot delete a later console or telemetry exporter. Covered by startup collector cleanup in `packages/boot/app-boot/tests/app-boot.spec.ts` and disabled-feedback output in `packages/session/session-telemetry-otel/tests/loader-composition.e2e.ts`.
 
+22. **Volatile config across `cosmokit`, `schemastery`, `cordis`, and `loader`**: Cosmokit supplies immutable references and framework-owned commits; `deepEqual` treats two references as equal, propagates strict comparison into arrays, compares every array slot with holes treated as undefined, handles cycles conservatively, compares URLs by normalized href, and compares other opaque objects by identity in strict mode. Schemastery adds `.volatile()`, optional/default inference, placement validation without eager lazy-schema expansion (a lazy inner is validated once when built), metadata-free serialized node compatibility, serialized metadata, reference-aware simplification, unsupported volatile values reported as `ValidationError` with their path, and `.default()` accepting the raw input type `Partial<S>` because a volatile field makes the output type carry references. Loader's save path calls `simplify` with its schema receiver (`unparse.call`), an independent fix for the unbound-`this` call. Cordis exports consumer types without changing Fiber lifecycle. Loader compares raw options strictly in `Entry.update`; for a config-only change on an active fiber it calls the pure `equalExceptVolatile` function in `config/diff.ts`, which narrows the Standard Schema to Schemastery's `Schema` type (a new type-only `@deepseek-ai/schemastery` dependency of `loader`) and recursively skips fixed volatile paths using schema metadata without executing config hooks or validation. Missing or null object nodes compare using their declared defaults, including nodes without volatile descendants; schema backedges retain raw comparison. Entry passes its actual schema and preserves ordinary context and custom-update lifecycles. For a volatile-only change, `Entry._commitVolatile` re-parses the raw config through the fiber's `internal/config` hook and `resolveConfig`, compares ordinary effective values, commits references and emits the instance-local `loader/volatile-update` declared in `loader/src/index.ts`; a changed ordinary effective value falls back to the ordinary remount, and an invalid candidate is logged while the raw config stays retained for the next activation. Cosmokit provides reference enumeration and commits, and `simplify` is called with its schema receiver. The package READMEs document these additions; schema tests live in `scripts/volatile-config.spec.ts`, Loader runtime and real-file tests in `scripts/loader-volatile-update.spec.ts`, and code replacement tests in the HMR module suite.
+
 ## Sync procedure
 
 To update a vendored package from upstream:
diff --git a/vendor/cordis/README.md b/vendor/cordis/README.md
index 538809ddfb..d0181dbf76 100644
--- a/vendor/cordis/README.md
+++ b/vendor/cordis/README.md
@@ -99,3 +99,7 @@ yarn lint
 The monorepo uses Yakumo to build and test all packages. Most examples in the
 docs use public APIs from `cordis`; loader examples additionally use
 `@cordisjs/plugin-loader` and `@cordisjs/plugin-include`.
+
+## Volatile configuration
+
+Schemas may return `Volatile<T>` references, whose values are read through `.get()`. Cordis exports the consumer types; Loader commits volatile-only changes into the running references without restarting and notifies the owning fiber through `loader/volatile-update`. Direct `fiber.update()` retains its existing update waterfall and default restart.
diff --git a/vendor/cordis/src/index.ts b/vendor/cordis/src/index.ts
index d0814213e0..5c27008b44 100644
--- a/vendor/cordis/src/index.ts
+++ b/vendor/cordis/src/index.ts
@@ -12,3 +12,5 @@ export * from './registry.ts'
 export * from './service.ts'
 /** Shared internal helpers used by context, services, and plugin fibers. */
 export * from './utils.ts'
+/** Readonly references returned by volatile config schemas. */
+export type { Volatile, VolatileSnapshot } from '@deepseek-ai/cosmokit'
diff --git a/vendor/cosmokit/README.md b/vendor/cosmokit/README.md
index 5398a146c2..7cdc1d1704 100644
--- a/vendor/cosmokit/README.md
+++ b/vendor/cosmokit/README.md
@@ -22,3 +22,9 @@ import cosmokit from 'cosmokit'
 ```ts
 import cosmokit from 'npm:cosmokit@latest'
 ```
+
+## Config references
+
+`Volatile<T>` exposes `get()` for immutable data snapshots. `createVolatile()` copies and freezes validated data; framework-owned `updateVolatile()` transfers a candidate snapshot into an existing reference. Framework-owned `volatileEntries()` enumerates references and their paths through plain config containers, stopping at snapshots and opaque objects. The shared symbol protocol recognizes references across ESM/CJS copies. Plugin consumers import the type from Cordis and retain the reference rather than caching values between operations.
+
+`deepEqual()` treats two volatile references as equal regardless of their snapshots. Strict comparisons distinguish null from undefined recursively, compare URLs by normalized `href` and other opaque objects by identity, and treat distinct cyclic structures as unequal. Array comparison visits every index and treats holes as undefined. Snapshot-change detection must compare `.get()` results separately.
diff --git a/vendor/cosmokit/src/index.ts b/vendor/cosmokit/src/index.ts
index 9fe48de069..b6b7144168 100644
--- a/vendor/cosmokit/src/index.ts
+++ b/vendor/cosmokit/src/index.ts
@@ -8,3 +8,5 @@ export * from './misc.ts'
 export * from './string.ts'
 /** Time constants, parsing, and formatting helpers. */
 export * from './time.ts'
+/** Immutable config references shared by schema validators and runtimes. */
+export * from './volatile.ts'
diff --git a/vendor/cosmokit/src/types.ts b/vendor/cosmokit/src/types.ts
index 499a46273a..0aab4420c1 100644
--- a/vendor/cosmokit/src/types.ts
+++ b/vendor/cosmokit/src/types.ts
@@ -1,4 +1,5 @@
 import { isNullable } from './misc.ts'
+import { isVolatile } from './volatile.ts'
 
 type GlobalConstructorNames = keyof {
   [K in keyof typeof globalThis as typeof globalThis[K] extends abstract new (...args: any) => any ? K : never]: K
@@ -114,29 +115,54 @@ export function clone(source: any, refs = new Map<any, any>()) {
   return result
 }
 
-/** Deeply compare arrays, dates, regexps, buffers, and plain object fields. */
+/**
+ * Compare values recursively, treating two volatile references as equal regardless of value.
+ * Strict comparison distinguishes null/undefined, treats opaque objects by identity,
+ * compares URLs by normalized href, treats array holes as undefined, and considers distinct cyclic structures unequal.
+ * @param a - first value.
+ * @param b - second value.
+ * @param strict - whether to require strict data equality outside volatile references.
+ * @returns whether the values compare equal.
+ */
 export function deepEqual(a: any, b: any, strict?: boolean): boolean {
-  if (a === b) return true
-  if (!strict && isNullable(a) && isNullable(b)) return true
-  if (typeof a !== typeof b) return false
-  if (typeof a !== 'object') return false
-  if (!a || !b) return false
+  const ancestors = new Set<object>()
+  function compare(a: any, b: any): boolean {
+    if (a === b) return true
+    if (isVolatile(a) || isVolatile(b)) return isVolatile(a) && isVolatile(b)
+    if (!strict && isNullable(a) && isNullable(b)) return true
+    if (typeof a !== typeof b || typeof a !== 'object' || !a || !b) return false
+    if (ancestors.has(a)) return false
 
-  function check<T>(test: (x: any) => x is T, then: (a: T, b: T) => boolean) {
-    return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : undefined
+    function check<T>(test: (x: any) => x is T, then: (a: T, b: T) => boolean) {
+      return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : undefined
+    }
+
+    ancestors.add(a)
+    try {
+      return check(Array.isArray, (a, b) => {
+        if (a.length !== b.length) return false
+        for (let index = 0; index < a.length; index++) {
+          if (!compare(a[index], b[index])) return false
+        }
+        return true
+      })
+        ?? check(is('Date'), (a, b) => a.valueOf() === b.valueOf())
+        ?? check(is('URL'), (a, b) => a.href === b.href)
+        ?? check(is('RegExp'), (a, b) => a.source === b.source && a.flags === b.flags)
+        ?? check(isArrayBufferLike, (a, b) => {
+          if (a.byteLength !== b.byteLength) return false
+          const viewA = new Uint8Array(a)
+          const viewB = new Uint8Array(b)
+          for (let i = 0; i < viewA.length; i++) {
+            if (viewA[i] !== viewB[i]) return false
+          }
+          return true
+        })
+        ?? ((!strict || [a, b].every(value => Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null))
+          && Object.keys({ ...a, ...b }).every(key => compare(a[key], b[key])))
+    } finally {
+      ancestors.delete(a)
+    }
   }
-
-  return check(Array.isArray, (a, b) => a.length === b.length && a.every((item, index) => deepEqual(item, b[index])))
-    ?? check(is('Date'), (a, b) => a.valueOf() === b.valueOf())
-    ?? check(is('RegExp'), (a, b) => a.source === b.source && a.flags === b.flags)
-    ?? check(isArrayBufferLike, (a, b) => {
-      if (a.byteLength !== b.byteLength) return false
-      const viewA = new Uint8Array(a)
-      const viewB = new Uint8Array(b)
-      for (let i = 0; i < viewA.length; i++) {
-        if (viewA[i] !== viewB[i]) return false
-      }
-      return true
-    })
-    ?? Object.keys({ ...a, ...b }).every(key => deepEqual(a[key], b[key], strict))
+  return compare(a, b)
 }
diff --git a/vendor/cosmokit/src/volatile.ts b/vendor/cosmokit/src/volatile.ts
new file mode 100644
index 0000000000..a64c35f253
--- /dev/null
+++ b/vendor/cosmokit/src/volatile.ts
@@ -0,0 +1,86 @@
+/** Shared config references used by schema validators and plugin runtimes. */
+
+const write = Symbol.for('cosmokit.volatile.write')
+
+/** Recursively readonly data returned by a volatile config reference. */
+export type VolatileSnapshot<T> = T extends object ? { readonly [K in keyof T]: VolatileSnapshot<T[K]> } : T
+
+/** A stable reference; keep the reference, or capture its value for one operation only. */
+export interface Volatile<T> {
+  /** @returns the current immutable snapshot, including undefined for an absent value. */
+  get(): VolatileSnapshot<T>
+}
+
+interface WritableVolatile extends Volatile<unknown> {
+  [write](value: unknown): void
+}
+
+function snapshot(value: unknown, ancestors = new Set<object>()): unknown {
+  if (typeof value === 'function') throw new TypeError('volatile config cannot contain functions')
+  if (value === null || typeof value !== 'object') return value
+  if (ancestors.has(value)) throw new TypeError('volatile config cannot contain cycles')
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) return Object.freeze(value.map(item => snapshot(item, ancestors)))
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+      throw new TypeError('volatile config objects must be plain objects or arrays')
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item, ancestors)])))
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+/**
+ * Create a detached reference containing an immutable copy of the supplied data.
+ * @param value - validated config data; class instances and functions are unsupported.
+ * @returns a reference whose value is updated only by its owning runtime.
+ */
+export function createVolatile<T>(value: T): Volatile<T> {
+  let current = snapshot(value)
+  return Object.freeze({
+    get: () => current,
+    [write]: (value: unknown) => { current = value },
+  }) as Volatile<T>
+}
+
+/**
+ * Identify references across ESM/CJS copies of the shared library.
+ * @param value - a parsed config value.
+ * @returns whether the value implements the shared reference protocol.
+ */
+export function isVolatile(value: unknown): value is Volatile<unknown> {
+  return typeof value === 'object' && value !== null && write in value
+}
+
+/**
+ * Collect config references without descending into their snapshots or opaque objects.
+ * @internal
+ * @param value - parsed config; cyclic ordinary fields are visited once per path.
+ * @returns references and their object-key paths, including an empty path for a root reference.
+ */
+export function volatileEntries(value: unknown): { path: string[]; ref: Volatile<unknown> }[] {
+  const ancestors = new Set<object>()
+  function visit(value: unknown, path: string[]): { path: string[]; ref: Volatile<unknown> }[] {
+    if (isVolatile(value)) return [{ path, ref: value }]
+    if (!value || typeof value !== 'object' || ancestors.has(value)) return []
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return []
+    ancestors.add(value)
+    try {
+      return Object.entries(value).flatMap(([key, child]) => visit(child, [...path, key]))
+    } finally {
+      ancestors.delete(value)
+    }
+  }
+  return visit(value, [])
+}
+
+/**
+ * Commit an already validated immutable snapshot from another reference.
+ * @internal
+ * @param target - the owning plugin's stable reference.
+ * @param source - a newly parsed candidate reference.
+ */
+export function updateVolatile(target: Volatile<unknown>, source: Volatile<unknown>): void {
+  ;(target as WritableVolatile)[write](source.get())
+}
diff --git a/vendor/loader/README.md b/vendor/loader/README.md
index fb71b774a8..9001b2a8c2 100644
--- a/vendor/loader/README.md
+++ b/vendor/loader/README.md
@@ -46,3 +46,7 @@ root.loader.update(id, { config: { enabled: false } })
 | `loader.locate(fiber?)` | Return the loader entry id that owns a fiber. |
 
 For file-backed trees, use `@cordisjs/plugin-include`.
+
+## Volatile configuration
+
+`Entry.update` compares raw entry options strictly; when only `config` changed on an active fiber in an unchanged context, the pure `equalExceptVolatile` function in `config/diff.ts` compares the raw configs using Schemastery metadata. It ignores volatile fields at fixed object paths without executing expressions, validators or `internal/config` hooks. Object nodes use their declared defaults for null or absent values, including objects without volatile fields; equivalent defaults skip updates. Other ordinary values, parent expressions and unknown fields retain raw comparison. Recursive schema backedges use raw comparison. Entry passes the actual plugin schema; a non-Schemastery schema compares raw. Context changes, other option changes and pending fibers use ordinary updates. A volatile-only change retains the raw Fiber config for later activation, then `_commitVolatile` parses it through the fiber's `internal/config` hook and schema, commits the new values into the running references when every ordinary effective value still matches, and emits `loader/volatile-update` to the owning fiber with the changed paths. A changed ordinary effective value uses the ordinary remount with a debug log naming the entry; because strict comparison treats class instances other than URL, Date and RegExp by identity, an ordinary field whose transform builds a fresh instance on every parse always takes that remount. An invalid candidate is logged and leaves the running references unchanged. A throwing `loader/volatile-update` listener is logged and does not fail the update; the values are already committed. Group/Include retain child dispatch, and programmatic Fiber updates preserve saving and `noSave`; `simplify` is called with its schema receiver so saved config contains plain values.
diff --git a/vendor/loader/package.json b/vendor/loader/package.json
index c8ad7bcd98..6ae5a43e9b 100644
--- a/vendor/loader/package.json
+++ b/vendor/loader/package.json
@@ -39,6 +39,7 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/cosmokit": "workspace:^"
+    "@deepseek-ai/cosmokit": "workspace:^",
+    "@deepseek-ai/schemastery": "workspace:^"
   }
 }
diff --git a/vendor/loader/src/config/diff.ts b/vendor/loader/src/config/diff.ts
new file mode 100644
index 0000000000..e97d53e5ad
--- /dev/null
+++ b/vendor/loader/src/config/diff.ts
@@ -0,0 +1,45 @@
+/** Compare raw plugin configs using schema metadata without executing config hooks or validators. */
+import type { Plugin } from '@deepseek-ai/cordis'
+import { deepEqual } from '@deepseek-ai/cosmokit'
+import type Schema from '@deepseek-ai/schemastery'
+import { isJsExpr } from './utils.ts'
+
+function isSchemastery(schema: Plugin.Runtime['Config']): schema is Schema {
+  return schema?.['~standard'].vendor === 'schemastery'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || isJsExpr(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function equal(a: unknown, b: unknown, schema: Schema | undefined, ancestors: Set<Schema>): boolean {
+  if (schema?.meta?.volatile) return true
+  if (schema?.type !== 'object' || !schema.dict || ancestors.has(schema)) return deepEqual(a, b, true)
+  const left = a ?? schema.meta?.default
+  const right = b ?? schema.meta?.default
+  if (!isRecord(left) || !isRecord(right)) return deepEqual(left, right, true)
+  const { dict } = schema
+  ancestors.add(schema)
+  try {
+    return Object.keys({ ...left, ...right }).every(key =>
+      equal(left[key], right[key], Object.hasOwn(dict, key) ? dict[key] : undefined, ancestors),
+    )
+  } finally {
+    ancestors.delete(schema)
+  }
+}
+
+/**
+ * Compare two raw configs, treating schema-declared volatile fields at fixed object paths as equal and absent objects as their schema default.
+ * Schema backedges, expressions, unknown fields and opaque values keep strict raw equality; an absent or non-Schemastery schema compares everything raw.
+ * @param previous - previous raw config.
+ * @param next - next raw config.
+ * @param schema - the plugin's config schema.
+ * @returns Whether the configs differ at most in volatile fields, without evaluating expressions, validating config or modifying inputs.
+ * @internal
+ */
+export function equalExceptVolatile(previous: unknown, next: unknown, schema: Plugin.Runtime['Config']): boolean {
+  return isSchemastery(schema) ? equal(previous, next, schema, new Set()) : deepEqual(previous, next, true)
+}
diff --git a/vendor/loader/src/config/entry.ts b/vendor/loader/src/config/entry.ts
index 4aa2c473fb..8ab9f8e6a0 100644
--- a/vendor/loader/src/config/entry.ts
+++ b/vendor/loader/src/config/entry.ts
@@ -1,9 +1,10 @@
-import { Context, Fiber, Inject } from '@deepseek-ai/cordis'
-import { deepEqual, isNullable } from '@deepseek-ai/cosmokit'
+import { Context, Fiber, FiberState, Inject, resolveConfig } from '@deepseek-ai/cordis'
+import { deepEqual, isNullable, updateVolatile, volatileEntries, type Volatile } from '@deepseek-ai/cosmokit'
 import { Loader } from '../index.ts'
 import { EntryGroup } from './group.ts'
 import { EntryTree } from './tree.ts'
 import { evaluate, isJsExpr } from './utils.ts'
+import { equalExceptVolatile } from './diff.ts'
 
 /** Serialized plugin entry options stored in loader config files. */
 export interface EntryOptions {
@@ -137,17 +138,62 @@ export class Entry {
 
     // step 3: check if options are changed
     if (this.fiber?.uid) {
-      const diff = Object
-        .keys({ ...this.options, ...legacy })
-        .filter(key => !deepEqual(this.options[key], legacy[key]))
-      if (!diff.length && !force) return
+      const changes = Object.keys({ ...this.options, ...legacy })
+        .filter(key => !deepEqual(this.options[key], legacy[key], key === 'config'))
+      // Only an active fiber in an unchanged context takes volatile-only config changes without a remount.
+      const volatileOnly = changes.length === 1 && changes[0] === 'config'
+        && this.fiber.state === FiberState.ACTIVE && Object.getPrototypeOf(this.ctx) === this.parent.ctx
+        && equalExceptVolatile(legacy.config, this.options.config, this.fiber.runtime?.Config)
+      if (volatileOnly) this.fiber._config = this.options.config
+      const pending = volatileOnly && this._commitVolatile() ? [] : changes
+      if (!pending.length && !force) return
       this.context.emit('loader/partial-dispose', this, legacy, true)
-      this._patchContext(diff)
+      this._patchContext(pending)
     } else {
       await this.init()
     }
   }
 
+  /**
+   * Parse a volatile-only raw config change and commit its values into the running fiber's references.
+   * An invalid candidate is logged and leaves the running references unchanged; the raw config stays retained for the next activation.
+   * @returns `false` when an ordinary effective value changed, so the caller applies the ordinary update lifecycle.
+   */
+  private _commitVolatile(): boolean {
+    const fiber = this.fiber!
+    const refs = volatileEntries(fiber.config)
+    if (!refs.length) return true
+    const raw = this.options.config
+    let candidate: unknown
+    try {
+      candidate = resolveConfig(fiber.runtime!, fiber.ctx.waterfall(fiber, 'internal/config', raw, () => raw))
+    } catch (error) {
+      this.ctx.logger.warn('volatile config update failed for %C', this.options.id)
+      this.ctx.logger.warn(error)
+      return true
+    }
+    if (!deepEqual(fiber.config, candidate, true)) {
+      this.ctx.logger.debug('ordinary config values of %C changed with its volatile values; applying the ordinary update', this.options.id)
+      return false
+    }
+    const paths = refs.flatMap(({ path, ref }) => {
+      const source = path.reduce<unknown>((value, key) => Reflect.get(value as object, key), candidate) as Volatile<unknown>
+      if (deepEqual(ref.get(), source.get(), true)) return []
+      updateVolatile(ref, source)
+      return [path]
+    })
+    if (!paths.length) return true
+    const self: Context = Object.create(fiber.ctx)
+    self[Context.filter] = (owner: Context) => owner.fiber === fiber
+    try {
+      fiber.ctx.emit(self, 'loader/volatile-update', paths)
+    } catch (error) {
+      // A listener failure must not fail the entry update; every value is already committed.
+      this.ctx.logger.warn(error)
+    }
+    return true
+  }
+
   getOuterStack = () => {
     let entry: Entry | undefined = this
     const result: string[] = []
diff --git a/vendor/loader/src/index.ts b/vendor/loader/src/index.ts
index ac736ae356..51d36260a8 100644
--- a/vendor/loader/src/index.ts
+++ b/vendor/loader/src/index.ts
@@ -26,6 +26,18 @@ declare module '@deepseek-ai/cordis' {
     'loader/config-update'(): void
     'loader/entry-init'(entry: Entry): void
     'loader/partial-dispose'(entry: Entry, legacy: Partial<EntryOptions>, active: boolean): void
+    /**
+     * Volatile config values were committed into the running fiber without a remount; dispatched to the owning fiber only.
+     * @param paths - changed config paths as key arrays; every value is committed before dispatch.
+     * @mode emit
+     */
+    'loader/volatile-update'(paths: readonly (readonly string[])[]): void
+    /**
+     * Refresh entry context before applying config.
+     * @param entry - entry containing the new raw config and optional current fiber.
+     * @param next - continue context refresh and Loader's config update.
+     * @mode waterfall
+     */
     'loader/patch-context'(entry: Entry, next: () => void): void
   }
 
@@ -103,7 +115,7 @@ export class Loader extends EntryTree {
     ctx.on('internal/update', function (config, noSave, next) {
       if (!this.entry || noSave || this.parent.fiber?.entry === this.entry) return next()
       const unparse = this.runtime?.Config?.['simplify']
-      this.entry.options.config = unparse ? unparse(config) : config
+      this.entry.options.config = unparse ? unparse.call(this.runtime!.Config, config) : config
       this.entry.parent.tree.write()
       return next()
     }, { global: true, prepend: true })
diff --git a/vendor/loader/tsconfig.json b/vendor/loader/tsconfig.json
index 2db62c7b63..341a8f0949 100644
--- a/vendor/loader/tsconfig.json
+++ b/vendor/loader/tsconfig.json
@@ -19,6 +19,9 @@
     },
     {
       "path": "../cordis"
+    },
+    {
+      "path": "../schemastery"
     }
   ]
 }
diff --git a/vendor/schemastery/README.md b/vendor/schemastery/README.md
index 24fdf3662f..54972ce4c6 100644
--- a/vendor/schemastery/README.md
+++ b/vendor/schemastery/README.md
@@ -387,3 +387,7 @@ const schema2 = new Schema(JSON.parse(JSON.stringify(schema1)))
 
 Schemastery also exposes the Standard Schema `~standard` property, so compatible
 tools can validate values without depending on Schemastery-specific APIs.
+
+## Volatile configuration
+
+`.volatile()` preserves a field's schema type and metadata while parsing its value into a stable reference read with `.get()`. Defaults remain ordinary data; absent optional fields return references containing `undefined`. `simplify()` unwraps references for persistence. See the [configuration guide](../../docs/cordis-tutorial/05-config.md#volatile-fields) for supported placements and Cordis update semantics.
diff --git a/vendor/schemastery/src/index.ts b/vendor/schemastery/src/index.ts
index 56a499e1cc..6edc132c49 100644
--- a/vendor/schemastery/src/index.ts
+++ b/vendor/schemastery/src/index.ts
@@ -1,4 +1,5 @@
 import { Binary, clone, deepEqual, filterKeys, isNullable, isPlainObject, pick, valueMap, type Dict } from '@deepseek-ai/cosmokit'
+import { createVolatile, isVolatile, type Volatile } from '@deepseek-ai/cosmokit'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 const kSchema = Symbol.for('schemastery')
@@ -9,7 +10,7 @@ declare global {
     /** Convert primitive constructors, constants, and existing schemas into a schema type. */
     export type From<X> =
       | X extends string | number | boolean ? Schema<X>
-      : X extends Schema ? X
+      : X extends Schema<any, any, SchemaMode> ? X
       : X extends typeof String ? Schema<string>
       : X extends typeof Number ? Schema<number>
       : X extends typeof Boolean ? Schema<boolean>
@@ -17,8 +18,8 @@ declare global {
       : X extends Constructor<infer S> ? Schema<S>
       : never
 
-    type TypeS1<X> = X extends Schema<infer S, unknown> ? S : never
-    type Inverse<X> = X extends Schema<any, infer Y> ? (arg: Y) => void : never
+    type TypeS1<X> = X extends Schema<infer S, infer _T, infer _M> ? S : never
+    type Inverse<X> = X extends Schema<infer _S, infer T, infer M> ? (arg: SchemaOutput<T, M>) => void : never
 
     /** Input type accepted by a schema-like value. */
     export type TypeS<X> = TypeS1<From<X>>
@@ -28,7 +29,7 @@ declare global {
     export type Resolve = (data: any, schema: Schema, options: Options, strict?: boolean) => [any, any?]
 
     /** Input type accepted by one schema in an intersection. */
-    export type IntersectS<X> = From<X> extends Schema<infer S, unknown> ? S : never
+    export type IntersectS<X> = From<X> extends Schema<infer S, infer _T, infer _M> ? S : never
     /** Output type returned by one schema in an intersection. */
     export type IntersectT<X> = Inverse<From<X>> extends ((arg: infer T) => void) ? T : never
 
@@ -85,8 +86,8 @@ declare global {
       dict<X, Y extends Schema<any, string> = Schema<string>>(inner: X, sKey?: Y): Schema<Dict<TypeS<X>, TypeS<Y>>, Dict<TypeT<X>, TypeT<Y>>>
       /** Accept tuple arrays where each index matches the corresponding schema. */
       tuple<const X extends readonly any[]>(list: X): Schema<TupleS<X>, TupleT<X>>
-      /** Accept plain objects whose declared properties match the schema dictionary. */
-      object<X extends Dict>(dict: X): Schema<ObjectS<X>, ObjectT<X>>
+      /** Accept plain objects; infer fields from the dictionary, not the enclosing schema's output type. */
+      object<X extends Dict>(dict: X): Schema<ObjectS<NoInfer<X>>, ObjectT<NoInfer<X>>>
       /** Accept values matching at least one schema in `list`. */
       union<const X>(list: readonly X[]): Schema<TypeS<X>, TypeT<X>>
       /** Accept values matching every schema in `list`, merging object outputs. */
@@ -94,7 +95,7 @@ declare global {
       /** Validate with `inner`, then convert the result with `callback`. */
       transform<X, T>(inner: X, callback: (value: TypeS<X>, options: Schemastery.Options) => T, preserve?: boolean): Schema<TypeS<X>, T>
       /** Defer construction of a recursive schema until validation or serialization. */
-      lazy<X extends Schema>(callback: () => X): X
+      lazy<X extends Schema<any, any, SchemaMode>>(callback: () => X): X
       ValidationError: typeof ValidationError
     }
 
@@ -112,6 +113,8 @@ declare global {
     export interface Meta<T = any> {
       default?: T extends {} ? Partial<T> : T
       required?: boolean
+      /** Parse this node as a stable config reference; its type and UI metadata remain unchanged. */
+      volatile?: boolean
       disabled?: boolean
       collapse?: boolean
       badges?: { text: string; type: string }[]
@@ -130,9 +133,9 @@ declare global {
   }
 
   /** Callable schema instance that validates input and returns normalized output. */
-  interface Schemastery<S = any, T = S> {
-    (data?: S | null, options?: Schemastery.Options): T
-    new (data?: S | null, options?: Schemastery.Options): T
+  interface Schemastery<S = any, T = S, Mode extends SchemaMode = 'plain'> {
+    (data?: S | null, options?: Schemastery.Options): SchemaOutput<T, Mode>
+    new (data?: S | null, options?: Schemastery.Options): SchemaOutput<T, Mode>
     [kSchema]: true
     uid: number
     meta: Schemastery.Meta<T>
@@ -152,49 +155,54 @@ declare global {
     /** Format this schema as a compact TypeScript-like type string. */
     toString(inline?: boolean): string
     /** Serialize this schema, preserving shared and recursive references. */
-    toJSON(): Schema<S, T>
+    toJSON(): Schema<S, T, Mode>
     /** Mark nullable input as invalid unless a default supplies a fallback. */
-    required(value?: boolean): Schema<S, T>
+    required<R extends boolean = true>(value?: R): Schema<S, T, SetRequired<Mode, R>>
+    /**
+     * Parse this config field as a stable reference containing immutable data.
+     * @returns a schema whose output supports get(), including when the field is absent.
+     */
+    volatile(): Schema<NoInfer<S>, NoInfer<T>, Mode extends 'defined' | 'volatile-defined' ? 'volatile-defined' : 'volatile'>
     /** Hide this schema node from UI renderers. */
-    hidden(value?: boolean): Schema<S, T>
+    hidden(value?: boolean): Schema<S, T, Mode>
     /** Return the default value instead of throwing when validation fails. */
-    loose(value?: boolean): Schema<S, T>
+    loose(value?: boolean): Schema<S, T, Mode>
     /** Attach a renderer role and optional role-specific metadata. */
-    role(text: string, extra?: any): Schema<S, T>
+    role(text: string, extra?: any): Schema<S, T, Mode>
     /** Attach an external documentation link. */
-    link(link: string): Schema<S, T>
+    link(link: string): Schema<S, T, Mode>
     /** Set the fallback value used for nullable input. */
-    default(value: T): Schema<S, T>
+    default(value: T | NoInfer<Partial<S>>): Schema<S, T, SetRequired<Mode, true>>
     /** Attach an auxiliary comment for documentation or form UIs. */
-    comment(text: string): Schema<S, T>
+    comment(text: string): Schema<S, T, Mode>
     /** Attach a localized or plain description for documentation or form UIs. */
-    description(text: string): Schema<S, T>
+    description(text: string): Schema<S, T, Mode>
     /** Mark this schema node as disabled for form UIs. */
-    disabled(value?: boolean): Schema<S, T>
+    disabled(value?: boolean): Schema<S, T, Mode>
     /** Request collapsed rendering for nested form UIs. */
-    collapse(value?: boolean): Schema<S, T>
+    collapse(value?: boolean): Schema<S, T, Mode>
     /** Add a deprecated badge to this schema node. */
-    deprecated(): Schema<S, T>
+    deprecated(): Schema<S, T, Mode>
     /** Add an experimental badge to this schema node. */
-    experimental(): Schema<S, T>
+    experimental(): Schema<S, T, Mode>
     /** Require strings to match a regular expression. */
-    pattern(regexp: RegExp): Schema<S, T>
+    pattern(regexp: RegExp): Schema<S, T, Mode>
     /** Set an inclusive maximum for numbers or collection lengths. */
-    max(value: number): Schema<S, T>
+    max(value: number): Schema<S, T, Mode>
     /** Set an inclusive minimum for numbers or collection lengths. */
-    min(value: number): Schema<S, T>
+    min(value: number): Schema<S, T, Mode>
     /** Set the numeric increment constraint. */
-    step(value: number): Schema<S, T>
+    step(value: number): Schema<S, T, Mode>
     /** Add or replace an object property schema. */
-    set(key: string, value: Schema): Schema<S, T>
+    set(key: string, value: Schema): Schema<S, T, Mode>
     /** Append a tuple, union, or intersection member schema. */
-    push(value: Schema): Schema<S, T>
+    push(value: Schema): Schema<S, T, Mode>
     /** Remove values equal to schema defaults from normalized output. */
     simplify(value?: any): any
     /** Return a schema clone with descriptions merged from locale messages. */
-    i18n(messages: Dict): Schema<S, T>
+    i18n(messages: Dict): Schema<S, T, Mode>
     /** Attach arbitrary metadata consumed by form renderers and downstream tools. */
-    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T>
+    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T, Mode>
   }
 }
 
@@ -234,7 +242,14 @@ Object.defineProperty(ValidationError.prototype, kValidationError, {
   value: true,
 })
 
-type Schema<S = any, T = S> = Schemastery<S, T>
+type SchemaMode = 'plain' | 'defined' | 'volatile' | 'volatile-defined'
+type SchemaOutput<T, M extends SchemaMode> = M extends 'volatile' ? Volatile<T | undefined>
+  : M extends 'volatile-defined' ? Volatile<T> : T
+type SetRequired<M extends SchemaMode, R extends boolean> = M extends 'volatile' | 'volatile-defined'
+  ? R extends true ? 'volatile-defined' : 'volatile'
+  : R extends true ? 'defined' : 'plain'
+
+type Schema<S = any, T = S, Mode extends SchemaMode = 'plain'> = Schemastery<S, T, Mode>
 
 const Schema = function (options: Schema) {
   const schema = function (data: any, options: Schemastery.Options = {}) {
@@ -405,6 +420,7 @@ Schema.prototype.pattern = function pattern(regexp) {
 }
 
 Schema.prototype.simplify = function simplify(this: Schema, value) {
+  if (isVolatile(value)) value = value.get()
   if (deepEqual(value, this.meta.default, this.type === 'dict')) return null
   if (isNullable(value)) return value
   if (this.type === 'object' || this.type === 'dict') {
@@ -461,7 +477,36 @@ for (const key of ['default', 'link', 'comment', 'description', 'max', 'min', 's
   })
 }
 
+Schema.prototype.volatile = function volatile() {
+  if (this.meta.volatile) throw new TypeError('volatile schema is already wrapped')
+  return this.extra('volatile', true)
+}
+
 const resolvers: Dict<Schemastery.Resolve> = {}
+const checkedVolatile = Symbol('checked-volatile-schema')
+
+function validateVolatileSchema(schema: Schema, path: (keyof any)[] = [], blocked = false, seen = new Map<Schema, Set<boolean>>()) {
+  const states = seen.get(schema) ?? new Set<boolean>()
+  if (states.has(blocked)) return
+  states.add(blocked)
+  seen.set(schema, states)
+  if (schema.meta?.volatile && blocked) {
+    throw new ValidationError('volatile fields require a fixed object path without an enclosing volatile field', { path })
+  }
+  const nested = blocked || !!schema.meta?.volatile
+  if (schema.dict) {
+    for (const [key, child] of Object.entries(schema.dict)) validateVolatileSchema(child, [...path, key], nested, seen)
+  }
+  if (schema.sKey) validateVolatileSchema(schema.sKey, [...path, '<key>'], true, seen)
+  if (schema.inner && (schema.type !== 'lazy' || schema.inner[kSchema])) {
+    validateVolatileSchema(schema.inner, [...path, '*'], true, seen)
+  }
+  if (schema.list) {
+    for (let index = 0; index < schema.list.length; index++) {
+      validateVolatileSchema(schema.list[index]!, [...path, String(index)], true, seen)
+    }
+  }
+}
 
 Schema.extend = function extend(type, resolve) {
   resolvers[type] = resolve
@@ -469,6 +514,20 @@ Schema.extend = function extend(type, resolve) {
 
 Schema.resolve = function resolve(data, schema, options = {}, strict = false) {
   if (!schema) return [data]
+  if (!(options as Schemastery.Options & { [checkedVolatile]?: boolean })[checkedVolatile]) {
+    validateVolatileSchema(schema, options.path)
+    options = { ...options, [checkedVolatile]: true } as Schemastery.Options
+  }
+  if (schema.meta?.volatile) {
+    const inner = Schema(schema)
+    inner.meta = { ...schema.meta, volatile: false }
+    const [value, adapted] = Schema.resolve(data, inner, options, strict)
+    try {
+      return [createVolatile(value), adapted]
+    } catch (error) {
+      throw new ValidationError(error instanceof Error ? error.message : String(error), options)
+    }
+  }
   if (options.ignore?.(data, schema)) return [data]
 
   if (isNullable(data) && schema.type !== 'lazy') {
@@ -582,6 +641,7 @@ Schema.extend('lazy', (data, schema, options, strict) => {
   if (!schema.inner![kSchema]) {
     schema.inner = schema.builder!()
     schema.inner!.meta = { ...schema.meta, ...schema.inner!.meta }
+    validateVolatileSchema(schema.inner!, options.path, true)
   }
   return Schema.resolve(data, schema.inner!, options, strict)
 })
@@ -706,7 +766,7 @@ function property(data: any, key: keyof any, schema: Schema, options: Schemaster
   } catch (e) {
     if (!options?.autofix) throw e
     delete data[key]
-    return schema.meta.default
+    return schema.meta.volatile ? createVolatile(schema.meta.default) : schema.meta.default
   }
 }
 
diff --git a/vitest.config.ts b/vitest.config.ts
index baf4f35fc3..22c5e530e3 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -224,6 +224,9 @@ export default defineConfig({
         // harness the jsdom lane doesn't cover yet. TODO(gui): cover and
         // remove as the client test lane matures.
         'packages/client/ui-trajectory/src/*',
+        // Electron guest integration retains its unit specs; per-file coverage
+        // is deferred until a native Electron harness covers guest behavior.
+        'packages/client/ui-sidebar-browser/src/client/electron/**',
         // Trajectory's compact Markdown projection retains deferred branch coverage.
         'packages/client/ui-primitives/src/markdown/plain-text.ts',
         'packages/client/ui-user-questions/src/client/QuestionComposer.tsx',